atlas-react-kit 0.13.0 → 1.1.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
@@ -99,13 +129,10 @@ or the viewport minus gutters on small screens.
 
 Use `EmptyPanel` for empty states, `TableBodySkeleton` for loading table bodies,
 and `<Card flush>` for an edge-to-edge list or table. `Table` scrolls wide
-columns inside itself (`min-w-0 overflow-x-auto`) and tightens cell padding
-below `sm`. `CardContent className="px-0"`
-overrides body padding without `!px-0` when only the body should go flush. Cards
-keep `min-h-min shrink-0` so they do not collapse inside a bounded flex
-column, and `min-w-0` so nested tables scroll instead of widening the card.
-`Dialog` already scrolls inside the viewport on small screens; avoid
-additional height limits.
+columns inside itself, `Card` neither collapses in a bounded flex column nor
+widens around a nested table, and `Dialog` already scrolls inside the
+viewport on small screens; avoid additional height limits. The classes each
+one uses are in its COMPONENTS.md row.
 
 Apps decide how wide and tall containers and overlays are. The kit sets
 intrinsic control sizes (the button, input, tab and row heights, icons,
@@ -114,12 +141,10 @@ clamps overlays to the viewport, but no design widths or heights on
 dialogs, popovers, menus, or lists. Set them with `className`: give each
 `DialogContent` a width such as `sm:max-w-md`, and each `PopoverContent`
 one such as `w-72`. Where the sized part is not the element `className`
-reaches, a prop names it: `InfoTip` takes `contentClassName` (default
-`w-72`), and `Combobox` and `SearchPicker` take `listClassName` (default
-`max-h-60`). `TabsNav` fills a block container but sizes to its links in a
-flex row; add `w-full` to stretch it there. `Tooltip` keeps a `max-w-xs` reading width, `Textarea` a
-`min-h-16` starting height, and toasts their 356px width; override the first
-two with `className`.
+reaches, a `*ClassName` prop names it, with its default where there is one
+(COMPONENTS.md, "Styling parts"). The few parts that keep a reading width or
+a starting height (`Tooltip`, `Textarea`) take `className` to override it;
+toasts keep their width.
 
 Parents do not force sizes on their children. A vertical `Field` stretches
 its controls through the flex column, so a control's own width class (such
@@ -142,32 +167,28 @@ triggers as outline buttons in application code.
 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
+single column. Wrap a control the kit has no form field for (a colour
 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.
+`gap-3` spacing does not match. A field shows its error once the person has
+touched it (`meta.isTouched`), never on a field they have not reached yet.
+`submitted` is for form libraries that do not mark every field touched on
+submit; TanStack Form does, so its users pass `meta` only.
 
 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. App-shell destinations
+`TabsNav` of `TabsNavLink`s with `active` from the app. 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
-`overflow-x-auto` — that pairing forces `overflow-y: auto` and a stray
-vertical scrollbar.
-
-Use `FormTextField`, `FormSelectField`, `FormDatePickerField`,
-`FormDateTimePickerField`, `FormMarkdownField`, and `FormFeedbackField` for
-portable form controls, and `FieldError` for field messages. `Combobox` (popover)
+from the app, not tabs. Both links take `asChild` for a router link, or come
+as Next adapters (`next/tabs-nav-link`, `next/nav-link`); `isNavActive`
+compares the pathname with a link's `href`. `TabsNav` and `TabsList` scroll overflowing
+labels inside themselves, like `Table`. Do not wrap them in another
+horizontal scroller: that pairing adds a stray vertical scrollbar.
+
+Use the `form/*` fields (one row each in COMPONENTS.md) for portable form
+controls, and `FieldError` for field messages. `Combobox` (popover)
 and `SearchPicker` (always-visible list), `DatePickerButton` (including
 `mode="range"`), `DateTimePickerButton`, `Slider`, `Meter` (scale with ticks;
 `Progress` is a plain 0–100 job bar), `InfoTip` (longer than `Tooltip`),
 `Markdown`, `ColorLegend`, `StatTile`, `ThemeProvider`, `ErrorBoundary`, and
 `SortableTableHead` are first-class kit pieces. Domain data and application
 shells stay with the application: currency or timezone option lists,
-query-library error views, WYSIWYG editors, kanban boards, and dashboard
-widgets.
+query-library error views, and WYSIWYG editors.

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/nav-link` or `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.1.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.
 
@@ -54,7 +55,8 @@ with the application.
 - [Design rules](./DESIGN_RULES.md): tokens, accessibility, writing, and
   composition. This guide ships in the npm package.
 - [Contributing](./CONTRIBUTING.md): component changes, checks, and releases.
-- [Roadmap to 1.0](./ROADMAP-1.0.md): decisions needed before the 1.0 release.
+- [Decisions behind 1.0 (record)](./ROADMAP-1.0.md): the closed roadmap that
+  led to 1.0.0.
 - [Changelog](./CHANGELOG.md): published and upcoming changes.
 
 ## AI coding assistants
@@ -85,51 +87,8 @@ and package entry points for search and indexing tools.
 
 ## Development and releases
 
-```sh
-npm ci
-npm run check
-npm test
-npm pack
-npm ci --prefix site
-npm run build --prefix site
-npm run preview --prefix site
-```
-
-`tsc` emits individual ESM files and TypeScript declarations. CSS is shipped
-without compilation and processed by the consuming application's Tailwind build.
-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
-peer dependencies and are required only when those entry points are imported.
-The package does not bundle React.
-
-Run `npm run dev --prefix site` (or `npm run storybook --prefix site`) for the
-playground on port 6006. Existing examples live in `stories/` and are imported
-by CSF story files in `site/stories/`, so component tests and previews share the
-same examples. Add Storybook entries there when adding an example; the
-static-output check reports any existing demo that has no Storybook entry.
-Interactive stories use Storybook args so changing a control or interacting with
-the component updates the same value. Configuration is in `site/.storybook/`.
-
-The Storybook preview disables the kit's theme shortcut and uses the theme
-toolbar instead. The accessibility panel checks the rendered story; it does not
-replace keyboard or assistive-technology testing.
-
-Bumping the version in `package.json` and merging to `main` (path-filtered
-to package files) or running `workflow_dispatch` publishes through npm OIDC
-trusted publishing after check, test, and pack gates. Versions already on npm
-are skipped.
-
-If trusted publishing is not configured, pack and publish a validated
-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
-```
+Setup, checks, the component checklist, and releases are in
+[CONTRIBUTING.md](./CONTRIBUTING.md).
 
 Pin an exact package version in consuming applications. Roll back an upgrade by
 restoring the previous version and lockfile. License: MIT; upstream notices are

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/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" | "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
@@ -11,7 +12,5 @@ declare const buttonVariants: (props?: ({
     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] }));
+}