# ASDropdown

ASDropdown presents a list of strings using a native HTML `select`. ASUI themes the closed control, optional leading icon, caret, and supported interaction states. The browser and operating system control the open option menu.

## Usage

```tsx
import { useState } from 'react';
import { ASDropdown, ComponentSize } from '@eleventheye/asui';

const SortField = () => {
  const [sortOrder, setSortOrder] = useState('Newest');

  return (
    <>
      <label htmlFor="sort-order">Sort order</label>
      <ASDropdown
        id="sort-order"
        size={ComponentSize.Medium}
        options={['Newest', 'Oldest']}
        value={sortOrder}
        onChange={setSortOrder}
      />
    </>
  );
};
```

## Props

| Prop                 | Meaning                                                              | Default   |
| -------------------- | -------------------------------------------------------------------- | --------- |
| `options`            | Strings used as both option labels and values; supply unique strings | `[]`      |
| `value`              | Initial selection and subsequent non-empty selection updates         | `''`      |
| `onChange`           | Receives the selected string, not a DOM event                        | No-op     |
| `placeholder`        | Adds a selectable option when the supplied `value` is empty          | `''`      |
| `size`               | `ComponentSize.Small`, `Medium`, or `Large`                          | `Medium`  |
| `Icon`               | Optional leading component accepting `IconProps`                     | Omitted   |
| `disabled`           | Disables the native select                                           | `false`   |
| `id`                 | ID of the native select, for label association                       | Generated |
| `className`, `style` | Styling of the outer wrapper                                         | Omitted   |
| `theme`              | Complete local theme replacement                                     | Inherited |
| `themeOverrides`     | Partial overrides of the inherited theme                             | Omitted   |

See [ASDropdownProps](../src/asdropdown/ASDropdown.types.ts) for the public type. Native select attributes such as `name`, `required`, and a select ref are not currently exposed by this API.

## Selection behavior

The component keeps local selection state and updates it immediately when a user chooses an option, then calls `onChange`. Non-empty `value` changes synchronize that state. Omitting `value` allows local selection.

This is not a strict controlled/uncontrolled split: keeping `value` unchanged does not prevent a local selection, and changing it to an empty string does not reset the stored selection. The placeholder is an ordinary selectable option, not a disabled prompt. These are existing API limitations; do not rely on empty-string resets or parent-veto behavior.

## Themes

`components.dropdown` configures state backgrounds, text, outlines, shadows, focus indication, caret colors, icon inset, typography, and size-specific height/padding. For example:

```tsx
<ASDropdown
  options={['Newest', 'Oldest']}
  themeOverrides={{
    components: {
      dropdown: {
        radius: '8px',
        rest: { background: '#ffffff', color: '#101828' },
        caretColor: '#475467',
      },
    },
  }}
/>
```

Omit both theme inputs to inherit; pass only one of `theme` or `themeOverrides`. The resolved theme also reaches the leading icon. Its explicit fill follows the dropdown's rest or disabled foreground. See the [dropdown theme reference](./theme-reference.md#dropdowns--asdropdownstyles) for every property and preset default.

Native option menus may not honor all CSS, including gradients. A project theme cannot guarantee identical open menus across platforms.

## Accessibility

Associate a visible `<label>` through `htmlFor` and the select's `id`. A placeholder or icon is not a substitute for an accessible name. Keyboard selection and disabled behavior come from the native select. ASUI preserves focus after pointer selection while distinguishing pointer decoration from keyboard focus indication.