atlas-react-kit 1.0.0 → 1.1.0

package/dist/picker-shell.d.ts

@@ -1,10 +1,11 @@
 import * as React from "react";
 import type { Locale } from "date-fns";
 import { type DateLike, type DateMatcher } from "./internal/date-like.js";
+import { LazyCalendar } from "./lazy-calendar.js";
 import { PopoverContent } from "./popover.js";
 /**
- * Not a public entry. The trigger, popover, and Clear footer that
- * `DatePickerButton` and `DateTimePickerButton` share.
+ * Not a public entry. The trigger, popover, calendar wiring, and Clear row
+ * that `DatePickerButton` and `DateTimePickerButton` share.
  */
 /**
  * Options for the picker's calendar. The picker owns the selection, focus,
@@ -80,13 +81,7 @@ export type PickerTriggerProps = {
     /** Day Picker options passed through to the calendar. */
     calendarProps?: PickerCalendarProps;
 };
-/**
- * `calendarProps` with `minDate` / `maxDate` applied: days outside them join
- * any `disabled` matchers, and they bound paging unless `startMonth` /
- * `endMonth` are set.
- */
-export declare function limitCalendarProps(calendarProps: PickerCalendarProps | undefined, minDate: DateLike, maxDate: DateLike): PickerCalendarProps | undefined;
-type PickerShellProps = Omit<PickerTriggerProps, "placeholder" | "defaultMonth" | "calendarProps" | "minDate" | "maxDate"> & {
+type PickerShellProps = Omit<PickerTriggerProps, "placeholder"> & {
     /** Muted trigger text while nothing is picked. */
     empty: boolean;
     /** Trigger text: the formatted value or the placeholder. */
@@ -97,17 +92,25 @@ type PickerShellProps = Omit<PickerTriggerProps, "placeholder" | "defaultMonth"
     open: boolean;
     /** Called when the popover opens or closes. */
     onOpenChange: (open: boolean) => void;
-    /** Called on a pointer down or focus outside the popover; can prevent the dismiss. */
-    onInteractOutside?: React.ComponentProps<typeof PopoverContent>["onInteractOutside"];
-    children: React.ReactNode;
+    /**
+     * The picker's own calendar props: its mode, selection and `onSelect`.
+     * The shell adds `calendarProps`, the date limits, `defaultMonth`, and
+     * focus on the selected day.
+     */
+    calendar: React.ComponentProps<typeof LazyCalendar>;
+    /**
+     * Shows a Clear row under the panel. Called when Clear is pressed; the
+     * popover then closes.
+     */
+    onClear?: () => void;
+    /** Disable Clear, e.g. while nothing is picked. */
+    clearDisabled?: boolean;
+    /** Extra panel rows between the calendar and Clear, e.g. time selects. */
+    children?: React.ReactNode;
 };
-/** Form-control trigger plus the viewport-clamped calendar popover. */
-export declare function PickerShell({ id, disabled, className, contentClassName, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, side, empty, label, dialogLabel, open, onOpenChange, onInteractOutside, children, }: PickerShellProps): React.JSX.Element;
-/** Clear button row under the calendar. */
-export declare function PickerClearFooter({ disabled, onClear, }: {
-    /** Disable the Clear button, e.g. while nothing is picked. */
-    disabled: boolean;
-    /** Called when Clear is pressed. */
-    onClear: () => void;
-}): React.JSX.Element;
+/**
+ * Form-control trigger plus the viewport-clamped popover holding the
+ * calendar, any extra rows, and an optional Clear row.
+ */
+export declare function PickerShell({ id, disabled, className, contentClassName, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, side, defaultMonth, minDate, maxDate, calendarProps, empty, label, dialogLabel, open, onOpenChange, calendar, onClear, clearDisabled, children, }: PickerShellProps): React.JSX.Element;
 export {};

package/dist/picker-shell.js

@@ -5,7 +5,7 @@ import { CalendarIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { toDate, } from "./internal/date-like.js";
 import { PICKER_COLLISION_PADDING, pickerContentClassName, pickerTriggerClassName, pickerValueId, } from "./internal/form-control.js";
-import { preloadCalendar } from "./lazy-calendar.js";
+import { LazyCalendar, preloadCalendar } from "./lazy-calendar.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { cn } from "./utils.js";
 /**
@@ -13,7 +13,7 @@ import { cn } from "./utils.js";
  * any `disabled` matchers, and they bound paging unless `startMonth` /
  * `endMonth` are set.
  */
-export function limitCalendarProps(calendarProps, minDate, maxDate) {
+function limitCalendarProps(calendarProps, minDate, maxDate) {
     const min = toDate(minDate);
     const max = toDate(maxDate);
     if (!min && !max)
@@ -35,15 +35,17 @@ export function limitCalendarProps(calendarProps, minDate, maxDate) {
         endMonth: calendarProps?.endMonth ?? max,
     };
 }
-/** Form-control trigger plus the viewport-clamped calendar popover. */
-export function PickerShell({ id, disabled, className, contentClassName, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, side, empty, label, dialogLabel, open, onOpenChange, onInteractOutside, children, }) {
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "data-empty": empty, className: cn(pickerTriggerClassName, className), onPointerEnter: preloadCalendar, onFocus: preloadCalendar, children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), _jsx("span", { "data-slot": "date-picker-value", className: "min-w-0 text-left whitespace-normal", id: id ? pickerValueId(id) : undefined, children: label })] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, "aria-label": dialogLabel, 
+/**
+ * Form-control trigger plus the viewport-clamped popover holding the
+ * calendar, any extra rows, and an optional Clear row.
+ */
+export function PickerShell({ id, disabled, className, contentClassName, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, side, defaultMonth, minDate, maxDate, calendarProps, empty, label, dialogLabel, open, onOpenChange, calendar, onClear, clearDisabled = false, children, }) {
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "data-empty": empty, className: cn(pickerTriggerClassName, className), onPointerEnter: preloadCalendar, onFocus: preloadCalendar, children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), _jsx("span", { "data-slot": "date-picker-value", className: "min-w-0 text-left whitespace-normal", id: id ? pickerValueId(id) : undefined, children: label })] }) }), _jsxs(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, "aria-label": dialogLabel, 
                 // The calendar's `autoFocus` puts focus on the selected day (or
                 // today) once it loads, as the APG date picker dialog does; Radix
                 // focusing the popover first would leave it on the container.
-                onOpenAutoFocus: (event) => event.preventDefault(), onInteractOutside: onInteractOutside, className: cn("w-auto min-w-0", pickerContentClassName, contentClassName), children: children })] }));
-}
-/** Clear button row under the calendar. */
-export function PickerClearFooter({ disabled, onClear, }) {
-    return (_jsx("div", { "data-slot": "date-picker-footer", className: "flex justify-end border-t p-2", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: disabled, onClick: onClear, children: "Clear" }) }));
+                onOpenAutoFocus: (event) => event.preventDefault(), className: cn("w-auto min-w-0", pickerContentClassName, contentClassName), children: [_jsx(LazyCalendar, { ...limitCalendarProps(calendarProps, minDate, maxDate), ...calendar, autoFocus: true, defaultMonth: defaultMonth }), children, onClear ? (_jsx("div", { "data-slot": "date-picker-footer", className: "flex justify-end border-t p-2", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", disabled: clearDisabled, onClick: () => {
+                                onClear();
+                                onOpenChange(false);
+                            }, children: "Clear" }) })) : null] })] }));
 }

package/dist/tabs.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 import { Tabs as TabsPrimitive } from "radix-ui";
+import type { AsChildProps } from "./internal/as-child.js";
 import { tabsListVariants, tabsTriggerVariants } from "./internal/tabs-styles.js";
 /** Props `TabsList` and `TabsNav` share for the scroller around their row. */
 type TabsScrollerClassNameProps = {
@@ -16,18 +17,28 @@ declare function Tabs({ className, orientation, ...props }: React.ComponentProps
 declare function TabsList({ className, scrollerClassName, variant, ...props }: React.ComponentProps<typeof TabsPrimitive.List> & Omit<VariantProps<typeof tabsListVariants>, "orientation"> & TabsScrollerClassNameProps): React.JSX.Element;
 declare function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>): React.JSX.Element;
 declare function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>): React.JSX.Element;
+/**
+ * Tab-styled link for `TabsNav`. Pass `active` from the route: the active
+ * link gets the trigger's selected chrome (`data-state="active"`) and
+ * `aria-current="page"`. `asChild` wraps a router `Link` with these styles,
+ * like `NavLink`; Next apps can import `next/tabs-nav-link` instead.
+ */
+declare function TabsNavLink({ asChild, active, className, ...props }: React.ComponentProps<"a"> & AsChildProps & {
+    /** This link is the current view: `aria-current="page"` and the active chrome. */
+    active: boolean;
+}): React.JSX.Element;
 /**
  * Tab-styled links for a view switcher that changes the URL. Use this, not
  * `Tabs` + `TabsTrigger asChild`, when there are no `TabsContent` panels:
- * tabs would point assistive tech at panels that don't exist. Style each link
- * with `tabsTriggerVariants()` and mark the active one with
- * `data-state="active"` and `aria-current="page"` (the Next adapter
- * `TabsNavLink` does this for you).
+ * tabs would point assistive tech at panels that don't exist. Each link is
+ * a `TabsNavLink` with `active` from the app (`asChild` for a router link,
+ * or the Next adapter `next/tabs-nav-link`).
  *
  * Overflow is handled here: the row scrolls horizontally only, with padding
  * for active borders and focus rings counted in the scroller height (so the
- * list cannot overflow on y), an edge fade while it overflows, and the
- * active link scrolled into view on mount. Do not wrap it in
+ * list cannot overflow on y), an edge fade while it overflows, the
+ * active link scrolled into view on mount, and a mouse drag that scrolls
+ * the row (a plain click still follows the link). Do not wrap it in
  * `overflow-x-auto`. `scrollerClassName` styles that scroller and
  * `listClassName` the row of links inside it.
  */
@@ -37,4 +48,4 @@ declare function TabsNav({ className, scrollerClassName, listClassName, children
     /** Classes for the row of links inside the scroller. */
     listClassName?: string;
 }): React.JSX.Element;
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants, tabsTriggerVariants, };
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, TabsNavLink, tabsListVariants, tabsTriggerVariants, };

package/dist/tabs.js

@@ -2,9 +2,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
 import {} from "class-variance-authority";
-import { Tabs as TabsPrimitive } from "radix-ui";
+import { Slot, Tabs as TabsPrimitive } from "radix-ui";
 import { focusRing } from "./internal/styles.js";
 import { tabsListVariants, tabsScrollerVariants, tabsTriggerVariants, } from "./internal/tabs-styles.js";
+import { useDragScroll } from "./internal/use-drag-scroll.js";
 import { useHorizontalOverflow } from "./internal/use-horizontal-overflow.js";
 import { cn } from "./utils.js";
 /**
@@ -22,12 +23,14 @@ function Tabs({ className, orientation = "horizontal", ...props }) {
  * active tab's border and focus ring grow a vertical scrollbar. Pad for
  * those strokes *inside* the box (`h-13` = `h-11` list + `p-1`), clip the
  * y axis as a backstop, and fade the edges while the row overflows —
- * same cue as `Table`.
+ * same cue as `Table`. While it overflows, a mouse can also drag the row
+ * sideways (`useDragScroll`); touch, wheel and keyboard scroll as before.
  */
 function TabsScroller({ variant = "default", orientation = "horizontal", className, children, }) {
     const ref = React.useRef(null);
     const revealed = React.useRef(null);
     const overflowing = useHorizontalOverflow(ref);
+    useDragScroll(ref, overflowing);
     // Runs after every render, not just mount: TabsNav usually sits in a
     // persistent layout, so a route change updates the active link in place.
     React.useLayoutEffect(() => {
@@ -63,22 +66,32 @@ function TabsTrigger({ className, ...props }) {
 function TabsContent({ className, ...props }) {
     return (_jsx(TabsPrimitive.Content, { "data-slot": "tabs-content", className: cn("flex-1 text-sm", focusRing, className), ...props }));
 }
+/**
+ * Tab-styled link for `TabsNav`. Pass `active` from the route: the active
+ * link gets the trigger's selected chrome (`data-state="active"`) and
+ * `aria-current="page"`. `asChild` wraps a router `Link` with these styles,
+ * like `NavLink`; Next apps can import `next/tabs-nav-link` instead.
+ */
+function TabsNavLink({ asChild, active, className, ...props }) {
+    const Comp = asChild ? Slot.Root : "a";
+    return (_jsx(Comp, { "data-slot": "tabs-nav-link", "data-state": active ? "active" : "inactive", "aria-current": active ? "page" : undefined, className: cn(tabsTriggerVariants(), className), ...props }));
+}
 /**
  * Tab-styled links for a view switcher that changes the URL. Use this, not
  * `Tabs` + `TabsTrigger asChild`, when there are no `TabsContent` panels:
- * tabs would point assistive tech at panels that don't exist. Style each link
- * with `tabsTriggerVariants()` and mark the active one with
- * `data-state="active"` and `aria-current="page"` (the Next adapter
- * `TabsNavLink` does this for you).
+ * tabs would point assistive tech at panels that don't exist. Each link is
+ * a `TabsNavLink` with `active` from the app (`asChild` for a router link,
+ * or the Next adapter `next/tabs-nav-link`).
  *
  * Overflow is handled here: the row scrolls horizontally only, with padding
  * for active borders and focus rings counted in the scroller height (so the
- * list cannot overflow on y), an edge fade while it overflows, and the
- * active link scrolled into view on mount. Do not wrap it in
+ * list cannot overflow on y), an edge fade while it overflows, the
+ * active link scrolled into view on mount, and a mouse drag that scrolls
+ * the row (a plain click still follows the link). Do not wrap it in
  * `overflow-x-auto`. `scrollerClassName` styles that scroller and
  * `listClassName` the row of links inside it.
  */
 function TabsNav({ className, scrollerClassName, listClassName, children, ...props }) {
     return (_jsx("nav", { "data-slot": "tabs-nav", "data-orientation": "horizontal", className: cn("group/tabs min-w-0 max-w-full", className), ...props, children: _jsx(TabsScroller, { className: scrollerClassName, children: _jsx("div", { "data-slot": "tabs-list", "data-variant": "default", className: cn(tabsListVariants({ orientation: "horizontal" }), "bg-transparent", listClassName), children: children }) }) }));
 }
-export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, tabsListVariants, tabsTriggerVariants, };
+export { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, TabsNavLink, tabsListVariants, tabsTriggerVariants, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas-react-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared React components and Tailwind theme for Atlas",
   "type": "module",
   "license": "MIT",
@@ -252,6 +252,10 @@
       "types": "./dist/form/field-error.d.ts",
       "default": "./dist/form/field-error.js"
     },
+    "./form/focus-first-invalid": {
+      "types": "./dist/form/focus-first-invalid.d.ts",
+      "default": "./dist/form/focus-first-invalid.js"
+    },
     "./form/markdown-field": {
       "types": "./dist/form/markdown-field.d.ts",
       "default": "./dist/form/markdown-field.js"
@@ -295,11 +299,11 @@
     "docs:check": "node scripts/check-doc-links.mjs",
     "lint": "oxlint --type-aware --deny-warnings",
     "knip": "knip",
-    "sast": "node scripts/sast.mjs",
+    "sast": "semgrep scan --config .semgrep.yml --metrics=off --disable-version-check --error --quiet src",
     "secrets": "secretlint \"**/*\"",
     "size": "size-limit",
     "gate:static": "npm run lint && npm run knip && npm run sast && npm run secrets",
-    "gate": "npm run check && npm run gate:static && npm run size && vitest run",
+    "gate": "npm run check && npm run gate:static && npm run size && vitest run --coverage",
     "test": "npm run build && vitest run",
     "test:coverage": "npm run build && vitest run --coverage",
     "prepack": "npm run build",

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

@@ -42,10 +42,9 @@ root (or a `dark` class on an ancestor). Toasts need one `<Toaster />` from
 `atlas-react-kit/toast`; show them with `toast()` from the same module, using
 only the options it declares. Never import a toast library such as `sonner`
 directly: the kit owns the toast API, and a second copy never reaches its
-toaster. Markdown, dates, toasts, and `ThemeProvider` are optional peers —
-install the extras listed in `COMPONENTS.md` when you import those entry
-points. Fix missing setup rather than working
-around unstyled components.
+toaster. Some entry points need optional peers; install the extras from the
+"Optional peer dependencies" table in `COMPONENTS.md` when you import them.
+Fix missing setup rather than working around unstyled components.
 
 ## 3. Pick the kit component for the job
 
@@ -53,42 +52,49 @@ Import each component from its subpath, e.g.
 `import { Button } from "atlas-react-kit/button"`. There is no root barrel, and
 `dist/` or `internal/` paths are not public API.
 
-| Need                                            | Use                                                                                                                     |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Short fixed list (a handful of options)         | `Select` family from `select`                                                                                           |
-| Long or searchable list (timezones, currencies) | `Combobox` from `combobox` with `{ value, label }[]` options; set `creatable` to invent a value the catalog lacks       |
-| Always-visible searchable list (places)         | `SearchPicker` from `search-picker`                                                                                     |
-| One date, or a from/to range                    | `DatePickerButton` from `date-picker` (`mode="range"` for ranges)                                                       |
-| Date and time (not `datetime-local`)            | `DateTimePickerButton` from `date-time-picker`                                                                          |
-| Labelled field with error text                  | `FormTextField`, `FormSelectField`, `FormDatePickerField`, `FormDateTimePickerField`, `FormMarkdownField` from `form/*` |
-| Labelled custom control (combobox) in a form    | `FormControlField` from `form/control-field`                                                                            |
-| Form-level error (save failed)                  | `FormFeedbackField` from `form/feedback-field`                                                                          |
-| Content panels on one page                      | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` from `tabs`                                                            |
-| View switch that changes the URL                | `TabsNav` with links: `TabsNavLink` from `next/tabs-nav-link` in Next, else `tabsTriggerVariants()`                     |
-| App shell nav (Calendar, Tasks, Settings)       | `NavLink` from `nav-link` (`asChild` for a router link); Next: `next/nav-link`                                          |
-| Status chip (paid, pending, failed)             | `Badge variant="soft"` with `tone="success"`, `"warning"`, `"destructive"`, or `"neutral"`                              |
-| Data table                                      | `Table` family from `table`; `SortableTableHead`; `TableBodySkeleton` while loading                                     |
-| Nothing to show yet                             | `EmptyPanel` from `empty-panel`                                                                                         |
-| Grouped content                                 | `Card` family from `card`; `<Card flush>` for an edge-to-edge table or list                                             |
-| Modal                                           | `Dialog` family from `dialog`                                                                                           |
-| Label for an icon button, or a short hint       | `Tooltip` from `tooltip`; keep `aria-label` on icon buttons                                                             |
-| Longer help from a glyph                        | `InfoTip` / `InlineTip` from `info-tip` (not `Tooltip`)                                                                 |
-| Color scale key                                 | `ColorLegend` from `color-legend`                                                                                       |
-| GitHub-flavoured Markdown                       | `Markdown` from `markdown`; write/preview with `FormMarkdownField`                                                      |
-| Summary figure in a strip                       | `StatTile` from `stat-tile` (`statTileGrid`, `sectionLabel`)                                                            |
-| Value against a scale, optional ticks           | `Meter` from `meter` (not `Progress`)                                                                                   |
-| Number on a continuous scale                    | `Slider` from `slider`                                                                                                  |
-| Row actions or an overflow menu of commands     | `DropdownMenu` family from `dropdown-menu`                                                                              |
-| Setting that applies immediately                | `Switch` from `switch`; `Checkbox` for choices submitted with a form                                                    |
-| One choice from a few visible options           | `RadioGroup` and `RadioGroupItem` from `radio-group`                                                                    |
-| Inline message about a page or section          | `Alert` from `alert` (`success`, `warning`, `destructive` variants)                                                     |
-| Person or workspace image                       | `Avatar`, `AvatarImage`, `AvatarFallback` from `avatar`                                                                 |
-| Sections that expand in place                   | `Accordion` family from `accordion`                                                                                     |
-| Pages of a long list                            | `Pagination` family from `pagination`                                                                                   |
-| Where the page sits in a hierarchy              | `Breadcrumb` family from `breadcrumb`                                                                                   |
-| Work in progress                                | `Progress` from `progress` when the percent is known, else `Spinner` from `spinner`                                     |
-| Crash recovery around a section                 | `ErrorBoundary` from `error-boundary`                                                                                   |
-| Conditional classes                             | `cn` from `utils`                                                                                                       |
+| Need                                                       | Use                                                                                                                     |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Short fixed list (a handful of options)                    | `Select` family from `select`                                                                                           |
+| Long or searchable list (timezones, currencies)            | `Combobox` from `combobox` with `{ value, label }[]` options; set `creatable` to invent a value the catalog lacks       |
+| Always-visible searchable list (places)                    | `SearchPicker` from `search-picker`                                                                                     |
+| One date, or a from/to range                               | `DatePickerButton` from `date-picker` (`mode="range"` for ranges)                                                       |
+| Date and time (not `datetime-local`)                       | `DateTimePickerButton` from `date-time-picker`                                                                          |
+| Labelled field with error text                             | `FormTextField`, `FormSelectField`, `FormDatePickerField`, `FormDateTimePickerField`, `FormMarkdownField` from `form/*` |
+| Checkbox, checkbox group, toggle group, combobox in a form | `FormCheckboxField`, `FormCheckboxGroupField`, `FormToggleGroupField`, `FormComboboxField` from `form/*`                |
+| Custom control the kit has no form field for               | `FormControlField` from `form/control-field`                                                                            |
+| Form-level error (save failed)                             | `FormFeedbackField` from `form/feedback-field`                                                                          |
+| Content panels on one page                                 | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` from `tabs`                                                            |
+| View switch that changes the URL                           | `TabsNav` with `TabsNavLink` from `tabs` (`asChild` for a router link); Next: `next/tabs-nav-link`                      |
+| App shell nav (Calendar, Tasks, Settings)                  | `NavLink` from `nav-link` (`asChild` for a router link); Next: `next/nav-link`; `active={isNavActive(pathname, href)}`  |
+| Focus the first invalid field when a submit fails          | `focusFirstInvalid(formId)` from `form/focus-first-invalid`; give fields `id={field.name}`                              |
+| Skip-to-content link                                       | `SkipLink` from `skip-link`                                                                                             |
+| Page title row with actions                                | `PageHeader` from `page-header`                                                                                         |
+| Previous / today / next period                             | `PeriodStepper` from `period-stepper`; `next/period-stepper` for URL periods                                            |
+| Cards in columns that drag                                 | `KanbanBoard` from `kanban`; `KanbanSkeleton` while loading                                                             |
+| SVG chart axes, grid, tooltip, legend                      | `chart` helpers (`chartFrame`, `ChartYAxisGrid`, `ChartTooltip`, `ChartLegend`)                                         |
+| Status chip (paid, pending, failed)                        | `Badge variant="soft"` with `tone="success"`, `"warning"`, `"destructive"`, or `"neutral"`                              |
+| Data table                                                 | `Table` family from `table`; `SortableTableHead`; `TableBodySkeleton` while loading                                     |
+| Nothing to show yet                                        | `EmptyPanel` from `empty-panel`                                                                                         |
+| Grouped content                                            | `Card` family from `card`; `<Card flush>` for an edge-to-edge table or list                                             |
+| Modal                                                      | `Dialog` family from `dialog`                                                                                           |
+| Label for an icon button, or a short hint                  | `Tooltip` from `tooltip`; keep `aria-label` on icon buttons                                                             |
+| Longer help from a glyph                                   | `InfoTip` / `InlineTip` from `info-tip` (not `Tooltip`)                                                                 |
+| Color scale key                                            | `ColorLegend` from `color-legend`                                                                                       |
+| GitHub-flavoured Markdown                                  | `Markdown` from `markdown`; write/preview with `FormMarkdownField`                                                      |
+| Summary figure in a strip                                  | `StatTile` from `stat-tile` (`statTileGrid`, `sectionLabel`)                                                            |
+| Value against a scale, optional ticks                      | `Meter` from `meter` (not `Progress`)                                                                                   |
+| Number on a continuous scale                               | `Slider` from `slider`                                                                                                  |
+| Row actions or an overflow menu of commands                | `DropdownMenu` family from `dropdown-menu`                                                                              |
+| Setting that applies immediately                           | `Switch` from `switch`; `Checkbox` for choices submitted with a form                                                    |
+| One choice from a few visible options                      | `RadioGroup` and `RadioGroupItem` from `radio-group`                                                                    |
+| Inline message about a page or section                     | `Alert` from `alert` (`success`, `warning`, `destructive` variants)                                                     |
+| Person or workspace image                                  | `Avatar`, `AvatarImage`, `AvatarFallback` from `avatar`                                                                 |
+| Sections that expand in place                              | `Accordion` family from `accordion`                                                                                     |
+| Pages of a long list                                       | `Pagination` family from `pagination`                                                                                   |
+| Where the page sits in a hierarchy                         | `Breadcrumb` family from `breadcrumb`                                                                                   |
+| Work in progress                                           | `Progress` from `progress` when the percent is known, else `Spinner` from `spinner`                                     |
+| Crash recovery around a section                            | `ErrorBoundary` from `error-boundary`                                                                                   |
+| Conditional classes                                        | `cn` from `utils`                                                                                                       |
 
 If nothing fits, build the piece in the app from kit primitives and semantic
 tokens. Do not copy kit source into the app; a missing shared component belongs

package/theme.css

@@ -90,6 +90,7 @@
 }
 
 :root {
+  color-scheme: light;
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
   --card: oklch(1 0 0);
@@ -142,6 +143,7 @@
 }
 
 .dark {
+  color-scheme: dark;
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
   --card: oklch(0.205 0 0);