atlas-react-kit 0.13.0 → 1.0.0

package/COMPONENTS.md

@@ -20,71 +20,81 @@ 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/nav-link`, `next/tabs-nav-link`                                                                  | `npm i next@^16.0.0`                             |
-
-| Subpath                       | Main exports and options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `accordion`                   | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`; Radix `type` `single` (with `collapsible`) or `multiple`                                                                                                                                                                                                                                                                                                                                                                               |
-| `alert`                       | `Alert`, `AlertTitle`, `AlertDescription`, `alertVariants`; `variant` `default`, `success`, `warning`, `destructive`; tone on title and icon, body stays muted; destructive is `role="alert"`                                                                                                                                                                                                                                                                                                                |
-| `avatar`                      | `Avatar`, `AvatarImage`, `AvatarFallback`; `size` `sm`, `default`, `lg`; round by design                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `breadcrumb`                  | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink` (`asChild` for router links), `BreadcrumbPage` (`aria-current`), `BreadcrumbSeparator`, `BreadcrumbEllipsis`                                                                                                                                                                                                                                                                                                                              |
-| `button`                      | `Button`, `buttonVariants`, `quietButtonInteraction`; `variant`, `size`, `asChild`; outline/ghost hover is brand purple + selected wash, not muted grey                                                                                                                                                                                                                                                                                                                                                      |
-| `badge`                       | `Badge`, `badgeVariants`; `variant`, `tone`, `asChild`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `calendar`                    | `Calendar`, `CalendarDayButton`; React Day Picker props and `buttonVariant`                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `card`                        | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`; `Card` supports `flush`; `CardTitle as="h2"` (up to `h4`) makes it a section heading; 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, `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`, and the kit's own `DateRange`, `DateMatcher`, `DateLike`, and `DatePickerCalendarProps` types (no Day Picker types); `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+`), `minDate` / `maxDate` (days outside are disabled), `side`, `aria-labelledby`, and `aria-describedby`            |
-| `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`                                                                                                                                                                                                                                                                                                                                                                           |
-| `dropdown-menu`               | `DropdownMenu` family (trigger, content, item, checkbox/radio items, label, separator, shortcut, sub menus); item `variant="destructive"` and `inset`; for commands, not values                                                                                                                                                                                                                                                                                                                              |
-| `empty-panel`                 | `EmptyPanel`; required `children`; optional `size`, `muted`, `className`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `error-boundary`              | `ErrorBoundary`, `ErrorFallback`; optional `message`; retry resets, reload refreshes the page                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `field`                       | Field, label, legend, description, group, set, title, content, separator, error; `Field` supports `orientation`                                                                                                                                                                                                                                                                                                                                                                                              |
-| `info-tip`                    | `InfoTip`, `InlineTip`; required `label` (aria-label); `title`, `description`, `children`, `layout` `box` \| `inline`, `side`, `align`, `badge`, `icon`, `className`. Popover, 20px glyph, 44px hit. Hover opens only on a fine pointer. Not a Tooltip.                                                                                                                                                                                                                                                      |
-| `input`, `textarea`, `label`  | `Input`, `Textarea`, `Label`; `Label` `required` shows a visible marker (set `required` on the control too)                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `markdown`                    | `Markdown`, `MarkdownContent`; `content`, optional `className`. GFM via `react-markdown` + `remark-gfm` in this subpath only. Sanitized (no raw HTML; http/https/mailto/#/`/` URLs). Token styles, no typography plugin.                                                                                                                                                                                                                                                                                     |
-| `meter`                       | `Meter`; `value`, `max`, optional `min` (default 0), `fillClassName`, `markers` as `{ position, className? }[]`, required `aria-label`, `className`. `role="meter"`. Not `Progress`.                                                                                                                                                                                                                                                                                                                         |
-| `nav-link`                    | `NavLink`, `navLinkVariants`; required `active` boolean, `asChild` for router links. Pill chrome: inactive `text-muted-foreground` + `hover:bg-accent`, active selected wash. No router.                                                                                                                                                                                                                                                                                                                     |
-| `pagination`                  | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink` (`isActive` sets `aria-current`, the selected wash, and a selected border; `disabled` drops the `href` for a page that does not exist, such as Previous on page 1), `PaginationPrevious`, `PaginationNext` (custom text becomes the link name), `PaginationEllipsis`                                                                                                                                                                   |
-| `popover`                     | `Popover`, trigger, anchor, content, header, title, description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `progress`                    | `Progress`; Radix props, `value` 0–100; label it with `aria-label` or `aria-labelledby`. For a value against a scale with ticks, use `Meter`.                                                                                                                                                                                                                                                                                                                                                                |
-| `radio-group`                 | `RadioGroup`, `RadioGroupItem`; short visible lists; arrow keys move the selection; round dots                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `search-picker`               | `SearchPicker<T>`; always-visible combobox + listbox; `items`, `getValue`, `getLabel`, optional `filter` (default casefold + accent-fold includes), `value`, `onSelect`, `label`, `placeholder`, `emptyText`, `listLabel`, `disabled`, `className`. Arrows, Home/End, PageUp/PageDown, Enter, Escape.                                                                                                                                                                                                        |
-| `select`                      | Select, trigger, value, content, group, label, item, separator, scroll buttons; trigger `size`; trigger text is `text-base md:text-sm` like Input                                                                                                                                                                                                                                                                                                                                                            |
-| `separator`, `skeleton`       | `Separator`, `Skeleton`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `slider`                      | `Slider`; `value` number, `onValueChange`, optional `onValueCommit`, `min`, `max`, `step`, `disabled`, `id`, `aria-labelledby`, `className`. Radix Slider; 44px thumb hit; square track; primary fill. Name it with `aria-labelledby`.                                                                                                                                                                                                                                                                       |
-| `sortable-table-head`         | `SortableTableHead`; `sorted`, `direction` (`asc` \                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `spinner`                     | `Spinner`; `role="status"` with `aria-label` (default `Loading`)                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `stat-tile`                   | `StatTile`, `statTileGrid`, `sectionLabel`; `label`, `value`, optional `sub`, `children`, `className`.                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `switch`                      | `Switch`; settings that apply immediately; square track and thumb                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `table`                       | Table, header, body, footer, row, head, cell, caption; root scroller is `min-w-0 overflow-x-auto` with a fade cue; cells are `px-2` below `sm`                                                                                                                                                                                                                                                                                                                                                               |
-| `table-body-skeleton`         | `TableBodySkeleton`; `columns`, optional `rows` (default 5)                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `tabs`                        | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabsNav`, `tabsListVariants`, `tabsTriggerVariants`; list `variant` is `default` or `line`; style `TabsNav` links with `tabsTriggerVariants()`; `TabsNav` / `TabsList` scroll horizontally only (`overflow-y` hidden, `p-1` counted in the scroller height, edge fade, active item into view) — do not wrap them in `overflow-x-auto`                                                                                                                     |
-| `toast`                       | `Toaster`, `toast`; mount one `Toaster` (`position`, `closeButton` (default on), `expand`, `visibleToasts`, `duration`), then `toast(message, options)`. The stack expands on hover and while keyboard focus is inside it; collapsed toasts behind the front one are hidden, `.success`, `.info`, `.warning`, `.error`, `.loading`, `.dismiss(id?)`. Options: `id` (replaces that toast), `description`, `duration`, `action` / `cancel` as `{ label, onClick }`. Kit-owned API: no toast library is exposed |
-| `toggle`                      | `Toggle`, `toggleVariants`, `selectedToggleChrome`; `variant`, `size`. Pressed state is the selected wash, text, and border via `data-state=on`, `aria-pressed`, and `aria-checked`                                                                                                                                                                                                                                                                                                                          |
-| `toggle-group`                | `ToggleGroup`, `ToggleGroupItem`; `variant`, `size`. Items share `toggleVariants`, so single (radio) and multiple selections match a pressed `Toggle`                                                                                                                                                                                                                                                                                                                                                        |
-| `theme-provider`              | `ThemeProvider`, `useTheme`; optional `storageKey` (default `atlas-theme`), `enableShortcut` for the `d` toggle                                                                                                                                                                                                                                                                                                                                                                                              |
-| `tooltip`                     | `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`; opens on hover and focus; short labels only                                                                                                                                                                                                                                                                                                                                                                                                |
-| `form/control-field`          | `FormControlField`, type `FormControlProps`; `label`, optional `id`, `description`, `required`, `meta`, `submitted`, `showError`; `children` renders the control from `{ id, aria-invalid, aria-describedby, aria-required }`                                                                                                                                                                                                                                                                                |
-| `form/markdown-field`         | `FormMarkdownField`; `field` is `TextFieldApi`; `label`, optional `id`, `placeholder`, `rows`, `showError`, `required`. Write / preview; preview uses `Markdown`.                                                                                                                                                                                                                                                                                                                                            |
-| `form/text-field`             | `FormTextField`, type `TextFieldApi`; controlled field, label, multiline, description, input constraints; `required` also marks the label                                                                                                                                                                                                                                                                                                                                                                    |
-| `form/select-field`           | `FormSelectField`; `value`, `onValueChange`, `label`, optional `meta`, placeholder, and `required`; select item children                                                                                                                                                                                                                                                                                                                                                                                     |
-| `form/date-picker-field`      | `FormDatePickerField`; `value`, `onValueChange`, `label`, optional `meta`, placeholder, `required`, `minDate` / `maxDate`, and `className` (forwarded to the trigger)                                                                                                                                                                                                                                                                                                                                        |
-| `form/date-time-picker-field` | `FormDateTimePickerField`; `value` is `Date` or `null`; `onValueChange` emits `Date` or `null`; optional `meta`, placeholder, `timeStep`, `required`, `minDate` / `maxDate`, and `className` (forwarded to the trigger)                                                                                                                                                                                                                                                                                      |
-| `form/field-error`            | `FieldError` (optional `id`), `getFieldErrorMessage`; types `FieldErrorMessage`, `FieldMetaState`, `ErrorTimingProps`                                                                                                                                                                                                                                                                                                                                                                                        |
-| `form/feedback-field`         | `FormFeedbackField`; nullable `message`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `next/nav-link`               | `NavLink`; Next Link props and required `active` boolean; same pill as `nav-link`; requires Next.js 16                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `next/tabs-nav-link`          | `TabsNavLink`; Next Link props and required `active` boolean; requires Next.js 16                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `utils`                       | `cn`, `onInputChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `theme.css`                   | Tailwind 4 theme; installation in [README](./README.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| 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`  |
+| `kanban`                                                                                               | `npm i @dnd-kit/react@^0.4.0 @dnd-kit/dom@^0.4.0` |
+| `theme-provider`                                                                                       | `npm i next-themes@^0.4.6`                        |
+| `toast`                                                                                                | `npm i sonner@^2.0.7 next-themes@^0.4.6`          |
+| `next/nav-link`, `next/period-stepper`, `next/tabs-nav-link`                                           | `npm i next@^16.0.0`                              |
+
+| Subpath                       | Main exports and options                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `accordion`                   | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`; Radix `type` `single` (with `collapsible`) or `multiple`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `alert`                       | `Alert`, `AlertTitle`, `AlertDescription`, `alertVariants`; `variant` `default`, `success`, `warning`, `destructive`; tone on title and icon, body stays muted; destructive is `role="alert"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `avatar`                      | `Avatar`, `AvatarImage`, `AvatarFallback`; `size` `sm`, `default`, `lg`; round by design                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `breadcrumb`                  | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink` (`asChild` for router links), `BreadcrumbPage` (`aria-current`), `BreadcrumbSeparator`, `BreadcrumbEllipsis`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `button`                      | `Button`, `buttonVariants`, `quietButtonInteraction`; `variant`, `size`, `asChild`; outline/ghost hover is brand purple + selected wash, not muted grey                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `badge`                       | `Badge`, `badgeVariants`; `variant`, `tone`, `asChild`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `calendar`                    | `Calendar`, `CalendarDayButton`; React Day Picker props and `buttonVariant`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `card`                        | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`; `Card` supports `flush`; `CardTitle as="h2"` (up to `h4`) makes it a section heading; 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 `!`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `chart`                       | `chartFrame(height, { width?, padding? })` (viewBox and plot box: `left`, `right`, `top`, `bottom`, `plotWidth`, `plotHeight`, `viewBox`), `niceCeil`, `niceTicks`, `scaleLinear`, `linePath`, `roundedTopBarPath`, `compactNumber`, `indexAtPlotX`, `stepIndex`, `useChartScrub({ frame, steps, min, max })` (pointer and arrow-key crosshair; Escape clears), `ChartYAxisGrid` (`frame`, `yMax`, optional `tickCount`, `format`), `ChartTooltip` (`xPct`, `yPct`; `role="status"`; flips left past 55%), `ChartTooltipRow`, `ChartLegend`, `ChartLegendKey` (`swatchClassName`, `dashed`). No chart library; draw the series in your own `<svg>`.                                                                                                                                                                                                                                                                     |
+| `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, `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`, and the kit's own `DateRange`, `DateMatcher`, `DateLike`, and `DatePickerCalendarProps` types (no Day Picker types); `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+`), `minDate` / `maxDate` (days outside are disabled), `side`, `aria-labelledby`, and `aria-describedby`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `date-time-picker`            | `DateTimePickerButton`, `resolveTimeStep`, `DEFAULT_TIME_STEP`; controlled `value` is `Date` or `null`; `onValueChange` emits `Date \                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `dialog`                      | `Dialog`, trigger, portal, overlay, content, close, header, footer, title, description; `DialogContent` supports `showCloseButton`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `dropdown-menu`               | `DropdownMenu` family (trigger, content, item, checkbox/radio items, label, separator, shortcut, sub menus); item `variant="destructive"` and `inset`; for commands, not values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `empty-panel`                 | `EmptyPanel`; required `children`; optional `size` (`sm`, `default`, `lg`), `muted`, `className`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `error-boundary`              | `ErrorBoundary`, `ErrorFallback`; optional `message`; retry resets, reload refreshes the page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `field`                       | Field, label, legend, description, group, set, title, content, separator, error; `Field` supports `orientation`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `info-tip`                    | `InfoTip`, `InlineTip`; required `label` (aria-label); `title`, `description`, `children`, `layout` `box` \| `inline`, `side`, `align`, `badge`, `icon`, `className`. Popover, 20px glyph, 44px hit. Hover opens only on a fine pointer. Not a Tooltip.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `kanban`                      | `KanbanBoard<T>`, `KanbanSkeleton`, `KanbanColumn` and `KanbanDropTarget` types; `columns` (`{ id, label, color?, badge?, emptyLabel? }`), `items` (`{ id, position }`), `getColumnId`, `onMove(item, toColumnId, { beforePosition, afterPosition })` for every column change or reorder, `renderCard`; optional `onCardClick` (body becomes a button), `onComplete` / `onDelete` (Finish / Remove drop zones while dragging), `isLoading` (skeleton cards on a first load, dimmed board on a refetch), `emptyLabel`, `completeLabel`, `deleteLabel`. Layout comes from `items`, so an optimistic cache update is the only state. Keep `renderCard` and `onCardClick` stable (`useCallback`) and only the changed card re-renders. Cards drag by the grip (`Drag to move`); dnd-kit edge-scrolls while dragging, and off-screen columns get fades and scroll buttons. `KanbanSkeleton` takes `columnCount` (default 4). |
+| `input`, `textarea`, `label`  | `Input`, `Textarea`, `Label`; `Label` `required` shows a visible marker (set `required` on the control too)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `markdown`                    | `Markdown`, `MarkdownContent`; `content`, optional `className`. GFM via `react-markdown` + `remark-gfm` in this subpath only. Sanitized (no raw HTML; http/https/mailto/#/`/` URLs). Token styles, no typography plugin.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `meter`                       | `Meter`; `value`, `max`, optional `min` (default 0), `fillClassName`, `markers` as `{ position, className? }[]`, required `aria-label`, `className`. `role="meter"`. Not `Progress`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `nav-link`                    | `NavLink`, `navLinkVariants`; required `active` boolean, `asChild` for router links. Pill chrome: inactive `text-muted-foreground` + `hover:bg-accent`, active selected wash. No router.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `page-header`                 | `PageHeader`; `title`, optional `description`, `actions`, `children` (under the description), `titleAs` (`h1` default), `titleClassName`. Stacks below `sm`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `pagination`                  | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink` (`isActive` sets `aria-current`, the selected wash, and a selected border; `disabled` drops the `href` for a page that does not exist, such as Previous on page 1), `PaginationPrevious`, `PaginationNext` (custom text becomes the link name), `PaginationEllipsis`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `period-stepper`              | `PeriodStepper`; `label` (announced with `aria-live`), `stepLabel` ("month" names "Previous month"), `onPrevious`, `onNext`, optional `onToday` (no Today button without it), `labelClassName`. `PeriodStepperFrame` takes a `control(step, content)` render for another router's links. `next/period-stepper` takes `previousHref`, `todayHref`, `nextHref` instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `popover`                     | `Popover`, trigger, anchor, content, header, title, description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `progress`                    | `Progress`; Radix props, `value` 0–100; label it with `aria-label` or `aria-labelledby`. For a value against a scale with ticks, use `Meter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `radio-group`                 | `RadioGroup`, `RadioGroupItem`; short visible lists; arrow keys move the selection; round dots                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `search-picker`               | `SearchPicker<T>`; always-visible combobox + listbox; `items`, `getValue`, `getLabel`, optional `filter` (default casefold + accent-fold includes), `value`, `onSelect`, `label`, `placeholder`, `emptyText`, `listLabel`, `disabled`, `className`. Arrows, Home/End, PageUp/PageDown, Enter, Escape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `select`                      | Select, trigger, value, content, group, label, item, separator, scroll buttons; trigger `size`; trigger text is `text-base md:text-sm` like Input                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `separator`, `skeleton`       | `Separator`, `Skeleton`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `skip-link`                   | `SkipLink`; `href` (default `#main-content`), children (default "Skip to content"). Visually hidden until focused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `slider`                      | `Slider`; `value` number, `onValueChange`, optional `onValueCommit`, `min`, `max`, `step`, `disabled`, `id`, `aria-labelledby`, `className`. Radix Slider; 44px thumb hit; square track; primary fill. Name it with `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `sortable-table-head`         | `SortableTableHead`; `sorted`, `direction` (`asc` \                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `spinner`                     | `Spinner`; `role="status"` with `aria-label` (default `Loading`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `stat-tile`                   | `StatTile`, `statTileGrid`, `sectionLabel`; `label`, `value`, optional `sub`, `children`, `className`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `switch`                      | `Switch`; settings that apply immediately; square track and thumb                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `table`                       | Table, header, body, footer, row, head, cell, caption; root scroller is `min-w-0 overflow-x-auto` with a fade cue; cells are `px-2` below `sm`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `table-body-skeleton`         | `TableBodySkeleton`; `columns`, optional `rows` (default 5)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `tabs`                        | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabsNav`, `tabsListVariants`, `tabsTriggerVariants`; list `variant` is `default` or `line`; style `TabsNav` links with `tabsTriggerVariants()`; `TabsNav` / `TabsList` scroll horizontally only (`overflow-y` hidden, `p-1` counted in the scroller height, edge fade, active item into view) — do not wrap them in `overflow-x-auto`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `toast`                       | `Toaster`, `toast`; mount one `Toaster` (`position`, `closeButton` (default on), `expand`, `visibleToasts`, `duration`), then `toast(message, options)`. The stack expands on hover and while keyboard focus is inside it; collapsed toasts behind the front one are hidden, `.success`, `.info`, `.warning`, `.error`, `.loading`, `.dismiss(id?)`. Options: `id` (replaces that toast), `description`, `duration`, `action` / `cancel` as `{ label, onClick }`. Kit-owned API: no toast library is exposed                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `toggle`                      | `Toggle`, `toggleVariants`, `selectedToggleChrome`; `variant`, `size`. Pressed state is the selected wash, text, and border via `data-state=on`, `aria-pressed`, and `aria-checked`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `toggle-group`                | `ToggleGroup`, `ToggleGroupItem`; `variant`, `size`. Items share `toggleVariants`, so single (radio) and multiple selections match a pressed `Toggle`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `theme-provider`              | `ThemeProvider`, `useTheme`; optional `storageKey` (default `atlas-theme`), `enableShortcut` for the `d` toggle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `tooltip`                     | `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`; opens on hover and focus; short labels only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `form/checkbox-field`         | `FormCheckboxField` (`checked`, `onCheckedChange(boolean)`, `label`, optional `description`, `controlPosition` `start` \| `end`, `meta`, `required`, `disabled`, `onBlur`) and `FormCheckboxGroupField<T>` (`label` as legend, `options` `{ value, label }[]`, `value: T[]`, `onValueChange` in option order, `className` lays out the options).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `form/combobox-field`         | `FormComboboxField`; every `Combobox` prop plus `label`, `description`, `meta`, `required`; pass the field's `onBlur`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `form/control-field`          | `FormControlField`, type `FormControlProps`; `label`, optional `id`, `description`, `required`, `meta`, `submitted`, `showError`; `children` renders the control from `{ id, aria-invalid, aria-describedby, aria-required }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `form/markdown-field`         | `FormMarkdownField`; `field` is `TextFieldApi`; `label`, optional `id`, `placeholder`, `rows`, `showError`, `required`. Write / preview; preview uses `Markdown`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `form/text-field`             | `FormTextField`, type `TextFieldApi`; controlled field, label, multiline, description, input constraints; `required` also marks the label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `form/select-field`           | `FormSelectField`; `value`, `onValueChange`, `label`, optional `meta`, placeholder, and `required`; select item children                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `form/date-picker-field`      | `FormDatePickerField`; `value`, `onValueChange`, `label`, optional `meta`, placeholder, `required`, `minDate` / `maxDate`, and `className` (forwarded to the trigger)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `form/date-time-picker-field` | `FormDateTimePickerField`; `value` is `Date` or `null`; `onValueChange` emits `Date` or `null`; optional `meta`, placeholder, `timeStep`, `required`, `minDate` / `maxDate`, and `className` (forwarded to the trigger)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `form/field-error`            | `FieldError` (optional `id`), `getFieldErrorMessage`; types `FieldErrorMessage`, `FieldMetaState`, `ErrorTimingProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `form/feedback-field`         | `FormFeedbackField`; nullable `message`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `form/toggle-group-field`     | `FormToggleGroupField<T>`; one choice from `options` `{ value, label }[]` as a joined outline toggle group named by its label; `value` (`""` for none), `onValueChange(T)` (pressing the active item keeps it), optional `description`, `meta`, `size` (`sm` default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `next/nav-link`               | `NavLink`; Next Link props and required `active` boolean; same pill as `nav-link`; requires Next.js 16                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `next/period-stepper`         | `PeriodStepper` with prefetched Next links: `previousHref`, `nextHref`, optional `todayHref`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `next/tabs-nav-link`          | `TabsNavLink`; Next Link props and required `active` boolean; requires Next.js 16                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `utils`                       | `cn`, `onInputChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `theme.css`                   | Tailwind 4 theme; installation in [README](./README.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
 ## Status
 
@@ -95,8 +105,9 @@ a deprecation notice first, removal in a later minor release.
 
 **Beta** components may still change shape in a minor release, before and
 after 1.0; they are exempt from semver, and the changelog calls out every
-change: `accordion`, `avatar`, `breadcrumb`, `dropdown-menu`, `nav-link`,
-`pagination`, `radio-group`, `spinner`, `switch`.
+change: `accordion`, `avatar`, `breadcrumb`, `chart`, `dropdown-menu`,
+`kanban`, `nav-link`, `page-header`, `pagination`, `period-stepper`,
+`radio-group`, `skip-link`, `spinner`, `switch`.
 
 ## Styling parts
 
@@ -105,27 +116,31 @@ through to it. Where a part sits inside a component, a prop names it, and
 each part carries a `data-slot` for parent selectors such as
 `*:data-[slot=stat-tile-value]:text-2xl`.
 
-| Component                                          | Part props                                                                                                                                                                                                                                                              | Slots                                                                                                                     |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `DialogContent`                                    | `overlayClassName`, `closeButtonClassName`                                                                                                                                                                                                                              | `dialog-close-button` (the built-in X; your own `DialogClose` keeps `dialog-close`)                                       |
-| `SelectTrigger`                                    | a `className` height replaces `size`                                                                                                                                                                                                                                    | `select-icon`, `select-viewport`, `select-item-indicator`                                                                 |
-| `TooltipContent`                                   | `arrowClassName`                                                                                                                                                                                                                                                        | `tooltip-arrow`                                                                                                           |
-| `Combobox`                                         | `contentClassName` (panel, default trigger width), `listClassName`; button props go to trigger                                                                                                                                                                          | `combobox-search`, `combobox-list`, `combobox-option`                                                                     |
-| `SearchPicker`                                     | `listClassName`; div props go to the root                                                                                                                                                                                                                               | `search-picker-option`, `search-picker-empty`                                                                             |
-| `InfoTip`                                          | `contentClassName`; button props go to the trigger                                                                                                                                                                                                                      |                                                                                                                           |
-| `Label`, `FieldLabel`                              | `requiredClassName`                                                                                                                                                                                                                                                     | `label-required`                                                                                                          |
-| `DatePickerButton`, `DateTimePickerButton`         | `contentClassName`, `calendarProps` (`disabled` / `hidden` days, `startMonth`, `endMonth`, `weekStartsOn`, date-fns `locale`, `showOutsideDays`, `fixedWeeks`, `showWeekNumber`, `captionLayout`, `today`, `className`); `minDate` / `maxDate` add to its disabled days | `date-picker-value`, `date-picker-footer`, `date-time-picker-time`                                                        |
-| `form/*` fields                                    | `fieldClassName` (wrapper); `className` styles the control (on `FormControlField`, the wrapper); `FormSelectField` `contentClassName`; `FormMarkdownField` `previewClassName`                                                                                           | `form-field`, `form-field-header`, `form-field-description`, `form-field-error`, `form-feedback`, `form-markdown-preview` |
-| `Table`                                            | `containerClassName` (the scroll box, e.g. `max-h-96 overflow-y-auto`); `className` styles the `<table>`                                                                                                                                                                |                                                                                                                           |
-| `TabsList`, `TabsNav`                              | `scrollerClassName`; `TabsNav` `listClassName`; a list `className` height replaces `h-11`                                                                                                                                                                               | `tabs-scroller`                                                                                                           |
-| `SortableTableHead`                                | `buttonClassName`                                                                                                                                                                                                                                                       | `sortable-table-head-button`                                                                                              |
-| `AccordionTrigger`, `AccordionContent`             | `headerClassName`; `AccordionContent` `className` styles the inner box                                                                                                                                                                                                  | `accordion-header`, `accordion-content-inner`                                                                             |
-| `Progress`                                         | `indicatorClassName`                                                                                                                                                                                                                                                    | `progress-indicator`                                                                                                      |
-| `Meter`                                            | `fillClassName`                                                                                                                                                                                                                                                         | `meter-fill`, `meter-marker`                                                                                              |
-| `StatTile`                                         |                                                                                                                                                                                                                                                                         | `stat-tile-label`, `stat-tile-value`, `stat-tile-sub`                                                                     |
-| `ColorLegend`                                      |                                                                                                                                                                                                                                                                         | `color-legend-title`, `-list`, `-item`, `-swatch`, `-range`, `-label`, `-caption`                                         |
-| `RadioGroupItem`                                   |                                                                                                                                                                                                                                                                         | `radio-group-dot`                                                                                                         |
-| `EmptyPanel`, `ErrorFallback`, `TableBodySkeleton` | `className`                                                                                                                                                                                                                                                             | `empty-panel`, `error-boundary`                                                                                           |
+| Component                                          | Part props                                                                                                                                                                                                                                                              | Slots                                                                                                                                                                                                                                                                                            |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DialogContent`                                    | `overlayClassName`, `closeButtonClassName`                                                                                                                                                                                                                              | `dialog-close-button` (the built-in X; your own `DialogClose` keeps `dialog-close`)                                                                                                                                                                                                              |
+| `SelectTrigger`                                    | a `className` height replaces `size`                                                                                                                                                                                                                                    | `select-icon`, `select-viewport`, `select-item-indicator`                                                                                                                                                                                                                                        |
+| `TooltipContent`                                   | `arrowClassName`                                                                                                                                                                                                                                                        | `tooltip-arrow`                                                                                                                                                                                                                                                                                  |
+| `Combobox`                                         | `contentClassName` (panel, default trigger width), `listClassName`; button props go to trigger                                                                                                                                                                          | `combobox-search`, `combobox-list`, `combobox-option`                                                                                                                                                                                                                                            |
+| `SearchPicker`                                     | `listClassName`; div props go to the root                                                                                                                                                                                                                               | `search-picker-option`, `search-picker-empty`                                                                                                                                                                                                                                                    |
+| `InfoTip`                                          | `contentClassName`; button props go to the trigger                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                  |
+| `KanbanBoard`                                      | `scrollerClassName`, `columnClassName` (default `w-72 min-w-72` and a drop-area min height), `cardClassName` (cards and the drag overlay); div props go to the root                                                                                                     | `kanban-board`, `kanban-scroller`, `kanban-column`, `kanban-column-header`, `kanban-column-empty`, `kanban-card`, `kanban-card-handle`, `kanban-card-body`, `kanban-drag-overlay`, `kanban-action-rail`, `kanban-action-zone`, `kanban-scroll-button`, `kanban-overflow-fade`, `kanban-skeleton` |
+| `chart` pieces                                     | `ChartTooltip` and `ChartLegend` take div props; `ChartLegendKey` `className`                                                                                                                                                                                           | `chart-y-axis`, `chart-tooltip`, `chart-tooltip-row`, `chart-legend`, `chart-legend-key`                                                                                                                                                                                                         |
+| `PageHeader`, `PeriodStepper`, `SkipLink`          | `PageHeader` `titleClassName`; `PeriodStepper` `labelClassName`                                                                                                                                                                                                         | `page-header`, `page-header-heading`, `page-header-title`, `page-header-description`, `page-header-actions`, `period-stepper`, `period-stepper-label`, `skip-link`                                                                                                                               |
+| `FormCheckboxGroupField`                           | `className` (the options box), `fieldClassName` (the fieldset)                                                                                                                                                                                                          | `form-checkbox-group-options`                                                                                                                                                                                                                                                                    |
+| `Label`, `FieldLabel`                              | `requiredClassName`                                                                                                                                                                                                                                                     | `label-required`                                                                                                                                                                                                                                                                                 |
+| `DatePickerButton`, `DateTimePickerButton`         | `contentClassName`, `calendarProps` (`disabled` / `hidden` days, `startMonth`, `endMonth`, `weekStartsOn`, date-fns `locale`, `showOutsideDays`, `fixedWeeks`, `showWeekNumber`, `captionLayout`, `today`, `className`); `minDate` / `maxDate` add to its disabled days | `date-picker-value`, `date-picker-footer`, `date-time-picker-time`                                                                                                                                                                                                                               |
+| `form/*` fields                                    | `fieldClassName` (wrapper); `className` styles the control (on `FormControlField`, the wrapper); `FormSelectField` `contentClassName`; `FormMarkdownField` `previewClassName`                                                                                           | `form-field`, `form-field-header`, `form-field-description`, `form-field-error`, `form-feedback`, `form-markdown-preview`                                                                                                                                                                        |
+| `Table`                                            | `containerClassName` (the scroll box, e.g. `max-h-96 overflow-y-auto`); `className` styles the `<table>`                                                                                                                                                                |                                                                                                                                                                                                                                                                                                  |
+| `TabsList`, `TabsNav`                              | `scrollerClassName`; `TabsNav` `listClassName`; a list `className` height replaces `h-11`                                                                                                                                                                               | `tabs-scroller`                                                                                                                                                                                                                                                                                  |
+| `SortableTableHead`                                | `buttonClassName`                                                                                                                                                                                                                                                       | `sortable-table-head-button`                                                                                                                                                                                                                                                                     |
+| `AccordionTrigger`, `AccordionContent`             | `headerClassName`; `AccordionContent` `className` styles the inner box                                                                                                                                                                                                  | `accordion-header`, `accordion-content-inner`                                                                                                                                                                                                                                                    |
+| `Progress`                                         | `indicatorClassName`                                                                                                                                                                                                                                                    | `progress-indicator`                                                                                                                                                                                                                                                                             |
+| `Meter`                                            | `fillClassName`                                                                                                                                                                                                                                                         | `meter-fill`, `meter-marker`                                                                                                                                                                                                                                                                     |
+| `StatTile`                                         |                                                                                                                                                                                                                                                                         | `stat-tile-label`, `stat-tile-value`, `stat-tile-sub`                                                                                                                                                                                                                                            |
+| `ColorLegend`                                      |                                                                                                                                                                                                                                                                         | `color-legend-title`, `-list`, `-item`, `-swatch`, `-range`, `-label`, `-caption`                                                                                                                                                                                                                |
+| `RadioGroupItem`                                   |                                                                                                                                                                                                                                                                         | `radio-group-dot`                                                                                                                                                                                                                                                                                |
+| `EmptyPanel`, `ErrorFallback`, `TableBodySkeleton` | `className`                                                                                                                                                                                                                                                             | `empty-panel`, `error-boundary`                                                                                                                                                                                                                                                                  |
 
 ## Forms
 
@@ -202,9 +217,11 @@ draws the same marker; set `required` on the control yourself.
 
 `DatePickerButton` is single-day by default. For a from/to range, set
 `mode="range"`; `value` is `{ from, to }` (each side `Date` or `yyyy-MM-dd`)
-and `onChange` receives `DateRange | undefined`. The trigger uses the same
-form-control chrome as `Input` and `SelectTrigger`. The range popover shows
-one month below `md` and two months at `md+` unless `numberOfMonths` is set,
+and `onValueChange` receives `DateRange | undefined`. The trigger uses the same
+form-control chrome as `Input` and `SelectTrigger`. Long picker values wrap
+inside narrow triggers; ordinary one-line values stay 40px tall, and consumer
+height classes still override that default. The range popover shows one
+month below `md` and two months at `md+` unless `numberOfMonths` is set,
 clamps to the viewport with collision padding and scroll, stays `w-auto` so
 it does not collapse to the default popover width, and includes a Clear
 action. Pass `side` to prefer a placement; Radix still flips on collision.
@@ -220,8 +237,11 @@ the trigger text's id (a `<label for>` alone names the button by the label
 only).
 `FormDatePickerField` forwards `className` to that trigger.
 
+Both pickers took `onChange` before 0.14; it still works as a deprecated
+alias until 2.0.
+
 `DateTimePickerButton` is the date-and-time control. `value` is a `Date` or
-`null`; `onChange` receives `Date | null`. The trigger matches the same
+`null`; `onValueChange` receives `Date | null`. The trigger matches the same
 form-control chrome. The popover is one month, a labelled Hour and Minute
 pair (24-hour, stepped by `timeStep`, default 15), and Clear. Picking a day
 keeps the popover open so the time can be set; the time selects stay
@@ -242,15 +262,15 @@ import { DateTimePickerButton } from "atlas-react-kit/date-time-picker"
 
 export function EventStarts({
   value,
-  onChange,
+  onValueChange,
 }: {
   value: Date | null
-  onChange: (date: Date | null) => void
+  onValueChange: (date: Date | null) => void
 }) {
   return (
     <DateTimePickerButton
       value={value}
-      onChange={onChange}
+      onValueChange={onValueChange}
       timeStep={15}
       placeholder="Pick a date and time"
     />
@@ -263,16 +283,16 @@ import { DatePickerButton, type DateRange } from "atlas-react-kit/date-picker"
 
 export function ExportRange({
   value,
-  onChange,
+  onValueChange,
 }: {
   value: DateRange | undefined
-  onChange: (range: DateRange | undefined) => void
+  onValueChange: (range: DateRange | undefined) => void
 }) {
   return (
     <DatePickerButton
       mode="range"
       value={value}
-      onChange={onChange}
+      onValueChange={onValueChange}
       numberOfMonths={2}
       placeholder="Export range"
     />

package/DESIGN_RULES.md

@@ -32,6 +32,36 @@ its own soft tint in both themes. Status tones have no paired foreground token;
 avoid placing text on solid status fills. Application-specific identity colors
 belong to the application.
 
+### Public tokens and slots
+
+These are public API from 1.0, so apps may use them and a rename or removal
+is a breaking change:
+
+- Color tokens and their `--color-*` utilities: `background`, `foreground`,
+  `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `selected`
+  (each with its `-foreground` pair where one exists), `destructive`,
+  `success`, `warning`, `border`, `input`, `ring`, `chart-1` to `chart-5`,
+  and the `sidebar` set.
+- `--radius` and the `--radius-*` scale, and `--font-heading`.
+- Every `data-slot` listed under "Styling parts" in
+  [COMPONENTS.md](./COMPONENTS.md#styling-parts).
+
+Everything else in `theme.css` is internal and may change in a minor
+release: the scroll-shadow variables (`--scroll-fade`, `--scroll-fill`,
+`--table-scroll-fade`, `--tabs-scroll-fade`) and any `data-slot` not listed
+in COMPONENTS.md.
+
+### Prop names
+
+- A controlled value is `value` with `onValueChange`; open state is `open`
+  with `onOpenChange`; a checked state is `checked` with `onCheckedChange`.
+- Sizes run `sm`, `default`, `lg`; `Button` adds `xs` and `icon-*` sizes.
+- `variant="default"` is the plain look; other variants name what they mean
+  (`outline`, `ghost`, `destructive`).
+
+Deprecated aliases (`onChange` on the date pickers, `EmptyPanel`
+`size="md"`) keep working until 2.0.
+
 ## Accessibility
 
 The target is WCAG 2.2 AA. CI runs axe-core's WCAG 2.2 A and AA rules against