atlas-react-kit 0.9.1 → 0.9.3

package/COMPONENTS.md

@@ -5,6 +5,11 @@ 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).
+
+## 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 +34,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`,
@@ -85,7 +88,9 @@ still read normal words.
 Primitives have square corners. Reserve `rounded-full` for dots, avatars,
 other circles, and the toast close badge. Card and dialog titles already use
 uppercase, tracked `font-heading` styling. Toasts are overlay popovers with
-the same square corners and Alert padding (`px-4 py-3`). The close control is
+the same square corners and Alert left/vertical padding (`pl-4 py-3`). Right
+padding is `pr-6` so copy clears the floating close badge. Icon-to-text is
+`gap-x-2.5` so the status icon and copy read as one unit. The close control is
 a circular badge centred on the top-right corner (half outside the border),
 not a control in the text row. A plain `toast()` has no icon — status icons
 belong to `success`, `info`, `warning`, `error`, and `loading`. Tone colors

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.1
+npm install --save-exact atlas-react-kit@0.9.3
 ```
 
 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.1.tgz --access public
+npm publish ./release-artifacts/atlas-react-kit-0.9.3.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 { moveListboxHighlight } from "./internal/listbox-navigation.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { 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(() => {
@@ -73,46 +117,25 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
     // 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 ? optionId(highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", className: "max-h-60 overflow-y-auto p-1", children: list.length === 0 ? (_jsx("li", { className: "px-3 py-4 text-center text-sm text-muted-foreground", 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 ? 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] }) }, isCreate ? CREATE_OPTION_KEY : option.value));
                         })) })] })] }));
 }

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

@@ -0,0 +1,2 @@
+/** Return the next highlighted index for a listbox navigation key. */
+export declare function moveListboxHighlight(key: string, index: number, length: number): number | undefined;

package/dist/internal/listbox-navigation.js

@@ -0,0 +1,21 @@
+/** 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;
+    }
+}

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 { moveListboxHighlight } from "./internal/listbox-navigation.js";
 import { 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,7 +30,20 @@ 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;
@@ -49,31 +62,11 @@ function SearchPicker({ items, getValue, getLabel, filter = defaultSearchFilter,
         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();

package/dist/toast.js

@@ -51,13 +51,18 @@ const toast = Object.assign(show(sonnerToast), {
  * popover fill, border, and muted text beat those fills. The 24px hit area
  * is the badge itself; the X is 12px. `overflow-visible` on the toast and
  * toaster keeps stacked badges from being clipped.
+ *
+ * Padding is asymmetric: `pl-4` matches Alert; `pr-6` clears the badge
+ * (about 16px of it sits inside the border). Icon-to-text is `gap-x-2.5`
+ * so the status icon and copy read as one unit.
  */
 const classNames = {
-    toast: "relative flex w-max max-w-[min(356px,calc(100vw-2rem))] flex-wrap items-center justify-end gap-x-3 gap-y-2 overflow-visible rounded-none border border-border bg-popover px-4 py-3 text-sm text-popover-foreground shadow-md",
+    toast: "relative flex w-max max-w-[min(356px,calc(100vw-2rem))] flex-wrap items-center justify-end gap-x-2.5 gap-y-2 overflow-visible rounded-none border border-border bg-popover py-3 pl-4 pr-6 text-sm text-popover-foreground shadow-md",
     // Fills the row beside the icon, so action buttons wrap to their own row
     // (aligned right by the toast's justify-end). Without an icon the basis
     // falls back to the title's width, so a one-word toast stays compact.
-    content: "flex min-w-0 flex-1 basis-full flex-col gap-1 [[data-icon]+&]:basis-[calc(100%-1.75rem)]",
+    // 1.625rem = 16px icon + 10px gap-x-2.5.
+    content: "flex min-w-0 flex-1 basis-full flex-col gap-1 [[data-icon]+&]:basis-[calc(100%-1.625rem)]",
     title: "font-medium leading-5",
     description: "leading-5 text-muted-foreground",
     icon: "flex size-4 shrink-0 items-center justify-center [&_svg]:size-4",

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.1",
+  "version": "0.9.3",
   "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