# List Components

Comprehensive list component system built with Angular 19+ and semantic design tokens. Features multiple variants, sizes, and interactive states for maximum flexibility.

## Components

### `ListItemComponent`
Individual list item with support for avatars, media, icons, and multiple text lines.

### `ListContainerComponent` 
Container for list items with elevation, spacing, and scrolling capabilities.

### `ListExamplesComponent`
Demonstration component showcasing all variants and usage patterns.

## Features

- **Multiple Sizes**: `sm`, `md`, `lg`
- **Line Variants**: One, two, or three lines of text
- **Content Types**: Text-only, avatar, media, icon
- **Interactive States**: Hover, focus, selected, disabled
- **Container Options**: Elevation, spacing, scrolling, rounded corners
- **Text Overflow**: Automatic ellipsis handling
- **Accessibility**: Full ARIA support and keyboard navigation
- **Responsive**: Mobile-first design with breakpoint adjustments

## Usage

### Basic Text List

```typescript
import { ListItemComponent, ListContainerComponent } from './shared/components';

// In your component:
items = [
  { primary: 'Inbox' },
  { primary: 'Starred' },
  { primary: 'Sent' }
];
```

```html
<ui-list-container elevation="sm" spacing="xs" rounded>
  @for (item of items; track item.primary) {
    <ui-list-item 
      [data]="item"
      size="md"
      lines="one"
      variant="text"
    />
  }
</ui-list-container>
```

### Avatar List with Two Lines

```typescript
avatarItems = [
  {
    primary: 'John Doe',
    secondary: 'Software Engineer',
    avatarSrc: 'https://example.com/avatar.jpg',
    avatarAlt: 'John Doe'
  }
];
```

```html
<ui-list-container elevation="md" spacing="sm">
  @for (item of avatarItems; track item.primary) {
    <ui-list-item 
      [data]="item"
      size="lg"
      lines="two"
      variant="avatar"
    >
      <button slot="trailing" class="action-btn">
        <i class="fas fa-more-vert"></i>
      </button>
    </ui-list-item>
  }
</ui-list-container>
```

### Media List with Three Lines

```typescript
mediaItems = [
  {
    primary: 'Angular Course',
    secondary: 'Complete guide to modern development',
    tertiary: 'Duration: 2h 30m • Updated: Today',
    mediaSrc: 'https://example.com/thumb.jpg',
    mediaAlt: 'Course thumbnail'
  }
];
```

```html
<ui-list-container elevation="lg" spacing="md" rounded>
  @for (item of mediaItems; track item.primary) {
    <ui-list-item 
      [data]="item"
      size="lg"
      lines="three"
      variant="media"
    >
      <div slot="trailing" class="rating">
        <i class="fas fa-star"></i>
        <span>4.8</span>
      </div>
    </ui-list-item>
  }
</ui-list-container>
```

### Scrollable List

```html
<ui-list-container 
  elevation="md"
  spacing="xs"
  [scrollable]="true"
  maxHeight="400px"
  [fadeIndicator]="true"
  rounded
>
  @for (item of longList; track item.id) {
    <ui-list-item [data]="item" size="md" lines="two" variant="avatar" />
  }
</ui-list-container>
```

## API

### ListItemComponent Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `ListItemData` | required | Item content and configuration |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Item height and spacing |
| `lines` | `'one' \| 'two' \| 'three'` | `'one'` | Number of text lines |
| `variant` | `'text' \| 'avatar' \| 'media'` | `'text'` | Content type |
| `interactive` | `boolean` | `true` | Enable hover/focus states |
| `divider` | `boolean` | `false` | Show bottom border |

### ListContainerComponent Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `elevation` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'none'` | Shadow elevation |
| `spacing` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | `'sm'` | Item spacing |
| `scrollable` | `boolean` | `false` | Enable vertical scrolling |
| `maxHeight` | `string?` | - | Maximum container height |
| `fadeIndicator` | `boolean` | `true` | Show fade at scroll bottom |
| `dense` | `boolean` | `false` | Reduce spacing between items |
| `rounded` | `boolean` | `false` | Round container corners |
| `ariaLabel` | `string?` | - | Accessibility label |

### ListItemData Interface

```typescript
interface ListItemData {
  primary: string;           // Main text (required)
  secondary?: string;        // Secondary text
  tertiary?: string;         // Tertiary text (three-line only)
  avatarSrc?: string;        // Avatar image URL
  avatarAlt?: string;        // Avatar alt text
  mediaSrc?: string;         // Media image URL
  mediaAlt?: string;         // Media alt text
  icon?: string;             // Icon class name
  disabled?: boolean;        // Disabled state
  selected?: boolean;        // Selected state
}
```

## Slots

### Trailing Content
Use the `slot="trailing"` attribute to add content to the right side of list items:

```html
<ui-list-item [data]="item">
  <button slot="trailing">Action</button>
</ui-list-item>
```

## Design Tokens

The components use semantic design tokens for consistent styling:

- **Colors**: `$semantic-color-*`
- **Spacing**: `$semantic-spacing-*`
- **Shadows**: `$semantic-shadow-*`
- **Borders**: `$semantic-border-radius-*`

## Accessibility

- Full ARIA support with proper roles and labels
- Keyboard navigation support
- Focus management and indicators
- Screen reader friendly
- High contrast mode support
- Reduced motion support

## Responsive Design

- Mobile-first approach
- Breakpoint-specific adjustments
- Touch-friendly tap targets
- Optimized spacing for different screen sizes

## Examples

Import and use the `ListExamplesComponent` to see all variants in action:

```typescript
import { ListExamplesComponent } from './shared/components';
```

```html
<ui-list-examples></ui-list-examples>
```