# Select Component

The `SelectComponent` provides a styled dropdown select element with support for single and multiple selection, custom options, and full accessibility features.

## Features

- **Single & Multiple Selection**: Support for both single choice and multi-select dropdowns
- **Custom Options**: Flexible option management with labels, values, and disabled states
- **Accessibility**: Full ARIA support with proper keyboard navigation
- **Event Handling**: Selection change events with typed data
- **Styling**: Native dropdown arrow by default, with option for custom icons
- **Validation**: Error states and helper text support

## Usage

### Basic Single Selection

```html
<ccl-select 
  [options]="countryOptions"
  placeholder="Choose a country">
</ccl-select>
```

### With FormFieldWrapper

```html
<ccl-form-field-wrapper 
  label="Country" 
  hint="Select your country"
  required>
  <ccl-select 
    id="country" 
    placeholder="Choose..."
    [options]="countryOptions"
    (selectionChange)="onCountryChange($event)">
  </ccl-select>
</ccl-form-field-wrapper>
```

### Multiple Selection

```html
<ccl-form-field-wrapper 
  label="Skills" 
  hint="Select multiple skills">
  <ccl-select 
    id="skills" 
    [multiple]="true"
    [size]="4"
    [options]="skillOptions"
    (selectionChange)="onSkillsChange($event)">
  </ccl-select>
</ccl-form-field-wrapper>
```

### Default Behavior (Native Dropdown Arrow)
```html
<ccl-select 
  [options]="countryOptions"
  placeholder="Choose a country">
</ccl-select>
```

### Custom Filter Icon
```html
<ng-template #customFilterIcon>
  <span class="custom-filter-icon">🔍</span>
</ng-template>

<ccl-select 
  [options]="countryOptions"
  [filterIcon]="customFilterIcon"
  placeholder="Choose a country">
</ccl-select>
```

## API Reference

### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `options` | `SelectOption[]` | `[]` | Array of select options |
| `placeholder` | `string` | `''` | Placeholder text for single selection |
| `disabled` | `boolean` | `false` | Disable the select element |
| `readonly` | `boolean` | `false` | Make the select readonly |
| `error` | `boolean` | `false` | Show error state styling |
| `errorMessage` | `string` | `''` | Error message to display |
| `helperText` | `string` | `''` | Helper text below the select |
| `multiple` | `boolean` | `false` | Enable multiple selection |
| `size` | `number` | `undefined` | Number of visible options (for multiple select) |
| `filterIcon` | `TemplateRef<unknown>` | `undefined` | Custom dropdown icon template (replaces native arrow) |
| `showPrefixIcon` | `boolean` | `false` | Show/hide the prefix icon (left side) |
| `prefixIcon` | `TemplateRef<unknown>` | `undefined` | Custom prefix icon template |
| `iconBackground` | `'none' \| 'rounded' \| 'square'` | `'none'` | Background style for prefix icon |

### Outputs

| Event | Type | Description |
|-------|------|-------------|
| `selectionChange` | `EventEmitter<string \| string[]>` | Emitted when selection changes |

### SelectOption Interface

```typescript
interface SelectOption {
  value: string;
  label: string;
  disabled?: boolean;
}
```

## Component Setup

### TypeScript Component

```typescript
import { Component } from '@angular/core';
import { SelectComponent, SelectOption } from '@Crystal-Code-Labs/ccl-ui-components';

@Component({
  selector: 'app-example',
  template: `
    <ccl-select 
      [options]="options"
      (selectionChange)="onSelectionChange($event)">
    </ccl-select>
  `,
  imports: [SelectComponent]
})
export class ExampleComponent {
  options: SelectOption[] = [
    { value: 'us', label: 'United States' },
    { value: 'ca', label: 'Canada' },
    { value: 'mx', label: 'Mexico', disabled: true }
  ];

  onSelectionChange(value: string | string[]): void {
    console.log('Selected:', value);
  }
}
```

## Styling

### CSS Classes

- `.ccl-select-wrapper` - Main wrapper container
- `.ccl-select` - Select element styling
- `.ccl-select__helper` - Helper text styling
- `.ccl-select__error` - Error message styling

### Design Tokens Used

- `--color-text` - Text color
- `--color-border` - Border color
- `--color-primary-500` - Focus and active states
- `--color-error-500` - Error state color
- `--color-success-500` - Helper text color
- `--color-background-default` - Background color
- `--color-background-surface` - Disabled background
- `--typography-font-family-sans` - Font family
- `--typography-font-size-md` - Font size
- `--spacing-sm` - Padding
- `--spacing-md` - Padding
- `--radius-sm` - Border radius
- `--motion-fast` - Transition timing

### Native Dropdown Arrow

The component uses the native browser dropdown arrow by default. When a custom `filterIcon` is provided, it replaces the native arrow with the custom icon.

## Accessibility Features

### Keyboard Navigation
- **Tab**: Focus the select element
- **Space/Enter**: Open dropdown (single select)
- **Arrow Keys**: Navigate options
- **Escape**: Close dropdown

### ARIA Support
- `aria-invalid`: Set when in error state
- `aria-describedby`: Links to helper text and error messages
- Proper labeling for screen readers

### Multiple Selection
- **Ctrl/Cmd + Click**: Select multiple options
- **Shift + Click**: Select range of options
- Visual indication of selected options

## Examples

### Dynamic Options

```typescript
export class DynamicSelectComponent {
  countries: SelectOption[] = [];
  
  ngOnInit() {
    this.loadCountries();
  }
  
  loadCountries() {
    // Load from API
    this.countries = [
      { value: 'us', label: 'United States' },
      { value: 'ca', label: 'Canada' },
      { value: 'mx', label: 'Mexico' }
    ];
  }
}
```

### Form Integration

```typescript
export class FormComponent {
  form = this.fb.group({
    country: [''],
    skills: [[]]
  });
  
  countryOptions: SelectOption[] = [
    { value: 'us', label: 'United States' },
    { value: 'ca', label: 'Canada' }
  ];
  
  skillOptions: SelectOption[] = [
    { value: 'js', label: 'JavaScript' },
    { value: 'ts', label: 'TypeScript' },
    { value: 'ng', label: 'Angular' }
  ];
  
  onCountryChange(value: string) {
    this.form.patchValue({ country: value });
  }
  
  onSkillsChange(value: string[]) {
    this.form.patchValue({ skills: value });
  }
}
```

### Conditional Options

```typescript
export class ConditionalSelectComponent {
  selectedCategory = '';
  
  categories: SelectOption[] = [
    { value: 'tech', label: 'Technology' },
    { value: 'design', label: 'Design' }
  ];
  
  get subcategories(): SelectOption[] {
    switch (this.selectedCategory) {
      case 'tech':
        return [
          { value: 'frontend', label: 'Frontend' },
          { value: 'backend', label: 'Backend' }
        ];
      case 'design':
        return [
          { value: 'ui', label: 'UI Design' },
          { value: 'ux', label: 'UX Design' }
        ];
      default:
        return [];
    }
  }
}
```

## Best Practices

### Option Management
- Use descriptive labels that are user-friendly
- Keep option values consistent and meaningful
- Consider using disabled options for unavailable choices

### Performance
- For large option lists (100+), consider implementing search/filter functionality
- Use `trackBy` functions if options change frequently

### Accessibility
- Always provide meaningful labels
- Use helper text to explain selection requirements
- Ensure sufficient color contrast for all states

### Error Handling
- Provide clear error messages
- Use both visual and programmatic validation
- Consider real-time validation for better UX

## Migration from HTML Select

### Before (HTML)
```html
<select id="country">
  <option value="">Choose...</option>
  <option value="us">United States</option>
  <option value="ca">Canada</option>
</select>
```

### After (Component)
```html
<ccl-select 
  id="country"
  placeholder="Choose..."
  [options]="countryOptions">
</ccl-select>
```

```typescript
countryOptions: SelectOption[] = [
  { value: 'us', label: 'United States' },
  { value: 'ca', label: 'Canada' }
];
```

## Testing

The component includes comprehensive unit tests covering:
- Option rendering and selection
- Single and multiple selection modes
- Event emission
- Accessibility attributes
- Error states
- Disabled states

Run tests with:
```bash
ng test --include="**/select.spec.ts"
```