@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/input-password.md

@@ -0,0 +1,197 @@
+# InputPassword
+
+> A single-line password field: an optional label (with an optional required marker), the value box with a built-in show/hide toggle, and an optional description or error message. Its own `--ui-input-password-*` token tier covers the box down to fill/border (unlike `InputText`, it doesn't build on the bare `Input` primitive).
+
+**Status:** ready · **Category:** forms · **Since:** v0.58.0
+
+## Import
+
+```tsx
+import { InputPassword } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputPassword label="Password" description="At least 8 characters" />
+
+{/* Error */}
+<InputPassword
+  label="Password"
+  value={value}
+  error="Too short"
+  onChange={onChange}
+/>
+```
+
+A single-line password field: a label, a themed value box with a built-in
+show/hide toggle, and an optional description or error message. Unlike
+[`InputText`](../input-text/README.md), the box isn't the bare `Input`
+primitive — it has its own `--ui-input-password-*` token tier, and the toggle
+is a [`ButtonIconInput`](../button-icon-input/README.md).
+
+## When to use
+
+- Any password / secret entry field that should let the user reveal what
+  they've typed.
+
+## When not to use
+
+- A general single-line text field — use `InputText`.
+- A one-time verification code — use `InputOTP`.
+
+## Examples
+
+```tsx
+import { InputPassword } from '@acronis-platform/ui-react';
+
+// Basic field with helper text
+<InputPassword label="Password" description="At least 8 characters" />;
+
+// Required
+<InputPassword label="Password" required />;
+
+// Error
+<InputPassword
+  label="Password"
+  value={value}
+  error="Enter at least 8 characters"
+  onChange={onChange}
+/>;
+
+// Localized toggle labels
+<InputPassword
+  label="Contraseña"
+  showPasswordLabel="Mostrar contraseña"
+  hidePasswordLabel="Ocultar contraseña"
+/>;
+```
+
+## Parts
+
+| Part          | Element    | Description                                                      |
+| ------------- | ---------- | ---------------------------------------------------------------- |
+| `label`       | `<label>`  | Field label (associated via `htmlFor`/`id`).                     |
+| `required`    | `<span>`   | Required `*` marker.                                             |
+| `box`         | `<div>`    | The themed container (border, fill) around the input + toggle.   |
+| `input`       | `<input>`  | The borderless value input; toggles `type="password" \| "text"`. |
+| `toggle`      | `<button>` | Show/hide button (`ButtonIconInput`).                            |
+| `description` | `<p>`      | Helper text (normal state).                                      |
+| `error`       | `<p>`      | Error message; replaces the description when `error`.            |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `label` | `ReactNode` | — | no | Field label rendered above the box, associated via `htmlFor`/`id`. |
+| `required` | `boolean` | `false` | no | Appends a required marker (`*`) after the label and sets `aria-required` on the input. |
+| `description` | `ReactNode` | — | no | Helper text below the box. Hidden while `error` is set. |
+| `error` | `ReactNode` | — | no | Error message below the box. Its presence switches the field to the error treatment (red box border + red message + error-toned toggle). |
+| `disabled` | `boolean` | `false` | no | Disables the field and the toggle button (native `<input disabled>`). |
+| `showPasswordLabel` | `string` | `'Show password'` | no | Accessible name for the toggle button while the password is hidden. |
+| `hidePasswordLabel` | `string` | `'Hide password'` | no | Accessible name for the toggle button while the password is shown. |
+| `value` | `string` | — | no | Controlled value. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `ChangeEvent<HTMLInputElement>` | Native input change — forwarded to the underlying `<input>`. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The label content. |
+| `description` | The helper text. |
+| `error` | The error message. |
+
+## Behavior
+
+### Rendering
+
+**Given** a `label`
+**When** the field renders
+**Then** the label appears above the box and is associated with the input via
+`htmlFor`/`id` (clicking the label focuses the input).
+
+**Given** `required`
+**When** the field renders
+**Then** a `*` marker is appended after the label and the input gets
+`aria-required="true"`.
+
+**Given** a `description`
+**When** no `error` is set
+**Then** the helper text shows below the box, associated via
+`aria-describedby`.
+
+### Show / hide toggle
+
+**Given** the field
+**When** it first renders
+**Then** the value is masked (`type="password"`) and the toggle shows the
+crossed-eye icon with accessible name `showPasswordLabel` ("Show password").
+
+**Given** the toggle button
+**When** it is activated
+**Then** the input's `type` flips to `"text"`, the icon becomes the plain eye,
+and the accessible name becomes `hidePasswordLabel` ("Hide password").
+Activating it again reverts both.
+
+### Error
+
+**Given** `error` is set
+**When** the field renders
+**Then** the box shows the error border, the toggle switches to its error
+tone, the error message replaces the description below the box, and the
+message is associated via `aria-describedby`. The input also gets
+`aria-invalid="true"`.
+
+### Interaction
+
+**Given** the box
+**When** the pointer hovers / the input receives keyboard focus
+**Then** the box border shifts to its hover token and keyboard focus paints a
+3px ring — `--ui-focus-primary` normally, `--ui-focus-error` in the error
+state.
+
+**Given** any typing
+**When** the value changes
+**Then** the native `change` event is forwarded to the consumer.
+
+### Disabled
+
+**Given** `disabled`
+**When** the field renders
+**Then** the input and the toggle button are both disabled (native
+`disabled`), and the box/label/description use their disabled tokens.
+
+## Accessibility
+
+- **Label association:** the `label` is a real `<label htmlFor>` tied to the
+  input's `id` (auto-generated when not supplied), so clicking it focuses the
+  input and screen readers announce the field name.
+- **Required:** `required` sets `aria-required="true"` on the input; the visual
+  `*` marker is decorative (no `aria-hidden` needed beyond styling — the
+  required semantics come from the attribute).
+- **Description / error:** whichever message is shown is linked to the input
+  via `aria-describedby`, so it is announced with the field. The error message
+  also drives `aria-invalid="true"` on the input.
+- **Toggle button:** a native `<button>` (`ButtonIconInput`) with an explicit
+  `aria-label` that tracks its state ("Show password" / "Hide password",
+  overridable via `showPasswordLabel`/`hidePasswordLabel`) and `aria-pressed`
+  reflecting whether the value is currently shown. Reachable by Tab and
+  activated by Enter / Space.
+- **Keyboard:** the input is a native text field (`type` toggles between
+  `password`/`text`); the toggle button is a separate tab stop after it.
+- **Focus visible:** keyboard focus on the input paints a 3px ring on the box —
+  `--ui-focus-primary` normally and `--ui-focus-error` in the error state; the
+  toggle button has its own focus ring (see `ButtonIconInput`).
+- **Disabled:** native `disabled` removes both the input and the toggle button
+  from the tab order; not used to convey state by color alone (the field is
+  also inert).
+- **Contrast:** label / value / placeholder / message / border pairs come from
+  the design tokens, authored to meet WCAG contrast.
+- **WCAG:** 1.3.1 (info/relationships), 2.1.1 (keyboard), 2.4.7 (focus
+  visible), 1.4.3 / 1.4.11 (contrast), 3.3.1 / 3.3.2 (error identification +
+  labels), 4.1.2.

package/dist/llms/input-search.md

@@ -0,0 +1,170 @@
+# InputSearch
+
+> A full search field: an optional label (with an optional required marker) above the search box. Builds on the bare `Search` box (leading magnifier, input, and clear button) and the `--ui-input-search-*` token tier.
+
+**Status:** ready · **Category:** forms · **Since:** v0.29.0
+
+## Import
+
+```tsx
+import { InputSearch } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputSearch label="Find" placeholder="Search table" />
+
+{/* Required */}
+<InputSearch label="Find" required />
+
+{/* Controlled with clear */}
+<InputSearch
+  label="Find"
+  value={query}
+  onChange={(e) => setQuery(e.target.value)}
+  onClear={() => setQuery('')}
+/>
+```
+
+A full search field: a label (with an optional required marker) above the search
+box. It composes the bare [`Search`](../search/README.md) box — a leading
+magnifier, the input, and a clear (×) button — and adds the surrounding field
+furniture.
+
+## When to use
+
+- A labelled search / filter field in a form or panel, where the field needs a
+  visible label above the box.
+
+## When not to use
+
+- For a bare search box with no label (e.g. in a toolbar or table header) — use
+  the [`Search`](../search/README.md) box directly.
+- For a plain labelled text field with no leading magnifier — use `InputText`.
+
+## Examples
+
+```tsx
+import { InputSearch } from '@acronis-platform/ui-react';
+
+// Basic labelled search field
+<InputSearch label="Find" placeholder="Search table" />;
+
+// Required
+<InputSearch label="Find" required />;
+
+// Controlled with clear
+<InputSearch
+  label="Find"
+  value={query}
+  onChange={(e) => setQuery(e.target.value)}
+  onClear={() => setQuery('')}
+/>;
+```
+
+## Parts
+
+| Part       | Element    | Description                                                 |
+| ---------- | ---------- | ----------------------------------------------------------- |
+| `label`    | `<label>`  | Field label (associated via `htmlFor`/`id`).                |
+| `required` | `<span>`   | Required `*` marker (decorative; `aria-hidden`).            |
+| `icon`     | `<svg>`    | Leading magnifier inside the box (from `Search`).           |
+| `input`    | `<input>`  | The search box input (`role="searchbox"`, from `Search`).   |
+| `clear`    | `<button>` | Optional clear (×) button; calls `onClear` (from `Search`). |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `label` | `ReactNode` | — | no | Field label rendered above the box, associated via `htmlFor`/`id`. |
+| `required` | `boolean` | `false` | no | Appends a required marker (`*`) after the label and sets `aria-required` on the input. |
+| `placeholder` | `string` | — | no | Hint text shown when empty (e.g. "Search table"). |
+| `value` | `string` | — | no | Controlled value. Pair with the change event. |
+| `default-value` | `string` | — | no | Initial value when uncontrolled. |
+| `disabled` | `boolean` | `false` | no | Disables the field; hides the clear button and applies the disabled tokens. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change` | `ChangeEvent<HTMLInputElement>` | Native input change — forwarded to the underlying `<input>`. Also fires when the value is cleared. |
+| `clear` | `void` | Fired after the clear (×) button empties the field (React: `onClear`). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The label content. |
+
+## Behavior
+
+### Rendering
+
+**Given** a `label`
+**When** the field renders
+**Then** the label appears above the box and is associated with the input via
+`htmlFor`/`id` (clicking the label focuses the input), and `Search`'s built-in
+`aria-label` is cleared so it doesn't shadow the visible label.
+
+**Given** no `label`
+**When** the field renders
+**Then** the field falls back to the composed `Search`'s accessible name
+(a caller-supplied `aria-label`, otherwise the default "Search").
+
+**Given** `required`
+**When** the field renders
+**Then** a `*` marker is appended after the label and the input gets
+`aria-required="true"`.
+
+### Clear
+
+**Given** a non-empty `value` (controlled or uncontrolled)
+**When** the field is not disabled
+**Then** the clear (×) button appears inside the box.
+
+**Given** the clear button
+**When** it is activated (click, Enter, or Space)
+**Then** the field empties, the input refocuses, and `onClear` fires alongside a
+native change event with an empty value.
+
+**Given** the field is `disabled`
+**Then** the clear button is not shown.
+
+### Interaction
+
+**Given** the box
+**When** the pointer hovers / the input receives keyboard focus
+**Then** the box border shifts to its hover token and keyboard focus paints a 3px
+`--ui-focus-primary` ring (via `:focus-within`).
+
+**Given** any typing
+**When** the value changes
+**Then** the native `change` event is forwarded to the consumer.
+
+## Accessibility
+
+- **Label association:** the `label` is a real `<label htmlFor>` tied to the
+  input's `id` (auto-generated when not supplied), so clicking it focuses the
+  input and screen readers announce the field name. When a visible label is
+  present, the composed `Search`'s default `aria-label` is cleared so the
+  accessible name matches the visible label (WCAG 2.5.3, label in name).
+- **Unlabelled fallback:** with no `label`, the field keeps `Search`'s accessible
+  name — a caller-supplied `aria-label`, or the default "Search".
+- **Required:** `required` sets `aria-required="true"` on the input; the visual `*`
+  marker is `aria-hidden` (decorative — the required semantics come from the
+  attribute).
+- **Search semantics:** the input is a native `<input type="search">`
+  (`role="searchbox"`).
+- **Clear button:** a native `<button>` with `aria-label="Clear search"`; reachable
+  by Tab and activated by Enter / Space, after which focus returns to the input.
+- **Keyboard:** the input is a native search field; the clear button is a separate
+  tab stop after it.
+- **Focus visible:** keyboard focus paints a 3px `--ui-focus-primary` ring flush to
+  the box (via `:focus-within`).
+- **Disabled:** native `disabled` removes the input (and clear button) from the tab
+  order; the field is also inert, so state is not conveyed by color alone.
+- **Contrast:** label / value / placeholder / icon / border pairs come from the
+  design tokens, authored to meet WCAG contrast.
+- **WCAG:** 1.3.1 (info/relationships), 2.1.1 (keyboard), 2.4.7 (focus visible),
+  2.5.3 (label in name), 1.4.3 / 1.4.11 (contrast), 3.3.2 (labels), 4.1.2.

package/dist/llms/input-select.md

@@ -0,0 +1,278 @@
+# InputSelect
+
+> The next-gen select field: an optional label (with a required marker), a trigger box showing the value / placeholder and a chevron, an optional description or error message, and a floating dropdown with an in-dropdown search, sections (groups), single or multiple selectable items, and loading / empty / error status. Composes Base UI `Select` and the `--ui-input-select-*` token tier.
+
+**Status:** ready · **Category:** forms · **Since:** v0.29.0
+
+## Import
+
+```tsx
+import { InputSelect, InputSelectField, InputSelectLabel, InputSelectTrigger, InputSelectValue, InputSelectContent, InputSelectSearch, InputSelectSection, InputSelectSectionLabel, InputSelectItem, InputSelectExpander, InputSelectDescription, InputSelectError, InputSelectStatus, useInputSelectFilter } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<InputSelect items={{ apple: 'Apple', banana: 'Banana' }} value={fruit} onValueChange={setFruit}>
+  <InputSelectField>
+    <InputSelectLabel required>Fruit</InputSelectLabel>
+    <InputSelectTrigger aria-invalid={Boolean(error)}>
+      <InputSelectValue placeholder="Select an option" />
+    </InputSelectTrigger>
+    {error ? (
+      <InputSelectError>{error}</InputSelectError>
+    ) : (
+      <InputSelectDescription>Pick your favourite</InputSelectDescription>
+    )}
+  </InputSelectField>
+  <InputSelectContent>
+    <InputSelectSearch placeholder="Search" value={q} onChange={(e) => setQ(e.target.value)} />
+    <InputSelectSection>
+      <InputSelectSectionLabel>Fruits</InputSelectSectionLabel>
+      <InputSelectItem value="apple">Apple</InputSelectItem>
+      <InputSelectItem value="banana">Banana</InputSelectItem>
+    </InputSelectSection>
+  </InputSelectContent>
+</InputSelect>
+
+{/* Status (instead of items) */}
+<InputSelectContent>
+  <InputSelectStatus variant="empty">No data found</InputSelectStatus>
+</InputSelectContent>
+```
+
+The next-gen select **field**: a label (with an optional required marker), a trigger
+box showing the value / placeholder and a chevron, an optional description or error,
+and a floating dropdown with an in-dropdown search, sections, single- or
+multiple-selectable items, and loading / empty / error status. It composes Base UI
+`Select` and the `--ui-input-select-*` token tier.
+
+> `Select` is an alias of this family (re-pointed off the deleted `--ui-form-*` tier).
+> Prefer importing `InputSelect*` directly in new code.
+
+## When to use
+
+- Choosing one (or several, with `multiple`) options from a list, with full field
+  furniture (label / description / error) and optional in-dropdown search / grouping /
+  status.
+
+## When not to use
+
+- For a free-text field — use `InputText`; for a search box — use `Search` /
+  `InputSearch`.
+- For a small fixed set shown inline — consider `Radio` (single) or `Checkbox` group.
+- The nested **tenant-tree** picker (Recent/Browse, collapsible tenant items) is a
+  separate follow-up component.
+
+## Examples
+
+```tsx
+import {
+  InputSelect,
+  InputSelectField,
+  InputSelectLabel,
+  InputSelectTrigger,
+  InputSelectValue,
+  InputSelectContent,
+  InputSelectSearch,
+  InputSelectSection,
+  InputSelectSectionLabel,
+  InputSelectItem,
+  InputSelectDescription,
+  InputSelectError,
+  InputSelectStatus,
+} from '@acronis-platform/ui-react';
+
+<InputSelect
+  items={{ apple: 'Apple', banana: 'Banana' }}
+  value={fruit}
+  onValueChange={setFruit}
+>
+  <InputSelectField>
+    <InputSelectLabel required>Fruit</InputSelectLabel>
+    <InputSelectTrigger>
+      <InputSelectValue placeholder="Select an option" />
+    </InputSelectTrigger>
+    <InputSelectDescription>Pick your favourite</InputSelectDescription>
+  </InputSelectField>
+  <InputSelectContent>
+    <InputSelectSection>
+      <InputSelectSectionLabel>Fruits</InputSelectSectionLabel>
+      <InputSelectItem value="apple">Apple</InputSelectItem>
+      <InputSelectItem value="banana">Banana</InputSelectItem>
+    </InputSelectSection>
+  </InputSelectContent>
+</InputSelect>;
+
+// Multiple selection
+<InputSelect multiple value={tags} onValueChange={setTags}>
+  …
+</InputSelect>;
+
+// Empty status instead of items
+<InputSelectContent>
+  <InputSelectStatus variant="empty">No data found</InputSelectStatus>
+</InputSelectContent>;
+```
+
+## Parts
+
+| Part                      | Element    | Description                                                       |
+| ------------------------- | ---------- | ----------------------------------------------------------------- |
+| `InputSelectField`        | `<div>`    | Vertical field stack (label / trigger / description-error).       |
+| `InputSelectLabel`        | `<label>`  | Field label (auto-associated); `required` adds `*`.               |
+| `InputSelectTrigger`      | `<button>` | The combobox box; `aria-invalid` switches to the error look.      |
+| `InputSelectValue`        | `<span>`   | Selected label or placeholder.                                    |
+| `InputSelectContent`      | `<div>`    | The floating listbox popup.                                       |
+| `InputSelectSearch`       | `<div>`    | In-dropdown search row; drives live filtering of the items.       |
+| `InputSelectSection`      | `<div>`    | A labelled group of items.                                        |
+| `InputSelectSectionLabel` | `<div>`    | The group heading.                                                |
+| `InputSelectItem`         | `<div>`    | An option; trailing check (single) / leading checkbox (multiple). |
+| `InputSelectExpander`     | `<button>` | Non-selectable expand/collapse toggle for a tree group.           |
+| `InputSelectDescription`  | `<p>`      | Helper text (normal state).                                       |
+| `InputSelectError`        | `<p>`      | Error message; replaces the description.                          |
+| `InputSelectStatus`       | `<div>`    | Loading / empty / error row shown instead of items.               |
+
+`useInputSelectFilter()` reads the search query set by `InputSelectSearch`;
+use it inside a custom tree/item renderer to filter items the flat
+`InputSelectItem` auto-filter doesn't cover.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `string | string[]` | — | no | Controlled selected value(s). Pair with the change event. |
+| `default-value` | `string | string[]` | — | no | Initial selection when uncontrolled. |
+| `open` | `boolean` | — | no | Controlled open state of the options popup. |
+| `default-open` | `boolean` | `false` | no | Whether the popup is initially open when uncontrolled. |
+| `disabled` | `boolean` | `false` | no | Disables the control; applies the disabled tokens and blocks opening. |
+| `multiple` | `boolean` | `false` | no | Whether more than one option can be selected. Items show a leading checkbox and the popup stays open on select. |
+| `required` | `boolean` | `false` | no | Marks the control required; the label shows a `*` marker. |
+| `name` | `string` | — | no | Form field name submitted with the form (via a hidden input). |
+| `placeholder` | `string` | — | no | Hint shown by the value part when nothing is selected. |
+| `items` | `Record<string, string>` | — | no | Map of value → label for every selectable option, so the value part can render a selected option's label while the popup is closed without inspecting the rendered items. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `value-change` | `string | string[]` | Fired when the selection changes (React: `onValueChange`). |
+| `open-change` | `boolean` | Fired when the popup opens or closes (React: `onOpenChange`). |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed field: a field wrapper holding the label, the trigger (with the value), and the description / error; then the content holding the optional search, sections, items, or a status row. Provide an `items` map on the root so the value part can render a selected option's label while the popup is closed. |
+
+## Behavior
+
+### Rendering
+
+**Given** a label
+**When** the field renders
+**Then** the label appears above the trigger and is auto-associated with it (Base UI
+`Select.Label`), so clicking the label focuses the trigger and screen readers announce
+the field name.
+
+**Given** `required`
+**When** the field renders
+**Then** a `*` marker is appended after the label.
+
+**Given** a description and no error
+**Then** the helper text shows below the trigger; **given** the trigger is
+`aria-invalid` with an error message, the error replaces the description and the
+trigger takes the error border.
+
+### Opening / selecting (single)
+
+**Given** the trigger
+**When** it is pressed (or Space / Enter / ArrowDown with focus)
+**Then** the popup opens (`data-popup-open`, chevron rotates 180°) and emits
+`open-change(true)`.
+
+**Given** an open popup
+**When** an item is clicked or activated with Enter
+**Then** the value updates (emits `value-change`), the selected row tints and shows a
+trailing check, the trigger shows the resolved label, and the popup closes.
+
+### Multiple selection
+
+**Given** `multiple`
+**When** the popup is open and items are toggled
+**Then** each item shows a leading checkbox reflecting its selected state, the row
+background stays the unselected color, and the popup **stays open** so several items
+can be picked.
+
+### Search / sections / status
+
+**Given** an in-dropdown search row (uncontrolled)
+**When** the user types into it
+**Then** it drives an internal filter query, and each flat `InputSelectItem`
+whose label doesn't match hides itself; tree dropdowns read the query via
+`useInputSelectFilter` and filter their own items. Passing `value`/`onChange`
+controls the query externally instead. Printable keys are kept from Base UI's
+own typeahead while it's focused; Arrow/Home/End/Enter/Escape still bubble so
+the user can move from the search box into the filtered list.
+
+**Given** an `InputSelectExpander` row inside a tree dropdown
+**When** the user clicks it
+**Then** it toggles `aria-expanded` and calls `onToggle` — it is not a
+selectable `SelectPrimitive.Item` and never sets the select value.
+
+**Given** a section with a label
+**Then** its items render under a heading, divided from the previous section by a top
+border.
+
+**Given** a status row (`loading` / `empty` / `error`)
+**When** rendered instead of items
+**Then** it shows the matching icon and message (and, for `error`, an optional retry
+action).
+
+### Interaction
+
+**Given** the trigger
+**When** the pointer hovers / it receives keyboard focus
+**Then** the box border shifts to its hover token and keyboard focus paints a 3px ring —
+`--ui-focus-primary` normally, `--ui-focus-error` while `aria-invalid`.
+
+**Given** the field is `disabled`
+**Then** the trigger is inert (does not open) and uses the disabled token set.
+
+## Accessibility
+
+- **Roles:** the trigger is a `role="combobox"` button; the popup is a
+  `role="listbox"`; each item is a `role="option"` (provided by Base UI `Select`).
+- **Label association:** `InputSelectLabel` (Base UI `Select.Label`) is automatically
+  associated with the trigger via the select context — clicking the label focuses the
+  trigger and screen readers announce the field name. No manual `htmlFor`/`id` needed.
+- **Required:** `required` appends a visual `*` marker (`aria-hidden`); set the root
+  `required` so the form-level constraint is conveyed via the hidden input.
+- **Error:** set `aria-invalid` on the trigger; pair with `InputSelectError`. Associate
+  the message via `aria-describedby` on the trigger when wiring a controlled error.
+- **Keyboard:** Space / Enter / ArrowDown open the popup; arrows move the highlight;
+  Enter selects; Escape closes and returns focus to the trigger; type-ahead matches
+  items. In `multiple` mode the popup stays open so several items can be toggled.
+- **Search box keyboard:** when the in-dropdown search row has focus, printable
+  keys are stopped from reaching Base UI's own typeahead (so they type into the
+  box instead of jumping the highlighted item); `Arrow*`/`Home`/`End`/`Enter`/
+  `Escape` still bubble, so the user can move from the search box into the
+  filtered list and select with the keyboard without leaving it first.
+- **Expander:** `InputSelectExpander` is a plain button with `aria-expanded`
+  reflecting its toggle state; it is not a `role="option"` and does not
+  register with Base UI's composite list (unlike `SelectPrimitive.Item`), so
+  Arrow-key roaming inside the listbox skips it entirely — it cannot be
+  reached with the keyboard once the popup is open, only by pointer. It
+  remains a normal native tab stop outside that roving focus order.
+- **Selection indicator:** single-select shows a trailing check on the selected item;
+  multiple-select shows a leading checkbox per item (not focusable — the row is the
+  control).
+- **Focus visible:** keyboard focus paints a 3px ring flush to the trigger —
+  `--ui-focus-primary` normally, `--ui-focus-error` while `aria-invalid`.
+- **Disabled:** native `disabled` removes the trigger from the tab order and blocks
+  opening; state is not conveyed by color alone (the control is also inert).
+- **Status:** the loading / empty / error row is informational; provide a real message
+  and, for errors, a focusable retry control.
+- **Contrast:** label / value / placeholder / border / item pairs come from the design
+  tokens, authored to meet WCAG contrast.
+- **WCAG:** 1.3.1, 2.1.1, 2.4.7, 1.4.3 / 1.4.11, 3.3.1 / 3.3.2, 4.1.2.