atlas-react-kit 0.12.0 → 1.0.0

package/dist/internal/kanban-layout.d.ts

@@ -0,0 +1,55 @@
+/** Column id → ordered card ids, derived from the consumer's `items`. */
+export type KanbanGroups = Record<string, string[]>;
+/** Drop zone ids for the drag-time action rail. */
+export declare const KANBAN_COMPLETE_ID = "__kanban_complete__";
+export declare const KANBAN_DELETE_ID = "__kanban_delete__";
+export declare function buildKanbanGroups<T extends {
+    id: string;
+}>(columns: {
+    id: string;
+}[], items: T[], getColumnId: (item: T) => string): KanbanGroups;
+/** What dnd-kit reports at drag end, reduced to plain ids. */
+export type KanbanDropInput = {
+    itemId: string;
+    /** Droppable under the pointer: a column, a card, or a rail zone. */
+    targetId: string | null;
+    /** The target card's column, when the target is a card. */
+    targetGroup: string | null;
+    /** Column the card started in. */
+    initialGroup: string | null;
+    /** Column the card is over now. */
+    currentGroup: string | null;
+    /** Sortable index in the target column. */
+    index: number | undefined;
+};
+export type KanbanDrop = {
+    kind: "complete";
+    itemId: string;
+} | {
+    kind: "delete";
+    itemId: string;
+} | {
+    kind: "move";
+    itemId: string;
+    toColumnId: string;
+    beforeId: string | null;
+    afterId: string | null;
+};
+/**
+ * Turn a drop into a complete, delete, or move with the neighbours at the
+ * insertion slot. `null` when the drop changes nothing.
+ */
+export declare function resolveKanbanDrop(input: KanbanDropInput, groups: KanbanGroups): KanbanDrop | null;
+export type KanbanOverflowEdges = {
+    start: boolean;
+    end: boolean;
+};
+/** Whether a horizontal scroller has more content past either edge. */
+export declare function kanbanOverflowEdges(scrollLeft: number, clientWidth: number, scrollWidth: number): KanbanOverflowEdges;
+/** One "page" of columns: most of the viewport, at least one narrow column. */
+export declare function kanbanScrollStepPx(clientWidth: number): number;
+/** Smooth-scroll toward the start (`-1`) or end (`1`); no-op without a scroller. */
+export declare function kanbanScrollBy(scroller: {
+    clientWidth: number;
+    scrollBy: (options: ScrollToOptions) => void;
+} | null, direction: -1 | 1): void;

package/dist/internal/kanban-layout.js

@@ -0,0 +1,80 @@
+/** Drop zone ids for the drag-time action rail. */
+export const KANBAN_COMPLETE_ID = "__kanban_complete__";
+export const KANBAN_DELETE_ID = "__kanban_delete__";
+export function buildKanbanGroups(columns, items, getColumnId) {
+    const groups = {};
+    for (const column of columns)
+        groups[column.id] = [];
+    for (const item of items) {
+        const columnId = getColumnId(item);
+        const group = groups[columnId];
+        if (!group) {
+            console.warn(`[KanbanBoard] item "${item.id}" maps to unknown column "${columnId}" and is not rendered`);
+            continue;
+        }
+        group.push(item.id);
+    }
+    return groups;
+}
+function targetColumn(input, groups) {
+    const { targetId, targetGroup, currentGroup } = input;
+    if (targetId != null) {
+        if (targetId in groups)
+            return targetId;
+        if (targetGroup != null)
+            return targetGroup;
+        for (const [columnId, ids] of Object.entries(groups)) {
+            if (ids.includes(targetId))
+                return columnId;
+        }
+    }
+    return currentGroup;
+}
+/**
+ * Turn a drop into a complete, delete, or move with the neighbours at the
+ * insertion slot. `null` when the drop changes nothing.
+ */
+export function resolveKanbanDrop(input, groups) {
+    const { itemId, targetId, initialGroup, index: rawIndex } = input;
+    if (targetId === KANBAN_COMPLETE_ID)
+        return { kind: "complete", itemId };
+    if (targetId === KANBAN_DELETE_ID)
+        return { kind: "delete", itemId };
+    const toColumnId = targetColumn(input, groups);
+    if (!initialGroup || !toColumnId)
+        return null;
+    const columnItems = groups[toColumnId] ?? [];
+    const remaining = columnItems.filter((id) => id !== itemId);
+    const index = Math.max(0, Math.min(rawIndex ?? remaining.length, remaining.length));
+    if (initialGroup === toColumnId && index === columnItems.indexOf(itemId)) {
+        return null;
+    }
+    return {
+        kind: "move",
+        itemId,
+        toColumnId,
+        beforeId: index > 0 ? (remaining[index - 1] ?? null) : null,
+        afterId: remaining[index] ?? null,
+    };
+}
+/** Pixel slop so sub-pixel scrollWidth vs clientWidth does not flicker cues. */
+const OVERFLOW_EDGE_PX = 8;
+/** Whether a horizontal scroller has more content past either edge. */
+export function kanbanOverflowEdges(scrollLeft, clientWidth, scrollWidth) {
+    const maxScroll = Math.max(0, scrollWidth - clientWidth);
+    return {
+        start: scrollLeft > OVERFLOW_EDGE_PX,
+        end: scrollLeft < maxScroll - OVERFLOW_EDGE_PX,
+    };
+}
+/** One "page" of columns: most of the viewport, at least one narrow column. */
+export function kanbanScrollStepPx(clientWidth) {
+    return Math.max(140, Math.round(clientWidth * 0.75));
+}
+/** Smooth-scroll toward the start (`-1`) or end (`1`); no-op without a scroller. */
+export function kanbanScrollBy(scroller, direction) {
+    scroller?.scrollBy({
+        left: direction * kanbanScrollStepPx(scroller.clientWidth),
+        behavior: "smooth",
+    });
+}

package/dist/internal/kanban-plugins.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentProps } from "react";
+import type { DragDropProvider } from "@dnd-kit/react";
+type PluginsProp = NonNullable<ComponentProps<typeof DragDropProvider>["plugins"]>;
+/**
+ * Board plugins. AutoScroller stays (edge scroll while dragging). Feedback
+ * stays because it positions and sizes `DragOverlay`; `feedback: "none"`
+ * would leave the overlay behind. The drop animation is off so it does not
+ * snap twice against an optimistic update.
+ */
+export declare const configureKanbanPlugins: Extract<PluginsProp, (...args: never[]) => unknown>;
+/**
+ * Cards leave out OptimisticSortingPlugin: it moves DOM nodes under React and
+ * throws `removeChild` on re-render (dnd-kit #1747). Column layout comes from
+ * the consumer's `items`.
+ */
+export declare function configureCardSortablePlugins<T>(defaults: readonly T[]): T[];
+export {};

package/dist/internal/kanban-plugins.js

@@ -0,0 +1,17 @@
+import { Feedback } from "@dnd-kit/dom";
+import { OptimisticSortingPlugin } from "@dnd-kit/dom/sortable";
+/**
+ * Board plugins. AutoScroller stays (edge scroll while dragging). Feedback
+ * stays because it positions and sizes `DragOverlay`; `feedback: "none"`
+ * would leave the overlay behind. The drop animation is off so it does not
+ * snap twice against an optimistic update.
+ */
+export const configureKanbanPlugins = (defaults) => defaults.map((plugin) => plugin === Feedback ? Feedback.configure({ dropAnimation: null }) : plugin);
+/**
+ * Cards leave out OptimisticSortingPlugin: it moves DOM nodes under React and
+ * throws `removeChild` on re-render (dnd-kit #1747). Column layout comes from
+ * the consumer's `items`.
+ */
+export function configureCardSortablePlugins(defaults) {
+    return defaults.filter((plugin) => plugin !== OptimisticSortingPlugin);
+}

package/dist/internal/use-media-query.d.ts

@@ -1,7 +1,9 @@
 /** Tailwind `md` breakpoint. Used for range calendars that stack on small screens. */
 export declare const MD_MEDIA_QUERY = "(min-width: 768px)";
 /**
- * Subscribe to a CSS media query. `defaultMatches` covers SSR and environments
- * without `matchMedia` (jsdom unless the test stubs it).
+ * Subscribe to a CSS media query with `useSyncExternalStore`. The server
+ * render and hydration use `defaultMatches`, so the markup always agrees;
+ * React then re-renders with the real value. `defaultMatches` also covers
+ * environments without `matchMedia` (jsdom unless the test stubs it).
  */
 export declare function useMediaQuery(query: string, defaultMatches?: boolean): boolean;

package/dist/internal/use-media-query.js

@@ -2,26 +2,22 @@
 import * as React from "react";
 /** Tailwind `md` breakpoint. Used for range calendars that stack on small screens. */
 export const MD_MEDIA_QUERY = "(min-width: 768px)";
+function hasMatchMedia() {
+    return (typeof window !== "undefined" && typeof window.matchMedia === "function");
+}
 /**
- * Subscribe to a CSS media query. `defaultMatches` covers SSR and environments
- * without `matchMedia` (jsdom unless the test stubs it).
+ * Subscribe to a CSS media query with `useSyncExternalStore`. The server
+ * render and hydration use `defaultMatches`, so the markup always agrees;
+ * React then re-renders with the real value. `defaultMatches` also covers
+ * environments without `matchMedia` (jsdom unless the test stubs it).
  */
 export function useMediaQuery(query, defaultMatches = false) {
-    const [matches, setMatches] = React.useState(() => {
-        if (typeof window === "undefined" ||
-            typeof window.matchMedia !== "function") {
-            return defaultMatches;
-        }
-        return window.matchMedia(query).matches;
-    });
-    React.useEffect(() => {
-        if (typeof window.matchMedia !== "function")
-            return;
+    const subscribe = React.useCallback((onChange) => {
+        if (!hasMatchMedia())
+            return () => { };
         const media = window.matchMedia(query);
-        const onChange = () => setMatches(media.matches);
-        onChange();
         media.addEventListener("change", onChange);
         return () => media.removeEventListener("change", onChange);
     }, [query]);
-    return matches;
+    return React.useSyncExternalStore(subscribe, () => (hasMatchMedia() ? window.matchMedia(query).matches : defaultMatches), () => defaultMatches);
 }

package/dist/kanban.d.ts

@@ -0,0 +1,84 @@
+import * as React from "react";
+/**
+ * One board column. Columns render in the order given. `color` (any CSS
+ * color) draws a status dot; `badge` is trailing header meta such as a total.
+ */
+export type KanbanColumn = {
+    /** Matches what `getColumnId` returns for the column's cards. */
+    id: string;
+    /** Header text. */
+    label: string;
+    /** Any CSS color; draws a status dot before the label. No dot when omitted. */
+    color?: string;
+    /** Trailing header meta under the card count, such as a total. */
+    badge?: React.ReactNode;
+    /** Replaces the board's `emptyLabel` for this column. */
+    emptyLabel?: string;
+};
+/**
+ * Positions of the cards on either side of the drop slot (`undefined` at a
+ * column edge). Feed them to a fractional-index helper to store the order.
+ */
+export type KanbanDropTarget = {
+    /** `position` of the card above the drop slot; `undefined` at the top. */
+    beforePosition: number | undefined;
+    /** `position` of the card below the drop slot; `undefined` at the bottom. */
+    afterPosition: number | undefined;
+};
+export type KanbanBoardProps<T extends {
+    id: string;
+    position: number;
+}> = {
+    /** The board's columns, in display order. */
+    columns: KanbanColumn[];
+    /** Every card, in display order; sort by `position` first. A card whose column id is unknown is not shown. */
+    items: T[];
+    /** The id of the column a card belongs in. */
+    getColumnId: (item: T) => string;
+    /** Every drop that changes a column or the order, including same-column reorders. */
+    onMove: (item: T, toColumnId: string, target: KanbanDropTarget) => void;
+    /** Shows a Finish zone while dragging. */
+    onComplete?: (itemId: string) => void;
+    /** Shows a Remove zone while dragging. */
+    onDelete?: (itemId: string) => void;
+    /**
+     * Card body; the board adds the grip, chrome, and sorting. Cards re-render
+     * only when their item changes while this and `onCardClick` keep their
+     * identity, so define them outside the render or wrap them in `useCallback`.
+     */
+    renderCard: (item: T) => React.ReactNode;
+    /** Makes the card body a button. */
+    onCardClick?: (item: T) => void;
+    /** Skeleton cards on a first load with no items; dims the board on a refetch. */
+    isLoading?: boolean;
+    /** Text in a column with no cards. Default `"Drop here"`. */
+    emptyLabel?: string;
+    /** Text on the Finish zone. Default `"Finish"`. */
+    completeLabel?: string;
+    /** Text on the Remove zone. Default `"Remove"`. */
+    deleteLabel?: string;
+    /** Classes for the horizontal scroller that holds the columns. */
+    scrollerClassName?: string;
+    /** Classes for every column, e.g. its width. */
+    columnClassName?: string;
+    /** Classes for every card, including the one under the pointer while dragging. */
+    cardClassName?: string;
+} & Omit<React.ComponentProps<"div">, "children">;
+/**
+ * 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.
+ */
+declare function KanbanBoard<T extends {
+    id: string;
+    position: number;
+}>({ columns, items, getColumnId, onMove, onComplete, onDelete, renderCard, onCardClick, isLoading, emptyLabel, completeLabel, deleteLabel, className, scrollerClassName, columnClassName, cardClassName, ...props }: KanbanBoardProps<T>): React.JSX.Element;
+/** Board-shaped placeholder for a route `loading` file. */
+declare function KanbanSkeleton({ columnCount, className, columnClassName, ...props }: {
+    /** How many placeholder columns to draw. Default 4. */
+    columnCount?: number;
+    /** Classes for every placeholder column, e.g. to match the board's width. */
+    columnClassName?: string;
+} & Omit<React.ComponentProps<"div">, "children">): React.JSX.Element;
+export { KanbanBoard, KanbanSkeleton };

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

@@ -0,0 +1,23 @@
+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
+ * (`selectedState.active`) so the current page meets non-text contrast.
+ * Apps pass `active` — the kit has no router.
+ */
+declare const navLinkVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+/**
+ * Pill link for app-shell destinations (Calendar, Tasks, Settings). Pass
+ * `active` from the route; the kit does not read the URL. `asChild` wraps a
+ * router `Link` with these styles, the same Slot pattern as `BreadcrumbLink`.
+ *
+ * Not a tab: in-page view switches that belong in the URL use `TabsNav`
+ * 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"> & AsChildProps & {
+    /** This link is the current page: `aria-current="page"` and the selected chrome. */
+    active: boolean;
+}): React.JSX.Element;
+export { NavLink, navLinkVariants };

package/dist/nav-link.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { Slot } from "radix-ui";
+import { focusRing, selectedState } from "./internal/styles.js";
+import { cn } from "./utils.js";
+/**
+ * Pill chrome for app-shell navigation. Inactive is muted text with an
+ * accent hover; active uses the shared selected wash, text, and border
+ * (`selectedState.active`) so the current page meets non-text contrast.
+ * Apps pass `active` — the kit has no router.
+ */
+const navLinkVariants = cva([
+    focusRing,
+    selectedState.active,
+    "inline-flex items-center gap-1.5 rounded-none border border-transparent px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-accent data-[state=active]:font-medium",
+]);
+/**
+ * Pill link for app-shell destinations (Calendar, Tasks, Settings). Pass
+ * `active` from the route; the kit does not read the URL. `asChild` wraps a
+ * router `Link` with these styles, the same Slot pattern as `BreadcrumbLink`.
+ *
+ * Not a tab: in-page view switches that belong in the URL use `TabsNav`
+ * and `tabsTriggerVariants()`. Next apps can import the optional adapter
+ * from `atlas-react-kit/next/nav-link` instead of composing `asChild`.
+ */
+function NavLink({ asChild, active, className, ...props }) {
+    const Comp = asChild ? Slot.Root : "a";
+    return (_jsx(Comp, { "data-slot": "nav-link", "data-state": active ? "active" : "inactive", "aria-current": active ? "page" : undefined, className: cn(navLinkVariants(), className), ...props }));
+}
+export { NavLink, navLinkVariants };

package/dist/next/nav-link.d.ts

@@ -0,0 +1,11 @@
+import type * as React from "react";
+import Link from "next/link.js";
+/**
+ * Next.js adapter for the shell `NavLink` pill. Same contract as
+ * `TabsNavLink`: Next `Link` props plus a required `active` boolean. The
+ * kit still does not read the router; the app passes `active`.
+ */
+declare function NavLink({ active, className, ...props }: React.ComponentProps<typeof Link> & {
+    active: boolean;
+}): React.JSX.Element;
+export { NavLink };

package/dist/next/nav-link.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Link from "next/link.js";
+import { navLinkVariants } from "../nav-link.js";
+import { cn } from "../utils.js";
+/**
+ * Next.js adapter for the shell `NavLink` pill. Same contract as
+ * `TabsNavLink`: Next `Link` props plus a required `active` boolean. The
+ * kit still does not read the router; the app passes `active`.
+ */
+function NavLink({ active, className, ...props }) {
+    return (_jsx(Link, { "data-slot": "nav-link", "data-state": active ? "active" : "inactive", "aria-current": active ? "page" : undefined, className: cn(navLinkVariants(), className), ...props }));
+}
+export { NavLink };

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 };