@nanisoft/prism-ui 0.10.2 → 0.13.0

package/dist/components/ui/calendar.js

@@ -0,0 +1,216 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/** `YYYY-MM-DD` in local time, which is the only date format a form should post. */
+function iso(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+const addDays = (date, days) => new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+const startOfMonth = (date) => new Date(date.getFullYear(), date.getMonth(), 1);
+const sameMonth = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+const sameDay = (a, b) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+/**
+ * The same day of the month, `months` along.
+ *
+ * The day is clamped to the length of the month it lands in, so stepping back from
+ * the 31st lands on the 30th, the 28th or the 29th rather than rolling into the
+ * month before. A calendar that rolled would move the focus to a different month
+ * than the reader asked for, and the date would be wrong by a month with nothing
+ * on screen to say so.
+ */
+const shiftMonth = (date, months) => {
+    const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
+    const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+    return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), lastDay));
+};
+const DAY_CELL = 
+// `transition-colors` is a property list, which Tailwind owns; the duration and
+// the easing are the motion tokens, and neither is written here as a number.
+'text-foreground hover:bg-accent hover:text-accent-foreground flex h-9 w-full cursor-pointer items-center justify-center rounded-md text-sm tabular-nums outline-none transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * How a day cell looks.
+ *
+ * `selected` states a fill and therefore states its own ink. `today` does not set
+ * a fill, so it does not set an ink: it is a ring inside the cell and a weight,
+ * and a ring has no foreground to keep in step with the two states above it.
+ */
+const DAY_STATE = {
+    selected: 'bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground font-semibold',
+    today: 'ring-ring ring-1 ring-inset font-semibold',
+    unavailable: 'text-muted-foreground aria-disabled:hover:bg-transparent',
+};
+/**
+ * A month grid for picking one date.
+ *
+ * **It is built here because Base UI does not ship one.** The package at 1.8.0
+ * has a combobox, a number field, an OTP field and a field, and no calendar, so
+ * there is nothing to compose and everything here is the Component's own. That is
+ * stated rather than implied because "the docs show one" is not evidence, and a
+ * wrapper around a module that is not in the installed package is the failure this
+ * Component could have shipped.
+ *
+ * **The grid is always six weeks tall.** A month that needs five rows and a month
+ * that needs six would otherwise resize as the reader pages through, which moves
+ * the dates under the pointer and under the highlight: a reader who aims at the
+ * 24th after reading its position in a five-row month clicks the 31st in a
+ * six-row one. The empty cells at the edges are marked `aria-hidden` rather than
+ * filled with the neighbouring month's dates, because a date from another month in
+ * this grid is a date the reader did not come for.
+ *
+ * **Every date, weekday name and month name is the caller's.** The caption, the
+ * seven column headings and the month the reader moves to are all reader-facing
+ * text in the reader's language, and the Component has no business carrying a
+ * table of them. What it does carry is the geometry: which column a date falls in
+ * and which day it sits on.
+ *
+ * **One cell is in the tab order, and the arrows move it.** The roving tab stop
+ * sits on the chosen date, or on today, or on the first of the month, so a reader
+ * who tabs in lands on the date they care about rather than on the 1st. The arrows
+ * step a day and a week, Home and End step to the ends of the week, and PageUp and
+ * PageDown step a month, with Shift for a year. Moving past the end of a month
+ * changes the month on show and carries the focus with it, so paging never leaves
+ * the highlight on a cell that is no longer drawn.
+ *
+ * **A disabled date is drawn, reachable and refused.** It stays in the grid and
+ * stays in the arrow path, because a date that is simply missing is
+ * indistinguishable from a grid that failed to render that week, and a reader who
+ * cannot reach it cannot tell a fully booked day from a bug. Enter, Space and a
+ * click on it do nothing, and it announces as unavailable. Explain the reason in
+ * text beside the field; a greyed cell on its own says only that it is not
+ * available.
+ *
+ * **The caption is a live region.** Paging a month changes the month with no other
+ * visible change for a reader who is on the grid, so the caption announces itself
+ * when it changes.
+ */
+function Calendar({ label, monthLabel, weekdayLabels, firstWeekday = 0, previousLabel, nextLabel, month, onMonthChange, value = null, onValueChange, isDateDisabled, dayLabel, today, disabled = false, name, form, className, }) {
+    const gridRef = useRef(null);
+    // `null` means "wherever the reader would expect to land", which is derived
+    // rather than stored, so an external change to `value` or `month` moves the tab
+    // stop without this Component having to watch for it.
+    const [movedTo, setMovedTo] = useState(null);
+    const isUnavailable = useMemo(() => (date) => disabled || (isDateDisabled?.(date) ?? false), [disabled, isDateDisabled]);
+    /**
+     * Six weeks from the Sunday, or the reader's first day, on or before the first
+     * of the month.
+     */
+    const cells = useMemo(() => {
+        const first = startOfMonth(month);
+        const offset = (first.getDay() - firstWeekday + 7) % 7;
+        const start = addDays(first, -offset);
+        return Array.from({ length: 42 }, (_, index) => addDays(start, index));
+    }, [month, firstWeekday]);
+    /**
+     * Where a reader who tabs into the grid lands: the chosen date, else today, else
+     * the first of the month. A month on show is never empty, so there is always an
+     * answer and the grid is always reachable by one Tab.
+     */
+    const landing = useMemo(() => {
+        if (value !== null && sameMonth(value, month))
+            return value;
+        if (today !== undefined && sameMonth(today, month))
+            return today;
+        return startOfMonth(month);
+    }, [value, today, month]);
+    const focused = movedTo !== null && sameMonth(movedTo, month) ? movedTo : landing;
+    /** Focus follows a move, because a move that changed month draws a new cell. */
+    useEffect(() => {
+        if (movedTo === null)
+            return;
+        gridRef.current?.querySelector(`[data-date="${iso(movedTo)}"]`)?.focus();
+    }, [movedTo, month]);
+    /** Moves the tab stop, and the month on show when the move crosses a month. */
+    const goTo = (date) => {
+        setMovedTo(date);
+        if (!sameMonth(date, month))
+            onMonthChange(startOfMonth(date));
+    };
+    const choose = (date) => {
+        // The tab stop follows whatever the reader last operated, so a click leaves the
+        // grid in the state the reader is now looking at rather than snapping the stop
+        // back to the landing cell.
+        setMovedTo(date);
+        if (isUnavailable(date))
+            return;
+        onValueChange?.(date);
+    };
+    /**
+     * The keys on one day cell.
+     *
+     * The date comes from the cell the event fired on rather than from state,
+     * because a reader may have reached a cell by Tab or by a click and the tab stop
+     * is the Component's own decision. Deriving the move from state would step from
+     * wherever the tab stop happened to be, which is a cell the reader is not on.
+     */
+    const onDayKeyDown = (event, date) => {
+        const row = Math.floor(cells.findIndex((entry) => sameDay(entry, date)) / 7);
+        const first = cells[row * 7];
+        const last = first === undefined ? null : addDays(first, 6);
+        // Enter by `key`, Space by `code`. The space bar's `key` has been reported as a
+        // space, as "Spacebar" and as "Space" by different engines over the years, and
+        // its `code` has been the same in all of them, so this is the one activation key
+        // whose physical position is the more reliable half of the event.
+        if (event.key === 'Enter' || event.code === 'Space') {
+            event.preventDefault();
+            choose(date);
+            return;
+        }
+        switch (event.key) {
+            case 'ArrowLeft':
+                event.preventDefault();
+                goTo(addDays(date, -1));
+                return;
+            case 'ArrowRight':
+                event.preventDefault();
+                goTo(addDays(date, 1));
+                return;
+            case 'ArrowUp':
+                event.preventDefault();
+                goTo(addDays(date, -7));
+                return;
+            case 'ArrowDown':
+                event.preventDefault();
+                goTo(addDays(date, 7));
+                return;
+            case 'Home':
+                event.preventDefault();
+                if (first !== undefined)
+                    goTo(first);
+                return;
+            case 'End':
+                event.preventDefault();
+                if (last !== null)
+                    goTo(last);
+                return;
+            case 'PageUp':
+                event.preventDefault();
+                goTo(shiftMonth(date, event.shiftKey ? -12 : -1));
+                return;
+            case 'PageDown':
+                event.preventDefault();
+                goTo(shiftMonth(date, event.shiftKey ? 12 : 1));
+                return;
+            default:
+        }
+    };
+    const focusedIso = iso(focused);
+    const chosenIso = value === null ? null : iso(value);
+    const todayIso = today === undefined ? null : iso(today);
+    return (_jsxs("div", { "data-slot": "calendar", className: cn('bg-popover text-popover-foreground w-64 rounded-md border p-3 shadow-md', className), children: [_jsxs("div", { className: "mb-2 flex items-center justify-between gap-1", children: [_jsx("button", { type: "button", "data-slot": "calendar-previous", "aria-label": previousLabel, disabled: disabled, onClick: () => onMonthChange(shiftMonth(month, -1)), className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground inline-flex size-8 items-center justify-center rounded-md outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronLeftIcon, { className: "size-4" }) }), _jsx("div", { "data-slot": "calendar-caption", "aria-live": "polite", className: "text-foreground text-sm font-medium tabular-nums", children: monthLabel }), _jsx("button", { type: "button", "data-slot": "calendar-next", "aria-label": nextLabel, disabled: disabled, onClick: () => onMonthChange(shiftMonth(month, 1)), className: cn('text-muted-foreground hover:bg-accent hover:text-accent-foreground inline-flex size-8 items-center justify-center rounded-md outline-none', 'transition-colors duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronRightIcon, { className: "size-4" }) })] }), _jsx("div", { ref: gridRef, children: _jsxs("table", { "data-slot": "calendar-grid", role: "grid", "aria-label": label, className: "w-full border-collapse tabular-nums", children: [_jsx("thead", { children: _jsx("tr", { children: weekdayLabels.map((weekday, column) => (_jsx("th", { scope: "col", "data-slot": "calendar-weekday", className: "text-muted-foreground flex h-8 items-center justify-center text-xs font-medium", children: weekday }, `${weekday}-${column}`))) }) }), _jsx("tbody", { children: Array.from({ length: 6 }, (_, row) => (_jsx("tr", { children: cells.slice(row * 7, row * 7 + 7).map((date) => {
+                                    const key = iso(date);
+                                    if (!sameMonth(date, month)) {
+                                        // The cells that pad the month out. They are hidden from the
+                                        // accessibility tree rather than filled with the neighbouring
+                                        // month's dates, because a date from another month drawn in
+                                        // this grid is a date the reader did not come for.
+                                        return (_jsx("td", { role: "gridcell", "aria-hidden": "true", className: "p-0" }, key));
+                                    }
+                                    const unavailable = isUnavailable(date);
+                                    const isSelected = key === chosenIso;
+                                    const isToday = key === todayIso;
+                                    return (_jsx("td", { role: "gridcell", "data-slot": "calendar-day", "data-date": key, tabIndex: key === focusedIso ? 0 : -1, "aria-selected": isSelected, "aria-current": isToday ? 'date' : undefined, "aria-disabled": unavailable || undefined, ...(dayLabel === undefined ? null : { 'aria-label': dayLabel(date) }), onClick: () => choose(date), onKeyDown: (event) => onDayKeyDown(event, date), className: cn(DAY_CELL, unavailable && DAY_STATE.unavailable, isToday && !isSelected && DAY_STATE.today, isSelected && DAY_STATE.selected), children: date.getDate() }, key));
+                                }) }, row))) })] }) }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosenIso ?? '', readOnly: true }))] }));
+}
+export { Calendar };

package/dist/components/ui/card.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps } from 'react';
+import type { HeadingElement } from './typography.js';
 /**
  * A bordered surface for a small group of related content.
  *
@@ -18,13 +19,24 @@ declare function CardHeader({ className, ...props }: ComponentProps<'div'>): imp
 /**
  * The card's title: the one line that names the group of related content.
  *
- * Renders a `div` rather than a heading, because a card's title is not always the
- * heading of the region it sits in: four cards in a grid are four titles under one
- * section heading, and four `h3`s under one `h2` is right while four `h2`s is
- * four sections. Pass Prism's `Heading` inside it when the card is the only thing
- * in its region and the outline should say so.
+ * Renders a `div` by default, because a card's title is not always the heading of
+ * the region it sits in: four cards in a grid are four titles under one section
+ * heading, and four `h3`s under one `h2` is right while four `h2`s is four
+ * sections. So the element is a decision the caller makes with `as`, and a Block
+ * that draws a set of titled cards passes `childLevel(headingLevel)` rather than a
+ * literal, so the titles follow the section when the block is composed one level
+ * deeper than it was written for.
+ *
+ * An earlier version of this note told a caller to pass Prism's `Heading` inside
+ * instead, and that was wrong. `Heading` is a step of the *type* scale and its
+ * floor is `lg`; a card title sits at body size, so the only way to use it was to
+ * override the size back down, which asks a type-scale component to have no opinion
+ * about type. The element and the visual step are separate questions and this is the
+ * one that answers the element.
  */
-declare function CardTitle({ className, ...props }: ComponentProps<'div'>): import("react").JSX.Element;
+declare function CardTitle({ className, as: Tag, ...props }: ComponentProps<'h2'> & {
+    as?: HeadingElement | 'div';
+}): import("react").JSX.Element;
 /**
  * The supporting line under a card's title: one sentence about what the card
  * holds.

package/dist/components/ui/card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAW3D;AAED;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAWjE;AAED;;;;;;;;GAQG;AACH,iBAAS,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQhE;AAED;;;GAGG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQtE;AAED,wEAAwE;AACxE,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAElE;AAED;;;GAGG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQjE;AAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../../src/components/ui/card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,OAAO,CAAA;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIlD;;;;;;GAMG;AACH,iBAAS,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAW3D;AAED;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAWjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,EAAE,EAAE,GAAW,EACf,GAAG,KAAK,EACT,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,cAAc,GAAG,KAAK,CAAA;CAAE,+BAcxD;AAED;;;GAGG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQtE;AAED,wEAAwE;AACxE,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAElE;AAED;;;GAGG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,+BAQjE;AAED,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/card.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A bordered surface for a small group of related content.
  *
@@ -23,14 +23,29 @@ function CardHeader({ className, ...props }) {
 /**
  * The card's title: the one line that names the group of related content.
  *
- * Renders a `div` rather than a heading, because a card's title is not always the
- * heading of the region it sits in: four cards in a grid are four titles under one
- * section heading, and four `h3`s under one `h2` is right while four `h2`s is
- * four sections. Pass Prism's `Heading` inside it when the card is the only thing
- * in its region and the outline should say so.
+ * Renders a `div` by default, because a card's title is not always the heading of
+ * the region it sits in: four cards in a grid are four titles under one section
+ * heading, and four `h3`s under one `h2` is right while four `h2`s is four
+ * sections. So the element is a decision the caller makes with `as`, and a Block
+ * that draws a set of titled cards passes `childLevel(headingLevel)` rather than a
+ * literal, so the titles follow the section when the block is composed one level
+ * deeper than it was written for.
+ *
+ * An earlier version of this note told a caller to pass Prism's `Heading` inside
+ * instead, and that was wrong. `Heading` is a step of the *type* scale and its
+ * floor is `lg`; a card title sits at body size, so the only way to use it was to
+ * override the size back down, which asks a type-scale component to have no opinion
+ * about type. The element and the visual step are separate questions and this is the
+ * one that answers the element.
  */
-function CardTitle({ className, ...props }) {
-    return (_jsx("div", { "data-slot": "card-title", className: cn('font-semibold leading-none', className), ...props }));
+function CardTitle({ className, as: Tag = 'div', ...props }) {
+    // The same cast `Heading` makes, and for the same reason: the element is chosen
+    // at runtime, so the union of the six headings and a `div` is not one prop type.
+    // The props are typed from `h2` rather than `div` because every prop a caller
+    // passes to a card title is valid on a heading, and typing from `h2` would stop a
+    // caller passing one that only a `div` takes.
+    const Element = Tag;
+    return (_jsx(Element, { "data-slot": "card-title", className: cn('font-semibold leading-none', className), ...props }));
 }
 /**
  * The supporting line under a card's title: one sentence about what the card

package/dist/components/ui/carousel.d.ts

@@ -0,0 +1,118 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** One slide, and the words a reader is given for it. */
+export type CarouselSlide = {
+    /** A stable key. A slide's key must not change as the reader moves. */
+    id: string;
+    /** The slide's content. */
+    children: ReactNode;
+    /**
+     * The accessible name of this slide.
+     *
+     * A carousel hides its content, so this is often the only way a reader knows
+     * which slide they are on before they read it. It is required for the same
+     * reason a region's name is: it is the caller's word, and a slide announced only
+     * by its content is a slide a reader cannot skip past by name.
+     */
+    label: string;
+};
+/** The props the Carousel accepts. */
+export interface CarouselProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** The slides, in the order a reader meets them. */
+    slides: readonly CarouselSlide[];
+    /**
+     * The accessible name of the carousel.
+     *
+     * Required rather than defaulted. A carousel is a region, and a page with two is
+     * a page where a reader cannot tell which set of slides they are in. The name is
+     * the caller's word.
+     */
+    label: string;
+    /**
+     * The words read for a slide position, given its one-based index and the total.
+     *
+     * Required, and required as a function rather than a string, because a position
+     * has to be a sentence and the sentence is different in every language. It is
+     * also the answer to the only real defect a carousel has: one with no position
+     * indicator is a guessing game, because a reader who has been moved three times
+     * with nothing telling them where they are has no way to know how much is left.
+     *
+     * The function receives the index of the slide the control moves *to*, so the
+     * words always describe where the reader will be rather than where they are.
+     */
+    position: (index: number, total: number) => string;
+    /**
+     * What a reader is told when there is nothing to show.
+     *
+     * A carousel with no slides is a frame with controls in it that move nowhere, so
+     * the case is authored rather than left to a caller to notice.
+     */
+    empty?: ReactNode;
+    /** The words read for the control that moves back. @defaultValue 'Previous slide' */
+    previousLabel?: string;
+    /** The words read for the control that moves forward. @defaultValue 'Next slide' */
+    nextLabel?: string;
+    /**
+     * The slide to show first.
+     *
+     * Omit it and the first slide is shown. It is a prop because a carousel dropped
+     * into the middle of a page is often a deep link's target, and a Component that
+     * always opened on slide one would show the reader a different slide from the
+     * one the address names.
+     */
+    initialIndex?: number;
+    /** The slide the reader is on, when the caller owns it. */
+    index?: number;
+    /** Called with the index of the slide the reader moves to. */
+    onIndexChange?: (index: number) => void;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A set of slides with controls that move between them.
+ *
+ * **A carousel hides content, so it must never be the only route to it.** That is
+ * the decision worth making, and it is a constraint on the caller as much as on
+ * this Component. Everything a carousel shows, a reader must be able to reach some
+ * other way: a tab, a section below it, a list. A carousel used as the only
+ * presentation of a set of images is a set of images a reader on a keyboard, on a
+ * screen reader, or with the controls hidden by a stylesheet cannot see at all,
+ * and the Component cannot detect that case. So the rule is here, in the
+ * documentation, where a caller meets it, rather than assumed.
+ *
+ * **The controls say where the reader is, and the position is a sentence the
+ * caller writes.** `position` is required and is a function of the index and the
+ * total, so a reader is told "3 of 7" rather than being left to infer it. A
+ * carousel with no position indicator is a guessing game: a reader moved three
+ * times with nothing counting has no way to know whether there are three slides
+ * left or three hundred, and the only way to find out is to keep pressing. The
+ * current position is also in `aria-live="polite"` on the position, because a
+ * carousel that moves silently under a reader who did not press anything is a
+ * carousel a reader cannot follow.
+ *
+ * **One slide is the whole content, with no controls.** A carousel of one slide is
+ * a picture with two buttons that do nothing, and it is the state a filtered or
+ * partially-loaded set passes through. The controls are absent rather than
+ * disabled, and the position says 1 of 1, because "there is one slide and you are
+ * on it" is a true and useful thing to tell a reader.
+ *
+ * **No slide is authored rather than rendered as an empty frame.** Zero slides is
+ * a state a caller reaches before their data arrives or after a filter excludes
+ * everything, and a region with an empty track and two dead controls is a gap
+ * rather than a state.
+ *
+ * **It is operable from the keyboard, and the arrow keys do what a reader
+ * expects.** Left and Right move between slides when the carousel has focus, Home
+ * and End jump to the first and last, and the controls are real buttons so Tab
+ * reaches them and Enter and Space press them. Nothing here is a div with a
+ * handler, which is the version a consumer cannot assemble for themselves because
+ * every one of those keys is a chance to get one wrong.
+ *
+ * **The slide transition is a state change and not an entrance.** The track moves
+ * with `duration-base ease-out`, which is the reader's own press being reported
+ * back, and there is no fade on mount and no motion a reader did not ask for.
+ *
+ * It is a client Component, because a carousel holds a position and answers keys.
+ */
+declare function Carousel({ slides, label, position, className, empty, previousLabel, nextLabel, initialIndex, index, onIndexChange, ...props }: CarouselProps): import("react").JSX.Element;
+export { Carousel };
+//# sourceMappingURL=carousel.d.ts.map

package/dist/components/ui/carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/carousel.tsx"],"names":[],"mappings":"AAGA,OAAO,EAML,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG;IAC1B,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC5E,oDAAoD;IACpD,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAS,QAAQ,CAAC,EAChB,MAAM,EACN,KAAK,EACL,QAAQ,EACR,SAAS,EACT,KAAK,EACL,aAAgC,EAChC,SAAwB,EACxB,YAAgB,EAChB,KAAK,EACL,aAAa,EACb,GAAG,KAAK,EACT,EAAE,aAAa,+BAgNf;AASD,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/carousel.js

@@ -0,0 +1,152 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { cn } from '../../lib/utils.js';
+/**
+ * A set of slides with controls that move between them.
+ *
+ * **A carousel hides content, so it must never be the only route to it.** That is
+ * the decision worth making, and it is a constraint on the caller as much as on
+ * this Component. Everything a carousel shows, a reader must be able to reach some
+ * other way: a tab, a section below it, a list. A carousel used as the only
+ * presentation of a set of images is a set of images a reader on a keyboard, on a
+ * screen reader, or with the controls hidden by a stylesheet cannot see at all,
+ * and the Component cannot detect that case. So the rule is here, in the
+ * documentation, where a caller meets it, rather than assumed.
+ *
+ * **The controls say where the reader is, and the position is a sentence the
+ * caller writes.** `position` is required and is a function of the index and the
+ * total, so a reader is told "3 of 7" rather than being left to infer it. A
+ * carousel with no position indicator is a guessing game: a reader moved three
+ * times with nothing counting has no way to know whether there are three slides
+ * left or three hundred, and the only way to find out is to keep pressing. The
+ * current position is also in `aria-live="polite"` on the position, because a
+ * carousel that moves silently under a reader who did not press anything is a
+ * carousel a reader cannot follow.
+ *
+ * **One slide is the whole content, with no controls.** A carousel of one slide is
+ * a picture with two buttons that do nothing, and it is the state a filtered or
+ * partially-loaded set passes through. The controls are absent rather than
+ * disabled, and the position says 1 of 1, because "there is one slide and you are
+ * on it" is a true and useful thing to tell a reader.
+ *
+ * **No slide is authored rather than rendered as an empty frame.** Zero slides is
+ * a state a caller reaches before their data arrives or after a filter excludes
+ * everything, and a region with an empty track and two dead controls is a gap
+ * rather than a state.
+ *
+ * **It is operable from the keyboard, and the arrow keys do what a reader
+ * expects.** Left and Right move between slides when the carousel has focus, Home
+ * and End jump to the first and last, and the controls are real buttons so Tab
+ * reaches them and Enter and Space press them. Nothing here is a div with a
+ * handler, which is the version a consumer cannot assemble for themselves because
+ * every one of those keys is a chance to get one wrong.
+ *
+ * **The slide transition is a state change and not an entrance.** The track moves
+ * with `duration-base ease-out`, which is the reader's own press being reported
+ * back, and there is no fade on mount and no motion a reader did not ask for.
+ *
+ * It is a client Component, because a carousel holds a position and answers keys.
+ */
+function Carousel({ slides, label, position, className, empty, previousLabel = 'Previous slide', nextLabel = 'Next slide', initialIndex = 0, index, onIndexChange, ...props }) {
+    const [uncontrolled, setUncontrolled] = useState(() => clamp(initialIndex, slides.length));
+    const controlled = index !== undefined;
+    const at = controlled ? clamp(index, slides.length) : uncontrolled;
+    const total = slides.length;
+    const set = useCallback((next) => {
+        const bounded = clamp(next, total);
+        if (!controlled)
+            setUncontrolled(bounded);
+        onIndexChange?.(bounded);
+    }, [controlled, onIndexChange, total]);
+    const labelId = useId();
+    const root = useRef(null);
+    const previous = useRef(null);
+    const next = useRef(null);
+    const atFirst = at <= 0;
+    const atLast = at >= total - 1;
+    // The reader's own arrow keys, which are the reason this is a Component rather
+    // than a stack of divs with two buttons beside them.
+    const onKeyDown = (event) => {
+        const keys = ['ArrowLeft', 'ArrowRight', 'Home', 'End'];
+        if (!keys.includes(event.key))
+            return;
+        if (total <= 1)
+            return;
+        event.preventDefault();
+        if (event.key === 'Home')
+            set(0);
+        else if (event.key === 'End')
+            set(total - 1);
+        else
+            set(at + (event.key === 'ArrowRight' ? 1 : -1));
+    };
+    useEffect(() => {
+        // A carousel that has lost slides must not leave the reader past the end, and
+        // the failure is silent: the track is translated to an offset with no slide
+        // there, so the reader is looking at blank space in a carousel that is
+        // working perfectly well.
+        if (at > total - 1)
+            set(total - 1);
+    }, [at, set, total]);
+    useEffect(() => {
+        // A control that has just been disabled must not keep the reader's focus.
+        //
+        // A disabled button is out of the tab order but it does not give up focus, so
+        // a reader who pressed "next" on the last-but-one slide is left focused on a
+        // control that can no longer answer anything: not Enter, not Space, and not
+        // the arrow keys this Component listens for on the way past. The reader is
+        // stranded inside the carousel with no working control under their fingers and
+        // no way to know why. So focus is handed to the sibling that is still live,
+        // which is the same thing a browser does when focus lands on something that
+        // has become inert.
+        const active = document.activeElement;
+        if (!(active instanceof HTMLButtonElement))
+            return;
+        if (active !== previous.current && active !== next.current)
+            return;
+        if (active.disabled !== true)
+            return;
+        const live = active === previous.current ? next.current : previous.current;
+        if (live === null || live.disabled)
+            return;
+        live.focus();
+    });
+    if (total === 0) {
+        // A region with an empty track and two dead controls is a gap rather than a
+        // state, so the empty case is authored.
+        return (_jsx("div", { "data-slot": "carousel-empty", className: cn('text-muted-foreground text-sm', className), children: empty ?? null }));
+    }
+    return (_jsxs("div", { ref: root, "data-slot": "carousel", 
+        // A carousel is a region, and it is named, because a page with two of them
+        // is a page where a reader cannot tell which set of slides they are in.
+        role: "region", "aria-roledescription": "carousel", "aria-label": label, onKeyDown: onKeyDown, className: cn('flex flex-col gap-3', className), ...props, children: [_jsx("div", { "data-slot": "carousel-viewport", className: "overflow-hidden", style: {
+                    // A track width of one slide each is what makes the translate a whole
+                    // slide, and a negative margin of the track's own width is what puts the
+                    // first slide at zero. Both are the layout rather than a value, so they
+                    // are the two numbers this Component is allowed to hold.
+                    width: `${100 / total}%`,
+                    marginInlineStart: `${-(100 * (total - 1)) / total}%`,
+                    transform: `translateX(${(at * 100) / total}%)`,
+                }, children: _jsx("div", { "data-slot": "carousel-track", 
+                    // A state change, reported with a token. There is no fade on mount and no
+                    // motion a reader did not ask for, because there is no decorative or
+                    // entrance animation in this system.
+                    className: "flex transition-transform duration-base ease-out", style: { width: `${100 * total}%` }, children: slides.map((slide, slideAt) => {
+                        const current = slideAt === at;
+                        return (_jsx("div", { "data-slot": "carousel-slide", "data-current": current ? 'true' : undefined, id: `${labelId}-slide-${slideAt}`, role: "group", "aria-label": slide.label, "aria-roledescription": "slide", "aria-hidden": current ? undefined : true, className: "w-full shrink-0", children: slide.children }, slide.id));
+                    }) }) }), total > 1 ? (_jsxs("div", { "data-slot": "carousel-controls", className: "flex items-center justify-between gap-3", children: [_jsx("button", { type: "button", ref: previous, "data-slot": "carousel-previous", "aria-label": previousLabel, disabled: atFirst, onClick: () => set(at - 1), className: cn('border-input bg-background text-foreground inline-flex size-9 items-center justify-center rounded-md border outline-none', 'transition-colors duration-fast ease-out', 'hover:bg-accent hover:text-accent-foreground', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronLeftIcon, { className: "size-4", "aria-hidden": "true" }) }), _jsx("p", { "data-slot": "carousel-position", "aria-live": "polite", className: "text-muted-foreground text-sm tabular-nums", children: position(at + 1, total) }), _jsx("button", { type: "button", ref: next, "data-slot": "carousel-next", "aria-label": nextLabel, disabled: atLast, onClick: () => set(at + 1), className: cn('border-input bg-background text-foreground inline-flex size-9 items-center justify-center rounded-md border outline-none', 'transition-colors duration-fast ease-out', 'hover:bg-accent hover:text-accent-foreground', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50'), children: _jsx(ChevronRightIcon, { className: "size-4", "aria-hidden": "true" }) })] })) : (
+            // One slide is the whole content, and the position still says so rather
+            // than the reader being left to infer that there is nothing to move to.
+            _jsx("p", { "data-slot": "carousel-position", "aria-live": "polite", className: "text-muted-foreground text-sm tabular-nums", children: position(1, 1) }))] }));
+}
+/** An index inside the set, so a caller cannot move the reader past either end. */
+function clamp(value, total) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (total === 0)
+        return 0;
+    return Math.min(Math.max(Math.trunc(value), 0), total - 1);
+}
+export { Carousel };