@nanisoft/prism-ui 0.10.1 → 0.13.0

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

@@ -0,0 +1,79 @@
+import type { ComponentProps } from 'react';
+/**
+ * The props a Spinner accepts.
+ *
+ * `label` is required and there is no default, which is the Component's one
+ * design decision and the reason it is not simply "a div with a border on it".
+ */
+export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'children'> {
+    /**
+     * The words a screen reader hears while the work is happening.
+     *
+     * Required, and required to be a real sentence rather than a verb. A busy
+     * indicator with no name is an animation, and an animation is nothing to a
+     * reader who cannot see it; the whole reason this Component exists rather
+     * than a border on a `div` is that it has to be able to say what is busy in
+     * the consumer's own words, because a shared library cannot know whether the
+     * answer is "Loading invoices" or "Carregando faturas".
+     *
+     * The words name the work, not the Component. "Loading" alone is a weaker
+     * name than "Loading invoices", and a caller who has two spinners on a page
+     * needs to tell them apart in the same way a sighted reader does.
+     */
+    label: string;
+    /**
+     * The diameter of the ring, in one of three authored steps.
+     *
+     * A prop rather than something a caller sets through `className`, because a
+     * ring whose size is a layout decision is a ring that can be 2px and become
+     * invisible, and `className` is layout only on every Component in this
+     * package. Three steps is what a spinner is ever drawn at: beside body text,
+     * beside a control's label, and alone in a region of its own.
+     *
+     * @defaultValue 'default'
+     */
+    size?: 'sm' | 'default' | 'lg';
+}
+/**
+ * A mark that says work is happening and nothing about how much of it is left.
+ *
+ * **It is not a Progress and it is not a Skeleton, and the three are confused
+ * often enough to be worth stating.** A Skeleton stands in for content: it has
+ * the shape of the thing that is arriving, so the page does not move when the
+ * content lands. A Progress reports a position: it carries a value, a minimum
+ * and a maximum, and a screen reader is told "68 percent" rather than the width
+ * of a coloured bar. A Spinner reports exactly one fact, that something is
+ * happening, and carries neither a shape nor a value. Pick by the question:
+ * *what will arrive* is a Skeleton, *how far along* is a Progress, and *is
+ * anything happening at all* is a Spinner.
+ *
+ * **The honest reason a Spinner is often the wrong answer is that it causes a
+ * layout shift.** The ring is a fixed square, so the content it stands in for
+ * is not, and everything below it moves twice: once when the content is
+ * replaced by the ring, and again when the ring is replaced by the content.
+ * A reader's eye has to find the thing twice. That is the whole cost of this
+ * Component and it is not paid when the shape of what is coming is already
+ * known, which is why:
+ *
+ * - **Do not use a Spinner as a page-level loading state where the layout is
+ *   known.** A first paint of Skeletons is a better answer, and
+ *   `Skeleton` is the Component for it. A Spinner alone in the middle of an
+ *   empty page tells the reader nothing about the page they are about to get.
+ * - **Do not use a Spinner for a task of known length.** A countable upload
+ *   is a `Progress`, and a bar that shows real information beats a ring that
+ *   shows anxiety.
+ * - **Do not use a Spinner for a wait under about a second.** A control that
+ *   disables itself for 400ms and then re-enables is a control that flickers.
+ *   A `Skeleton` that never gets to paint, or nothing at all, is quieter.
+ * - **Do not use a Spinner inside a Button next to a label that already says
+ *   what is happening.** The label is the announcement; the ring is the
+ *   confirmation, and beside a label that already reads "Saving..." it is a
+ *   second copy of a sentence the reader can already see.
+ *
+ * **It is a server Component.** It reads its props and renders, so the client
+ * directive would be a claim about work this Component does not do. A hundred
+ * spinners on a page cost no JavaScript.
+ */
+declare function Spinner({ className, label, size, ...props }: SpinnerProps): import("react").JSX.Element;
+export { Spinner };
+//# sourceMappingURL=spinner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../../src/components/ui/spinner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC5E;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,IAAI,CAAA;CAC/B;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,iBAAS,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,IAAgB,EAAE,GAAG,KAAK,EAAE,EAAE,YAAY,+BA+B9E;AAED,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/dist/components/ui/spinner.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The ring, at each authored size.
+ *
+ * `size-*` on the box and `border-2` on the arc. A spinner is drawn as a
+ * rounded box with one transparent edge, which is the shape that reads as
+ * "turning" without a keyframe: the gap in the border is what moves, and the
+ * box is a fixed frame around it.
+ *
+ * The one animation is `animate-spin`, and it is the only motion in this
+ * package that is a *rotation* rather than a transition between two states.
+ * A keyframe cannot be authored here - the design system emits no keyframes
+ * and a Component cannot add one - and `animate-spin` is a Tailwind utility
+ * that already carries its own, so this is the honest ceiling: a spinner that
+ * cannot be built from a transition between two states needs a loop, and a
+ * loop is what `animate-spin` is. It is state feedback rather than decoration
+ * for the reason `Timeline`'s pulsing mark is: it is running because work is
+ * running, and it stops when the work does.
+ */
+const RING = {
+    sm: 'size-4 border-2',
+    default: 'size-5 border-2',
+    lg: 'size-8 border-[3px]',
+};
+/**
+ * A mark that says work is happening and nothing about how much of it is left.
+ *
+ * **It is not a Progress and it is not a Skeleton, and the three are confused
+ * often enough to be worth stating.** A Skeleton stands in for content: it has
+ * the shape of the thing that is arriving, so the page does not move when the
+ * content lands. A Progress reports a position: it carries a value, a minimum
+ * and a maximum, and a screen reader is told "68 percent" rather than the width
+ * of a coloured bar. A Spinner reports exactly one fact, that something is
+ * happening, and carries neither a shape nor a value. Pick by the question:
+ * *what will arrive* is a Skeleton, *how far along* is a Progress, and *is
+ * anything happening at all* is a Spinner.
+ *
+ * **The honest reason a Spinner is often the wrong answer is that it causes a
+ * layout shift.** The ring is a fixed square, so the content it stands in for
+ * is not, and everything below it moves twice: once when the content is
+ * replaced by the ring, and again when the ring is replaced by the content.
+ * A reader's eye has to find the thing twice. That is the whole cost of this
+ * Component and it is not paid when the shape of what is coming is already
+ * known, which is why:
+ *
+ * - **Do not use a Spinner as a page-level loading state where the layout is
+ *   known.** A first paint of Skeletons is a better answer, and
+ *   `Skeleton` is the Component for it. A Spinner alone in the middle of an
+ *   empty page tells the reader nothing about the page they are about to get.
+ * - **Do not use a Spinner for a task of known length.** A countable upload
+ *   is a `Progress`, and a bar that shows real information beats a ring that
+ *   shows anxiety.
+ * - **Do not use a Spinner for a wait under about a second.** A control that
+ *   disables itself for 400ms and then re-enables is a control that flickers.
+ *   A `Skeleton` that never gets to paint, or nothing at all, is quieter.
+ * - **Do not use a Spinner inside a Button next to a label that already says
+ *   what is happening.** The label is the announcement; the ring is the
+ *   confirmation, and beside a label that already reads "Saving..." it is a
+ *   second copy of a sentence the reader can already see.
+ *
+ * **It is a server Component.** It reads its props and renders, so the client
+ * directive would be a claim about work this Component does not do. A hundred
+ * spinners on a page cost no JavaScript.
+ */
+function Spinner({ className, label, size = 'default', ...props }) {
+    return (_jsx("span", { "data-slot": "spinner", 
+        // The role is what makes the label legal, and the reason is the same one
+        // `LiveRegion` gives: a `span` with no role has no accessible name, so
+        // `aria-label` on one is prohibited rather than merely ignored. `status`
+        // is also the honest role, because a spinner is content that reports a
+        // state and is not waiting for the reader. It is deliberately NOT
+        // `aria-busy`: a busy *region* is still readable, and which regions are
+        // busy is the caller's knowledge rather than this Component's, so a
+        // consumer that wants it wraps the region in a `LiveRegion` and sets
+        // `busy` there.
+        role: "status", "aria-label": label, className: cn('inline-flex shrink-0', className), ...props, children: _jsx("span", { "data-slot": "spinner-ring", "aria-hidden": "true", className: cn('border-current animate-spin rounded-full border-transparent border-t-current', RING[size]) }) }));
+}
+export { Spinner };

package/dist/components/ui/switch.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Switch as SwitchPrimitive } from '@base-ui/react/switch';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A binary control that takes effect immediately.
  *

package/dist/components/ui/table-sort.d.ts

@@ -0,0 +1,97 @@
+import { type ComponentProps, type ReactNode } from 'react';
+/** Which way a column is sorted, and `none` for a column that is not. */
+export type TableSortDirection = 'none' | 'ascending' | 'descending';
+/** What activating a header will do, given where the column is now. */
+export type TableSortAnnouncement = (direction: TableSortDirection) => string;
+/** The props the TableSort accepts. */
+export interface TableSortProps extends Omit<ComponentProps<'th'>, 'children'> {
+    /**
+     * The column's name, and the visible text of the header.
+     *
+     * It is a `th` with `scope="col"` rather than a `button` dressed as a header,
+     * because the header is what a screen reader announces while a reader is moving
+     * across the table, and a header that is not a header is a row of buttons above a
+     * grid with no column names in it.
+     */
+    children?: ReactNode;
+    /** The column this header sorts. */
+    column: string;
+    /** The direction the column is currently sorted in. @defaultValue 'none' */
+    direction?: TableSortDirection;
+    /**
+     * Called with the direction the column will be in after this activation.
+     *
+     * The caller owns the sort and the rows, because a Component cannot sort an
+     * arbitrary set of records: it does not know what the column means, whether it
+     * is a number or a date or a name, or what the original order was. So the
+     * header reports the direction and the caller's table reorders.
+     */
+    onDirectionChange?: (direction: TableSortDirection) => void;
+    /**
+     * The words read for what activating the header will do.
+     *
+     * Required, and required as a **function of the next direction** rather than as
+     * a string, because the announcement has to say what *will* happen, not what is.
+     * A header that announces "sorted ascending" when it is already ascending tells
+     * a reader nothing about the press they are about to make, and one that
+     * announces "sort" says nothing about which way. The words are the caller's for
+     * the reason every other reader-facing string in this package is: a shared
+     * library cannot know whether the word for this is "sort", "trier" or
+     * "sortieren", and a sentence it chose would be inherited by every consumer in
+     * a language they did not write.
+     */
+    announce: TableSortAnnouncement;
+    /** Whether this header ignores user interaction. */
+    disabled?: boolean;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * The sortable header affordance for a `Table`.
+ *
+ * **`aria-sort` belongs on the `th`, and this is a `th`.** Not a `button` inside a
+ * `th`, and not a `th` with a `role="button"` on it. A column header is what a
+ * screen reader announces while a reader is moving across a table, and the sort
+ * state is a property of that header rather than of a control inside it, so
+ * `aria-sort` sits on the cell where the reader is told about it. It is set on
+ * exactly one header at a time, which is the rule: two columns both reporting
+ * `aria-sort` is a table claiming to be ordered two ways at once, and a reader
+ * comparing the two hears a contradiction.
+ *
+ * **The announcement says what will happen, not what is.** That is the decision
+ * this Component is built around, and it is why `announce` is a function of the
+ * next direction rather than a string. A reader who is about to press a header
+ * needs to know what the press will do, and the honest way to say it depends on
+ * the column's current state: on an unsorted column the press sorts ascending, on
+ * an ascending one it reverses, on a descending one it returns the original
+ * order. One string cannot be right for all three, and a string chosen for one of
+ * them is wrong for the other two in a way the reader cannot detect.
+ *
+ * **Two clicks to descending, three back to unsorted, and the third is the point.**
+ * The cycle is `none`, `ascending`, `descending`, and back to `none`, and the last
+ * step is a decision rather than an omission. A reader who has sorted to find the
+ * largest value and no longer cares has to be able to get the original order back
+ * from the control they already know, because any other route is a second
+ * affordance this package would then have to document. The announcement prop
+ * exists so a caller can say what that third press does in their own words, which
+ * is the one sentence in the whole interaction Prism cannot write for them.
+ *
+ * **The sort is the caller's.** A Component cannot sort an arbitrary set of
+ * records: it does not know whether the column is a number, a date or a name, it
+ * does not know the locale a name sorts in, and it does not know the original
+ * order it would have to restore. So this header owns the state it displays and
+ * reports the direction, and the caller's table reorders the rows.
+ *
+ * **The mark is a shape as well as a colour.** An unsorted column carries the
+ * two-headed mark, an ascending one an up arrow and a descending one a down
+ * arrow, and the mark is `aria-hidden` because the state is already on the cell in
+ * `aria-sort` and a reader is not told twice. A reader who cannot separate the
+ * three marks still gets the state from the attribute, which is the same order the
+ * whole package keeps: the attribute is the fact and the drawing is the reminder.
+ *
+ * It is a client Component, because a header that reports a direction and holds
+ * the announcement is holding state and attaching a handler.
+ */
+declare function TableSort({ children, column, direction, onDirectionChange, announce, disabled, className, ...props }: TableSortProps): import("react").JSX.Element;
+export { TableSort };
+//# sourceMappingURL=table-sort.d.ts.map

package/dist/components/ui/table-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-sort.d.ts","sourceRoot":"","sources":["../../../src/components/ui/table-sort.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAI5E,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CAAA;AAEpE,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,kBAAkB,KAAK,MAAM,CAAA;AAE7E,uCAAuC;AACvC,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC5E;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,kBAAkB,CAAA;IAC9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,qBAAqB,CAAA;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAS,SAAS,CAAC,EACjB,QAAQ,EACR,MAAM,EACN,SAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,QAAgB,EAChB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAmFhB;AAED,OAAO,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ui/table-sort.js

@@ -0,0 +1,102 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowDownIcon, ArrowUpIcon, ChevronsUpDownIcon } from 'lucide-react';
+import { useId, useState } from 'react';
+import { cn } from '../../lib/utils.js';
+/** The direction a click on a header in `from` produces. */
+function nextDirection(from) {
+    // Unsorted, then ascending, then descending, then unsorted again.
+    //
+    // Returning to `none` is the decision worth making, and it is why the cycle has
+    // three states rather than two. A reader who has sorted a column to find the
+    // extreme and no longer cares has to get the original order back, and the only
+    // route to it is a third click on the header they already know. A two-state
+    // control makes that order unreachable from the control, which means the caller
+    // has to invent a second affordance for it, and a second affordance is a second
+    // thing a reader has to find. So the cycle closes.
+    if (from === 'none')
+        return 'ascending';
+    if (from === 'ascending')
+        return 'descending';
+    return 'none';
+}
+/** The mark each state draws, which is a shape and not only a colour. */
+const MARK = {
+    // The unsorted mark is the two-headed one, because it says "this column can be
+    // ordered either way" rather than "this column is ordered". A single upward
+    // arrow on an unsorted column claims an order that is not in force.
+    none: _jsx(ChevronsUpDownIcon, { className: "size-3.5" }),
+    ascending: _jsx(ArrowUpIcon, { className: "size-3.5" }),
+    descending: _jsx(ArrowDownIcon, { className: "size-3.5" }),
+};
+/**
+ * The sortable header affordance for a `Table`.
+ *
+ * **`aria-sort` belongs on the `th`, and this is a `th`.** Not a `button` inside a
+ * `th`, and not a `th` with a `role="button"` on it. A column header is what a
+ * screen reader announces while a reader is moving across a table, and the sort
+ * state is a property of that header rather than of a control inside it, so
+ * `aria-sort` sits on the cell where the reader is told about it. It is set on
+ * exactly one header at a time, which is the rule: two columns both reporting
+ * `aria-sort` is a table claiming to be ordered two ways at once, and a reader
+ * comparing the two hears a contradiction.
+ *
+ * **The announcement says what will happen, not what is.** That is the decision
+ * this Component is built around, and it is why `announce` is a function of the
+ * next direction rather than a string. A reader who is about to press a header
+ * needs to know what the press will do, and the honest way to say it depends on
+ * the column's current state: on an unsorted column the press sorts ascending, on
+ * an ascending one it reverses, on a descending one it returns the original
+ * order. One string cannot be right for all three, and a string chosen for one of
+ * them is wrong for the other two in a way the reader cannot detect.
+ *
+ * **Two clicks to descending, three back to unsorted, and the third is the point.**
+ * The cycle is `none`, `ascending`, `descending`, and back to `none`, and the last
+ * step is a decision rather than an omission. A reader who has sorted to find the
+ * largest value and no longer cares has to be able to get the original order back
+ * from the control they already know, because any other route is a second
+ * affordance this package would then have to document. The announcement prop
+ * exists so a caller can say what that third press does in their own words, which
+ * is the one sentence in the whole interaction Prism cannot write for them.
+ *
+ * **The sort is the caller's.** A Component cannot sort an arbitrary set of
+ * records: it does not know whether the column is a number, a date or a name, it
+ * does not know the locale a name sorts in, and it does not know the original
+ * order it would have to restore. So this header owns the state it displays and
+ * reports the direction, and the caller's table reorders the rows.
+ *
+ * **The mark is a shape as well as a colour.** An unsorted column carries the
+ * two-headed mark, an ascending one an up arrow and a descending one a down
+ * arrow, and the mark is `aria-hidden` because the state is already on the cell in
+ * `aria-sort` and a reader is not told twice. A reader who cannot separate the
+ * three marks still gets the state from the attribute, which is the same order the
+ * whole package keeps: the attribute is the fact and the drawing is the reminder.
+ *
+ * It is a client Component, because a header that reports a direction and holds
+ * the announcement is holding state and attaching a handler.
+ */
+function TableSort({ children, column, direction = 'none', onDirectionChange, announce, disabled = false, className, ...props }) {
+    // Uncontrolled use is a state the header keeps for itself, so a caller who wants
+    // to read the sort back has a `direction` to pass. The two together are the
+    // usual React shape, and the state is a convenience rather than the contract:
+    // `onDirectionChange` is the contract.
+    const [uncontrolled, setUncontrolled] = useState('none');
+    const active = direction === 'none' && onDirectionChange === undefined ? uncontrolled : direction;
+    const next = nextDirection(active);
+    // The id that ties the announcement to the button. Generated rather than
+    // derived from the column, because two tables on a page may sort the same column
+    // and an id built from its name would collide, leaving both headers describing
+    // each other.
+    const descriptionId = useId();
+    return (_jsxs("th", { "data-slot": "table-sort", "data-column": column, "data-direction": active, scope: "col", "aria-sort": active === 'none' ? undefined : active, className: cn('p-0', className), ...props, children: [_jsx("span", { id: descriptionId, "data-slot": "table-sort-announcement", className: "sr-only", children: announce(next) }), _jsxs("button", { type: "button", "data-slot": "table-sort-button", "aria-describedby": descriptionId, disabled: disabled, onClick: () => {
+                    if (onDirectionChange === undefined)
+                        setUncontrolled(next);
+                    onDirectionChange?.(next);
+                }, className: cn('text-muted-foreground hover:text-foreground flex h-10 w-full items-center gap-1.5 px-2 text-left align-middle text-sm font-medium whitespace-nowrap outline-none', 'transition-colors duration-fast ease-out', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:opacity-50', 
+                // The sorted column says so in the foreground ink rather than the muted
+                // one, which is a second channel on top of the arrow and the attribute:
+                // a reader who can see neither the arrow nor the attribute still sees
+                // which column is ordered.
+                active === 'none' ? '' : 'text-foreground'), children: [_jsx("span", { "data-slot": "table-sort-label", className: "truncate", children: children }), _jsx("span", { "data-slot": "table-sort-mark", "aria-hidden": "true", className: "ml-auto inline-flex shrink-0 items-center", children: MARK[active] })] })] }));
+}
+export { TableSort };

package/dist/components/ui/table.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The semantic table components for tabular data.
  *

package/dist/components/ui/tabs.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A set of layered panels shown one at a time.
  *

package/dist/components/ui/textarea.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * The multi-line text control.
  *

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

@@ -0,0 +1,106 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * How far along an event is, where the run is still going.
+ *
+ * Four states, and this is a different vocabulary from the four product-capability
+ * tiers a StatusLedger01 row carries. Those answer "what can this product do
+ * today" and these answer "what happened to this run", so they are two lists
+ * about two different subjects rather than two lists about one. A `planned` agent
+ * run is a category error, and a `failed` capability is a category error, which is
+ * the test that tells them apart.
+ *
+ * `running` is the only one that moves. It is the state a run is in while it is
+ * still arriving events, and it is the reason a Timeline is normally wrapped in a
+ * LiveRegion rather than being one.
+ */
+export type TimelineState = 'pending' | 'running' | 'done' | 'failed';
+/** One event in a run. */
+export type TimelineEntry = {
+    /**
+     * A stable key for the entry.
+     *
+     * Required, because a run's entries arrive and are reordered as it goes, and a
+     * list keyed by index would have a reader's focus jump to a different step when
+     * an earlier one is inserted.
+     */
+    id: string;
+    /** The words naming what happened. */
+    title: string;
+    /**
+     * How long the step took, in milliseconds.
+     *
+     * Omit it for a step whose duration is meaningless: a run's opening event has no
+     * length, and a bar drawn for it would be a bar comparing nothing.
+     */
+    duration?: number;
+    /** Where the step is. @defaultValue 'done' */
+    state?: TimelineState;
+    /** Anything the caller wants under the step: a command, a diff, a payload. */
+    children?: ReactNode;
+};
+/** The props the Timeline accepts. */
+export interface TimelineProps extends Omit<ComponentProps<'ol'>, 'children'> {
+    /**
+     * The events, in the order they happened.
+     *
+     * Order is the caller's, not this Component's: a run log arrives in the order
+     * the transport delivered it, and a Timeline that sorted by duration or by state
+     * would be a different component that answers a different question.
+     */
+    entries: readonly TimelineEntry[];
+    /**
+     * The accessible name of the list, read before its entries.
+     *
+     * Required rather than defaulted, because two timelines on a page are two lists a
+     * reader cannot tell apart, and the name is the caller's word.
+     */
+    label: string;
+    /**
+     * The words for a duration, given the number of milliseconds.
+     *
+     * The default renders seconds with at most one decimal, which is a measurement
+     * rather than a sentence. A caller whose steps are measured in minutes or whose
+     * readers want a different precision passes its own.
+     */
+    format?: (ms: number) => string;
+    /** Layout only. */
+    className?: string;
+    /**
+     * What a reader is told when the run has no events yet.
+     *
+     * An empty list is the state a run spends its first moments in, so it is
+     * authored rather than left to a caller to notice.
+     */
+    empty?: ReactNode;
+}
+/**
+ * A run's events in order, with the time each one took drawn to scale.
+ *
+ * The second half of an agent console is always the same question: not what
+ * happened, but where the time went. A list of events in order answers the first
+ * and is silent on the second, so a reader who wants to know why a run took forty
+ * seconds has to read every number and do the arithmetic themselves.
+ *
+ * **The bars share a left edge and are drawn to scale against the longest step in
+ * the run.** That is the whole idea. The scale is relative rather than absolute,
+ * which is the right choice here: the shape of the run is the question, and a
+ * shared zero baseline would be a second axis nobody reads. The consequence worth
+ * stating is that the bars answer "which step was slow" and deliberately do not
+ * answer "how long did the run take", because only the caller knows whether its
+ * steps were sequential or overlapping, and a bar that implied otherwise would be
+ * claiming something about the run it cannot see.
+ *
+ * **A step with no duration draws no bar.** A run's opening event has no length,
+ * and a zero-width bar beside it would read as "this was instant" rather than
+ * "this has no duration", which are different claims and only one is true.
+ *
+ * **It is a list, not a live region.** The order is the accessibility tree: an
+ * ordered list, so a reader hears the sequence and the count. A run that is still
+ * arriving is normally wrapped in a LiveRegion by the caller, because the arrival
+ * is the event worth announcing and the list is the thing worth reading
+ * afterwards. Making the list itself live would announce the whole run again on
+ * every append.
+ */
+declare function Timeline({ entries, label, format, className, empty, ...props }: TimelineProps): import("react").JSX.Element;
+export { Timeline };
+//# sourceMappingURL=timeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../../src/components/ui/timeline.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAErE,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG;IAC1B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3E;;;;;;OAMG;IACH,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;IACjC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/B,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,QAAQ,CAAC,EAChB,OAAO,EACP,KAAK,EACL,MAAsB,EACtB,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,aAAa,+BAkIf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/timeline.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The border each state draws its mark in.
+ *
+ * Every mark is a ring and none of them is filled, for two reasons that point the
+ * same way. The first is the measurement the StatusLedger01 mark gives: a filled
+ * pastel dot fails contrast against a light card, and a state a reader cannot see
+ * is not a state. The second is uniformity: one geometry for all four states means
+ * a reader scanning the column is comparing colours rather than shapes, and a
+ * column where some marks are solid and some are hollow is a column to decode.
+ *
+ * A ring also needs no background of its own. An unfilled mark shows the surface
+ * behind it, which is the page ground or the card it is on, and a ground-coloured
+ * interior inside a coloured ring is exactly what a ring looks like. A filled
+ * variant had to paint `bg-background` into the middle to avoid rendering as a
+ * transparent hole, and that is a fill declaring a surface while carrying nothing
+ * on it.
+ *
+ * The state is not carried by the colour alone. The mark is `aria-hidden` and the
+ * entry's own words carry it, so a reader who cannot separate the four borders
+ * still reads "Failed to fetch" on the entry itself.
+ */
+const STATE_MARK = {
+    pending: 'border-border',
+    running: 'border-primary',
+    done: 'border-brand-ink',
+    failed: 'border-destructive',
+};
+const STATE_BAR = {
+    // A pending step's bar is the border colour rather than a muted fill, because a
+    // bar that is drawn but empty says "this took no time" rather than "this has not
+    // run yet". Those are different claims and only one of them is true.
+    pending: 'bg-border',
+    running: 'bg-primary',
+    done: 'bg-brand-ink',
+    failed: 'bg-destructive',
+};
+/** A duration in the compact form the default uses, and the guard against a non-number. */
+function defaultFormat(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return '';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    return `${seconds >= 10 ? Math.round(seconds) : Math.round(seconds * 10) / 10}s`;
+}
+/**
+ * A run's events in order, with the time each one took drawn to scale.
+ *
+ * The second half of an agent console is always the same question: not what
+ * happened, but where the time went. A list of events in order answers the first
+ * and is silent on the second, so a reader who wants to know why a run took forty
+ * seconds has to read every number and do the arithmetic themselves.
+ *
+ * **The bars share a left edge and are drawn to scale against the longest step in
+ * the run.** That is the whole idea. The scale is relative rather than absolute,
+ * which is the right choice here: the shape of the run is the question, and a
+ * shared zero baseline would be a second axis nobody reads. The consequence worth
+ * stating is that the bars answer "which step was slow" and deliberately do not
+ * answer "how long did the run take", because only the caller knows whether its
+ * steps were sequential or overlapping, and a bar that implied otherwise would be
+ * claiming something about the run it cannot see.
+ *
+ * **A step with no duration draws no bar.** A run's opening event has no length,
+ * and a zero-width bar beside it would read as "this was instant" rather than
+ * "this has no duration", which are different claims and only one is true.
+ *
+ * **It is a list, not a live region.** The order is the accessibility tree: an
+ * ordered list, so a reader hears the sequence and the count. A run that is still
+ * arriving is normally wrapped in a LiveRegion by the caller, because the arrival
+ * is the event worth announcing and the list is the thing worth reading
+ * afterwards. Making the list itself live would announce the whole run again on
+ * every append.
+ */
+function Timeline({ entries, label, format = defaultFormat, className, empty, ...props }) {
+    if (entries.length === 0) {
+        // A run spends its first moments with nothing in it, and an empty list with no
+        // words in it is a gap rather than a state.
+        return (_jsx("div", { "data-slot": "timeline-empty", className: cn('text-muted-foreground text-sm', className), children: empty ?? null }));
+    }
+    // The longest step with a duration sets the scale. A run whose steps all report
+    // no duration has no scale, and every bar is then omitted rather than drawn at
+    // an arbitrary width.
+    const longest = Math.max(0, ...entries
+        .map((entry) => entry.duration)
+        .filter((duration) => typeof duration === 'number' && duration > 0));
+    return (_jsx("ol", { "data-slot": "timeline", "aria-label": label, className: cn('flex flex-col', className), ...props, children: entries.map((entry, index) => {
+            const state = entry.state ?? 'done';
+            // Bound to a local before the test, because a boolean derived from a
+            // narrowing check does not carry the narrowing to its own use: reading
+            // `entry.duration` after `hasDuration` is still `number | undefined` to
+            // the checker, which is the sort of thing a boolean is a poor carrier for.
+            const duration = entry.duration;
+            const hasDuration = typeof duration === 'number' && duration > 0 && longest > 0;
+            const width = hasDuration ? (duration / longest) * 100 : 0;
+            const isLast = index === entries.length - 1;
+            return (_jsxs("li", { "data-slot": "timeline-entry", "data-state": state, className: "grid grid-cols-[auto_1fr] gap-x-3", children: [_jsxs("div", { "data-slot": "timeline-rail", "aria-hidden": "true", className: "flex flex-col items-center", children: [_jsx("span", { "data-slot": "timeline-mark", className: cn('mt-1.5 size-2 shrink-0 rounded-full border-2', STATE_MARK[state], 
+                                // A running step is the one that is still moving, and a ring that
+                                // pulses is the only motion in the Component. It is state
+                                // feedback, not decoration: it stops when the step stops.
+                                state === 'running' && 'animate-pulse') }), isLast ? null : _jsx("span", { "data-slot": "timeline-spine", className: "bg-border w-px flex-1" })] }), _jsxs("div", { className: cn(
+                        // The last entry has nothing under it, so its bottom padding is
+                        // dropped rather than leaving a gap the reader reads as a
+                        // missing step.
+                        'flex min-w-0 flex-col gap-1.5', isLast ? 'pb-0' : 'pb-4'), children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { "data-slot": "timeline-title", className: cn('min-w-0 truncate text-sm', state === 'pending' && 'text-muted-foreground', state === 'failed' && 'text-destructive', state === 'done' || state === 'running'
+                                            ? 'text-foreground'
+                                            : 'text-muted-foreground'), children: entry.title }), typeof entry.duration === 'number' && entry.duration > 0 ? (_jsx("span", { "data-slot": "timeline-duration", className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: format(entry.duration) })) : null] }), hasDuration ? (_jsx("span", { "data-slot": "timeline-bar", className: cn('block h-1 w-full overflow-hidden rounded-full', STATE_BAR[state]), style: { width: `${width}%` } })) : null, entry.children === undefined ? null : (_jsx("div", { "data-slot": "timeline-detail", className: "text-muted-foreground min-w-0 text-sm", children: entry.children }))] })] }, entry.id));
+        }) }));
+}
+export { Timeline };