atlas-react-kit 0.12.0 → 1.0.0

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
@@ -138,9 +168,22 @@ or its `data-slot`.
 `text-base md:text-sm`, `border-input`, and `shadow-xs`. Do not restyle those
 triggers as outline buttons in application code.
 
+`form/*` fields stack label, hint, control, and error with `gap-1.5`, and the
+error sits below the control. It takes no space until it shows, so a row of
+fields keeps its controls on one top edge only with `items-start`
+(`grid grid-cols-2 items-start gap-3`); the default `stretch` is fine for a
+single column. Wrap a control the kit does not ship (a combobox, a segmented
+picker) in `FormControlField` instead of `Field` and `FieldLabel`, whose
+`gap-3` spacing does not match. A field shows its error once
+`meta.isTouched` is true or `submitted` is set, never on a field the person
+has not reached yet.
+
 Use `Tabs` with actual `TabsContent` panels. For URL view switches, use a labelled
 `TabsNav` with links and `aria-current="page"` on the active link. The optional
-Next adapter provides `TabsNavLink` with this behavior. `TabsNav` and `TabsList`
+Next adapter provides `TabsNavLink` with this behavior. App-shell destinations
+(Calendar, Tasks, Settings) use `NavLink` from `nav-link`: a pill with `active`
+from the app, not tabs. Pass `asChild` for a router link, or use the optional
+Next adapter `next/nav-link`. `TabsNav` and `TabsList`
 scroll overflowing labels inside themselves (`overflow-x-auto overflow-y-hidden`,
 with padding for the active border and focus ring counted in the scroller
 height, and an edge fade like `Table`). Do not wrap them in another

package/README.md

@@ -1,14 +1,14 @@
 # Atlas React Kit
 
 Shared React components and a Tailwind theme with square corners, semantic
-colors, and distinct selected states. 0.6.0 added generic pieces apps were
-keeping locally (`InfoTip`, `ColorLegend`, `SearchPicker`, `Markdown`,
-`StatTile`, `Meter`, `Slider`) plus the ToggleGroup selected-state fix.
+colors, and distinct selected states. From 1.0 the API is stable: breaking
+changes to stable components only ship in a major release (see
+[CONTRIBUTING.md](./CONTRIBUTING.md#versions-and-releases)).
 React 19, Tailwind 4, and Node >=20.19 are required. Next 16 is needed only
-when using `next/tabs-nav-link`.
+when using `next/nav-link`, `next/period-stepper`, or `next/tabs-nav-link`.
 
 ```sh
-npm install --save-exact atlas-react-kit@0.12.0
+npm install --save-exact atlas-react-kit@1.0.0
 ```
 
 Import components by subpath:
@@ -42,8 +42,9 @@ this example assumes it is one directory below the project root.
 ```
 
 The theme includes animations and shared light/dark tokens. Wrap the tree with
-`ThemeProvider` from `atlas-react-kit/theme-provider`, or set the `dark` class
-on an ancestor to activate dark colors. Supply your own font configuration;
+`ThemeProvider` from `atlas-react-kit/theme-provider` (install
+`next-themes@^0.4.6` first), or set the `dark` class on an ancestor to activate
+dark colors. Supply your own font configuration;
 `font-heading` uses the configured sans font. Application-specific tokens stay
 with the application.
 
@@ -101,7 +102,7 @@ The public site is Storybook in `site/`. `npm run build --prefix site`
 typechecks the stories, builds Storybook into `site/dist`, then checks the
 static output. Vercel serves that directory; `/playground` and `/storybook`
 redirect to `/`. The site and Storybook dependencies are not part of the npm
-package. Optional feature libraries (markdown, dates, toasts, theme, Next) are
+package. Optional feature libraries (markdown, dates, toasts, theme, Next, dnd-kit) are
 peer dependencies and are required only when those entry points are imported.
 The package does not bundle React.
 
@@ -128,7 +129,7 @@ artifact with the package owner's npm login:
 ```sh
 mkdir -p release-artifacts
 npm pack --pack-destination release-artifacts
-npm publish ./release-artifacts/atlas-react-kit-0.12.0.tgz --access public
+npm publish ./release-artifacts/atlas-react-kit-1.0.0.tgz --access public
 ```
 
 Pin an exact package version in consuming applications. Roll back an upgrade by

package/dist/accordion.d.ts

@@ -5,6 +5,7 @@ declare function Accordion({ ...props }: React.ComponentProps<typeof AccordionPr
 declare function AccordionItem({ className, ...props }: React.ComponentProps<typeof AccordionPrimitive.Item>): React.JSX.Element;
 /** `headerClassName` styles the heading wrapper (`data-slot="accordion-header"`). */
 declare function AccordionTrigger({ className, headerClassName, children, ...props }: React.ComponentProps<typeof AccordionPrimitive.Trigger> & {
+    /** Classes for the heading wrapper around the trigger. */
     headerClassName?: string;
 }): React.JSX.Element;
 /**

package/dist/alert.d.ts

@@ -6,7 +6,7 @@ import { type VariantProps } from "class-variance-authority";
  * (the destructive tint is too faint for text in light mode).
  */
 declare const alertVariants: (props?: ({
-    variant?: "default" | "success" | "warning" | "destructive" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
  * Inline message about the page or a section (save failed, trial ending).

package/dist/avatar.d.ts

@@ -6,6 +6,7 @@ import { Avatar as AvatarPrimitive } from "radix-ui";
  * replaces it.
  */
 declare function Avatar({ className, size, ...props }: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+    /** `sm` 24px, `default` 32px, `lg` 40px. Default `default`. */
     size?: "sm" | "default" | "lg";
 }): React.JSX.Element;
 declare function AvatarImage({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Image>): React.JSX.Element;

package/dist/badge.d.ts

@@ -1,10 +1,9 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
+import type { AsChildProps } from "./internal/as-child.js";
 declare const badgeVariants: (props?: ({
-    variant?: "default" | "link" | "destructive" | "secondary" | "outline" | "ghost" | "soft" | null | undefined;
-    tone?: "success" | "warning" | "destructive" | "neutral" | null | undefined;
+    variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary" | "soft" | null | undefined;
+    tone?: "destructive" | "neutral" | "success" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function Badge({ className, variant, tone, asChild, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & {
-    asChild?: boolean;
-}): React.JSX.Element;
+declare function Badge({ className, variant, tone, asChild, ...props }: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants> & AsChildProps): React.JSX.Element;
 export { Badge, badgeVariants };

package/dist/breadcrumb.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { AsChildProps } from "./internal/as-child.js";
 /**
  * Where the current page sits in a hierarchy. The last item is
  * `BreadcrumbPage` (plain text with `aria-current="page"`), not a link.
@@ -7,9 +8,7 @@ declare function Breadcrumb({ ...props }: React.ComponentProps<"nav">): React.JS
 declare function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">): React.JSX.Element;
 declare function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">): React.JSX.Element;
 /** Pass `asChild` to render a router link (e.g. Next `Link`) with these styles. */
-declare function BreadcrumbLink({ asChild, className, ...props }: React.ComponentProps<"a"> & {
-    asChild?: boolean;
-}): React.JSX.Element;
+declare function BreadcrumbLink({ asChild, className, ...props }: React.ComponentProps<"a"> & AsChildProps): React.JSX.Element;
 declare function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 declare function BreadcrumbSeparator({ children, className, ...props }: React.ComponentProps<"li">): React.JSX.Element;
 declare function BreadcrumbEllipsis({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;

package/dist/button.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
+import type { AsChildProps } from "./internal/as-child.js";
 /**
  * Outline and ghost hover/focus: selected-foreground border, selected wash, and
  * `selected-foreground` text (primary in light mode, a lighter purple that
@@ -8,10 +9,8 @@ import { type VariantProps } from "class-variance-authority";
  */
 declare const quietButtonInteraction: string;
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "link" | "destructive" | "secondary" | "outline" | "ghost" | null | undefined;
-    size?: "default" | "sm" | "lg" | "xs" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+    variant?: "default" | "destructive" | "ghost" | "link" | "outline" | "secondary" | null | undefined;
+    size?: "default" | "icon" | "icon-lg" | "icon-sm" | "icon-xs" | "lg" | "sm" | "xs" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
-    asChild?: boolean;
-}): React.JSX.Element;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & AsChildProps): React.JSX.Element;
 export { Button, buttonVariants, quietButtonInteraction };

package/dist/calendar.d.ts

@@ -2,9 +2,11 @@ import * as React from "react";
 import { DayPicker, type DayButton, type Locale } from "react-day-picker";
 import { Button } from "./button.js";
 declare function Calendar({ className, classNames, showOutsideDays, captionLayout, buttonVariant, locale, formatters, labels, components, ...props }: React.ComponentProps<typeof DayPicker> & {
+    /** Button variant for the previous / next month buttons. Default `ghost`. */
     buttonVariant?: React.ComponentProps<typeof Button>["variant"];
 }): React.JSX.Element;
 declare function CalendarDayButton({ className, day, modifiers, locale, ...props }: React.ComponentProps<typeof DayButton> & {
+    /** Locale for the day's `data-day` date string. */
     locale?: Partial<Locale>;
 }): React.JSX.Element;
 export { Calendar, CalendarDayButton };

package/dist/card.d.ts

@@ -8,11 +8,14 @@ import * as React from "react";
  * scroll instead of widening the card. `overflow-hidden` still clips media.
  */
 declare function Card({ className, size, flush, role, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }: React.ComponentProps<"div"> & {
+    /** `sm` tightens padding and gaps. Default `default`. */
     size?: "default" | "sm";
+    /** Remove the padding so lists and tables run edge to edge. Default `false`. */
     flush?: boolean;
 }): React.JSX.Element;
 declare function CardHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function CardTitle({ as: Component, className, ...props }: React.ComponentProps<"div"> & {
+    /** Element to render, e.g. a heading level for the outline. Default `div`. */
     as?: "div" | "h1" | "h2" | "h3" | "h4";
 }): React.JSX.Element;
 declare function CardDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;

package/dist/chart.d.ts

@@ -0,0 +1,152 @@
+import * as React from "react";
+/**
+ * Building blocks for small SVG charts: a plot frame in viewBox units, axis
+ * math, a gridline axis, a tooltip, a legend, and pointer/arrow-key
+ * scrubbing. The chart itself (bars, lines, what they mean) stays in the
+ * app; these pieces keep every chart's axis, readout, and keyboard use alike.
+ */
+/** Space around the plot, in viewBox units, for axis labels. */
+export type ChartPadding = {
+    /** Above the plot. Default 10. */
+    top: number;
+    /** Right of the plot. Default 12. */
+    right: number;
+    /** Below the baseline, for x labels. Default 20. */
+    bottom: number;
+    /** Left of the plot, for y labels. Default 40. */
+    left: number;
+};
+/** A chart's viewBox and the plot box inside it, in viewBox units. */
+export type ChartFrame = {
+    /** The whole chart's width. */
+    width: number;
+    /** The whole chart's height. */
+    height: number;
+    /** The `viewBox` attribute for the chart's `<svg>`. */
+    viewBox: string;
+    /** The plot's left edge on x. */
+    left: number;
+    /** The plot's right edge on x. */
+    right: number;
+    /** The plot's top edge on y. */
+    top: number;
+    /** The plot's bottom edge on y: the baseline, where 0 sits. */
+    bottom: number;
+    /** `right - left`. */
+    plotWidth: number;
+    /** `bottom - top`. */
+    plotHeight: number;
+};
+/**
+ * Frame for a chart `height` units tall. Charts that share a `width` and
+ * padding line up when stacked. The SVG scales to its box, so these are
+ * viewBox units, not pixels.
+ */
+export declare function chartFrame(height: number, { width, padding, }?: {
+    /** The chart's width in viewBox units. Default 640. */
+    width?: number;
+    /** Overrides for any side of the default padding. */
+    padding?: Partial<ChartPadding>;
+}): ChartFrame;
+/**
+ * Round `max` up to a clean axis ceiling (1, 2, 2.5, 4, or 5 × 10^n). The 4
+ * step keeps a value just past 25 off a half-empty 50 axis.
+ */
+export declare function niceCeil(max: number): number;
+/** `count` even steps from 0 to `niceCeil(max)`, both ends included. */
+export declare function niceTicks(max: number, count?: number): number[];
+/** Linear scale from [0, domainMax] onto [0, rangeMax]; a zero domain maps to 0. */
+export declare function scaleLinear(domainMax: number, rangeMax: number): (value: number) => number;
+/** SVG path through the points (`M x y L x y …`); empty for no points. */
+export declare function linePath(points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>): string;
+/**
+ * A bar with a rounded data end and a square baseline. (x, y) is the top
+ * left; the bar grows down to y + h. Pass `r = 0` for a square bar.
+ */
+export declare function roundedTopBarPath(x: number, y: number, w: number, h: number, r?: number): string;
+/** Short axis label: 1500 → "1.5k", 2000000 → "2M". */
+export declare function compactNumber(n: number): string;
+type IndexRange = {
+    /** The first data index the plot can pick. */
+    min: number;
+    /** The last data index the plot can pick; may stop short of the axis end. */
+    max: number;
+};
+/** The index range plus how many intervals the plot's width spans. */
+type PlotSteps = IndexRange & {
+    /** Intervals across the plot width (data points minus one on a full axis). */
+    steps: number;
+};
+/**
+ * Data index at viewBox x `viewX`. The plot spans `steps` intervals from
+ * `min`; the result is clamped to [min, max], so `max` can stop short of the
+ * axis (days not reached yet).
+ */
+export declare function indexAtPlotX(viewX: number, frame: ChartFrame, { steps, min, max }: PlotSteps): number;
+/** Arrow-key move by `delta`, clamped; with nothing picked it starts at `min`. */
+export declare function stepIndex(current: number | null, delta: 1 | -1, { min, max }: IndexRange): number;
+/**
+ * Crosshair state: the pointer or the arrow keys pick a data index in
+ * [min, max], and Escape or leaving the plot clears it. Put `svgRef` and the
+ * handlers on the chart's `<svg>`, which needs `tabIndex={0}`.
+ */
+export declare function useChartScrub({ frame, steps, min, max, }: PlotSteps & {
+    /** The chart's frame, for mapping pointer x onto the plot. */
+    frame: ChartFrame;
+}): {
+    svgRef: React.RefObject<SVGSVGElement | null>;
+    index: number | null;
+    clear: () => void;
+    onPointerMove: (event: React.PointerEvent<SVGSVGElement>) => void;
+    onKeyDown: (event: React.KeyboardEvent) => void;
+};
+/**
+ * Horizontal gridlines from 0 to `niceCeil(yMax)` with labels in the left
+ * padding. Render inside the chart's `<svg>`.
+ */
+export declare function ChartYAxisGrid({ frame, yMax, tickCount, format, }: {
+    /** The chart's frame; lines span the plot, labels sit in the left padding. */
+    frame: ChartFrame;
+    /** The largest data value; the axis tops out at `niceCeil(yMax)`. */
+    yMax: number;
+    /** How many even steps from 0 to the top. Default 4. */
+    tickCount?: number;
+    /** Label text for a tick value. Default `compactNumber`. */
+    format?: (value: number) => string;
+}): React.JSX.Element;
+/**
+ * Readout for the hovered or focused point, placed in percent of the chart
+ * box (its wrapper must be `relative`). It sits right of the point and
+ * flips left past 55% so it does not clip at the edge.
+ */
+export declare function ChartTooltip({ xPct, yPct, className, style, children, ...props }: {
+    /** The point's x, in percent of the chart box's width. */
+    xPct: number;
+    /** The point's y, in percent of the chart box's height; capped at 60. */
+    yPct: number;
+} & React.ComponentProps<"div">): React.JSX.Element;
+/** A series' line key, shared by tooltip rows and legend keys. */
+type SeriesKeyProps = {
+    /** The series name. */
+    label: React.ReactNode;
+    /** The series stroke, e.g. `stroke-primary`. */
+    swatchClassName: string;
+    /** Draws the swatch dashed, for a dashed series line. */
+    dashed?: boolean;
+};
+/** Tooltip row: the value leads, the label follows, keyed by the series stroke. */
+export declare function ChartTooltipRow({ label, value, swatchClassName, dashed, }: SeriesKeyProps & {
+    /** The series' value at the point, shown first in bold. */
+    value: React.ReactNode;
+}): React.JSX.Element;
+/** Row of legend keys under a chart. */
+export declare function ChartLegend({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+/** One legend entry: a solid or dashed line swatch and its label. */
+export declare function ChartLegendKey({ label, swatchClassName, dashed, className, }: SeriesKeyProps & {
+    /** Classes for the key's wrapper. */
+    className?: string;
+}): React.JSX.Element;
+export {};

package/dist/chart.js

@@ -0,0 +1,177 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { clamp } from "./internal/math.js";
+import { overlaySurface } from "./internal/overlay-styles.js";
+import { cn } from "./utils.js";
+/** Room for compact y labels on the left and x labels underneath. */
+const defaultPadding = {
+    top: 10,
+    right: 12,
+    bottom: 20,
+    left: 40,
+};
+/**
+ * Frame for a chart `height` units tall. Charts that share a `width` and
+ * padding line up when stacked. The SVG scales to its box, so these are
+ * viewBox units, not pixels.
+ */
+export function chartFrame(height, { width = 640, padding, } = {}) {
+    const pad = { ...defaultPadding, ...padding };
+    const plotWidth = width - pad.left - pad.right;
+    const plotHeight = height - pad.top - pad.bottom;
+    return {
+        width,
+        height,
+        viewBox: `0 0 ${width} ${height}`,
+        left: pad.left,
+        right: pad.left + plotWidth,
+        top: pad.top,
+        bottom: pad.top + plotHeight,
+        plotWidth,
+        plotHeight,
+    };
+}
+/**
+ * Round `max` up to a clean axis ceiling (1, 2, 2.5, 4, or 5 × 10^n). The 4
+ * step keeps a value just past 25 off a half-empty 50 axis.
+ */
+export function niceCeil(max) {
+    if (max <= 0)
+        return 1;
+    const pow = 10 ** Math.floor(Math.log10(max));
+    for (const step of [1, 2, 2.5, 4, 5]) {
+        if (max <= step * pow)
+            return step * pow;
+    }
+    return 10 * pow;
+}
+/** `count` even steps from 0 to `niceCeil(max)`, both ends included. */
+export function niceTicks(max, count = 4) {
+    const top = niceCeil(max);
+    return Array.from({ length: count + 1 }, (_, i) => (top / count) * i);
+}
+/** Linear scale from [0, domainMax] onto [0, rangeMax]; a zero domain maps to 0. */
+export function scaleLinear(domainMax, rangeMax) {
+    return (value) => domainMax === 0 ? 0 : (value / domainMax) * rangeMax;
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** SVG path through the points (`M x y L x y …`); empty for no points. */
+export function linePath(points) {
+    return points
+        .map((p, i) => `${i === 0 ? "M" : "L"} ${round2(p.x)} ${round2(p.y)}`)
+        .join(" ");
+}
+/**
+ * A bar with a rounded data end and a square baseline. (x, y) is the top
+ * left; the bar grows down to y + h. Pass `r = 0` for a square bar.
+ */
+export function roundedTopBarPath(x, y, w, h, r = 4) {
+    const rad = Math.min(r, w / 2, h);
+    return [
+        `M ${round2(x)} ${round2(y + h)}`,
+        `L ${round2(x)} ${round2(y + rad)}`,
+        `Q ${round2(x)} ${round2(y)} ${round2(x + rad)} ${round2(y)}`,
+        `L ${round2(x + w - rad)} ${round2(y)}`,
+        `Q ${round2(x + w)} ${round2(y)} ${round2(x + w)} ${round2(y + rad)}`,
+        `L ${round2(x + w)} ${round2(y + h)}`,
+        "Z",
+    ].join(" ");
+}
+function trimZero(n) {
+    const fixed = n.toFixed(1);
+    return fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed;
+}
+/** Short axis label: 1500 → "1.5k", 2000000 → "2M". */
+export function compactNumber(n) {
+    const abs = Math.abs(n);
+    if (abs >= 1_000_000)
+        return `${trimZero(n / 1_000_000)}M`;
+    if (abs >= 1_000)
+        return `${trimZero(n / 1_000)}k`;
+    return String(Math.round(n));
+}
+/**
+ * Data index at viewBox x `viewX`. The plot spans `steps` intervals from
+ * `min`; the result is clamped to [min, max], so `max` can stop short of the
+ * axis (days not reached yet).
+ */
+export function indexAtPlotX(viewX, frame, { steps, min, max }) {
+    const index = Math.round(((viewX - frame.left) / frame.plotWidth) * steps) + min;
+    return clamp(index, min, max);
+}
+/** Arrow-key move by `delta`, clamped; with nothing picked it starts at `min`. */
+export function stepIndex(current, delta, { min, max }) {
+    if (current === null)
+        return min;
+    return clamp(current + delta, min, max);
+}
+/**
+ * Crosshair state: the pointer or the arrow keys pick a data index in
+ * [min, max], and Escape or leaving the plot clears it. Put `svgRef` and the
+ * handlers on the chart's `<svg>`, which needs `tabIndex={0}`.
+ */
+export function useChartScrub({ frame, steps, min, max, }) {
+    const svgRef = React.useRef(null);
+    const [index, setIndex] = React.useState(null);
+    const clear = React.useCallback(() => setIndex(null), []);
+    const onPointerMove = React.useCallback((event) => {
+        const rect = svgRef.current?.getBoundingClientRect();
+        if (!rect)
+            return;
+        const viewX = ((event.clientX - rect.left) / rect.width) * frame.width;
+        setIndex(indexAtPlotX(viewX, frame, { steps, min, max }));
+    }, [frame, steps, min, max]);
+    const onKeyDown = React.useCallback((event) => {
+        if (event.key === "ArrowRight" || event.key === "ArrowLeft") {
+            const delta = event.key === "ArrowRight" ? 1 : -1;
+            setIndex((current) => stepIndex(current, delta, { min, max }));
+            event.preventDefault();
+        }
+        else if (event.key === "Escape") {
+            setIndex(null);
+        }
+    }, [min, max]);
+    return { svgRef, index, clear, onPointerMove, onKeyDown };
+}
+/**
+ * Horizontal gridlines from 0 to `niceCeil(yMax)` with labels in the left
+ * padding. Render inside the chart's `<svg>`.
+ */
+export function ChartYAxisGrid({ frame, yMax, tickCount = 4, format = compactNumber, }) {
+    const ticks = niceTicks(yMax, tickCount);
+    const top = ticks[ticks.length - 1] ?? 1;
+    const y = (value) => frame.bottom - (value / top) * frame.plotHeight;
+    return (_jsx("g", { "data-slot": "chart-y-axis", children: ticks.map((tick) => (_jsxs("g", { children: [_jsx("line", { x1: frame.left, y1: y(tick), x2: frame.right, y2: y(tick), strokeWidth: 1, className: "stroke-border" }), _jsx("text", { x: frame.left - 6, y: y(tick) + 3, textAnchor: "end", className: "fill-muted-foreground text-[10px] tabular-nums", children: format(tick) })] }, tick))) }));
+}
+/**
+ * Readout for the hovered or focused point, placed in percent of the chart
+ * box (its wrapper must be `relative`). It sits right of the point and
+ * flips left past 55% so it does not clip at the edge.
+ */
+export function ChartTooltip({ xPct, yPct, className, style, children, ...props }) {
+    const flip = xPct > 55;
+    return (_jsx("div", { role: "status", "data-slot": "chart-tooltip", className: cn(overlaySurface, "pointer-events-none absolute z-10 min-w-32 px-2.5 py-2 text-xs", className), style: {
+            left: `${xPct}%`,
+            top: `${Math.min(yPct, 60)}%`,
+            transform: flip ? "translateX(calc(-100% - 12px))" : "translateX(12px)",
+            ...style,
+        }, ...props, children: children }));
+}
+function SeriesSwatch({ width, strokeWidth, dashed, className, }) {
+    return (_jsx("svg", { width: width, height: "4", "aria-hidden": true, className: "shrink-0", children: _jsx("line", { x1: "0", y1: "2", x2: width, y2: "2", strokeWidth: strokeWidth, strokeDasharray: dashed ? "3 2" : undefined, className: className }) }));
+}
+/** Tooltip row: the value leads, the label follows, keyed by the series stroke. */
+export function ChartTooltipRow({ label, value, swatchClassName, dashed, }) {
+    return (_jsxs("div", { "data-slot": "chart-tooltip-row", className: "flex items-center gap-2 py-0.5", children: [_jsx(SeriesSwatch, { width: 14, strokeWidth: 2.5, dashed: dashed, className: swatchClassName }), _jsx("span", { className: "font-semibold tabular-nums", children: value }), _jsx("span", { className: "text-muted-foreground", children: label })] }));
+}
+/** Row of legend keys under a chart. */
+export function ChartLegend({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "chart-legend", className: cn("flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground", className), ...props }));
+}
+/** One legend entry: a solid or dashed line swatch and its label. */
+export function ChartLegendKey({ label, swatchClassName, dashed, className, }) {
+    return (_jsxs("span", { "data-slot": "chart-legend-key", className: cn("inline-flex items-center gap-1.5", className), children: [_jsx(SeriesSwatch, { width: 16, strokeWidth: 2, dashed: dashed, className: swatchClassName }), label] }));
+}

package/dist/color-legend.d.ts

@@ -2,15 +2,23 @@ import type * as React from "react";
 export type ColorLegendItem = {
     /** CSS color from the app (map bins, status scales). The kit does not own it. */
     color: string;
+    /** Value range for the swatch, such as `0–10`, shown before the label. */
     range?: string;
+    /** What the color means. */
     label: string;
 };
 export type ColorLegendProps = Omit<React.ComponentProps<"figure">, "children" | "title"> & {
+    /** Heading above the list, drawn as the figure's caption. */
     title?: string;
+    /** One row per color, in display order. */
     items: ColorLegendItem[];
+    /** A small muted note under the list, such as the data source. */
     caption?: React.ReactNode;
+    /** Extra content after the caption. */
     children?: React.ReactNode;
+    /** Names the legend when there is no `title`. */
     "aria-label"?: string;
+    /** Classes for the figure, e.g. overlay position and card fill. */
     className?: string;
 };
 /**

package/dist/combobox.d.ts

@@ -1,29 +1,38 @@
 import * as React from "react";
+import type { SearchPickerProps } from "./search-picker.js";
 export type ComboboxOption = {
+    /** What `onValueChange` reports and `value` matches; unique in the list. */
     value: string;
+    /** The visible text, on the trigger when selected and in the list. */
     label: string;
 };
 type ComboboxProps = {
+    /** Every choice, in display order. */
     options: ComboboxOption[];
+    /** The selected option's value; the trigger shows its label. */
     value?: string;
+    /** Called with the chosen (or created) value; the popover then closes. */
     onValueChange: (value: string) => void;
+    /** Trigger text when nothing is selected. Default `"Select"`. */
     placeholder?: string;
+    /** Placeholder and accessible name for the search input. Default `"Search"`. */
     searchPlaceholder?: string;
-    emptyText?: string;
+    /** Disables the trigger, so the list cannot open. */
     disabled?: boolean;
+    /** Goes on the trigger, so a `<Label htmlFor>` names it. Generated when omitted. */
     id?: string;
     /** Classes for the trigger, e.g. its width; the list matches it. */
     className?: string;
-    /** Classes for the listbox, e.g. its height. Defaults to `max-h-60`. */
-    listClassName?: string;
     /**
      * Classes for the popover panel, e.g. a width other than the trigger's.
      * Defaults to the trigger width.
      */
     contentClassName?: string;
+    /** Marks the trigger invalid, drawing the error border. */
     "aria-invalid"?: boolean;
     /** Name the trigger when there is no `<Label htmlFor={id}>`. */
     "aria-label"?: string;
+    /** Id of the element that names the trigger and the list. */
     "aria-labelledby"?: string;
     /**
      * Offer creating the current query when it is not already an option.
@@ -41,7 +50,7 @@ type ComboboxProps = {
      * `Create "{value}"`.
      */
     createLabel?: (value: string) => string;
-} & Omit<React.ComponentProps<"button">, "value" | "defaultValue" | "children" | "type" | "role" | "aria-expanded" | "aria-controls" | "onKeyDown">;
+} & Pick<SearchPickerProps<ComboboxOption>, "emptyText" | "listClassName"> & Omit<React.ComponentProps<"button">, "value" | "defaultValue" | "children" | "type" | "role" | "aria-expanded" | "aria-controls" | "onKeyDown">;
 /**
  * Searchable single-select built from Button, Popover, and Input.
  * The trigger uses the same form-control chrome as Input and SelectTrigger.