gh-trabian-fluxwing-skills/skills/fluxwing-component-creator/templates/list.md

# List Component

Ordered and unordered list component with various display patterns, selection support, and keyboard navigation.

## Unordered List (Default)

```
┌────────────────────────────────────────┐
│ {{marker}} {{items[0].text}}          │
│ {{marker}} {{items[1].text}}          │
│ {{marker}} {{items[2].text}}          │
└────────────────────────────────────────┘
```

## Ordered List

```
┌────────────────────────────────────────┐
│ 1. {{items[0].text}}                   │
│ 2. {{items[1].text}}                   │
│ 3. {{items[2].text}}                   │
└────────────────────────────────────────┘
```

## Selectable List with Selection

```
┌────────────────────────────────────────┐
│   {{items[0].text}}                    │
│ ▓▓{{items[1].text}}▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓     │
│   {{items[2].text}}                    │
└────────────────────────────────────────┘
```

## Checklist Variant

```
┌────────────────────────────────────────┐
│ ☐ {{items[0].text}}                    │
│ ☑ {{items[1].text}}                    │
│ ☐ {{items[2].text}}                    │
└────────────────────────────────────────┘
```

## Multi-Select List

```
┌────────────────────────────────────────┐
│ ☑ {{items[0].text}}                    │
│ ☑ {{items[1].text}}                    │
│ ☐ {{items[2].text}}                    │
└────────────────────────────────────────┘
```

## Compact List (No Borders)

```
{{marker}} {{items[0].text}}
{{marker}} {{items[1].text}}
{{marker}} {{items[2].text}}
```

## Striped List

```
┌────────────────────────────────────────┐
│ {{marker}} {{items[0].text}}          │
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
│ {{marker}} {{items[1].text}}          │
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
│ {{marker}} {{items[2].text}}          │
└────────────────────────────────────────┘
```

## Definition List

```
┌────────────────────────────────────────┐
│ {{items[0].text}}                      │
│   {{items[0].description}}             │
│                                        │
│ {{items[1].text}}                      │
│   {{items[1].description}}             │
│                                        │
│ {{items[2].text}}                      │
│   {{items[2].description}}             │
└────────────────────────────────────────┘
```

## Menu-Style List

```
┌────────────────────────────────────────┐
│ > {{items[0].text}}                    │
│   {{items[1].text}}                    │
│   {{items[2].text}}                    │
│   {{items[3].text}}                    │
└────────────────────────────────────────┘
```

## Numbered List Variants

### Decimal (Default)
```
┌────────────────────────────────────────┐
│ 1. {{items[0].text}}                   │
│ 2. {{items[1].text}}                   │
│ 3. {{items[2].text}}                   │
└────────────────────────────────────────┘
```

### Alphabetic
```
┌────────────────────────────────────────┐
│ a. {{items[0].text}}                   │
│ b. {{items[1].text}}                   │
│ c. {{items[2].text}}                   │
└────────────────────────────────────────┘
```

### Roman Numerals
```
┌────────────────────────────────────────┐
│ i.  {{items[0].text}}                  │
│ ii. {{items[1].text}}                  │
│ iii.{{items[2].text}}                  │
└────────────────────────────────────────┘
```

## Disabled Items

```
┌────────────────────────────────────────┐
│ {{marker}} {{items[0].text}}          │
│ ░ {{items[1].text}} (disabled)        │
│ {{marker}} {{items[2].text}}          │
└────────────────────────────────────────┘
```

## Interactive States

### Hover State
```
┌────────────────────────────────────────┐
│ {{marker}} {{items[0].text}}          │
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
│▓{{marker}} {{items[1].text}}         ▓│
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│
│ {{marker}} {{items[2].text}}          │
└────────────────────────────────────────┘
```

## Dimensions

- **Standard Width**: 30-60 characters
- **Compact Width**: 20-40 characters
- **Item Height**: 1 character (compact), 2-3 characters (normal)
- **Container Height**: Variable based on item count
- **Marker Width**: 2-4 characters depending on type

## Variables

- `items` (array, required): List items with text and metadata
  - Each item: `{id, text, selected?, disabled?, description?}`
  - Min: 1 item, Max: 50 items
- `type` (string): "unordered", "ordered", "definition", or "checklist"
- `marker` (string): Bullet character for unordered lists (default: "•")
- `numbering` (string): Style for ordered lists ("decimal", "alpha", "roman", "roman-upper")
- `selectable` (boolean): Whether items can be selected (default: true)
- `multiSelect` (boolean): Allow multiple selections (default: false)
- `bordered` (boolean): Show container border (default: true)
- `compact` (boolean): Use minimal spacing (default: false)

## Accessibility

- **Role**: list (or listbox if selectable)
- **Item Role**: listitem (or option if selectable)
- **Focusable**: Yes, if selectable
- **Keyboard Support**:
  - Arrow Up/Down: Navigate between items
  - Enter/Space: Select item
  - Ctrl+A: Select all (if multiSelect)
  - Home/End: Jump to first/last item
- **ARIA**:
  - `aria-multiselectable`: "true" if multiSelect enabled
  - `aria-selected`: "true" for selected items
  - `aria-disabled`: "true" for disabled items

## Usage Examples

### Navigation Menu
```
┌────────────────────────────────────────┐
│ > Dashboard                            │
│   Products                             │
│   Orders                               │
│   Customers                            │
│   Settings                             │
└────────────────────────────────────────┘
```

### Task List
```
┌────────────────────────────────────────┐
│ ☑ Complete project proposal           │
│ ☑ Review team feedback                │
│ ☐ Update documentation               │
│ ☐ Schedule client meeting             │
│ ☐ Prepare presentation                │
└────────────────────────────────────────┘
```

### File Browser
```
┌────────────────────────────────────────┐
│ 📁 Documents                           │
│ 📁 Downloads                           │
│ 📁 Pictures                            │
│ 📄 README.md                           │
│ 📄 package.json                       │
└────────────────────────────────────────┘
```

### Settings Menu
```
┌────────────────────────────────────────┐
│ • General Settings                     │
│ • Privacy & Security                   │
│ • Notifications                        │
│ • Account Management                   │
│ • Help & Support                       │
└────────────────────────────────────────┘
```

### Multi-Select Options
```
┌────────────────────────────────────────┐
│ ☑ Email Notifications                 │
│ ☐ SMS Alerts                          │
│ ☑ Push Notifications                  │
│ ☐ Weekly Digest                       │
│ ☑ Marketing Updates                   │
└────────────────────────────────────────┘
```

## Component Behavior

### Selection Management

1. **Single Select**: Only one item selected at a time
2. **Multi Select**: Multiple items can be selected simultaneously
3. **Toggle Selection**: Click to select/deselect items
4. **Keyboard Navigation**: Arrow keys move focus, Enter/Space selects

### State Management

- **Default**: No items selected
- **Selected**: One or more items selected
- **Focused**: Current keyboard focus position
- **Disabled**: Items that cannot be interacted with

### Visual Feedback

- **Selection**: Highlighted background for selected items
- **Hover**: Temporary highlight on mouse over
- **Focus**: Keyboard focus indicator
- **Disabled**: Grayed out appearance

## Design Tokens

### Visual Elements
- `┌─┐└┘─│` = List container borders
- `{{marker}}` = Configurable bullet points (•, -, *, ►)
- `▓` = Selection/hover background
- `░` = Disabled state indicator
- `☐☑` = Checkbox states (unchecked/checked)
- `>` = Active/current item indicator

### List Markers
- **Bullets**: •, -, *, ►, ○, ■, ♦
- **Numbers**: 1., a., i., I., (1), [1]
- **Custom**: Any single character or short string

## Related Components

- **Menu**: Dropdown or context menu with list items
- **Navigation**: Hierarchical navigation lists
- **Table**: Tabular data display with rows
- **Tree**: Hierarchical list with expand/collapse

## Implementation Notes

This ASCII representation demonstrates list patterns and interactions. When implementing:

1. **Virtual Scrolling**: Handle large lists efficiently
2. **Keyboard Navigation**: Full accessibility support
3. **Selection Persistence**: Maintain selection state across updates
4. **Performance**: Optimize rendering for large item counts
5. **Customization**: Support custom markers and styling
6. **Search/Filter**: Add search capabilities for long lists

## Variants

- **Simple List**: Basic display without interaction
- **Selectable List**: Single or multi-selection support
- **Menu List**: Navigation and action items
- **Checklist**: Task management with completion states
- **Definition List**: Term and description pairs
- **Nested List**: Hierarchical list structures