@12-apps/ui 6.46.1 → 6.47.0

package/dist/types-native/components/form/Select/Select.base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Select.base.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Select/Select.base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;OAEG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"Select.base.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Select/Select.base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;OAEG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/types-native/components/form/Select/Select.metrics.d.ts

@@ -69,4 +69,24 @@ export declare const selectedWashAlpha: (theme: UiTheme) => number;
  * would come to disagree about what an outlined field looks like.
  */
 export { INPUT_BORDER as SELECT_BORDER, INPUT_GLASS as SELECT_GLASS, INPUT_GLOW as SELECT_GLOW, INPUT_GRADIENT as SELECT_GRADIENT, INPUT_PULSE as SELECT_PULSE, } from '../Input/Input.metrics';
+/**
+ * WHEN A `Select` BECOMES A SEARCH BOX, AND HOW TALL ITS LIST MAY GROW.
+ *
+ * Past five options a menu stops being scannable at a glance and starts being
+ * scrolled — and MUI's menu grows to the viewport's height to show them all, so
+ * a staff picker covered the whole screen. From six options on the field turns
+ * into the searchable dropdown (`CreatableSelect`'s engine, MUI `Autocomplete`)
+ * and its list stops at {@link SELECT_SEARCH.listMaxHeight}: about six rows,
+ * the seventh cut in half so the list reads as scrollable.
+ */
+export declare const SEARCHABLE_MIN_OPTIONS = 6;
+export declare const SELECT_SEARCH: {
+    /** px — six 40px rows and half of the seventh. */
+    readonly listMaxHeight: 260;
+    /**
+     * px — what a field that does not fill its row adds to its longest label:
+     * the input's inline padding and the arrow's slot.
+     */
+    readonly fieldChrome: 72;
+};
 //# sourceMappingURL=Select.metrics.d.ts.map

package/dist/types-native/components/form/Select/Select.metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Select.metrics.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Select/Select.metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,GAAI,SAAS,aAAa,KAAG,YACX,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,GAAG,SAAS,KAAG,IAAI,GAAG,IACxC,CAAC;AAE9B;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,eAAe,QAC4C,CAAC;AAEzE,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;IAOtB,8DAA8D;;CAEtD,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,eAAe,wGAAuB,CAAC;AAEpD,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MACuC,CAAC;AAE3F;;;;;GAKG;AACH,OAAO,EACL,YAAY,IAAI,aAAa,EAC7B,WAAW,IAAI,YAAY,EAC3B,UAAU,IAAI,WAAW,EACzB,cAAc,IAAI,eAAe,EACjC,WAAW,IAAI,YAAY,GAC5B,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"Select.metrics.d.ts","sourceRoot":"","sources":["../../../../../src/components/form/Select/Select.metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,GAAI,SAAS,aAAa,KAAG,YACX,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,GAAG,SAAS,KAAG,IAAI,GAAG,IACxC,CAAC;AAE9B;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,eAAe,QAC4C,CAAC;AAEzE,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;IAOtB,8DAA8D;;CAEtD,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,eAAe,wGAAuB,CAAC;AAEpD,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MACuC,CAAC;AAE3F;;;;;GAKG;AACH,OAAO,EACL,YAAY,IAAI,aAAa,EAC7B,WAAW,IAAI,YAAY,EAC3B,UAAU,IAAI,WAAW,EACzB,cAAc,IAAI,eAAe,EACjC,WAAW,IAAI,YAAY,GAC5B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,aAAa;IACxB,kDAAkD;;IAElD;;;OAGG;;CAEK,CAAC"}

package/dist/user-avatar.js

@@ -1,13 +1,13 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-UUJ7J7NE.js";
+} from "./chunk-PP7CDKO4.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-PGPPN63I.js";
-import "./chunk-TNQDSTIA.js";
+import "./chunk-EMEXXAQI.js";
+import "./chunk-Y6C4MYZE.js";
+import "./chunk-MTEQEPNY.js";
 import "./chunk-6ZZGK5DT.js";
 import "./chunk-3ZVUNSFF.js";
-import "./chunk-MTEQEPNY.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
 import "./chunk-OP5JR5Q5.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.46.1",
+  "version": "6.47.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",

package/src/components/form/Select/Select.base.ts

@@ -75,4 +75,19 @@ export interface SelectBaseProps {
   disabled?: boolean;
   testID?: string;
   dataTestId?: string;
+  /**
+   * Draw the field as a search box that filters the options as you type,
+   * with a list of bounded height.
+   *
+   * Left unset, it follows the option count: a list longer than
+   * five options searches (`SEARCHABLE_MIN_OPTIONS`), a shorter one opens
+   * as a plain menu. `multiple` and `renderValue` always keep the menu.
+   */
+  searchable?: boolean;
+  /**
+   * What the searchable list says when nothing matches the typed text. The
+   * host's sentence: this library ships no copy. Unset, the empty list shows
+   * no message.
+   */
+  noOptionsText?: string;
 }

package/src/components/form/Select/Select.md

@@ -50,6 +50,36 @@ function MyComponent() {
 - `glow`: Whether to show glow effect on hover/focus
 - `pulse`: Whether to show pulse animation
 - `fullWidth`: Whether select should take full width of container
+- `searchable`: Force the search box on (`true`) or the menu on (`false`); unset, it follows the option count (see below)
+- `noOptionsText`: The host's sentence the search box shows when nothing matches the typed text
+
+## Six options or more: a search box
+
+Up to **five** options the select opens a menu. From **six** on it becomes the
+searchable dropdown — the same engine as `CreatableSelect` (MUI `Autocomplete`):
+the field is a text box that filters the options as you type, and the list
+stops at `SELECT_SEARCH.listMaxHeight` (about six rows) and scrolls, instead of
+growing to the height of the viewport.
+
+The props stay the same: `options`, `value`/`defaultValue`, `label`,
+`placeholder`, `helperText`, `error`, `name`, `required`, disabled options,
+variants and sizes. `onChange` still receives `{ target: { value, name } }` with
+the option's value in its own type. The test ids keep their spelling.
+
+**What does change — and breaks tests written against the menu:**
+
+- `{dataTestId}-select` (and `role="combobox"`) is now the search `<input>`,
+  not the menu's display `<div>`. The selected label is its VALUE, not its
+  text: assert with `toHaveValue('Garçom')` / `input.value`, not `toHaveText`.
+- `onChange`'s event is a plain `{ target }` object (no `preventDefault`), and
+  its second argument is `null` rather than the clicked `MenuItem`.
+- Opening it with a click or `mouseDown` on the combobox still works; typing
+  filters only while the input has real focus.
+
+- `searchable` overrides the count either way.
+- `multiple` and `renderValue` always keep the menu: a search box holds one value.
+- Pass `noOptionsText` — the library ships no copy, so unset means an empty list
+  says nothing.
 
 ## Visual Variants
 
@@ -138,7 +168,7 @@ The Select component includes `data-testid` attributes for reliable testing:
 | Test ID | Element | Description |
 |---------|---------|-------------|
 | `{dataTestId}` | FormControl | Root FormControl wrapper element |
-| `{dataTestId}-select` | Select element | The MUI Select component |
+| `{dataTestId}-select` | Select element | The MUI Select component (the search `<input>` from six options on) |
 | `{dataTestId}-option-{value}` | Menu items | Individual option elements (one per option) |
 
 **Default Test IDs (when no dataTestId prop provided):**

package/src/components/form/Select/Select.metrics.ts

@@ -88,3 +88,25 @@ export {
   INPUT_GRADIENT as SELECT_GRADIENT,
   INPUT_PULSE as SELECT_PULSE,
 } from '../Input/Input.metrics';
+
+/**
+ * WHEN A `Select` BECOMES A SEARCH BOX, AND HOW TALL ITS LIST MAY GROW.
+ *
+ * Past five options a menu stops being scannable at a glance and starts being
+ * scrolled — and MUI's menu grows to the viewport's height to show them all, so
+ * a staff picker covered the whole screen. From six options on the field turns
+ * into the searchable dropdown (`CreatableSelect`'s engine, MUI `Autocomplete`)
+ * and its list stops at {@link SELECT_SEARCH.listMaxHeight}: about six rows,
+ * the seventh cut in half so the list reads as scrollable.
+ */
+export const SEARCHABLE_MIN_OPTIONS = 6;
+
+export const SELECT_SEARCH = {
+  /** px — six 40px rows and half of the seventh. */
+  listMaxHeight: 260,
+  /**
+   * px — what a field that does not fill its row adds to its longest label:
+   * the input's inline padding and the arrow's slot.
+   */
+  fieldChrome: 72,
+} as const;

package/src/components/form/Select/Select.searchable.tsx

@@ -0,0 +1,203 @@
+import Autocomplete from '@mui/material/Autocomplete/index.js';
+import type { AutocompleteRenderInputParams } from '@mui/material/Autocomplete/index.js';
+import type { SelectChangeEvent } from '@mui/material/Select/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import type { Theme } from '@mui/material/styles/index.js';
+import TextField from '@mui/material/TextField/index.js';
+import React from 'react';
+
+import { SEARCHABLE_MIN_OPTIONS, SELECT_SEARCH } from './Select.metrics';
+import { formControlSize, SelectFieldControl } from './Select.styles';
+import type { SelectOption, SelectProps } from './Select.types';
+
+import { splitTestId } from '../../../platform/test-id';
+import { asFieldSize } from '../../../tokens/field-height';
+import { stackedOverlayZIndex } from '../../../tokens/layers';
+import { rem } from '../../../tokens/relative';
+
+/**
+ * THE SELECT, PAST FIVE OPTIONS: a search box over a list of bounded height.
+ *
+ * Same engine as `CreatableSelect` — MUI `Autocomplete` — so every searchable
+ * dropdown in the library types, filters and scrolls the same way. What it
+ * keeps from `Select` is the whole CONTRACT, so a call site cannot tell which
+ * one it got until it opens it:
+ *
+ * - the field chrome ({@link SelectFieldControl}: variant, size, glow, pulse);
+ * - the floating label, placeholder, helper text and error;
+ * - `onChange(event)` with `event.target.value` — the option's value, a number
+ *   staying a number, exactly what MUI's `Select` hands its handlers;
+ * - disabled options, and the `-select` / `-option-<value>` test ids.
+ *
+ * It cannot be cleared (a `Select` has no "none" either — its placeholder is
+ * disabled), and it never accepts text that is not an option.
+ */
+
+/** Whether `props` should render as a search box. */
+export function shouldSearch(props: SelectProps): boolean {
+  if (props.multiple || props.renderValue) return false;
+  if (props.searchable !== undefined) return props.searchable;
+  return props.options.length >= SEARCHABLE_MIN_OPTIONS;
+}
+
+/**
+ * The change MUI's `Select` would have emitted: handlers read
+ * `event.target.value` (and sometimes `.name`), so that is what they get.
+ */
+function selectChange(value: SelectOption['value'], name: string | undefined): SelectChangeEvent<unknown> {
+  return { target: { value, name: name ?? '' } } as unknown as SelectChangeEvent<unknown>;
+}
+
+function renderOption(
+  props: React.HTMLAttributes<HTMLLIElement>,
+  option: SelectOption,
+  optionTestId: (value: SelectOption['value']) => string,
+): React.JSX.Element {
+  const { key, ...rest } = props as typeof props & { key?: React.Key };
+  return (
+    <li key={key ?? option.value} {...rest} data-testid={optionTestId(option.value)}>
+      {option.label}
+    </li>
+  );
+}
+
+interface FieldProps {
+  params: AutocompleteRenderInputParams;
+  field: Pick<SelectProps, 'label' | 'placeholder' | 'helperText' | 'error' | 'name' | 'required' | 'autoFocus' | 'onBlur' | 'onFocus'>;
+  ariaLabel: string | undefined;
+  disabled: boolean | undefined;
+  triggerTestId: string;
+}
+
+function renderField({ params, field, ariaLabel, disabled, triggerTestId }: FieldProps): React.JSX.Element {
+  return (
+    <TextField
+      {...params}
+      label={field.label}
+      placeholder={field.placeholder}
+      helperText={field.helperText}
+      error={field.error}
+      name={field.name}
+      required={field.required}
+      autoFocus={field.autoFocus}
+      onBlur={field.onBlur as React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> | undefined}
+      onFocus={field.onFocus as React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> | undefined}
+      // The menu drew its placeholder under a shrunk label (`displayEmpty`);
+      // a floating label left down would hide it until focus.
+      slotProps={field.placeholder ? { inputLabel: { shrink: true } } : undefined}
+      inputProps={{
+        ...params.inputProps,
+        'aria-label': ariaLabel,
+        // The menu's display div carried `aria-disabled`; the input keeps it.
+        'aria-disabled': disabled ? true : undefined,
+        'data-testid': triggerTestId,
+      }}
+    />
+  );
+}
+
+/**
+ * The option the field shows, KEPT STABLE while it is the same one.
+ *
+ * Consumers build `options` inline (`xs.map(...)`), so a fresh `find` returns a
+ * new object on every parent render, which MUI reads as a changed value and
+ * answers by resetting the typed text — a refetch mid-search wiped the query.
+ * Uncontrolled use (`defaultValue`, no `value`) keeps its own state, as MUI's
+ * Select did.
+ */
+function useSelectedOption(
+  options: SelectOption[],
+  value: unknown,
+  defaultValue: unknown,
+): [SelectOption | null, (next: SelectOption) => void] {
+  const [own, setOwn] = React.useState<unknown>(defaultValue ?? '');
+  const current = value === undefined ? own : value;
+  const match = options.find((option) => String(option.value) === String(current ?? '')) ?? null;
+  const key = match === null ? null : `${String(match.value)}\u0000${match.label}\u0000${match.disabled === true}`;
+  // Keyed on the option's identity, not the object `find` just returned.
+  const stable = React.useMemo(() => match, [key]);
+  return [stable, (next) => setOwn(next.value)];
+}
+
+/**
+ * A field that does not fill its row sizes to its longest option, the way the
+ * menu sized to its selected text: MUI's Autocomplete input is `width: 0`, so
+ * without this a `fullWidth={false}` select collapsed to its arrow.
+ */
+function intrinsicWidth(
+  theme: Theme,
+  options: SelectOption[],
+  fullWidth: boolean,
+): React.CSSProperties | undefined {
+  if (fullWidth) return undefined;
+  const longest = options.reduce((max, option) => Math.max(max, option.label.length), 0);
+  // The label in `ch`, plus the field's inline padding and the arrow's slot.
+  return { minWidth: `calc(${longest}ch + ${rem(theme, SELECT_SEARCH.fieldChrome)})` };
+}
+
+export const SearchableSelect = React.forwardRef<HTMLDivElement, SelectProps>((props, ref) => {
+  const { variant, options, fullWidth = true, size, error, glow, pulse, value, defaultValue } = props;
+  const { onChange, disabled, name, noOptionsText, sx, className, style, id } = props;
+  const { testId: dataTestId } = splitTestId(props as unknown as Record<string, unknown>);
+  const [selected, setOwn] = useSelectedOption(options, value, defaultValue);
+  const theme = useTheme();
+  const optionTestId = (optionValue: SelectOption['value']): string =>
+    dataTestId ? `${dataTestId}-option-${optionValue}` : `option-${optionValue}`;
+
+  return (
+    <SelectFieldControl
+      fullWidth={fullWidth}
+      size={formControlSize(size)}
+      error={error}
+      customVariant={variant}
+      fieldSize={asFieldSize(size)}
+      glow={glow}
+      pulse={pulse}
+      ref={ref}
+      sx={sx}
+      className={className}
+      style={{ ...intrinsicWidth(theme, options, fullWidth), ...style }}
+      data-testid={dataTestId}
+    >
+      <Autocomplete<SelectOption, false, true, false>
+        id={id}
+        value={selected as SelectOption}
+        options={options}
+        disabled={disabled}
+        disableClearable
+        autoHighlight
+        handleHomeEndKeys
+        size={formControlSize(size)}
+        noOptionsText={noOptionsText ?? null}
+        getOptionLabel={(option) => option.label}
+        // Two people may share a name; the value is what tells them apart.
+        getOptionKey={(option) => String(option.value)}
+        getOptionDisabled={(option) => option.disabled === true}
+        isOptionEqualToValue={(option, current) => String(option.value) === String(current.value)}
+        onChange={(_event, next) => {
+          setOwn(next);
+          onChange?.(selectChange(next.value, name), null);
+        }}
+        renderOption={(optionProps, option) => renderOption(optionProps, option, optionTestId)}
+        slotProps={{
+          // Above stacked sheets and dialogs, as `CreatableSelect` does.
+          popper: { sx: { zIndex: stackedOverlayZIndex } },
+          // THE bounded height: MUI's own default is 40vh, which on a tall
+          // screen is the whole page again.
+          listbox: { sx: (theme) => ({ maxHeight: rem(theme, SELECT_SEARCH.listMaxHeight) }) },
+        }}
+        renderInput={(params) =>
+          renderField({
+            params,
+            field: props,
+            ariaLabel: props['aria-label'],
+            disabled,
+            triggerTestId: dataTestId ? `${dataTestId}-select` : 'select',
+          })
+        }
+      />
+    </SelectFieldControl>
+  );
+});
+
+SearchableSelect.displayName = 'SearchableSelect';

package/src/components/form/Select/Select.styles.tsx

@@ -0,0 +1,195 @@
+import FormControl, { type FormControlProps } from '@mui/material/FormControl/index.js';
+import { alpha, type CSSObject, keyframes, styled, type Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import {
+  SELECT_BORDER,
+  SELECT_GLASS,
+  SELECT_GLOW,
+  SELECT_GRADIENT,
+  SELECT_PULSE,
+  selectInputSize,
+} from './Select.metrics';
+import type { SelectProps } from './Select.types';
+
+import { fieldEdge } from '../../../tokens/field-edge';
+import { FIELD_BORDER_WIDTH, fieldControlStyles, fieldHeight } from '../../../tokens/field-height';
+import type { SizeValue } from '../../../tokens/vocabulary';
+import { fieldRadius } from '../../../tokens/field-radius';
+import { absoluteInk } from '../../../tokens/ink';
+import { rem } from '../../../tokens/relative';
+
+/**
+ * THE FIELD CHROME BOTH WEB SELECTS WEAR — the menu `Select` and the searchable
+ * one it becomes past {@link SEARCHABLE_MIN_OPTIONS} options. Shared so the two
+ * cannot drift: a form whose short select and long select were drawn by two
+ * copies of these rules would show it the first time one of them changed.
+ */
+
+// Define pulse animation
+const pulseAnimation = (theme: Theme) => keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 ${rem(theme, SELECT_PULSE.spread)} currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+/** Glow ring on the outlined input, keyed off the `glow` prop. */
+const glowStyles = (theme: Theme): CSSObject => ({
+  '& .MuiOutlinedInput-root': {
+    boxShadow: `0 0 ${rem(theme, SELECT_GLOW.rest.blur)} ${alpha(theme.palette.primary.main, SELECT_GLOW.rest.alpha)}`,
+    '&.Mui-focused': {
+      boxShadow: `0 0 ${rem(theme, SELECT_GLOW.focused.blur)} ${alpha(theme.palette.primary.main, SELECT_GLOW.focused.alpha)}`,
+    },
+  },
+});
+
+/** Pulsing halo behind the control, keyed off the `pulse` prop. */
+const pulseStyles = (theme: Theme, size: SizeValue): CSSObject => ({
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    top: '50%',
+    left: '0',
+    right: '0',
+    height: fieldHeight(theme, size),
+    transform: 'translateY(-50%)',
+    borderRadius: fieldRadius(theme),
+    backgroundColor: theme.palette.primary.main,
+    opacity: SELECT_PULSE.opacity,
+    animation: `${pulseAnimation(theme)} ${SELECT_PULSE.ms / 1000}s infinite`,
+    pointerEvents: 'none',
+    zIndex: -1,
+  },
+});
+
+/** `glass` variant: translucent, blurred background. */
+const glassVariant = (theme: Theme): CSSObject => ({
+  backgroundColor: alpha(theme.palette.background.paper, SELECT_GLASS.background.rest),
+  backdropFilter: `blur(${rem(theme, SELECT_GLASS.blur)})`,
+  // `SELECT_BORDER.rest` is the field hairline.
+  border: `${FIELD_BORDER_WIDTH}px solid ${fieldEdge(theme)}`,
+  '& fieldset': { border: 'none' },
+  '&:hover': {
+    backgroundColor: alpha(theme.palette.background.paper, SELECT_GLASS.background.hover),
+    borderColor: alpha(theme.palette.primary.main, SELECT_GLASS.hoverBorderAlpha),
+  },
+  '&.Mui-focused': {
+    backgroundColor: alpha(theme.palette.background.paper, SELECT_GLASS.background.focused),
+    borderColor: theme.palette.primary.main,
+    boxShadow: `0 0 0 ${rem(theme, SELECT_GLASS.focusRing.width)} ${alpha(theme.palette.primary.main, SELECT_GLASS.focusRing.alpha)}`,
+  },
+});
+
+/** `gradient` variant: gradient fill with a masked gradient border. */
+const gradientFill = (theme: Theme, strength: number): string =>
+  `linear-gradient(${SELECT_GRADIENT.angleDeg}deg, ${alpha(theme.palette.primary.main, strength)}, ${alpha(theme.palette.secondary.main, strength)})`;
+
+const gradientVariant = (theme: Theme): CSSObject => ({
+  background: gradientFill(theme, SELECT_GRADIENT.fill.rest),
+  border: `${rem(theme, SELECT_GRADIENT.borderWidth)} solid transparent`,
+  backgroundOrigin: 'border-box',
+  backgroundClip: 'padding-box, border-box',
+  position: 'relative',
+  '& fieldset': { border: 'none' },
+  '&::before': {
+    content: '""',
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 'inherit',
+    background: `linear-gradient(${SELECT_GRADIENT.angleDeg}deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`,
+    mask: `linear-gradient(${absoluteInk(theme).white} 0 0) content-box, linear-gradient(${absoluteInk(theme).white} 0 0)`,
+    maskComposite: 'exclude',
+    padding: rem(theme, SELECT_GRADIENT.borderWidth),
+    zIndex: -1,
+  },
+  '&:hover': {
+    background: gradientFill(theme, SELECT_GRADIENT.fill.hover),
+  },
+  '&.Mui-focused': {
+    background: gradientFill(theme, SELECT_GRADIENT.fill.focused),
+    '&::before': {
+      background: `linear-gradient(${SELECT_GRADIENT.angleDeg}deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`,
+    },
+  },
+});
+
+/** `default` variant: standard outlined borders with hover/focus/error states. */
+const defaultVariant = (theme: Theme): CSSObject => ({
+  '& fieldset': { borderColor: fieldEdge(theme) },
+  '&:hover fieldset': { borderColor: theme.palette.primary.main },
+  '&.Mui-focused fieldset': { borderColor: theme.palette.primary.main, borderWidth: rem(theme, SELECT_BORDER.focused) },
+  '&.Mui-error fieldset': { borderColor: theme.palette.error.main },
+});
+
+/** Pick the variant style block for the outlined input. */
+const variantStyles = (theme: Theme, variant: SelectProps['variant']): CSSObject => {
+  if (variant === 'glass') return glassVariant(theme);
+  if (variant === 'gradient') return gradientVariant(theme);
+  return defaultVariant(theme);
+};
+
+const StyledFormControl = styled(FormControl, {
+  shouldForwardProp: (prop) =>
+    prop !== 'customVariant' && prop !== 'fieldSize' && prop !== 'glow' && prop !== 'pulse',
+})<{
+  customVariant?: SelectProps['variant'];
+  fieldSize: SizeValue;
+  glow?: boolean;
+  pulse?: boolean;
+}>(({ theme, customVariant, fieldSize, glow, pulse }) => ({
+  position: 'relative',
+  // The theme's field height for this size — the height `Input` draws for it.
+  ...fieldControlStyles(theme, fieldSize),
+  ...(glow ? glowStyles(theme) : {}),
+  ...(pulse ? pulseStyles(theme, fieldSize) : {}),
+  '& .MuiOutlinedInput-root': {
+    transition: 'all 0.3s ease',
+    borderRadius: fieldRadius(theme),
+    ...variantStyles(theme, customVariant),
+  },
+}));
+
+/** What {@link SelectFieldControl} takes: a FormControl, plus the four look switches. */
+export interface SelectFieldControlProps extends FormControlProps {
+  customVariant?: SelectProps['variant'];
+  fieldSize: SizeValue;
+  glow?: boolean;
+  pulse?: boolean;
+  'data-testid'?: string;
+}
+
+/**
+ * The styled FormControl, behind a component with a NAMED type: a `styled()`
+ * export's inferred type reaches into `@mui/system`'s pnpm path, which the
+ * declaration build refuses to write (TS2742).
+ */
+export const SelectFieldControl = React.forwardRef<HTMLDivElement, SelectFieldControlProps>(
+  (props, ref) => <StyledFormControl ref={ref} {...props} />,
+);
+
+SelectFieldControl.displayName = 'SelectFieldControl';
+
+/**
+ * The house scale as a FormControl size.
+ *
+ * Not `muiSize`: that collapses five onto MUI's three, and a FormControl takes
+ * only two. This component's scale is already narrowed to `sm | md`, so the map
+ * is exact rather than lossy.
+ */
+export const formControlSize = (size: SelectProps['size']): 'small' | 'medium' | undefined => {
+  if (size === undefined) return undefined;
+  return selectInputSize(size) === 'sm' ? 'small' : 'medium';
+};
+