# Native Select

Styled native HTML select for browser-native dropdown behavior, mobile-friendly pickers, and lightweight form integrations.

Use Native Select when you want the platform select interaction rather than the custom overlay behavior of `SelectField`.

## Import

```ts
import {
  NativeSelectComponent,
  NativeSelectOptGroupDirective,
  NativeSelectOptionDirective,
} from '@edsis/component/native-select';
import {
  FormControlDirective,
  FormDescriptionComponent,
  FormFieldComponent,
  FormLabelComponent,
  FormMessageComponent,
} from '@edsis/component/form';
```

## Composition

The Angular structure keeps the native `<select>`, `<option>`, and `<optgroup>` elements in the DOM while adding shadcn-style design tokens.

```text
select[NativeSelect]
├── option[NativeSelectOption]
├── option[NativeSelectOption]
└── optgroup[NativeSelectOptGroup]
    ├── option[NativeSelectOption]
    └── option[NativeSelectOption]
```

## Basic usage

Use the directive on a real `<select>` so Angular forms continue to work through the native control.

```html
<label Label for="status-select">Status</label>
<select id="status-select" NativeSelect [(ngModel)]="status">
  <option NativeSelectOption value="">Select status</option>
  <option NativeSelectOption value="todo">Todo</option>
  <option NativeSelectOption value="in-progress">In progress</option>
  <option NativeSelectOption value="done">Done</option>
</select>
```

## Common patterns

### Grouped options

Use `optgroup[NativeSelectOptGroup]` when the options belong to clear categories.

```html
<select NativeSelect [(ngModel)]="department">
  <option NativeSelectOption value="">Select department</option>

  <optgroup NativeSelectOptGroup label="Engineering">
    <option NativeSelectOption value="frontend">Frontend</option>
    <option NativeSelectOption value="backend">Backend</option>
  </optgroup>

  <optgroup NativeSelectOptGroup label="Operations">
    <option NativeSelectOption value="support">Support</option>
    <option NativeSelectOption value="product">Product</option>
  </optgroup>
</select>
```

### Form-field integration

When you want label, helper text, and invalid state wiring similar to the newer shadcn `Field` examples, compose the native select with the existing form primitives.

```html
<FormField>
  <FormLabel>Timezone</FormLabel>
  <select NativeSelect FormControl [(ngModel)]="timezone">
    <option NativeSelectOption value="">Select timezone</option>
    <option NativeSelectOption value="utc">UTC</option>
    <option NativeSelectOption value="gmt-plus-7">GMT+7</option>
  </select>
  <FormDescription>Used for scheduling and invoice timestamps.</FormDescription>
</FormField>
```

### Invalid state

Forward `aria-invalid="true"` when validation is managed outside Angular forms, or let `FormControl` mirror the state from `NgControl`.

```html
<FormField invalid>
  <FormLabel>Department</FormLabel>
  <select NativeSelect FormControl aria-invalid="true">
    <option NativeSelectOption value="">Choose department</option>
    <option NativeSelectOption value="engineering">Engineering</option>
    <option NativeSelectOption value="sales">Sales</option>
  </select>
  <FormMessage>Select a department before continuing.</FormMessage>
</FormField>
```

### Disabled and RTL

Disabled state stays fully native, and right-to-left layouts only need a wrapping `dir="rtl"` container or a direct `dir` attribute on the select.

```html
<section dir="rtl" lang="ar" class="max-w-sm text-right">
  <select NativeSelect disabled>
    <option NativeSelectOption value="">اختر الحالة</option>
    <option NativeSelectOption value="todo">مهام</option>
    <option NativeSelectOption value="done">منجز</option>
  </select>
</section>
```

## API reference

### `NativeSelectComponent`

| Input   | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` | `''`    |

Public methods:

- `focus()` focuses the underlying native select element.

All native `<select>` attributes and Angular form bindings such as `name`, `required`, `disabled`, `multiple`, `[(ngModel)]`, and `formControlName` pass through unchanged.

### `NativeSelectOptionDirective`

| Input   | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` | `''`    |

All native `<option>` attributes such as `value`, `disabled`, and `selected` pass through unchanged.

### `NativeSelectOptGroupDirective`

| Input   | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` | `''`    |

All native `<optgroup>` attributes such as `label` and `disabled` pass through unchanged.

## Styling and theming

The control uses the shared border, ring, foreground, muted, and destructive theme tokens so it matches the rest of the library. The chevron is decorative and hidden automatically for multi-select or listbox-style `size` configurations.

Pass `class` when a layout needs custom width, margin, or grid placement utilities around the native select.

## Accessibility

- Prefer a visible label or another accessible name source for every select.
- Use grouped options only when the categories help people scan the choices faster.
- Keep the placeholder option descriptive when the empty value is a valid initial state.
- `FormControl` can synchronize `id`, `aria-describedby`, and invalid state when the select lives inside `FormField`.

## Keyboard interactions

- Native browser select keyboard interactions stay intact.
- Closed single selects open and cycle according to the platform behavior.
- Multi-select and `size` listbox modes keep the browser's built-in selection model.

## Angular notes

- `select[NativeSelect]` works with template-driven and reactive forms without a custom value accessor.
- The directive is the Angular mapping for upstream `NativeSelect`; the local API intentionally keeps the real HTML elements instead of wrapping them in another component tree.
- Use `SelectField` when you need the custom overlay panel rather than the native browser picker.

## Source parity

This Angular entrypoint follows the shadcn Native Select information architecture while staying honest about local differences: the runtime surface is a styled native `<select>`, and the upstream `Field` examples map to the existing form primitives instead of a new field package.