@ahrowe/ui 0.35.0 → 0.37.0

package/docs/CLAUDE.md

@@ -1,230 +1,124 @@
-# ahrowe-ui — Claude Code Reference
-
-Package name: `@ahrowe/ui`  
-Install: `npm install @ahrowe/ui`  
-Import: `import { Button, Input, Card, ... } from '@ahrowe/ui'`  
-CSS: `import '@ahrowe/ui/style.css'` (add once in your app entry point)
-
-## Required: ThemeProvider
-
-Wrap your app (or the root layout) with `ThemeProvider`. Without it, CSS variables are undefined and components will be unstyled.
-
-```tsx
-import { ThemeProvider } from '@ahrowe/ui';
-
-// Minimal — uses built-in defaults
-<ThemeProvider>
-  <App />
-</ThemeProvider>
-
-// With a custom theme
-import type { Theme } from '@ahrowe/ui';
-const myTheme: Theme = {
-  id: 'brand',
-  variables: {
-    '--primary-color': '#6200ea',
-    '--primary-lighter': '#b388ff',
-    '--background': '#ffffff',
-    '--text-color': '#212121',
-  },
-};
-<ThemeProvider themes={[myTheme]} currentThemeId="brand">
-  <App />
-</ThemeProvider>
-```
-
-`useTheme()` hook returns `{ currentThemeId, setTheme }` for theme switching.
-
-## FormValidator (for form-connected components)
-
-Input, NumberInput, Dropdown, Checkbox, DatePicker, IconPicker, InputDropdown, and Textarea all accept a `formValidator` prop. Use it to connect validation state.
-
-```tsx
-import { FormValidator, Validators, Input } from '@ahrowe/ui';
-
-// Create with initial value and optional validators
-const nameValidator = new FormValidator('', [Validators.required(), Validators.minLength(2)]);
-
-// Pass to component — it tracks value, dirty, touched, errors internally
-<Input label="Name" formValidator={nameValidator} />
-```
-
-For multi-field forms with a single submit handler, use `useFormValidatorGroup`:
-
-```tsx
-import { useFormValidatorGroup, FormValidator, Validators } from '@ahrowe/ui';
-
-const form = useFormValidatorGroup(
-  {
-    name:  new FormValidator('', [Validators.required()]),
-    email: new FormValidator('', [Validators.required(), Validators.email()]),
-  },
-  { onSubmit: async (values) => save(values) }, // values is fully typed
-);
-
-<form.Form>
-  <Input label="Name"  formValidator={form.group.name} />
-  <Input label="Email" formValidator={form.group.email} />
-</form.Form>
-```
-
-Full reference: see **FormValidator.md** (single field, all built-in validators, custom validators) and **FormValidatorGroup.md** (whole-form submit, validate, reset, server-error mapping) below.
-
-## Slot customisation (classNames / styles)
-
-Most components expose `classNames` and `styles` props for styling inner elements without fighting CSS specificity.
-
-```tsx
-// className / style → root element
-// classNames.<slot> → named inner element
-// styles.<slot>     → inline style on inner element
-
-<Button
-  className="my-btn"
-  classNames={{ background: 'my-bg', label: 'my-label' }}
-  styles={{ background: { borderRadius: '99px' } }}
->
-  Save
-</Button>
-```
-
-Slot keys per component are documented in each component's doc file below.
-
-## Refs
-
-The library targets **React 19 or newer**. Every component that takes a ref takes it as a plain
-prop, not through `forwardRef`, so there is nothing to unwrap and a generic component keeps its
-type parameter.
-
-```tsx
-const input = useRef<HTMLInputElement>(null);
-<Input label="Name" ref={input} />;
-input.current?.focus();
-```
-
-A ref lands on the element you would actually reach for, which is not always the root: `Input`,
-`Textarea`, `NumberInput` and `SearchInput` give you the `<input>` or `<textarea>` inside, not
-their wrapper. Components that do more than hold a node expose an imperative handle instead of an
-element: `Timer` (`start`/`pause`/`reset`), `Flip` (`flip`/`setFlipped`/`reset`), `Tilt`
-(`setTilt`/`reset`), `Ripple` (`addRipple`), `VirtualList` (scrolling and column layout),
-`RoomDrawer` and `RoomViewer`. Each handle's type is exported next to the component's props.
-
-## Server components
-
-Every module in the package is marked `'use client'`. All the components are interactive, so none
-of them renders on a server, but they can be imported straight into a React Server Components app
-(Next.js App Router and the like) with no wrapper component in between.
-
-## Right to left
-
-Not supported. The stylesheets use physical CSS properties (`margin-left`, `left`), so the library
-does not mirror for right-to-left languages.
-
-## Reduced motion
-
-Components honour `prefers-reduced-motion: reduce`: entrances, slides, chevron rotations and the
-ink ripple stop, while fades and colour changes stay. Two things deliberately keep moving, because
-freezing them would state something untrue: the loading spinners, and the Toast progress bar that
-shows how long a toast has left.
-
-## Icon props (`IconDefinition | ReactElement`)
-
-Every `icon` prop (and every icon field inside an item/action object) accepts either a
-FontAwesome `IconDefinition` or an arbitrary React node — an inline `<svg>`, an `<img>`,
-or another icon library's component.
-
-```tsx
-import { faPen } from '@fortawesome/free-solid-svg-icons';
-
-<Button icon={faPen}>Edit</Button>                    // FontAwesome
-<Button icon={<MyIcon />}>Edit</Button>               // any React node
-<Button icon={<img src="/pen.svg" alt="" />}>Edit</Button>
-```
-
-A definition is rendered through `FontAwesomeIcon`; an element is rendered as-is, wrapped in a
-`<span>` carrying the component's icon class when that slot is styled. A custom element is not
-sized by FontAwesome's `1em` geometry, so give it its own width/height if the surrounding
-layout expects a square icon.
-
-`IconPicker` and the internal `AnimatedIcon` are the exceptions — their behaviour depends on
-FontAwesome internals, so they still take an `IconDefinition` only.
-
-## Component docs
-
-@Accordion.md
-@ActionButtons.md
-@ActionIcon.md
-@Alert.md
-@AnimatedLogo.md
-@AnimatedText.md
-@Avatar.md
-@Badge.md
-@BodyEnd.md
-@Breadcrumb.md
-@Button.md
-@ButtonGroup.md
-@Card.md
-@Carousel.md
-@Checkbox.md
-@Chip.md
-@ColorPicker.md
-@ConfigProvider.md
-@ConfirmModal.md
-@DatePicker.md
-@Divider.md
-@Drawer.md
-@Dropdown.md
-@DropZone.md
-@EmptyState.md
-@ErrorBoundary.md
-@Fab.md
-@Flip.md
-@FloorPlan.md
-@FormValidator.md
-@FormValidatorGroup.md
-@IconPicker.md
-@IdleManager.md
-@InfiniteBlock.md
-@Input.md
-@InputDropdown.md
-@InteractableDiv.md
-@KanbanBoard.md
-@KlipyPicker.md
-@Loading.md
-@Menu.md
-@Modal.md
-@MultiSelect.md
-@NumberInput.md
-@OptionPicker.md
-@OtpInput.md
-@Overscroll.md
-@Pagination.md
-@Popover.md
-@ProgressBar.md
-@RadioGroup.md
-@Rating.md
-@RevealLens.md
-@Ripple.md
-@RoomDrawer.md
-@RoomViewer.md
-@ScrollbarProvider.md
-@SearchInput.md
-@SectionHeader.md
-@Skeleton.md
-@Slider.md
-@SplitButton.md
-@Stepper.md
-@Sticky.md
-@Switch.md
-@TabHeader.md
-@Textarea.md
-@ThemeProvider.md
-@Tilt.md
-@TimeInput.md
-@Timeline.md
-@Timer.md
-@Toast.md
-@Tooltip.md
-@Tree.md
-@VirtualList.md
-@Wizard.md
+# @ahrowe/ui
+
+React 19 component library. `npm install @ahrowe/ui`, import everything from `@ahrowe/ui`, and
+import `@ahrowe/ui/style.css` once in the app entry.
+
+**Before using a component, read its doc: `node_modules/@ahrowe/ui/docs/<Doc>`**, where `<Doc>` is
+the first column of the table below. The doc has the import line, runnable examples, key props,
+enums and slot names. Do not infer props from a component's name.
+
+## Rules for every component
+
+- **`ThemeProvider` is required.** It injects the CSS variables every component paints with;
+  without it they render unstyled. Wrap the app once. Two themes ship, `defaultTheme` (dark) and
+  `lightTheme`; a custom theme is `{ id, variables: { '--primary-color': '#6200ea', … } }` passed
+  through `themes`, selected with `currentThemeId`. `useTheme()` switches at runtime. The variable
+  list is in ThemeProvider.md.
+- **Portals need a host.** Modal, Tooltip, Popover, Toast and Menu render into `<div id="bodyEnd" />`.
+  Put it inside `ThemeProvider`, once.
+- **Form components** (Input, NumberInput, Dropdown, MultiSelect, InputDropdown, Checkbox, Switch,
+  RadioGroup, DatePicker, TimeInput, OtpInput, IconPicker) take `formValidator`, which then owns
+  the value: `new FormValidator('', [Validators.required()])`. Whole forms use
+  `useFormValidatorGroup`. See FormValidator.md and FormValidatorGroup.md.
+- **Styling.** `className` and `style` hit the root element; `classNames.<slot>` and `styles.<slot>`
+  hit named inner elements. Slot names are on each doc's **Slots** line. Every native attribute of
+  the root element passes through (`id`, `aria-*`, `data-*`, `on*`).
+- **Text a component renders itself** (close buttons, empty messages, page labels) is set with its
+  `labels` prop. App-wide defaults for any prop go through `ConfigProvider` (ConfigProvider.md).
+- **Variants are enums**, not strings: `ButtonStyleType.Primary`, `ButtonSize.Small`. Each doc lists
+  them under **Enums**.
+- **`icon` props** take a FontAwesome `IconDefinition` or any React element.
+- **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
+  Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`. Timer, Flip, Tilt,
+  Ripple, VirtualList, RoomDrawer and RoomViewer expose an imperative handle instead; its type is
+  exported next to the props.
+- Every module is `'use client'`; nothing renders on the server. No right-to-left support.
+  `prefers-reduced-motion` is honoured. Built for Chrome and Edge 111, Firefox 114, Safari 16.4
+  and newer, with no polyfills. The package is 0.x: a minor can break, a patch cannot.
+
+## Components
+
+<!-- components:start -->
+
+| Doc | Exports | When to use |
+|-----|---------|-------------|
+| Accordion.md | Accordion | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
+| ActionButtons.md | ActionButtons | Standardised Submit / Cancel button pair for forms, dialogs, and drawer footers |
+| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, icon-only controls |
+| Alert.md | Alert, AlertStyleType | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
+| AnimatedLogo.md | AnimatedLogo | A self-drawing SVG mark for splash/loading screens, empty states, or anywhere a brand or icon mark should feel alive rather than static |
+| AnimatedText.md | AnimatedText, AnimatedTextVariant, AnimatedTextUnit | Decorative text entrance or emphasis effect, for hero headlines, empty-state messages, "premium"/"new" callouts, loading/decoding states |
+| Avatar.md | Avatar, AvatarGroup | User or entity image — profile pictures, comment authors, member lists |
+| Badge.md | Badge, BadgeStyleType, BadgePosition | Small count or status indicator — unread counts, notification dots, "new" markers |
+| BodyEnd.md | BodyEnd | Renders children via a React portal into a `#bodyEnd` DOM node |
+| Breadcrumb.md | Breadcrumb | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
+| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType | Primary interactive action trigger |
+| ButtonGroup.md | ButtonGroup, ButtonGroupOrientation | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
+| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
+| Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
+| Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
+| Chip.md | Chip, ChipContainer, ChipStyleType | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
+| ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |
+| ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
+| ConfirmModal.md | ConfirmModal | Confirmation dialog before destructive or irreversible actions — delete, archive, send, overwrite |
+| DatePicker.md | DatePicker | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
+| Divider.md | Divider, DividerTextPosition, DividerOrientation | A rule that separates sections of content — horizontal by default, filling the width of its parent |
+| Drawer.md | Drawer | Inline horizontal panel that collapses and expands by animating its width — side panels, navigation rails, detail/filter panes that slide open beside the main content |
+| DropZone.md | DropZone, DropZoneReturnType, DropZoneStatus | Drag-and-drop file upload area, optionally click-to-open the native picker |
+| Dropdown.md | Dropdown | Single-value selection from a list — country pickers, status selectors, category filters, any select-style input |
+| EmptyState.md | EmptyState | Placeholder shown when a list, table, or search result has no items — empty inboxes, no search matches, freshly-created sections |
+| ErrorBoundary.md | ErrorBoundary | Wrap any subtree whose render errors shouldn't take down the rest of the app — a widget, a route, a third-party embed, a list row |
+| Fab.md | Fab | Floating action button — primary screen action (create, add, compose), optionally with a speed-dial sub-menu |
+| Flip.md | Flip | Flip a front/back pair of content 180°, like a physical playing card |
+| FloorPlan.md | emptyFloorPlan, addWall, derivePlan | The shared data model behind `RoomDrawer` and `RoomViewer` |
+| FormValidator.md | FormValidator, Validators, useFormValidator | Track and validate a single form field's value, dirty/touched state, and errors |
+| FormValidatorGroup.md | useFormValidatorGroup, FormValidatorGroup, FormValidator, Validators | Manage a whole form — multiple fields, a single submit handler, validate-on-submit, dirty/touched tracking across the form, and mapping server-side errors back onto the right fields |
+| Hooks.md | useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, tabbablesIn | Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay |
+| IconPicker.md | IconPicker | Pick one item from a visual icon/image grid — category selectors, emoji-style pickers, avatar selectors, anything where each option is best represented by an icon or image rather than text alone |
+| IdleManager.md | IdleManager | Show something only once the user has stopped interacting — a screen saver, a session-timeout warning, an "are you still there?" prompt, an idle dashboard view |
+| Input.md | Input, InputType | Text input with floating label, validation state, and type variants |
+| InputDropdown.md | InputDropdown | Combobox-style input — the user can type to filter and also pick from a dropdown list |
+| InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
+| KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
+| KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
+| Loading.md | SpinnerLoading | A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes |
+| Menu.md | Menu, menuHotkeys | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
+| Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
+| MultiSelect.md | MultiSelect | Pick several options from a list |
+| NumberInput.md | NumberInput | Numeric input with formatting — prices, quantities, percentages, phone numbers with separators |
+| OptionPicker.md | OptionPicker | Segmented control for picking exactly one option from a small set — view modes, sort directions, simple tab-like switches |
+| OtpInput.md | OtpInput, OtpInputCharset | A one-time-passcode / verification-code input, rendered as one box per character |
+| Overscroll.md | Overscroll | Mobile-style collapsing header that shrinks as the user scrolls — profile pages, detail screens, anywhere a large hero area should yield space to content on scroll |
+| Pagination.md | Pagination | Move through server-paged results a page at a time — a results list, an admin table, a report |
+| Popover.md | Popover | Any panel anchored to a trigger: profile cards, quick forms, action menus, pickers, filter dropdowns |
+| ProgressBar.md | ProgressBar | Visual progress indicator — file uploads, multi-step completion, storage usage, stacked stats (e.g. budget breakdown) |
+| RadioGroup.md | RadioGroup, RadioGroupOrientation | Single-choice selection from a small, always-visible set of options — plan pickers, shipping methods, yes/no/maybe, settings with 2–5 mutually exclusive choices |
+| Rating.md | Rating | A star rating input or display, for review scores, feedback prompts, and quality indicators |
+| RevealLens.md | RevealLens | A two-layer reveal/magnifier effect — an `overlay` covers a `background` by default, and moving the pointer over the component uncovers the `background` in an area around the cursor |
+| Ripple.md | Ripple | Material-style ink ripple effect on any interactive element — buttons, list items, cards, tiles |
+| RoomDrawer.md | RoomDrawer | An interactive floor plan editor |
+| RoomViewer.md | RoomViewer | Shows a floor plan someone can look at and click, without letting them change it — a building directory, a booking screen, a dashboard beside a room list |
+| ScrollFade.md | ScrollFade, ScrollFadeAxis | A scrollable box whose content dissolves at the edge it is scrolling past, instead of being cut off mid-line against it |
+| ScrollbarProvider.md | ScrollbarProvider | Applies custom scrollbar styling to a scrollable region — use to keep scrollbar appearance consistent with the theme |
+| SearchInput.md | SearchInput | Search field with built-in debouncing and an optional result count line — list filters, search-as-you-type pages |
+| SectionHeader.md | SectionHeader, SectionHeaderSize | A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area |
+| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers) |
+| Slider.md | Slider | Let the user pick a number from a continuous or stepped range by dragging a thumb: volume, brightness, price ranges, zoom, quality presets |
+| SplitButton.md | SplitButton | A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close" |
+| Stepper.md | Stepper | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
+| Sticky.md | Sticky | Pin a piece of content to the top of the viewport once the page scrolls past it — section headers, toolbars, filter bars, table headers |
+| Switch.md | Switch | Sliding boolean toggle — settings panels, feature flags, preference lists |
+| TabHeader.md | TabHeader | A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages |
+| Textarea.md | Textarea | Multiline text input — comments, descriptions, notes, code snippets, long-form content |
+| ThemeProvider.md | ThemeProvider | Required wrapper for the entire component library |
+| Tilt.md | Tilt, TiltGroup | Wrap content that should tilt toward the cursor in 3D |
+| TimeInput.md | TimeInput | Time-of-day selection — appointment times, opening hours, shift starts, reminders |
+| Timeline.md | Timeline, TimelineAlignment, TimelineItemStatus | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
+| Timer.md | Timer | A countdown timer with a depleting ring, add/remove-time and pause/cancel controls, and an imperative ref API |
+| Toast.md | ToastProvider, showToast | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
+| Tooltip.md | Tooltip | Contextual help, info icons, field explanations, error pointers |
+| Tree.md | Tree, flattenTree | A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts |
+| VirtualList.md | VirtualList | Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM |
+| Wizard.md | Wizard | Animated step container for multi-step forms and flows |
+
+<!-- components:end -->

package/docs/Card.md

@@ -56,7 +56,7 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 | Prop | Type | Description |
 |------|------|-------------|
 | `styleType` | `CardStyleType` | Surface variant — `Elevated` (fill + shadow), `Outlined` (transparent + border), `Filled` (flat fill) |
-| `onClick` | `() => void` | Makes card clickable |
+| `onClick` | `() => void` | Makes the card clickable, by pointer and by Enter/Space. A click or key on a control inside the card (a field, a link, a button, anything with an interactive `role`) is that control's, and neither fires this nor ripples |
 | `hoverEffect` | `boolean` | Adds hover elevation |
 | `tabIndex` | `number \| null` | For keyboard navigation |
 | `autoGap` | `boolean` | Space stacked sub-components apart with a shared gap (default `true`); set `false` to space them yourself |

package/docs/Divider.md

@@ -2,6 +2,8 @@
 
 **When to use:** A rule that separates sections of content — horizontal by default, filling the width of its parent. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it. Set `orientation` to `Vertical` for a vertical line filling the height of its parent instead, e.g. as a separator between two buttons in a `ButtonGroup`.
 
+**Keywords:** separator, hr, spacer
+
 **Import:** `import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui'`
 
 **Text position:** `DividerTextPosition.Left` | `DividerTextPosition.Center` (default) | `DividerTextPosition.Right`

package/docs/Dropdown.md

@@ -66,4 +66,24 @@ The list is rendered through a portal and tracks the trigger across scroll, so i
 
 **Bottom sheet:** `presentation={Presentation.Sheet}` drops the anchoring entirely and pins the list to the bottom of the screen instead, full width up to 560px, behind a backdrop, scrolling internally past 70% of the viewport height and lifting itself above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Tapping the backdrop closes the list without also pressing whatever sits behind it. It is the same list with the same keyboard handling, so selection, highlighting and infinite scroll are unchanged. `Presentation.Auto` does that only when the pointer is coarse *and* the screen is under 768px wide. The default is `Presentation.Default`. A whole app can opt in with `<ConfigProvider defaultProps={{ Dropdown: { presentation: Presentation.Auto } }}>`, or for every sheet-capable component at once with `<ConfigProvider presentation={Presentation.Auto}>` — see [ConfigProvider.md](ConfigProvider.md).
 
+**Sheet dimensions:** as a sheet it spans the full width up to `--sheet-max-width` (560px) and centres beyond it, caps its height at `--sheet-max-height` (70dvh) of the space actually visible, and clears a phone's home indicator with `--sheet-safe-padding` (8px, or the device's own safe-area inset where that is larger). Set any of them per instance via `style` or theme-wide via `ThemeProvider`.
+
+**Keyboard:** `ArrowDown` / `ArrowUp` open the list and move the highlight, wrapping at the ends and
+skipping disabled items. `Home` / `End` jump to the first and last. `Enter` and `Space` open the list,
+then pick the highlighted item. `Escape` and `Tab` close it without selecting. Typing a letter jumps to
+the next item whose label starts with it, as a native `<select>` does; typing while the list is closed
+selects that item outright. Keystrokes within half a second of each other match as one prefix.
+
+**Screen readers:** the trigger is a `combobox` named by the field's `label`, with the selected item as
+its value, `aria-expanded`, and `aria-activedescendant` pointing at the highlighted option while the
+list is open. The list is a `listbox` of `option`s carrying `aria-selected` and `aria-disabled`. The
+chevron is `aria-hidden`, because it only repeats what the trigger already offers. The focus stays on
+the trigger the whole time the list is open.
+
+Nothing highlights on open unless `scrollToSelected` is set, which starts on the current value.
+
+**Width:** the control fills its container, the way `Input` and `MultiSelect` do. Constrain it from the
+outside (a wrapper, a grid column, `style={{ maxWidth: 240 }}`) rather than expecting it to size itself
+to the label: everything inside is absolutely positioned, so it has no width of its own to fall back on.
+
 **Slots:** `root` `label` `field` `control` `icon` `placeholder` `list` `option`