atlas-react-kit 0.9.2 → 0.9.4

package/COMPONENTS.md

@@ -5,6 +5,17 @@ underlying element or Radix props, including `className`, alongside their option
 Form helpers and `TableBodySkeleton` accept only their documented props. There is
 no root component barrel.
 
+For installation, see [README.md](./README.md); for styling and accessibility,
+see [DESIGN_RULES.md](./DESIGN_RULES.md).
+
+For LLM-assisted implementation of patterns this kit does not export, use
+[COSS UI](https://coss.com/ui) as a reference before building a component from
+scratch. Its Base UI catalog includes input groups, number fields, OTP fields,
+drawers, and segmented controls. COSS is a separate library; its components
+are not Atlas exports.
+
+## Optional peer dependencies
+
 Core entries need only the kit. These feature entries need an extra install
 (same version ranges as the kit's optional peers). `Toaster` also reads the
 theme from `next-themes`, so toast consumers install that too.
@@ -29,7 +40,7 @@ theme from `next-themes`, so toast consumers install that too.
 | `card`                        | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`; `Card` supports `flush`; root uses `min-h-min shrink-0` so flex columns do not collapse it, and `min-w-0` so nested tables scroll; `CardContent className="px-0"` overrides padding without `!`                                                                                         |
 | `checkbox`                    | `Checkbox`                                                                                                                                                                                                                                                                                                                                                                               |
 | `color-legend`                | `ColorLegend`; `title`, `items` as `{ color, range?, label }[]`, optional `caption`, `children`, `aria-label`, `className` (overlay chrome). No attribution.                                                                                                                                                                                                                             |
-| `combobox`                    | `Combobox`; `options` as `{ value, label }[]`, `value`, `onValueChange`; optional placeholder, search, empty text; trigger matches Input/SelectTrigger chrome; keyboard highlight scrolls into view                                                                                                                                                                                      |
+| `combobox`                    | `Combobox`; `options` as `{ value, label }[]`, `value`, `onValueChange`; optional placeholder, search, empty text, `creatable`, `normalizeCreateValue` (query → value or `null`), `createLabel`; trigger matches Input/SelectTrigger chrome; keyboard highlight scrolls into view; create is a listbox option selected with Enter                                                        |
 | `date-picker`                 | `DatePickerButton`, `toDate`, `formatLocalDate`, `DateRange`; `mode` `"single"` (default) or `"range"`; single `value` is `Date` or `yyyy-MM-dd`; range `value` is `{ from, to }`; trigger matches Input chrome; optional `numberOfMonths` (range default 1 below `md`, 2 at `md+`) and `side`                                                                                           |
 | `date-time-picker`            | `DateTimePickerButton`, `resolveTimeStep`, `DEFAULT_TIME_STEP`; controlled `value` is `Date` or `null`; `onChange` emits `Date \                                                                                                                                                                                                                                                         |
 | `dialog`                      | `Dialog`, trigger, portal, overlay, content, close, header, footer, title, description; `DialogContent` supports `showCloseButton`                                                                                                                                                                                                                                                       |

package/DESIGN_RULES.md

@@ -4,6 +4,9 @@ Atlas owns these shared rules, its theme, and component implementations. Change
 them here and release a package version. Build application-specific UI by composing
 the shipped components.
 
+Use [COMPONENTS.md](./COMPONENTS.md) for public entry points, props, and
+component-specific behavior.
+
 ## Tokens
 
 Use semantic colors, radii, and fonts: `bg-primary`, `text-muted-foreground`,

package/README.md

@@ -4,10 +4,11 @@ Shared React components and a Tailwind theme with square corners, semantic
 colors, and distinct selected states. 0.6.0 added generic pieces apps were
 keeping locally (`InfoTip`, `ColorLegend`, `SearchPicker`, `Markdown`,
 `StatTile`, `Meter`, `Slider`) plus the ToggleGroup selected-state fix.
-React 19 and Tailwind 4 are required.
+React 19, Tailwind 4, and Node >=20.19 are required. Next 16 is needed only
+when using `next/tabs-nav-link`.
 
 ```sh
-npm install --save-exact atlas-react-kit@0.9.2
+npm install --save-exact atlas-react-kit@0.9.4
 ```
 
 Import components by subpath:
@@ -27,17 +28,8 @@ export function Example() {
 }
 ```
 
-Core entries need only the kit. These feature entries need an extra install
-(same version ranges as the kit's optional peers). `Toaster` also reads the
-theme from `next-themes`, so toast consumers install that too.
-
-| Entry points                                                                                           | Extra install                                    |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| `calendar`, `date-picker`, `date-time-picker`, `form/date-picker-field`, `form/date-time-picker-field` | `npm i react-day-picker@^10.0.1 date-fns@^4.4.0` |
-| `markdown`, `form/markdown-field`                                                                      | `npm i react-markdown@^10.1.0 remark-gfm@^4.0.1` |
-| `theme-provider`                                                                                       | `npm i next-themes@^0.4.6`                       |
-| `toast`                                                                                                | `npm i sonner@^2.0.7 next-themes@^0.4.6`         |
-| `next/tabs-nav-link`                                                                                   | `npm i next@^16.0.0`                             |
+Core entries need only the kit. Feature entries may need optional peers; see
+the [component guide's install table](./COMPONENTS.md#optional-peer-dependencies).
 
 In your global stylesheet, import the theme after Tailwind and register the
 installed JavaScript directory. Paths in `@source` are relative to that stylesheet;
@@ -55,9 +47,15 @@ on an ancestor to activate dark colors. Supply your own font configuration;
 `font-heading` uses the configured sans font. Application-specific tokens stay
 with the application.
 
-See [design rules](./DESIGN_RULES.md) for shared styling decisions and the
-[component guide](./COMPONENTS.md) for exports and composition examples. Both
-files ship in the npm package.
+## Documentation
+
+- [Component guide](./COMPONENTS.md): imports, props, optional installs, and
+  composition. This guide ships in the npm package.
+- [Design rules](./DESIGN_RULES.md): tokens, accessibility, writing, and
+  composition. This guide ships in the npm package.
+- [Contributing](./CONTRIBUTING.md): component changes, checks, and releases.
+- [Roadmap to 1.0](./ROADMAP-1.0.md): decisions needed before the 1.0 release.
+- [Changelog](./CHANGELOG.md): published and upcoming changes.
 
 ## AI coding assistants
 
@@ -82,7 +80,8 @@ Public docs and a live playground are at
 [design.querobines.com](https://design.querobines.com). The site is Storybook:
 tokens parsed from `theme.css`, these markdown guides rendered from source, and
 editable component stories with light/dark themes, viewport previews, and
-accessibility checks.
+accessibility checks. Its build publishes `docs-index.json` with guide headings
+and package entry points for search and indexing tools.
 
 ## Development and releases
 
@@ -129,12 +128,9 @@ artifact with the package owner's npm login:
 ```sh
 mkdir -p release-artifacts
 npm pack --pack-destination release-artifacts
-npm publish ./release-artifacts/atlas-react-kit-0.9.2.tgz --access public
+npm publish ./release-artifacts/atlas-react-kit-0.9.4.tgz --access public
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for adding components, the browser
-checks, versioning, and deprecations.
-
 Pin an exact package version in consuming applications. Roll back an upgrade by
 restoring the previous version and lockfile. License: MIT; upstream notices are
 preserved in [NOTICE](./NOTICE).

package/dist/combobox.d.ts

@@ -17,6 +17,22 @@ type ComboboxProps = {
     /** Name the trigger when there is no `<Label htmlFor={id}>`. */
     "aria-label"?: string;
     "aria-labelledby"?: string;
+    /**
+     * Offer creating the current query when it is not already an option.
+     * Off by default so existing callers stay search-and-select.
+     */
+    creatable?: boolean;
+    /**
+     * Turn the search query into a value to create, or `null` to hide the
+     * create action. Default trims the query. Apps own domain rules (for
+     * example `^[A-Z]{3}$` for currency codes); catalogs stay in the app.
+     */
+    normalizeCreateValue?: (query: string) => string | null;
+    /**
+     * Visible and accessible name for the create option. Default is
+     * `Create "{value}"`.
+     */
+    createLabel?: (value: string) => string;
 };
 /**
  * Searchable single-select built from Button, Popover, and Input.
@@ -24,6 +40,8 @@ type ComboboxProps = {
  * Options are a plain `{ value, label }` list; domain data stays in the app.
  * Keyboard highlight (arrows, Home/End, PageUp/PageDown) scrolls the active
  * option into view inside the overflow list.
+ * Opt-in `creatable` appends a create action when the query is not already
+ * an option; choosing it calls `onValueChange` like a normal selection.
  */
-export declare function Combobox({ options, value, onValueChange, placeholder, searchPlaceholder, emptyText, disabled, id, className, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: ComboboxProps): React.JSX.Element;
+export declare function Combobox({ options, value, onValueChange, placeholder, searchPlaceholder, emptyText, disabled, id, className, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, creatable, normalizeCreateValue, createLabel, }: ComboboxProps): React.JSX.Element;
 export {};

package/dist/combobox.js

@@ -5,35 +5,79 @@ import { CheckIcon, ChevronDownIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Input } from "./input.js";
 import { formControlTriggerClassName } from "./internal/form-control.js";
+import { listboxOptionId, moveListboxHighlight, scrollOptionIntoView, } from "./internal/listbox-navigation.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
-import { optionState } from "./internal/styles.js";
+import { listboxEmpty, optionState } from "./internal/styles.js";
 import { cn, onInputChange } from "./utils.js";
+const CREATE_OPTION_KEY = "__atlas-combobox-create";
 /**
- * PageUp/PageDown jump size. The option list is `max-h-60`; ten rows is a
- * bit more than one viewport so long lists (timezones, currencies) move
- * without requiring an End key.
+ * Trimmed query, or `null` when there is nothing to create.
  */
-const LISTBOX_PAGE_SIZE = 10;
+function defaultNormalizeCreateValue(query) {
+    const next = query.trim();
+    return next.length > 0 ? next : null;
+}
+/**
+ * Accessible create action: the word "Create" plus the quoted value.
+ */
+function defaultCreateLabel(value) {
+    return `Create "${value}"`;
+}
+/**
+ * Value to offer as a new option, or `null` when the query is empty,
+ * rejected by `normalize`, or already in the list (value or label,
+ * case-insensitive). Domain catalogs stay with the caller.
+ */
+function resolveCreateValue(query, options, normalize) {
+    const created = normalize(query);
+    if (created == null)
+        return null;
+    const value = created.trim();
+    if (!value)
+        return null;
+    const needle = value.toLowerCase();
+    const exists = options.some((option) => option.value.toLowerCase() === needle ||
+        option.label.toLowerCase() === needle);
+    return exists ? null : value;
+}
 /**
  * Searchable single-select built from Button, Popover, and Input.
  * The trigger uses the same form-control chrome as Input and SelectTrigger.
  * Options are a plain `{ value, label }` list; domain data stays in the app.
  * Keyboard highlight (arrows, Home/End, PageUp/PageDown) scrolls the active
  * option into view inside the overflow list.
+ * Opt-in `creatable` appends a create action when the query is not already
+ * an option; choosing it calls `onValueChange` like a normal selection.
  */
-export function Combobox({ options, value, onValueChange, placeholder = "Select", searchPlaceholder = "Search", emptyText = "No results", disabled, id, className, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }) {
+export function Combobox({ options, value, onValueChange, placeholder = "Select", searchPlaceholder = "Search", emptyText = "No results", disabled, id, className, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, creatable = false, normalizeCreateValue = defaultNormalizeCreateValue, createLabel = defaultCreateLabel, }) {
     const [open, setOpen] = React.useState(false);
     const [query, setQuery] = React.useState("");
     const [highlight, setHighlight] = React.useState(0);
     const inputRef = React.useRef(null);
     const listId = React.useId();
-    const selected = options.find((option) => option.value === value);
+    // A created value may not be in `options` yet (the app owns the catalog).
+    // Keep it visible on the trigger and in the list so reopen/Enter still work.
+    const resolvedOptions = React.useMemo(() => {
+        if (!creatable || !value)
+            return options;
+        if (options.some((option) => option.value === value))
+            return options;
+        return [...options, { value, label: value }];
+    }, [creatable, options, value]);
+    const selected = resolvedOptions.find((option) => option.value === value);
     const filtered = React.useMemo(() => {
         const needle = query.trim().toLowerCase();
         if (!needle)
-            return options;
-        return options.filter((option) => option.label.toLowerCase().includes(needle));
-    }, [options, query]);
+            return resolvedOptions;
+        return resolvedOptions.filter((option) => option.label.toLowerCase().includes(needle));
+    }, [resolvedOptions, query]);
+    const createValue = creatable
+        ? resolveCreateValue(query, resolvedOptions, normalizeCreateValue)
+        : null;
+    const createOption = createValue
+        ? { value: createValue, label: createLabel(createValue) }
+        : null;
+    const list = createOption ? [...filtered, createOption] : filtered;
     const onOpenChange = (next) => {
         setOpen(next);
         if (!next) {
@@ -43,7 +87,7 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         // Set the highlight in the same turn as open so the first painted list
         // already points at the selected option (a timezone at the end of 400
         // rows) instead of flashing index 0 and scrolling twice.
-        const selectedIndex = options.findIndex((option) => option.value === value);
+        const selectedIndex = resolvedOptions.findIndex((option) => option.value === value);
         setHighlight(selectedIndex >= 0 ? selectedIndex : 0);
     };
     React.useEffect(() => {
@@ -52,12 +96,6 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         const frame = window.requestAnimationFrame(() => inputRef.current?.focus());
         return () => window.cancelAnimationFrame(frame);
     }, [open]);
-    // Callback ref (not an effect) so scroll runs when Radix mounts the list
-    // and when the highlight moves. A layout effect on `open` is too early:
-    // the option node does not exist until the popover content is in the DOM.
-    const scrollHighlightedOption = React.useCallback((node) => {
-        node?.scrollIntoView({ block: "nearest" });
-    }, []);
     const onQueryChange = onInputChange((next) => {
         setQuery(next);
         setHighlight(0);
@@ -70,49 +108,25 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         setOpen(false);
         setQuery("");
     };
-    // Index-based ids: option values may contain spaces, which are not valid
-    // in an id or an aria-activedescendant reference.
-    const optionId = (index) => `${listId}-option-${index}`;
-    const activeOption = filtered[highlight];
+    const activeOption = list[highlight];
     const onSearchKeyDown = (event) => {
-        if (event.key === "ArrowDown") {
+        const nextHighlight = moveListboxHighlight(event.key, highlight, list.length);
+        if (nextHighlight !== undefined) {
             event.preventDefault();
-            setHighlight((index) => filtered.length === 0 ? 0 : Math.min(index + 1, filtered.length - 1));
-        }
-        if (event.key === "ArrowUp") {
-            event.preventDefault();
-            setHighlight((index) => Math.max(index - 1, 0));
+            setHighlight(nextHighlight);
+            return;
         }
         if (event.key === "Enter") {
             event.preventDefault();
-            const option = filtered[highlight];
+            const option = list[highlight];
             if (option)
                 selectValue(option.value);
         }
-        // Home/End/Page jump the highlight; preventDefault so the search caret
-        // stays put and the page behind the list does not scroll.
-        if (event.key === "Home") {
-            event.preventDefault();
-            setHighlight(0);
-        }
-        if (event.key === "End") {
-            event.preventDefault();
-            setHighlight(filtered.length === 0 ? 0 : filtered.length - 1);
-        }
-        if (event.key === "PageDown") {
-            event.preventDefault();
-            setHighlight((index) => filtered.length === 0
-                ? 0
-                : Math.min(index + LISTBOX_PAGE_SIZE, filtered.length - 1));
-        }
-        if (event.key === "PageUp") {
-            event.preventDefault();
-            setHighlight((index) => Math.max(index - LISTBOX_PAGE_SIZE, 0));
-        }
     };
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, className: cn(formControlTriggerClassName, "justify-between", !selected && "text-muted-foreground", className), children: [_jsx("span", { className: "truncate", children: selected?.label ?? placeholder }), _jsx(ChevronDownIcon, { "data-icon": "inline-end", className: "opacity-50" })] }) }), _jsxs(PopoverContent, { align: "start", className: "w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", children: [_jsx("div", { className: "border-b p-2", children: _jsx(Input, { ref: inputRef, value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? optionId(highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", className: "max-h-60 overflow-y-auto p-1", children: filtered.length === 0 ? (_jsx("li", { className: "px-3 py-4 text-center text-sm text-muted-foreground", children: emptyText })) : (filtered.map((option, index) => {
-                            const isSelected = option.value === value;
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, className: cn(formControlTriggerClassName, "justify-between", !selected && "text-muted-foreground", className), children: [_jsx("span", { className: "truncate", children: selected?.label ?? placeholder }), _jsx(ChevronDownIcon, { "data-icon": "inline-end", className: "opacity-50" })] }) }), _jsxs(PopoverContent, { align: "start", className: "w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", children: [_jsx("div", { className: "border-b p-2", children: _jsx(Input, { ref: inputRef, value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? listboxOptionId(listId, highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", className: "max-h-60 overflow-y-auto p-1", children: list.length === 0 ? (_jsx("li", { className: listboxEmpty, children: emptyText })) : (list.map((option, index) => {
+                            const isCreate = createOption != null && option === createOption;
+                            const isSelected = option.value === value && !isCreate;
                             const isActive = index === highlight;
-                            return (_jsx("li", { role: "none", children: _jsxs("button", { ref: isActive ? scrollHighlightedOption : undefined, id: optionId(index), type: "button", role: "option", "aria-selected": isSelected, className: cn("relative flex w-full cursor-default items-center gap-2 rounded-none py-2 pr-8 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active), onMouseEnter: () => setHighlight(index), onClick: () => selectValue(option.value), children: [_jsx("span", { className: "truncate", children: option.label }), isSelected ? (_jsx(CheckIcon, { className: "pointer-events-none absolute right-2 size-3.5" })) : null] }) }, option.value));
+                            return (_jsx("li", { role: "none", children: _jsxs("button", { ref: isActive ? scrollOptionIntoView : undefined, id: listboxOptionId(listId, index), type: "button", role: "option", "aria-selected": isSelected, className: cn("relative flex w-full cursor-default items-center gap-2 rounded-none py-2 pr-8 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active), onMouseEnter: () => setHighlight(index), onClick: () => selectValue(option.value), children: [_jsx("span", { className: "truncate", children: option.label }), isSelected ? (_jsx(CheckIcon, { className: "pointer-events-none absolute right-2 size-3.5" })) : null] }) }, isCreate ? CREATE_OPTION_KEY : option.value));
                         })) })] })] }));
 }

package/dist/date-picker.js

@@ -5,7 +5,7 @@ import { format, isSameDay, parseISO } from "date-fns";
 import { CalendarIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Calendar } from "./calendar.js";
-import { formControlTriggerClassName } from "./internal/form-control.js";
+import { PICKER_COLLISION_PADDING, pickerContentClassName, pickerTriggerClassName, } from "./internal/form-control.js";
 import { MD_MEDIA_QUERY, useMediaQuery } from "./internal/use-media-query.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { cn } from "./utils.js";
@@ -56,11 +56,9 @@ function formatRangeTriggerLabel(from, to, placeholder) {
         return format(from, "PPP");
     return `${format(from, "PPP")} – ${format(to, "PPP")}`;
 }
-/** Gutter used when the calendar popover collides with the viewport. */
-const DATE_PICKER_COLLISION_PADDING = 16;
 /** Shared trigger + auto-sized popover chrome for single and range modes. */
 function DatePickerShell({ id, disabled, ariaInvalid, className, empty, label, open, onOpenChange, side, children, }) {
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(formControlTriggerClassName, "justify-start data-[empty=true]:text-muted-foreground", className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: DATE_PICKER_COLLISION_PADDING, className: "w-auto max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0", children: children })] }));
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(pickerTriggerClassName, className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, className: cn("w-auto", pickerContentClassName), children: children })] }));
 }
 function DatePickerSingleButton({ id, value, onChange, placeholder = "Pick a date", disabled, className, "aria-invalid": ariaInvalid, numberOfMonths, side, defaultMonth, }) {
     const [open, setOpen] = React.useState(false);

package/dist/date-time-picker.js

@@ -5,14 +5,12 @@ import { format } from "date-fns";
 import { CalendarIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Calendar } from "./calendar.js";
-import { formControlTriggerClassName } from "./internal/form-control.js";
+import { PICKER_COLLISION_PADDING, pickerContentClassName, pickerTriggerClassName, } from "./internal/form-control.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./select.js";
 import { cn } from "./utils.js";
 /** Default clock increment, in minutes. Must divide 60. */
 export const DEFAULT_TIME_STEP = 15;
-/** Gutter used when the calendar popover collides with the viewport. */
-const DATE_TIME_PICKER_COLLISION_PADDING = 16;
 /**
  * Normalize a minute step so option lists stay even (1, 5, 15, 30, 60).
  * Invalid values fall back to 15 so a bad prop cannot empty the minute list.
@@ -81,7 +79,7 @@ export function DateTimePickerButton({ id, value, onChange, timeStep, placeholde
     const label = date ? format(date, "PPP p") : placeholder;
     const hourId = React.useId();
     const minuteId = React.useId();
-    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(formControlTriggerClassName, "justify-start data-[empty=true]:text-muted-foreground", className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsxs(PopoverContent, { align: "start", side: side, collisionPadding: DATE_TIME_PICKER_COLLISION_PADDING, onInteractOutside: preventDismissForPortaledSelect, className: "w-auto min-w-0 max-w-[min(100vw-2rem,24rem)] max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0", children: [_jsx(Calendar, { mode: "single", selected: date ?? undefined, defaultMonth: defaultMonth ?? date ?? undefined, onSelect: (next) => {
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(pickerTriggerClassName, className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsxs(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, onInteractOutside: preventDismissForPortaledSelect, className: cn("w-auto min-w-0 max-w-[min(100vw-2rem,24rem)]", pickerContentClassName), children: [_jsx(Calendar, { mode: "single", selected: date ?? undefined, defaultMonth: defaultMonth ?? date ?? undefined, onSelect: (next) => {
                             // Re-clicking a selected day would clear it; require Clear instead
                             // so a time already set is not dropped by an accidental second tap.
                             if (!next)

package/dist/field.d.ts

@@ -6,7 +6,7 @@ declare function FieldLegend({ className, variant, ...props }: React.ComponentPr
 }): import("react").JSX.Element;
 declare function FieldGroup({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
 declare const fieldVariants: (props?: ({
-    orientation?: "horizontal" | "vertical" | "responsive" | null | undefined;
+    orientation?: "vertical" | "horizontal" | "responsive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Field({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>): import("react").JSX.Element;
 declare function FieldContent({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;

package/dist/form/date-picker-field.d.ts

@@ -1,5 +1,5 @@
 import { type DateLike } from "../date-picker.js";
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: DateLike;
     onValueChange: (date: Date | undefined) => void;

package/dist/form/date-picker-field.js

@@ -1,12 +1,11 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from "react";
 import { DatePickerButton } from "../date-picker.js";
-import { Label } from "../label.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /** Date picker with built-in field error text and invalid styling. */
 export function FormDatePickerField({ value, onValueChange, label, meta, placeholder, disabled, className, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsx(DatePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, className: className, "aria-invalid": errorText ? true : undefined }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsx(DatePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, className: className, "aria-invalid": invalidWhen(errorText) }) }));
 }

package/dist/form/date-time-picker-field.d.ts

@@ -1,4 +1,4 @@
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: Date | null;
     onValueChange: (date: Date | null) => void;

package/dist/form/date-time-picker-field.js

@@ -1,12 +1,11 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from "react";
 import { DateTimePickerButton } from "../date-time-picker.js";
-import { Label } from "../label.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /** Date-time picker with built-in field error text and invalid styling. */
 export function FormDateTimePickerField({ value, onValueChange, label, meta, placeholder, disabled, timeStep, className, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsx(DateTimePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, timeStep: timeStep, className: className, "aria-invalid": errorText ? true : undefined }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsx(DateTimePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, timeStep: timeStep, className: className, "aria-invalid": invalidWhen(errorText) }) }));
 }

package/dist/form/field-shell.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { type FieldMetaState } from "./field-error.js";
+/**
+ * Not a public entry. The layout and error wiring every `form/*` field
+ * shares, so a field only says which control it renders.
+ */
+/** First error in `meta`, or `undefined` when there is no meta or no error. */
+export declare function metaErrorText(meta: FieldMetaState | undefined): string | undefined;
+/** `aria-invalid` for the control: `true` while there is error text. */
+export declare function invalidWhen(errorText: string | undefined): true | undefined;
+/**
+ * Label, control, and error text stacked with the kit's field spacing.
+ * `labelAction` sits on the label's row (the Markdown field's mode toggle).
+ */
+export declare function FormFieldShell({ id, label, labelAction, errorText, children, }: {
+    id: string;
+    label: string;
+    labelAction?: ReactNode;
+    errorText: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/form/field-shell.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Label } from "../label.js";
+import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+/**
+ * Not a public entry. The layout and error wiring every `form/*` field
+ * shares, so a field only says which control it renders.
+ */
+/** First error in `meta`, or `undefined` when there is no meta or no error. */
+export function metaErrorText(meta) {
+    return meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+}
+/** `aria-invalid` for the control: `true` while there is error text. */
+export function invalidWhen(errorText) {
+    return errorText ? true : undefined;
+}
+/**
+ * Label, control, and error text stacked with the kit's field spacing.
+ * `labelAction` sits on the label's row (the Markdown field's mode toggle).
+ */
+export function FormFieldShell({ id, label, labelAction, errorText, children, }) {
+    const labelNode = _jsx(Label, { htmlFor: id, children: label });
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [labelAction ? (_jsxs("div", { className: "flex items-center justify-between gap-2", children: [labelNode, labelAction] })) : (labelNode), children, _jsx(FieldError, { text: errorText })] }));
+}

package/dist/form/markdown-field.js

@@ -1,13 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-import { Label } from "../label.js";
 import { Markdown } from "../markdown.js";
 import { Textarea } from "../textarea.js";
 import { ToggleGroup, ToggleGroupItem } from "../toggle-group.js";
 import { fieldSurface } from "../internal/styles.js";
 import { cn, onInputChange } from "../utils.js";
-import { FieldError, getFieldErrorMessage } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /**
  * GFM body field: Write is a textarea, Preview is the sanitized Markdown
  * renderer. String-in/string-out — not a WYSIWYG document model.
@@ -15,13 +14,11 @@ import { FieldError, getFieldErrorMessage } from "./field-error.js";
 export function FormMarkdownField({ field, id = field.name, label, placeholder = "Markdown supported", rows = 5, showError = true, }) {
     const [mode, setMode] = useState("write");
     const onChange = onInputChange(field.handleChange);
-    const errorText = showError
-        ? getFieldErrorMessage(field.state.meta.errors[0])
-        : undefined;
+    const errorText = showError ? metaErrorText(field.state.meta) : undefined;
     const trimmed = field.state.value.trim();
     function handleModeChange(value) {
         if (value === "write" || value === "preview")
             setMode(value);
     }
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx(Label, { htmlFor: id, children: label }), _jsxs(ToggleGroup, { type: "single", value: mode, onValueChange: handleModeChange, variant: "outline", size: "sm", spacing: 0, "aria-label": `${label} mode`, children: [_jsx(ToggleGroupItem, { value: "write", children: "Write" }), _jsx(ToggleGroupItem, { value: "preview", children: "Preview" })] })] }), mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, "aria-invalid": errorText ? true : undefined })) : (_jsx("div", { className: cn(fieldSurface, "min-h-16"), "aria-live": "polite", children: trimmed ? (_jsx(Markdown, { content: trimmed })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })), showError ? _jsx(FieldError, { text: errorText }) : null] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, labelAction: _jsxs(ToggleGroup, { type: "single", value: mode, onValueChange: handleModeChange, variant: "outline", size: "sm", spacing: 0, "aria-label": `${label} mode`, children: [_jsx(ToggleGroupItem, { value: "write", children: "Write" }), _jsx(ToggleGroupItem, { value: "preview", children: "Preview" })] }), children: mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, "aria-invalid": invalidWhen(errorText) })) : (_jsx("div", { className: cn(fieldSurface, "min-h-16"), "aria-live": "polite", children: trimmed ? (_jsx(Markdown, { content: trimmed })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })) }));
 }

package/dist/form/select-field.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: string | undefined;
     meta?: FieldMetaState;

package/dist/form/select-field.js

@@ -1,12 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
-import { Label } from "../label.js";
 import { Select, SelectContent, SelectTrigger, SelectValue } from "../select.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /** Select control with built-in field error text and invalid styling. */
 export function FormSelectField({ value, meta, label, onValueChange, placeholder, children, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsxs(Select, { value: value, onValueChange: onValueChange, children: [_jsx(SelectTrigger, { id: id, "aria-invalid": errorText ? true : undefined, children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { children: children })] }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsxs(Select, { value: value, onValueChange: onValueChange, children: [_jsx(SelectTrigger, { id: id, "aria-invalid": invalidWhen(errorText), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { children: children })] }) }));
 }

package/dist/form/text-field.d.ts

@@ -1,4 +1,4 @@
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 export type TextFieldApi = {
     name: string;
     state: {

package/dist/form/text-field.js

@@ -1,15 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Input } from "../input.js";
-import { Label } from "../label.js";
 import { Textarea } from "../textarea.js";
 import { onInputChange } from "../utils.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 export function FormTextField({ field, id = field.name, label, placeholder, description, autoFocus, multiline, rows = 3, inputType = "text", showError = true, autoComplete, required, minLength, }) {
     const onChange = onInputChange(field.handleChange);
-    const errorText = showError
-        ? getFieldErrorMessage(field.state.meta.errors[0])
-        : undefined;
+    const errorText = showError ? metaErrorText(field.state.meta) : undefined;
     const controlProps = {
         id,
         value: field.state.value,
@@ -19,7 +16,7 @@ export function FormTextField({ field, id = field.name, label, placeholder, desc
         autoComplete,
         required,
         minLength,
-        "aria-invalid": errorText ? true : undefined,
+        "aria-invalid": invalidWhen(errorText),
     };
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), description ? (_jsx("p", { className: "text-xs text-muted-foreground", children: description })) : null, multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus })), showError ? _jsx(FieldError, { text: errorText }) : null] }));
+    return (_jsxs(FormFieldShell, { id: id, label: label, errorText: errorText, children: [description ? (_jsx("p", { className: "text-xs text-muted-foreground", children: description })) : null, multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus }))] }));
 }

package/dist/internal/form-control.d.ts

@@ -7,3 +7,12 @@
  * outline Button's purple selected wash.
  */
 export declare const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
+/**
+ * Date and date-time picker trigger: the form-control chrome, start-aligned,
+ * with muted text while empty (`data-empty`).
+ */
+export declare const pickerTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background justify-start data-[empty=true]:text-muted-foreground";
+/** Calendar popover body: fits the viewport height and scrolls inside it. */
+export declare const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
+/** Gutter used when a calendar popover collides with the viewport. */
+export declare const PICKER_COLLISION_PADDING = 16;

package/dist/internal/form-control.js

@@ -7,3 +7,12 @@
  * outline Button's purple selected wash.
  */
 export const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
+/**
+ * Date and date-time picker trigger: the form-control chrome, start-aligned,
+ * with muted text while empty (`data-empty`).
+ */
+export const pickerTriggerClassName = `${formControlTriggerClassName} justify-start data-[empty=true]:text-muted-foreground`;
+/** Calendar popover body: fits the viewport height and scrolls inside it. */
+export const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
+/** Gutter used when a calendar popover collides with the viewport. */
+export const PICKER_COLLISION_PADDING = 16;

package/dist/internal/listbox-navigation.d.ts

@@ -0,0 +1,14 @@
+/** Return the next highlighted index for a listbox navigation key. */
+export declare function moveListboxHighlight(key: string, index: number, length: number): number | undefined;
+/**
+ * Option id for `aria-activedescendant`. Index-based because option values
+ * may contain spaces, which are not valid in an id reference.
+ */
+export declare function listboxOptionId(listId: string, index: number): string;
+/**
+ * Callback ref for the highlighted option. It runs when the option mounts
+ * (including when a popover first renders the list) and when the highlight
+ * moves, keeping the option in view inside the overflow list. Module-level,
+ * so the ref is stable without `useCallback`.
+ */
+export declare function scrollOptionIntoView(node: HTMLElement | null): void;

package/dist/internal/listbox-navigation.js

@@ -0,0 +1,37 @@
+/** Page keys move ten rows, a little more than one max-h-60 list viewport. */
+const PAGE_SIZE = 10;
+/** Return the next highlighted index for a listbox navigation key. */
+export function moveListboxHighlight(key, index, length) {
+    switch (key) {
+        case "ArrowDown":
+            return length === 0 ? 0 : Math.min(index + 1, length - 1);
+        case "ArrowUp":
+            return Math.max(index - 1, 0);
+        case "Home":
+            return 0;
+        case "End":
+            return length === 0 ? 0 : length - 1;
+        case "PageDown":
+            return length === 0 ? 0 : Math.min(index + PAGE_SIZE, length - 1);
+        case "PageUp":
+            return Math.max(index - PAGE_SIZE, 0);
+        default:
+            return undefined;
+    }
+}
+/**
+ * Option id for `aria-activedescendant`. Index-based because option values
+ * may contain spaces, which are not valid in an id reference.
+ */
+export function listboxOptionId(listId, index) {
+    return `${listId}-option-${index}`;
+}
+/**
+ * Callback ref for the highlighted option. It runs when the option mounts
+ * (including when a popover first renders the list) and when the highlight
+ * moves, keeping the option in view inside the overflow list. Module-level,
+ * so the ref is stable without `useCallback`.
+ */
+export function scrollOptionIntoView(node) {
+    node?.scrollIntoView({ block: "nearest" });
+}

package/dist/internal/styles.d.ts

@@ -37,6 +37,8 @@ export declare const selectedState: {
     /** Quiet buttons and toggles on hover. */
     hover: string;
 };
+/** The "No results" row of a listbox. */
+export declare const listboxEmpty = "px-3 py-4 text-center text-sm text-muted-foreground";
 /** Options in menus and listboxes. */
 export declare const optionState: {
     /** Highlight as focus moves: grey fill plus a 2px ring bar (the fill alone is 1.1:1). */

package/dist/internal/styles.js

@@ -37,6 +37,8 @@ export const selectedState = {
     /** Quiet buttons and toggles on hover. */
     hover: "hover:border-selected-foreground hover:bg-selected hover:text-selected-foreground",
 };
+/** The "No results" row of a listbox. */
+export const listboxEmpty = "px-3 py-4 text-center text-sm text-muted-foreground";
 /** Options in menus and listboxes. */
 export const optionState = {
     /** Highlight as focus moves: grey fill plus a 2px ring bar (the fill alone is 1.1:1). */

package/dist/search-picker.js

@@ -3,9 +3,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Input } from "./input.js";
 import { Label } from "./label.js";
-import { optionState } from "./internal/styles.js";
+import { listboxOptionId, moveListboxHighlight, scrollOptionIntoView, } from "./internal/listbox-navigation.js";
+import { listboxEmpty, optionState } from "./internal/styles.js";
 import { cn } from "./utils.js";
-const LISTBOX_PAGE_SIZE = 10;
 /**
  * Case-fold and strip combining marks so "nino" matches "Niño".
  */
@@ -30,50 +30,48 @@ function SearchPicker({ items, getValue, getLabel, filter = defaultSearchFilter,
     const [query, setQuery] = React.useState("");
     const listId = React.useId();
     const inputId = React.useId();
-    const filtered = React.useMemo(() => items.filter((item) => filter(item, query, getLabel)), [items, filter, query, getLabel]);
+    const normalizedItems = React.useMemo(() => filter === defaultSearchFilter
+        ? items.map((item) => [item, foldSearchText(getLabel(item))])
+        : null, [filter, getLabel, items]);
+    const foldedQuery = filter === defaultSearchFilter ? foldSearchText(query.trim()) : "";
+    const filtered = React.useMemo(() => {
+        if (normalizedItems) {
+            if (!foldedQuery)
+                return items;
+            return normalizedItems
+                .filter(([, label]) => label.includes(foldedQuery))
+                .map(([item]) => item);
+        }
+        return items.filter((item) => filter(item, query, getLabel));
+    }, [items, filter, foldedQuery, getLabel, normalizedItems, query]);
     const selectedIndex = React.useMemo(() => {
         const index = filtered.findIndex((item) => getValue(item) === value);
         return index >= 0 ? index : 0;
     }, [filtered, getValue, value]);
     const [highlight, setHighlight] = React.useState(selectedIndex);
-    React.useEffect(() => {
+    // Reset the highlight while rendering, not in an effect, when the query or
+    // the selected row changes: an effect commits every keystroke twice, once
+    // with the stale highlight and again with the reset.
+    const [highlightFor, setHighlightFor] = React.useState({
+        query,
+        selectedIndex,
+    });
+    if (highlightFor.query !== query ||
+        highlightFor.selectedIndex !== selectedIndex) {
+        setHighlightFor({ query, selectedIndex });
         setHighlight(query ? 0 : selectedIndex);
-    }, [query, selectedIndex]);
-    const optionId = (index) => `${listId}-option-${index}`;
+    }
     const active = filtered[highlight];
-    const scrollHighlightedOption = React.useCallback((node) => {
-        node?.scrollIntoView({ block: "nearest" });
-    }, []);
     const selectItem = (item) => {
         onSelect(item);
         setQuery("");
     };
     const onKeyDown = (event) => {
-        if (event.key === "ArrowDown") {
-            event.preventDefault();
-            setHighlight((index) => filtered.length === 0 ? 0 : Math.min(index + 1, filtered.length - 1));
-        }
-        if (event.key === "ArrowUp") {
-            event.preventDefault();
-            setHighlight((index) => Math.max(index - 1, 0));
-        }
-        if (event.key === "Home") {
-            event.preventDefault();
-            setHighlight(0);
-        }
-        if (event.key === "End") {
-            event.preventDefault();
-            setHighlight(filtered.length === 0 ? 0 : filtered.length - 1);
-        }
-        if (event.key === "PageDown") {
-            event.preventDefault();
-            setHighlight((index) => filtered.length === 0
-                ? 0
-                : Math.min(index + LISTBOX_PAGE_SIZE, filtered.length - 1));
-        }
-        if (event.key === "PageUp") {
+        const nextHighlight = moveListboxHighlight(event.key, highlight, filtered.length);
+        if (nextHighlight !== undefined) {
             event.preventDefault();
-            setHighlight((index) => Math.max(index - LISTBOX_PAGE_SIZE, 0));
+            setHighlight(nextHighlight);
+            return;
         }
         if (event.key === "Enter") {
             event.preventDefault();
@@ -89,11 +87,11 @@ function SearchPicker({ items, getValue, getLabel, filter = defaultSearchFilter,
             event.currentTarget.blur();
         }
     };
-    return (_jsxs("div", { "data-slot": "search-picker", className: cn("flex flex-col gap-1.5", className), children: [_jsx(Label, { htmlFor: inputId, children: label }), _jsx(Input, { id: inputId, role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": active ? optionId(highlight) : undefined, value: query, disabled: disabled, placeholder: placeholder, onChange: (event) => setQuery(event.target.value), onKeyDown: onKeyDown }), _jsx("ul", { id: listId, role: "listbox", "aria-label": listLabel ?? label, className: "max-h-60 overflow-y-auto border border-input bg-background", children: filtered.length === 0 ? (_jsx("li", { className: "px-3 py-4 text-center text-sm text-muted-foreground", children: emptyText })) : (filtered.map((item, index) => {
+    return (_jsxs("div", { "data-slot": "search-picker", className: cn("flex flex-col gap-1.5", className), children: [_jsx(Label, { htmlFor: inputId, children: label }), _jsx(Input, { id: inputId, role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": active ? listboxOptionId(listId, highlight) : undefined, value: query, disabled: disabled, placeholder: placeholder, onChange: (event) => setQuery(event.target.value), onKeyDown: onKeyDown }), _jsx("ul", { id: listId, role: "listbox", "aria-label": listLabel ?? label, className: "max-h-60 overflow-y-auto border border-input bg-background", children: filtered.length === 0 ? (_jsx("li", { className: listboxEmpty, children: emptyText })) : (filtered.map((item, index) => {
                     const itemValue = getValue(item);
                     const isSelected = itemValue === value;
                     const isActive = index === highlight;
-                    return (_jsx("li", { role: "none", children: _jsx("button", { ref: isActive ? scrollHighlightedOption : undefined, id: optionId(index), type: "button", role: "option", "aria-selected": isSelected, disabled: disabled, className: cn("relative flex w-full cursor-default items-center rounded-none py-2 pr-3 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active, isActive &&
+                    return (_jsx("li", { role: "none", children: _jsx("button", { ref: isActive ? scrollOptionIntoView : undefined, id: listboxOptionId(listId, index), type: "button", role: "option", "aria-selected": isSelected, disabled: disabled, className: cn("relative flex w-full cursor-default items-center rounded-none py-2 pr-3 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active, isActive &&
                                 !isSelected &&
                                 "bg-accent text-accent-foreground"), onMouseEnter: () => setHighlight(index), onClick: () => selectItem(item), children: _jsx("span", { className: "truncate", children: getLabel(item) }) }) }, itemValue));
                 })) })] }));

package/dist/select.js

@@ -5,6 +5,7 @@ import { Select as SelectPrimitive } from "radix-ui";
 import { dataDisabledState, disabledState, fieldSurface, focusRing, invalidState, optionState, } from "./internal/styles.js";
 import { cn } from "./utils.js";
 import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react";
+const scrollButtonClassName = "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5";
 function Select({ ...props }) {
     return _jsx(SelectPrimitive.Root, { "data-slot": "select", ...props });
 }
@@ -19,7 +20,7 @@ function SelectTrigger({ className, size = "default", children, ...props }) {
 }
 function SelectContent({ className, children, position = "popper", align = "center", sideOffset = 4, collisionPadding = 8, ...props }) {
     return (_jsx(SelectPrimitive.Portal, { children: _jsxs(SelectPrimitive.Content, { "data-slot": "select-content", "data-align-trigger": position === "item-aligned", className: cn("relative z-50 max-h-(--radix-select-content-available-height) min-w-(--radix-select-trigger-width) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-none bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", position === "popper" &&
-                "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className), position: position, align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, ...props, children: [_jsx(SelectScrollUpButton, {}), _jsx(SelectPrimitive.Viewport, { "data-position": position, className: cn("data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)", position === "popper" && ""), children: children }), _jsx(SelectScrollDownButton, {})] }) }));
+                "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className), position: position, align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, ...props, children: [_jsx(SelectScrollUpButton, {}), _jsx(SelectPrimitive.Viewport, { "data-position": position, className: "data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)", children: children }), _jsx(SelectScrollDownButton, {})] }) }));
 }
 function SelectLabel({ className, ...props }) {
     return (_jsx(SelectPrimitive.Label, { "data-slot": "select-label", className: cn("px-3 py-2 text-xs font-semibold tracking-wider text-muted-foreground uppercase", className), ...props }));
@@ -31,9 +32,9 @@ function SelectSeparator({ className, ...props }) {
     return (_jsx(SelectPrimitive.Separator, { "data-slot": "select-separator", className: cn("pointer-events-none -mx-1.5 my-1.5 h-px bg-border/50", className), ...props }));
 }
 function SelectScrollUpButton({ className, ...props }) {
-    return (_jsx(SelectPrimitive.ScrollUpButton, { "data-slot": "select-scroll-up-button", className: cn("z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5", className), ...props, children: _jsx(ChevronUpIcon, {}) }));
+    return (_jsx(SelectPrimitive.ScrollUpButton, { "data-slot": "select-scroll-up-button", className: cn(scrollButtonClassName, className), ...props, children: _jsx(ChevronUpIcon, {}) }));
 }
 function SelectScrollDownButton({ className, ...props }) {
-    return (_jsx(SelectPrimitive.ScrollDownButton, { "data-slot": "select-scroll-down-button", className: cn("z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5", className), ...props, children: _jsx(ChevronDownIcon, {}) }));
+    return (_jsx(SelectPrimitive.ScrollDownButton, { "data-slot": "select-scroll-down-button", className: cn(scrollButtonClassName, className), ...props, children: _jsx(ChevronDownIcon, {}) }));
 }
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, };

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { ChangeEvent } from "react";
 import { type ClassValue } from "clsx";
 export declare function cn(...inputs: ClassValue[]): string;
-/** Stable onChange handler for controlled text inputs (satisfies react/jsx-no-bind). */
+/** Read the next value from an input event for a controlled text field. */
 export declare function onInputChange(setValue: (value: string) => void): (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;

package/dist/utils.js

@@ -3,7 +3,7 @@ import { twMerge } from "tailwind-merge";
 export function cn(...inputs) {
     return twMerge(clsx(inputs));
 }
-/** Stable onChange handler for controlled text inputs (satisfies react/jsx-no-bind). */
+/** Read the next value from an input event for a controlled text field. */
 export function onInputChange(setValue) {
     return (e) => {
         setValue(e.target.value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas-react-kit",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Shared React components and Tailwind theme for Atlas",
   "type": "module",
   "license": "MIT",
@@ -243,7 +243,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "check": "npm run build && prettier --check .",
+    "check": "npm run build && npm run docs:check && prettier --check .",
+    "docs:check": "node scripts/check-doc-links.mjs",
     "test": "npm run build && vitest run",
     "test:coverage": "npm run build && vitest run --coverage",
     "prepack": "npm run build"
@@ -263,6 +264,7 @@
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
     "sonner": "^2.0.7",
     "tailwindcss": "^4.0.0"
   },
@@ -319,6 +321,7 @@
     "sonner": "^2.0.7",
     "tailwindcss": "^4.2.1",
     "typescript": "^6.0.3",
+    "unified": "^11.0.5",
     "vitest": "^4.1.9"
   }
 }

package/skills/atlas-react-kit/SKILL.md

@@ -56,7 +56,7 @@ Import each component from its subpath, e.g.
 | Need                                            | Use                                                                                                                     |
 | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
 | Short fixed list (a handful of options)         | `Select` family from `select`                                                                                           |
-| Long or searchable list (timezones, currencies) | `Combobox` from `combobox` with `{ value, label }[]` options                                                            |
+| Long or searchable list (timezones, currencies) | `Combobox` from `combobox` with `{ value, label }[]` options; set `creatable` to invent a value the catalog lacks       |
 | Always-visible searchable list (places)         | `SearchPicker` from `search-picker`                                                                                     |
 | One date, or a from/to range                    | `DatePickerButton` from `date-picker` (`mode="range"` for ranges)                                                       |
 | Date and time (not `datetime-local`)            | `DateTimePickerButton` from `date-time-picker`                                                                          |
@@ -97,42 +97,12 @@ buttons). Don't copy that style into new UI. Move what the task touches onto kit
 components and tokens, and mention the rest to the user instead of rewriting
 files the task doesn't need.
 
-## 4. Style with tokens, not values
-
-These rules are what make Atlas look like Atlas. `DESIGN_RULES.md` has the full
-list; the ones that come up most:
-
-- **Semantic colors only**: `bg-primary`, `text-muted-foreground`,
-  `border-border`, `bg-card`, `text-destructive`. Raw palette classes
-  (`bg-purple-600`, `text-gray-500`) and paired `dark:` colors drift from the
-  theme; tokens already switch with light and dark.
-- **Selected and active state**: `bg-selected text-selected-foreground` plus
-  a `border-selected-foreground` border (or bar) for the current nav item,
-  chip, row, or toggle; the wash alone is too faint to show state. Grey fills
-  read as hover, not selection.
-- **Status**: `success`, `warning`, and `destructive` for good, caution, and
-  bad. Use them as text or soft tints (the `Badge` tones), which meet AA in
-  both themes. Don't override a soft badge's colors. There is no foreground
-  token for text on a solid status fill, so avoid that combination.
-- **Brand-colored text**: `text-selected-foreground`, not `text-primary`,
-  which is too dark to read on the dark background.
-- **Accessibility**: the kit targets WCAG 2.2 AA. Give every control a name
-  (`Label htmlFor`, or `aria-label` on icon-only buttons and an unlabelled
-  `Combobox`), keep the shipped focus rings (solid `ring-ring`, never
-  `ring-ring/30`), keep field borders on `border-input` (3:1; `border-border`
-  is for dividers), and don't lower contrast with raw colors or opacity.
-- **Square corners**: primitives have none. Use `rounded-full` only for real
-  circles (avatars, dots). Adding `rounded-md` to a card or button breaks the
-  system.
-- **Don't restyle kit controls**: `Input`, `SelectTrigger`, `DatePickerButton`,
-  `DateTimePickerButton`, and `Combobox` share 40px form-control chrome.
-  Overriding their height, padding, or border makes one field look different
-  from its neighbors.
-- **Layout overrides**: `CardContent className="px-0"` makes one section flush
-  without `!important`. Tables and tab rows already scroll horizontally, so do
-  not wrap them in another overflow container.
-- **Headings**: `CardTitle` and `DialogTitle` already apply the uppercase,
-  tracked heading style; use `font-heading` for other headings.
+## 4. Follow the design rules
+
+Use semantic tokens and the shipped component APIs. Avoid raw palette color
+classes and rounded corners on square primitives; do not restyle kit controls.
+For accessibility, copy, selection, status, and layout details, follow the
+matching sections in `DESIGN_RULES.md`; it is the source of truth.
 
 ## 5. Check before you finish