atlas-react-kit 0.13.0 → 1.0.0

package/dist/kanban.js

@@ -0,0 +1,197 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { DragDropProvider, DragOverlay, useDragOperation, useDroppable, } from "@dnd-kit/react";
+import { isSortable, useSortable } from "@dnd-kit/react/sortable";
+import { CheckCircle2, ChevronLeft, ChevronRight, GripVertical, Trash2, } from "lucide-react";
+import { Button } from "./button.js";
+import { KANBAN_COMPLETE_ID, KANBAN_DELETE_ID, buildKanbanGroups, kanbanOverflowEdges, kanbanScrollBy, resolveKanbanDrop, } from "./internal/kanban-layout.js";
+import { configureCardSortablePlugins, configureKanbanPlugins, } from "./internal/kanban-plugins.js";
+import { Skeleton } from "./skeleton.js";
+import { cn } from "./utils.js";
+/** Column droppables lose to cards, so a drop lands between cards. */
+const COLUMN_DROP_PRIORITY = 1;
+/** Rail zones beat columns when both are under the pointer. */
+const ACTION_ZONE_PRIORITY = 10;
+const columnSize = "w-72 min-w-72 min-h-[min(70vh,32rem)]";
+/**
+ * Drag-and-drop board built on dnd-kit. The consumer owns `items` and maps
+ * each to a column; the board derives its layout from them, so an optimistic
+ * cache update is the only state. Cards drag by their grip, the body stays
+ * clickable, and off-screen columns get edge fades and scroll buttons.
+ */
+function KanbanBoard({ columns, items, getColumnId, onMove, onComplete, onDelete, renderCard, onCardClick, isLoading = false, emptyLabel = "Drop here", completeLabel = "Finish", deleteLabel = "Remove", className, scrollerClassName, columnClassName, cardClassName, ...props }) {
+    const scrollerRef = React.useRef(null);
+    const overflow = useOverflowEdges(scrollerRef, columns.length, items.length);
+    const itemById = React.useMemo(() => new Map(items.map((item) => [item.id, item])), [items]);
+    const groups = React.useMemo(() => buildKanbanGroups(columns, items, getColumnId), [columns, items, getColumnId]);
+    const showSkeletons = isLoading && items.length === 0;
+    const dimmed = isLoading && !showSkeletons;
+    const handleDragOver = React.useCallback((event) => {
+        // Layout comes from `items`; stop dnd-kit moving cards between groups.
+        event.preventDefault();
+    }, []);
+    const handleDragEnd = React.useCallback((event) => {
+        if (event.canceled)
+            return;
+        const { source, target } = event.operation;
+        if (!source || !isSortable(source))
+            return;
+        const drop = resolveKanbanDrop({
+            itemId: String(source.id),
+            targetId: target ? String(target.id) : null,
+            targetGroup: target && isSortable(target) && target.group != null
+                ? String(target.group)
+                : null,
+            initialGroup: source.initialGroup != null ? String(source.initialGroup) : null,
+            currentGroup: source.group != null ? String(source.group) : null,
+            index: typeof source.index === "number" ? source.index : undefined,
+        }, groups);
+        if (!drop)
+            return;
+        if (drop.kind === "complete")
+            return onComplete?.(drop.itemId);
+        if (drop.kind === "delete")
+            return onDelete?.(drop.itemId);
+        const item = itemById.get(drop.itemId);
+        if (!item)
+            return;
+        onMove(item, drop.toColumnId, {
+            beforePosition: drop.beforeId
+                ? itemById.get(drop.beforeId)?.position
+                : undefined,
+            afterPosition: drop.afterId
+                ? itemById.get(drop.afterId)?.position
+                : undefined,
+        });
+    }, [groups, itemById, onComplete, onDelete, onMove]);
+    const scrollToStart = React.useCallback(() => kanbanScrollBy(scrollerRef.current, -1), []);
+    const scrollToEnd = React.useCallback(() => kanbanScrollBy(scrollerRef.current, 1), []);
+    const renderOverlay = React.useCallback((source) => {
+        const item = source ? itemById.get(String(source.id)) : undefined;
+        if (!item)
+            return null;
+        return (_jsxs("div", { "data-slot": "kanban-drag-overlay", className: cn(cardChrome, "shadow-lg ring-2 ring-ring/30", cardClassName), children: [_jsx("div", { className: cn(handleChrome, "cursor-grabbing"), children: _jsx(GripVertical, { className: "size-4", "aria-hidden": true }) }), _jsx("div", { className: "min-w-0 flex-1 p-3", children: renderCard(item) })] }));
+    }, [cardClassName, itemById, renderCard]);
+    // `min-w-0` lets a flex or grid parent shrink the board so the scroller,
+    // not the page, overflows.
+    return (_jsx("div", { "data-slot": "kanban-board", className: cn("min-w-0", className), ...props, children: _jsxs(DragDropProvider, { plugins: configureKanbanPlugins, onDragOver: handleDragOver, onDragEnd: handleDragEnd, children: [_jsxs("div", { className: "relative min-w-0", children: [_jsx("div", { ref: scrollerRef, "data-slot": "kanban-scroller", "data-loading": dimmed || undefined, "data-overflow-start": overflow.start || undefined, "data-overflow-end": overflow.end || undefined, onScroll: overflow.measure, className: cn("flex min-w-0 gap-4 overflow-x-auto pb-2", 
+                            // AutoScroller scrolls in small steps near the edge; mandatory
+                            // snap would pull each one back, so it is off mid-drag.
+                            "snap-x snap-mandatory scroll-px-2 has-data-dragging:snap-none", "data-loading:opacity-60", scrollerClassName), children: columns.map((column) => {
+                                const ids = groups[column.id] ?? [];
+                                return (_jsx(KanbanColumnView, { column: column, count: showSkeletons ? 0 : ids.length, emptyLabel: column.emptyLabel ?? emptyLabel, loading: showSkeletons, className: columnClassName, children: ids.map((id, index) => {
+                                        const item = itemById.get(id);
+                                        if (!item)
+                                            return null;
+                                        return (_jsx(KanbanCardView, { item: item, index: index, column: column.id, onCardClick: onCardClick, className: cardClassName, renderCard: renderCard }, id));
+                                    }) }, column.id));
+                            }) }), _jsx(OverflowFade, { side: "start", visible: overflow.start }), _jsx(OverflowFade, { side: "end", visible: overflow.end }), overflow.start ? (_jsx(ScrollButton, { side: "start", onClick: scrollToStart })) : null, overflow.end ? (_jsx(ScrollButton, { side: "end", onClick: scrollToEnd })) : null, overflow.start || overflow.end ? (_jsx("p", { className: "sr-only", children: "More columns available. Scroll horizontally to see them." })) : null] }), onComplete || onDelete ? (_jsx(ActionRail, { completeLabel: onComplete ? completeLabel : null, deleteLabel: onDelete ? deleteLabel : null })) : null, _jsx(DragOverlay, { dropAnimation: null, children: renderOverlay })] }) }));
+}
+function useOverflowEdges(ref, columnCount, itemCount) {
+    const [edges, setEdges] = React.useState({
+        start: false,
+        end: false,
+    });
+    const measure = React.useCallback(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const next = kanbanOverflowEdges(element.scrollLeft, element.clientWidth, element.scrollWidth);
+        // Scroll fires every frame; keep the old object so the board (and every
+        // card in it) re-renders only when an edge appears or goes.
+        setEdges((edges) => edges.start === next.start && edges.end === next.end ? edges : next);
+    }, [ref]);
+    React.useLayoutEffect(() => {
+        const element = ref.current;
+        if (!element || typeof ResizeObserver === "undefined")
+            return;
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        for (const child of element.children)
+            observer.observe(child);
+        return () => observer.disconnect();
+    }, [columnCount, itemCount, measure, ref]);
+    return { ...edges, measure };
+}
+function KanbanColumnView({ column, count, emptyLabel, loading, className, children, }) {
+    const { ref, isDropTarget } = useDroppable({
+        id: column.id,
+        type: "column",
+        accept: "item",
+        collisionPriority: COLUMN_DROP_PRIORITY,
+    });
+    const empty = count === 0;
+    return (_jsxs("div", { ref: ref, "data-slot": "kanban-column", "data-drop-target": isDropTarget || undefined, className: cn("flex shrink-0 snap-start flex-col gap-3 p-3", "bg-muted/40 ring-1 ring-foreground/5", "data-drop-target:bg-muted/60 data-drop-target:ring-2 data-drop-target:ring-ring/60", columnSize, className), children: [_jsxs("header", { "data-slot": "kanban-column-header", className: "flex items-start justify-between gap-2", children: [_jsxs("span", { className: "flex items-center gap-2 text-xs font-semibold tracking-widest uppercase", children: [column.color ? (_jsx("span", { "aria-hidden": true, className: "size-2 shrink-0 rounded-full", style: { backgroundColor: column.color } })) : null, _jsx("span", { className: "leading-tight", children: column.label })] }), _jsxs("span", { className: "flex shrink-0 flex-col items-end gap-0.5 text-muted-foreground tabular-nums", children: [_jsx("span", { className: "text-xs", children: count }), column.badge ? (_jsx("span", { className: "text-[10px] font-medium", children: column.badge })) : null] })] }), _jsx("div", { className: "flex min-h-32 flex-1 flex-col gap-2 overflow-y-auto pr-1", children: loading ? (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-20" }), _jsx(Skeleton, { className: "h-16" })] })) : (_jsxs(_Fragment, { children: [children, _jsx("p", { "data-slot": "kanban-column-empty", "aria-hidden": !empty, className: cn("border border-dashed px-3 py-6 text-center text-xs text-muted-foreground", !empty && "hidden"), children: emptyLabel })] })) })] }));
+}
+const cardChrome = cn("flex border border-border bg-card text-card-foreground");
+const handleChrome = cn("flex shrink-0 items-center self-stretch border-r border-border", "bg-muted/30 px-1.5 text-muted-foreground");
+function stopClick(event) {
+    event.stopPropagation();
+}
+function KanbanCardViewImpl({ item, index, column, onCardClick, className, renderCard, }) {
+    const children = renderCard(item);
+    const { handleRef, ref, isDragging } = useSortable({
+        id: item.id,
+        index,
+        type: "item",
+        accept: "item",
+        group: column,
+        transition: null,
+        plugins: configureCardSortablePlugins,
+    });
+    return (_jsxs("div", { ref: ref, "data-slot": "kanban-card", "data-dragging": isDragging || undefined, className: cn(cardChrome, "shadow-sm transition-[box-shadow,opacity,border-color]", 
+        // The overlay moves; the source keeps its slot.
+        "data-dragging:pointer-events-none data-dragging:invisible", 
+        // One ring on the card for the grip and the body alike.
+        "has-focus-visible:ring-2 has-focus-visible:ring-ring has-focus-visible:ring-offset-2 has-focus-visible:ring-offset-background", onCardClick && "hover:border-foreground/15", className), children: [_jsx("button", { type: "button", ref: handleRef, "data-slot": "kanban-card-handle", "aria-label": "Drag to move", onClick: stopClick, className: cn(handleChrome, "cursor-grab outline-none hover:bg-muted/50 active:cursor-grabbing"), children: _jsx(GripVertical, { className: "size-4", "aria-hidden": true }) }), onCardClick ? (_jsx("button", { type: "button", "data-slot": "kanban-card-body", onClick: () => onCardClick(item), className: "min-w-0 flex-1 cursor-pointer p-3 text-left outline-none hover:bg-muted/20", children: children })) : (_jsx("div", { "data-slot": "kanban-card-body", className: "min-w-0 flex-1 p-3", children: children }))] }));
+}
+/**
+ * Memoized so a board update re-renders only the cards whose item, index or
+ * column changed, when `renderCard` and the other props keep their identity.
+ */
+const KanbanCardView = React.memo(KanbanCardViewImpl);
+/**
+ * Finish / Remove zones under the board while a card drags. Not sticky: a
+ * sticky rail overlapping tall columns stole their drops.
+ */
+function ActionRail({ completeLabel, deleteLabel, }) {
+    const dragging = useDragOperation().source != null;
+    return (_jsxs("div", { "data-slot": "kanban-action-rail", "aria-hidden": !dragging, className: cn("relative z-20 -mx-1 mt-3 flex flex-col gap-2 bg-background px-1 pb-1 sm:flex-row", !dragging && "pointer-events-none"), children: [completeLabel != null ? (_jsx(ActionZone, { id: KANBAN_COMPLETE_ID, label: completeLabel, regionLabel: "Drop here to finish", icon: CheckCircle2, tone: "success", visible: dragging })) : null, deleteLabel != null ? (_jsx(ActionZone, { id: KANBAN_DELETE_ID, label: deleteLabel, regionLabel: "Drop here to remove", icon: Trash2, tone: "destructive", visible: dragging })) : null] }));
+}
+const zoneTone = {
+    success: {
+        idle: "border-success/60 bg-success/10 text-success",
+        active: "border-success bg-success/25 text-success ring-2 ring-success/40",
+    },
+    destructive: {
+        idle: "border-destructive/60 bg-destructive/10 text-destructive",
+        active: "border-destructive bg-destructive/25 text-destructive ring-2 ring-destructive/40",
+    },
+};
+function ActionZone({ id, label, regionLabel, icon: Icon, tone, visible, }) {
+    const { ref, isDropTarget } = useDroppable({
+        id,
+        type: "column",
+        accept: "item",
+        collisionPriority: ACTION_ZONE_PRIORITY,
+        disabled: !visible,
+    });
+    // A ring, not a scale, marks the target: scale clips in overflow parents.
+    return (_jsxs("div", { ref: ref, role: "region", "aria-label": regionLabel, "aria-hidden": !visible, "data-slot": "kanban-action-zone", "data-drop-target": isDropTarget || undefined, className: cn("relative z-10 flex flex-1 items-center justify-center gap-2 border-2 border-dashed p-3", "text-sm font-medium transition-[box-shadow,border-color,background-color,color] duration-150", visible ? "opacity-100" : "pointer-events-none opacity-0", isDropTarget ? zoneTone[tone].active : zoneTone[tone].idle), children: [_jsx(Icon, { className: "size-4 shrink-0", "aria-hidden": true }), label] }));
+}
+function ScrollButton({ side, onClick, }) {
+    const Icon = side === "start" ? ChevronLeft : ChevronRight;
+    return (_jsx(Button, { type: "button", variant: "outline", size: "icon-sm", "data-slot": "kanban-scroll-button", "aria-label": side === "start" ? "Show previous columns" : "Show next columns", onClick: onClick, className: cn("absolute top-1/2 z-20 -translate-y-1/2", side === "start" ? "left-1" : "right-1"), children: _jsx(Icon, {}) }));
+}
+function OverflowFade({ side, visible, }) {
+    return (_jsx("div", { "aria-hidden": true, "data-slot": "kanban-overflow-fade", "data-side": side, className: cn("pointer-events-none absolute inset-y-0 z-10 w-10 to-transparent transition-opacity", side === "start"
+            ? "left-0 bg-gradient-to-r from-background"
+            : "right-0 bg-gradient-to-l from-background", visible ? "opacity-100" : "opacity-0") }));
+}
+/** Board-shaped placeholder for a route `loading` file. */
+function KanbanSkeleton({ columnCount = 4, className, columnClassName, ...props }) {
+    return (_jsx("div", { "data-slot": "kanban-skeleton", className: cn("flex gap-4 overflow-hidden", className), ...props, children: Array.from({ length: columnCount }, (_, index) => (_jsx(Skeleton, { className: cn("shrink-0", columnSize, columnClassName) }, index))) }));
+}
+export { KanbanBoard, KanbanSkeleton };

package/dist/markdown.d.ts

@@ -4,7 +4,9 @@
  */
 export declare function safeMarkdownUrl(url: string): string;
 export type MarkdownProps = {
+    /** Markdown source to render. Raw HTML is dropped and unsafe URLs are removed. */
     content: string;
+    /** Classes for the `article` wrapper. */
     className?: string;
 };
 /**

package/dist/meter.d.ts

@@ -2,16 +2,23 @@ import type * as React from "react";
 export type MeterMarker = {
     /** Same scale as `value` / `min` / `max` (not a 0–1 fraction). */
     position: number;
+    /** Classes for the tick, e.g. its color. */
     className?: string;
 };
 export type MeterProps = Omit<React.ComponentProps<"div">, "children" | "role" | "aria-label"> & {
+    /** Current reading. Clamped to `min`–`max`; a non-finite value shows as empty. */
     value: number;
+    /** Start of the scale. Default `0`. */
     min?: number;
+    /** End of the scale. */
     max: number;
     /** App-owned fill (status, pace). Defaults to primary. */
     fillClassName?: string;
+    /** Thin ticks drawn over the track, e.g. a cap or a typical value. */
     markers?: MeterMarker[];
+    /** Required accessible name; the meter has no visible label. */
     "aria-label": string;
+    /** Classes for the track. */
     className?: string;
 };
 /**

package/dist/nav-link.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { AsChildProps } from "./internal/as-child.js";
 /**
  * Pill chrome for app-shell navigation. Inactive is muted text with an
  * accent hover; active uses the shared selected wash, text, and border
@@ -15,8 +16,8 @@ declare const navLinkVariants: (props?: import("class-variance-authority/types")
  * and `tabsTriggerVariants()`. Next apps can import the optional adapter
  * from `atlas-react-kit/next/nav-link` instead of composing `asChild`.
  */
-declare function NavLink({ asChild, active, className, ...props }: React.ComponentProps<"a"> & {
-    asChild?: boolean;
+declare function NavLink({ asChild, active, className, ...props }: React.ComponentProps<"a"> & AsChildProps & {
+    /** This link is the current page: `aria-current="page"` and the selected chrome. */
     active: boolean;
 }): React.JSX.Element;
 export { NavLink, navLinkVariants };

package/dist/next/period-stepper.d.ts

@@ -0,0 +1,11 @@
+import { type PeriodStepperFrameProps } from "../period-stepper.js";
+/**
+ * Next.js `PeriodStepper`: each step is a prefetched link, so the period
+ * lives in the URL. Leave out `todayHref` to drop the Today link.
+ */
+declare function PeriodStepper({ previousHref, todayHref, nextHref, ...props }: PeriodStepperFrameProps & {
+    previousHref: string;
+    todayHref?: string;
+    nextHref: string;
+}): import("react").JSX.Element;
+export { PeriodStepper };

package/dist/next/period-stepper.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Link from "next/link.js";
+import { PeriodStepperFrame, } from "../period-stepper.js";
+/**
+ * Next.js `PeriodStepper`: each step is a prefetched link, so the period
+ * lives in the URL. Leave out `todayHref` to drop the Today link.
+ */
+function PeriodStepper({ previousHref, todayHref, nextHref, ...props }) {
+    const hrefs = { previous: previousHref, today: todayHref, next: nextHref };
+    return (_jsx(PeriodStepperFrame, { ...props, control: (step, content) => {
+            const href = hrefs[step];
+            return href ? (_jsx(Link, { href: href, prefetch: true, children: content })) : null;
+        } }));
+}
+export { PeriodStepper };

package/dist/page-header.d.ts

@@ -0,0 +1,19 @@
+import type * as React from "react";
+/**
+ * A page's title row: the heading, an optional hint, anything else that
+ * belongs under them (badges, meta), and actions on the right. Stacks on
+ * small screens.
+ */
+declare function PageHeader({ title, description, actions, titleAs: Title, titleClassName, className, children, ...props }: {
+    /** The page heading. */
+    title: React.ReactNode;
+    /** Muted hint under the title. */
+    description?: React.ReactNode;
+    /** Buttons or links on the right (stacked below on small screens). */
+    actions?: React.ReactNode;
+    /** Heading level. Default `h1`. */
+    titleAs?: "h1" | "h2" | "h3";
+    /** Classes for the heading. */
+    titleClassName?: string;
+} & Omit<React.ComponentProps<"header">, "title">): React.JSX.Element;
+export { PageHeader };

package/dist/page-header.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "./utils.js";
+/**
+ * A page's title row: the heading, an optional hint, anything else that
+ * belongs under them (badges, meta), and actions on the right. Stacks on
+ * small screens.
+ */
+function PageHeader({ title, description, actions, titleAs: Title = "h1", titleClassName, className, children, ...props }) {
+    return (_jsxs("header", { "data-slot": "page-header", className: cn("flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-start sm:justify-between", className), ...props, children: [_jsxs("div", { "data-slot": "page-header-heading", className: "flex min-w-0 flex-col gap-1", children: [_jsx(Title, { "data-slot": "page-header-title", className: cn("text-2xl font-semibold tracking-tight", titleClassName), children: title }), description ? (_jsx("p", { "data-slot": "page-header-description", className: "text-sm text-muted-foreground", children: description })) : null, children] }), actions ? (_jsx("div", { "data-slot": "page-header-actions", className: "flex flex-wrap items-center gap-2", children: actions })) : null] }));
+}
+export { PageHeader };

package/dist/pagination.d.ts

@@ -9,7 +9,9 @@ declare function Pagination({ className, ...props }: React.ComponentProps<"nav">
 declare function PaginationContent({ className, ...props }: React.ComponentProps<"ul">): React.JSX.Element;
 declare function PaginationItem({ ...props }: React.ComponentProps<"li">): React.JSX.Element;
 type PaginationLinkProps = {
+    /** This link is the current page: `aria-current="page"` and the selected wash. */
     isActive?: boolean;
+    /** `icon` (default) is a square page number; `default` fits text such as Previous. */
     size?: "default" | "icon";
     /**
      * No page to go to, such as Previous on the first page. Renders without

package/dist/period-stepper.d.ts

@@ -0,0 +1,32 @@
+import type * as React from "react";
+type PeriodStepperFrameProps = {
+    /** The range shown, announced when it changes. */
+    label: React.ReactNode;
+    /** What one step moves ("month", "week"), for the button names. */
+    stepLabel: string;
+    /** Classes for the range heading. */
+    labelClassName?: string;
+} & Omit<React.ComponentProps<"div">, "children">;
+/**
+ * Layout under both steppers. `control` renders each step as the element a
+ * `Button` wraps (`asChild`), such as another router's link; returning
+ * `null` for "today" drops that button.
+ */
+declare function PeriodStepperFrame({ label, stepLabel, labelClassName, className, control, ...props }: PeriodStepperFrameProps & {
+    /** Renders the element for each step; return `null` for "today" to drop it. */
+    control: (step: "previous" | "today" | "next", content: React.ReactNode) => React.ReactElement | null;
+}): React.JSX.Element;
+/**
+ * Previous / Today / Next buttons and the range they show (a month, a
+ * week). The app owns the period; for URL-driven periods in Next use
+ * `next/period-stepper`. Leave out `onToday` to drop the Today button.
+ */
+declare function PeriodStepper({ onPrevious, onToday, onNext, ...props }: PeriodStepperFrameProps & {
+    /** Called when Previous is pressed. */
+    onPrevious: () => void;
+    /** Called when Today is pressed. Leave out to drop the Today button. */
+    onToday?: () => void;
+    /** Called when Next is pressed. */
+    onNext: () => void;
+}): React.JSX.Element;
+export { PeriodStepper, PeriodStepperFrame, type PeriodStepperFrameProps };

package/dist/period-stepper.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { Button } from "./button.js";
+import { cn } from "./utils.js";
+/**
+ * Layout under both steppers. `control` renders each step as the element a
+ * `Button` wraps (`asChild`), such as another router's link; returning
+ * `null` for "today" drops that button.
+ */
+function PeriodStepperFrame({ label, stepLabel, labelClassName, className, control, ...props }) {
+    const today = control("today", "Today");
+    return (_jsxs("div", { "data-slot": "period-stepper", className: cn("flex flex-wrap items-center gap-2", className), ...props, children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": `Previous ${stepLabel}`, asChild: true, children: control("previous", _jsx(ChevronLeft, {})) }), today ? (_jsx(Button, { variant: "outline", size: "sm", asChild: true, children: today })) : null, _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": `Next ${stepLabel}`, asChild: true, children: control("next", _jsx(ChevronRight, {})) }), _jsx("h2", { "aria-live": "polite", "data-slot": "period-stepper-label", className: cn("text-base font-semibold tabular-nums", labelClassName), children: label })] }));
+}
+/**
+ * Previous / Today / Next buttons and the range they show (a month, a
+ * week). The app owns the period; for URL-driven periods in Next use
+ * `next/period-stepper`. Leave out `onToday` to drop the Today button.
+ */
+function PeriodStepper({ onPrevious, onToday, onNext, ...props }) {
+    const handlers = { previous: onPrevious, today: onToday, next: onNext };
+    return (_jsx(PeriodStepperFrame, { ...props, control: (step, content) => {
+            const onClick = handlers[step];
+            return onClick ? (_jsx("button", { type: "button", onClick: onClick, children: content })) : null;
+        } }));
+}
+export { PeriodStepper, PeriodStepperFrame };

package/dist/picker-shell.d.ts

@@ -39,13 +39,20 @@ export type PickerCalendarProps = {
 };
 /** Props both pickers take for their trigger and popover. */
 export type PickerTriggerProps = {
+    /** Id of the trigger button; the trigger text gets `${id}-value`. */
     id?: string;
+    /**
+     * Trigger text while nothing is picked. Defaults to "Pick a date", "Pick a
+     * date range", or "Pick a date and time" depending on the picker.
+     */
     placeholder?: string;
+    /** Disable the trigger so the popover cannot open. */
     disabled?: boolean;
     /** Classes for the trigger button. */
     className?: string;
     /** Classes for the popover content, e.g. a width such as `w-80`. */
     contentClassName?: string;
+    /** Mark the trigger invalid, e.g. when its field has an error. */
     "aria-invalid"?: boolean;
     /**
      * Forwarded to the trigger. To name it from a visible label while still
@@ -86,8 +93,11 @@ type PickerShellProps = Omit<PickerTriggerProps, "placeholder" | "defaultMonth"
     label: string;
     /** Accessible name of the popover dialog. */
     dialogLabel: string;
+    /** Whether the popover is open. */
     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;
 };
@@ -95,7 +105,9 @@ type PickerShellProps = Omit<PickerTriggerProps, "placeholder" | "defaultMonth"
 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;
 export {};

package/dist/picker-shell.js

@@ -37,7 +37,7 @@ export function limitCalendarProps(calendarProps, minDate, maxDate) {
 }
 /** 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", id: id ? pickerValueId(id) : undefined, children: label })] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, "aria-label": dialogLabel, 
+    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, 
                 // 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.

package/dist/progress.d.ts

@@ -7,6 +7,7 @@ import { Progress as ProgressPrimitive } from "radix-ui";
  * label. `indicatorClassName` styles the fill (default `bg-primary`).
  */
 declare function Progress({ className, indicatorClassName, value, max, ...props }: React.ComponentProps<typeof ProgressPrimitive.Root> & {
+    /** Classes for the fill, e.g. a status color. Defaults to `bg-primary`. */
     indicatorClassName?: string;
 }): React.JSX.Element;
 export { Progress };

package/dist/search-picker.d.ts

@@ -6,17 +6,29 @@ export { foldSearchText };
  */
 export declare function defaultSearchFilter<T>(item: T, query: string, getLabel: (item: T) => string): boolean;
 export type SearchPickerProps<T> = {
+    /** Every choice, in display order. */
     items: T[];
+    /** A unique, stable value for an item; matched against `value`. */
     getValue: (item: T) => string;
+    /** The item's visible text, also what the default filter searches. */
     getLabel: (item: T) => string;
+    /** Whether an item matches the query. Default `defaultSearchFilter` (label contains query, ignoring case and accents). */
     filter?: (item: T, query: string, getLabel: (item: T) => string) => boolean;
+    /** The selected item's value, marked in the list. */
     value?: string;
+    /** Called with the item picked by click or Enter; the query then clears. */
     onSelect: (item: T) => void;
+    /** Visible label for the search input. */
     label: string;
+    /** Placeholder for the search input. Default `"Search"`. */
     placeholder?: string;
+    /** Text shown when nothing matches the query. Default `"No results"`. */
     emptyText?: string;
+    /** Accessible name for the listbox. Defaults to `label`. */
     listLabel?: string;
+    /** Disables the input and every option. */
     disabled?: boolean;
+    /** Classes for the wrapper, e.g. its width. */
     className?: string;
     /** Classes for the listbox, e.g. its height. Defaults to `max-h-60`. */
     listClassName?: string;

package/dist/select.d.ts

@@ -4,6 +4,7 @@ declare function Select({ ...props }: React.ComponentProps<typeof SelectPrimitiv
 declare function SelectGroup({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Group>): React.JSX.Element;
 declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>): React.JSX.Element;
 declare function SelectTrigger({ className, size, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+    /** Trigger height: `default` (`h-10`) or `sm` (`h-9`). Default `default`. */
     size?: "sm" | "default";
 }): React.JSX.Element;
 declare function SelectContent({ className, children, position, align, sideOffset, collisionPadding, ...props }: React.ComponentProps<typeof SelectPrimitive.Content>): React.JSX.Element;

package/dist/skip-link.d.ts

@@ -0,0 +1,7 @@
+import type * as React from "react";
+/**
+ * First focusable link on the page: hidden until a keyboard user tabs to
+ * it, then it jumps past the navigation to `href` (the main landmark's id).
+ */
+declare function SkipLink({ href, className, children, ...props }: React.ComponentProps<"a">): React.JSX.Element;
+export { SkipLink };

package/dist/skip-link.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "./utils.js";
+/**
+ * First focusable link on the page: hidden until a keyboard user tabs to
+ * it, then it jumps past the navigation to `href` (the main landmark's id).
+ */
+function SkipLink({ href = "#main-content", className, children = "Skip to content", ...props }) {
+    return (_jsx("a", { "data-slot": "skip-link", href: href, className: cn("sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-background focus:px-3 focus:py-2 focus:text-sm focus:ring-2 focus:ring-ring", className), ...props, children: children }));
+}
+export { SkipLink };

package/dist/slider.d.ts

@@ -1,18 +1,29 @@
 import type * as React from "react";
 import { Slider as SliderPrimitive } from "radix-ui";
 export type SliderProps = Omit<React.ComponentProps<typeof SliderPrimitive.Root>, "value" | "defaultValue" | "onValueChange" | "onValueCommit" | "children"> & {
+    /** The current value; the slider is always controlled. */
     value: number;
+    /** Called with the new value on every move while dragging or on a key press. */
     onValueChange: (value: number) => void;
+    /** Called with the final value when a drag ends or a key press settles. */
     onValueCommit?: (value: number) => void;
+    /** The lowest value. Default 0. */
     min?: number;
+    /** The highest value. Default 100. */
     max?: number;
+    /** The amount each move snaps to. Default 1. */
     step?: number;
+    /** Dims the slider and ignores pointer and keyboard input. */
     disabled?: boolean;
     /** Goes on the thumb, so a `<Label htmlFor>` names the slider. */
     id?: string;
+    /** Form field name, so the value submits with a surrounding `<form>`. */
     name?: string;
+    /** Classes for the root, e.g. its width. */
     className?: string;
+    /** Names the slider when there is no `<Label htmlFor={id}>`. Goes on the thumb. */
     "aria-label"?: string;
+    /** Id of the element that names the slider. Goes on the thumb. */
     "aria-labelledby"?: string;
 };
 /**

package/dist/sortable-table-head.d.ts

@@ -4,7 +4,9 @@ export type SortDirection = "asc" | "desc";
 type SortableTableHeadProps = ComponentProps<typeof TableHead> & {
     /** Whether this column is the active sort key. */
     sorted?: boolean;
+    /** Sort order shown while `sorted`. Default `asc`. */
     direction?: SortDirection;
+    /** Called when the header button is pressed, e.g. to toggle the sort. */
     onClick?: () => void;
     /** Classes for the inner sort button (`data-slot="sortable-table-head-button"`). */
     buttonClassName?: string;

package/dist/stat-tile.d.ts

@@ -8,10 +8,15 @@ export { sectionLabel };
 /** Row of tiles: stacked on phones, divided columns from `sm`. */
 export declare const statTileGrid = "grid ring-1 ring-foreground/5 sm:divide-x";
 export type StatTileProps = Omit<React.ComponentProps<"div">, "children" | "title"> & {
+    /** Small uppercase label above the figure. */
     label: string;
+    /** The big figure, already formatted. */
     value: string;
+    /** Muted line under the figure; hidden when empty. */
     sub?: React.ReactNode;
+    /** Extra content between the figure and `sub`, e.g. a `Meter`. */
     children?: React.ReactNode;
+    /** Classes for the root `div`. */
     className?: string;
 };
 /**

package/dist/table-body-skeleton.d.ts

@@ -1,5 +1,7 @@
 type Props = {
+    /** Placeholder cells per row; match the table's column count. */
     columns: number;
+    /** Placeholder rows. Default `5`. */
     rows?: number;
     /** Classes for the `tbody`. */
     className?: string;

package/dist/table.d.ts

@@ -11,6 +11,7 @@ import * as React from "react";
  * cap (`max-h-96 overflow-y-auto`) or a border.
  */
 declare function Table({ className, containerClassName, ...props }: React.ComponentProps<"table"> & {
+    /** Classes for the scroller around the table, e.g. a height cap or border. */
     containerClassName?: string;
 }): React.JSX.Element;
 declare function TableHeader({ className, ...props }: React.ComponentProps<"thead">): React.JSX.Element;