feat(SelectDropdown): isCreateable support, removes SearchIcon, styling fixes

.nx/version-plans/version-plan-1781295720164.md

@@ -0,0 +1,5 @@
+---
+gamut: minor
+---
+
+feat(SelectDropdown): add isCreatable prop + remove SearchIcon

packages/gamut/agent-tools/skills/gamut-forms/SKILL.md

@@ -26,6 +26,22 @@ For typical product forms, prefer `GridForm` (declarative `fields`, `LayoutGrid`
 
 ---
 
+## SelectDropdown vs Select
+
+Use `Select` for standard single-select fields where bundle size matters and no special styling is needed. Use `SelectDropdown` when the design calls for any of:
+
+- Styled dropdown menu (react-select appearance)
+- Search / typeahead
+- Multi-select with tags
+- Creatable options
+- Option icons, subtitles, right labels, abbreviations, or grouped options
+
+`SelectDropdown` carries a larger JS dependency (react-select); don't reach for it as a default drop-in for `Select`.
+
+For full SelectDropdown API detail — controlled vs uncontrolled patterns, creatable options, react-select action metadata — use [`gamut-select-dropdown`](../gamut-select-dropdown/SKILL.md). Generic `FormGroup` wiring (labels, errors, live regions) still applies as documented below.
+
+---
+
 ## `FormGroup` (baseline)
 
 `packages/gamut/src/Form/elements/FormGroup.tsx`

packages/gamut/agent-tools/skills/gamut-select-dropdown/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: gamut-select-dropdown
+description: Use when implementing or auditing SelectDropdown — single/multi modes, controlled vs uncontrolled value, creatable options, FormGroup wiring, and onChange contract. Pair with gamut-forms for error live regions, ConnectedForm, and field-level validation.
+---
+
+# Gamut SelectDropdown
+
+Styled dropdown built on react-select.
+
+Source: `@codecademy/gamut` — [SelectDropdown.tsx](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/SelectDropdown/SelectDropdown.tsx)
+
+See also: [`gamut-forms`](../gamut-forms/SKILL.md) — FormGroup wiring, error regions, and validation UX.
+
+Storybook: [Atoms / FormInputs / SelectDropdown](https://gamut.codecademy.com/?path=/docs-atoms-forminputs-selectdropdown--docs)
+
+---
+
+## When to use SelectDropdown vs Select
+
+Use `Select` for standard single-select forms with minimal bundle cost. Use `SelectDropdown` when designs specify the styled dropdown menu, search, multi-select tags, creatable options, icons, groups, or abbreviations. `SelectDropdown` has a larger JavaScript dependency (react-select).
+
+---
+
+## Options
+
+`options` accepts an array of plain strings or option objects. `value` is always a string and references an option's `value`.
+
+The table below shows the keys and value types for an option object:
+
+| Field          | Type                              | Required | Notes                                                                |
+| -------------- | --------------------------------- | -------- | -------------------------------------------------------------------- |
+| `label`        | `string`                          | yes      | Display text                                                         |
+| `value`        | `string`                          | yes      | Unique string; what `value` / `string[]` reference                   |
+| `disabled`     | `boolean`                         | no       | Option cannot be selected                                            |
+| `subtitle`     | `string`                          | no       | Secondary text below the label                                       |
+| `rightLabel`   | `string`                          | no       | Text on the right side of the option                                 |
+| `icon`         | icon component from `gamut-icons` | no       | A `@codecademy/gamut-icons` component                                |
+| `abbreviation` | `string`                          | no       | Short text shown in the input while the full label shows in the menu |
+
+Grouped options: `{ label, options: [...], divider? }` (extends react-select `GroupBase`; `divider` draws a rule above the group).
+
+---
+
+## Controlled vs uncontrolled
+
+`SelectDropdown` does **not** accept `defaultValue`.
+
+| Mode             | Uncontrolled                                       | Controlled                                                                        |
+| ---------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Single           | Not supported                                      | `value` (string) + update in `onChange`                                           |
+| Multi            | Omit `value` or pass non-array (`undefined`, `''`) | `value: string[]` + update in `onChange`                                          |
+| Creatable single | Not supported                                      | Same as single; `onCreateOption` appends to `options`                             |
+| Creatable multi  | Omit `value`; `onCreateOption` for options         | `value: string[]`; update in `onChange` on every change including `create-option` |
+
+Single-select selection is derived from the `value` prop only — internal state is not kept. Multi-select without `value: string[]` keeps selection in internal `multiValues`.
+
+**Controlled creatable multi pitfall:** Updating `options` alone without syncing `value` in `onChange` clears selection when options re-render.
+
+### When to use uncontrolled (multi only)
+
+Uncontrolled multi is appropriate when:
+
+- No other part of the UI needs to react to the current selection (no live summary, no dependent field, no enabled/disabled button).
+- You only need the value at form submission — via `FormData`, a submit handler reading the DOM, or react-hook-form's `getValues`.
+- Simplicity is the priority; omitting `value` means one less piece of state to manage.
+
+```tsx
+// Good fit: a "tags" field where only the submitted array matters
+<SelectDropdown
+  multiple
+  name="tags"
+  options={tagOptions}
+  onCreateOption={(v) => setTagOptions((prev) => [...prev, v])}
+/>
+```
+
+### When to use controlled
+
+Use controlled when:
+
+- Another part of the UI must reflect the current selection in real time (summary text, a filtered list, an enable/disable condition).
+- You need to pre-populate from an API response, reset on cancel, or sync with a form library like react-hook-form.
+- You are using single-select (the only supported mode for single).
+
+```tsx
+// Good fit: pre-populate from API, clear on cancel, show live summary
+const [selected, setSelected] = useState<string[]>(initialValues);
+
+<SelectDropdown
+  multiple
+  name="languages"
+  options={languageOptions}
+  value={selected}
+  onChange={(opts) => setSelected(opts.map((o) => o.value))}
+/>
+<p>Selected: {selected.join(', ') || 'none'}</p>
+```
+
+---
+
+## onChange contract
+
+`onChange` receives option object(s), not `event.target.value`:
+
+```tsx
+// Single
+onChange={(option) => setValue(option.value)}
+
+// Multi
+onChange={(selected) => setValue(selected.map((o) => o.value))}
+```
+
+Second argument is react-select `ActionMeta`. For creatable creates: `meta.action === 'create-option'`. Do **not** pass `onCreateOption` to react-select directly — Gamut invokes it from `changeHandler` while still forwarding `create-option` to consumer `onChange`.
+
+**Action normalization gotcha:** for every action other than `create-option`, `changeHandler` overwrites the real react-select action with a hardcoded `'select-option'` before calling consumer `onChange`. `meta.action` never distinguishes `remove-value`, `clear`, `pop-value`, or `deselect-option` — only `'select-option'` or `'create-option'` ever reach you. Derive "cleared" / "removed one tag" from a diff of the `selected` array instead of `meta.action`.
+
+---
+
+## Creatable
+
+- `isCreatable` forces `isSearchable: true` (TypeScript enforces this).
+- `onCreateOption(inputValue)` — convenience hook to append to `options`.
+- `onChange(selected, meta)` — use `meta.action === 'create-option'` to sync controlled `value` and `options` together.
+- `isValidNewOption` — return `false` to hide the Add row.
+- `createOptionPosition` — `'first' | 'last'` (default `'last'`). Renders the Add row above or below the rest of the options list.
+- `validationMessage` — content shown _inside the dropdown menu itself_ in place of the default "No options" text, whenever no option matches the current input (empty `options`, or every option filtered out by a search). Not tied to `isCreatable` — any searchable SelectDropdown can use it. Accepts a `ReactNode` or a function receiving `{ inputValue }`, so you can surface live validation/error copy (e.g. "No results for '{inputValue}'") right where the user is looking. Mirror the same text in `FormGroup`'s `error` prop for field-level feedback below the control.
+- SelectDropdown already announces its "No options" text (default or `validationMessage`) to screen readers via a debounced (`400ms`), standalone `aria-live="polite" role="status"` live region — react-select's own live region only fires when its `options` prop is non-empty, so it stays silent for the empty-options case; this fills that gap, including mid-fetch states. Don't build a separate announcement for this; just set `validationMessage`.
+
+**Validation after blur:** react-select's `onInputChange` reports an empty string on the `'input-blur'` action — the typed value has already been cleared internally by the time that fires. Store the last typed value in a ref during `'input-change'` and re-validate from it on `'input-blur'`:
+
+```tsx
+const lastInput = useRef('');
+
+<SelectDropdown
+  isCreatable
+  onInputChange={(value, { action }) => {
+    if (action === 'input-change') lastInput.current = value;
+    if (action === 'input-blur') validate(lastInput.current);
+  }}
+/>;
+```
+
+---
+
+## FormGroup wiring
+
+- `FormGroup` `htmlFor` must match SelectDropdown's `name` — **not** `id`. Unlike plain `Select`, SelectDropdown's `id`/`htmlFor` prop only sets the id of react-select's outer wrapper `<div>` (not labelable); the actual focusable combobox input always takes its id from `inputId`, which is `name`. A label pointed at `id` instead of `name` silently breaks the label/input association whenever the two differ.
+- Pass `name` on SelectDropdown (required for forms, and it doubles as the accessible id target).
+- Rely on FormGroupLabel's `htmlFor`/`id` connection for the accessible label — this is the standard HTML pattern and preferred method. Do not use `aria-label` when a FormGroupLabel is present, as it overrides the visible label.
+- Pass `error` boolean when FormGroup has an error.
+- Generic FormGroup live-region behavior: see [`gamut-forms`](../gamut-forms/SKILL.md).
+
+```tsx
+<FormGroup htmlFor="country" isSoloField label="Country" error={errors.country}>
+  <SelectDropdown
+    name="country"
+    options={options}
+    value={value}
+    error={Boolean(errors.country)}
+    onChange={(option) => setValue(option.value)}
+  />
+</FormGroup>
+```
+
+---
+
+## Styling & layout props
+
+| Prop                | Type                     | Default  | Notes                                                     |
+| ------------------- | ------------------------ | -------- | --------------------------------------------------------- |
+| `size`              | `'small' \| 'medium'`    | `medium` | Control height/density                                    |
+| `shownOptionsLimit` | `1`–`6`                  | `6`      | Visible options before the menu scrolls                   |
+| `inputWidth`        | `string \| number`       | —        | Width of the input independent of the menu                |
+| `dropdownWidth`     | `string \| number`       | —        | Width of the menu independent of the input                |
+| `menuAlignment`     | `'left' \| 'right'`      | `left`   | Menu edge alignment                                       |
+| `zIndex`            | `number`                 | `2`      | Menu z-index (control container defaults to `3`)          |
+| `inputProps`        | `{ hidden?, combobox? }` | —        | `data-*` / `aria-*` only, forwarded to the input elements |
+
+---
+
+## Examples
+
+### Single (controlled)
+
+```tsx
+const [value, setValue] = useState('us');
+
+<SelectDropdown
+  name="country"
+  options={options}
+  value={value}
+  onChange={(option) => setValue(option.value)}
+/>;
+```
+
+### Multi (uncontrolled)
+
+```tsx
+<SelectDropdown
+  multiple
+  name="tags"
+  options={options}
+  onChange={(selected) => console.log(selected)}
+/>
+```
+
+### Creatable multi (uncontrolled)
+
+```tsx
+const [options, setOptions] = useState(['Apple', 'Banana']);
+
+<SelectDropdown
+  isCreatable
+  multiple
+  name="fruits"
+  options={options}
+  onCreateOption={(v) => setOptions((prev) => [...prev, v])}
+/>;
+```
+
+### Creatable multi (controlled)
+
+```tsx
+const [options, setOptions] = useState(['Apple', 'Banana']);
+const [value, setValue] = useState<string[]>([]);
+
+<SelectDropdown
+  isCreatable
+  multiple
+  name="fruits"
+  options={options}
+  value={value}
+  onChange={(selected, meta) => {
+    setValue(selected.map((o) => o.value));
+    if (meta.action === 'create-option' && meta.option) {
+      setOptions((prev) => [...prev, meta.option.value]);
+    }
+  }}
+/>;
+```