@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/lifecycle-button.d.ts

@@ -0,0 +1,276 @@
+import type { ReactNode } from 'react';
+/**
+ * The four points a button's work can be at.
+ *
+ * A closed set of four, and the fourth is the one that makes it a lifecycle. A
+ * control that is idle, one that is working and one that has finished are three
+ * states, and every system that stops at three has folded success and failure
+ * into a single "done" and then had to choose which of the two words to print. The
+ * answer is a flag, and a flag that says `done` when the request was refused tells
+ * a reader their work was saved, which is the most expensive sentence a control
+ * can get wrong.
+ */
+export type LifecycleButtonPhase = 'idle' | 'in-flight' | 'succeeded' | 'failed';
+/**
+ * Where the work is, as a value the caller holds.
+ *
+ * A union rather than a `loading` boolean beside an `error` message, and the reason
+ * is the pair. A boolean has two answers and this has four, and the two answers
+ * nobody can express with a boolean are the two that matter: a request that
+ * failed, and a request whose position is known. A caller holding `loading` plus a
+ * string has to encode four states across two props that do not know about each
+ * other, and every one of those four combinations has to be drawn.
+ */
+export type LifecycleButtonState = 
+/** Nothing has been asked. The control is the caller's primary action. */
+{
+    phase: 'idle';
+}
+/**
+ * The work is running.
+ *
+ * `progress` is a fraction between zero and one and it is a real measurement, not
+ * a timer: a caller that has a byte count, a row count or a completed-step count
+ * passes the ratio and the reader is told the position. Omit it and the work is
+ * of unknown length, which is a different fact and is drawn and announced as
+ * such. It is never defaulted, because a bar that fills on its own is a
+ * measurement of nothing.
+ */
+ | {
+    phase: 'in-flight';
+    progress?: number;
+    progressText?: string;
+}
+/** The work finished. */
+ | {
+    phase: 'succeeded';
+}
+/** The work did not finish, with the caller's own sentence about why. */
+ | {
+    phase: 'failed';
+    reason?: ReactNode;
+};
+/**
+ * The props the Lifecycle button accepts.
+ *
+ * A declared interface rather than a forwarded native one, and the reason is the
+ * gate on the surface: a forwarded `onClick` would be a second way to say what the
+ * control does, and a forwarded `children` would be a second way to say what it
+ * says. Both are decided here. The five words are five props rather than one
+ * `labels` record because a record's keys are a second list of the lifecycle, and
+ * the lifecycle is already stated in the type of `state`; two lists of the same
+ * four states is two lists that can disagree.
+ */
+export interface LifecycleButtonProps {
+    /**
+     * Where the work is.
+     *
+     * Required and controlled, and the whole of the Component: the caller owns the
+     * request, so the caller owns where the request is. Prism draws the label, the
+     * mark, the meter and the retry that a position implies, and calls back. It
+     * never moves the position, and it holds no promise, no transport and no timer.
+     */
+    state: LifecycleButtonState;
+    /**
+     * Called when the reader presses the control while it is idle.
+     *
+     * Required, and it is called only from `idle`. A control that accepts presses
+     * while its work is running would let a reader queue a second request without
+     * knowing whether the first had finished, and a control that accepts presses
+     * after a failure would be a second way of retrying with a different meaning.
+     * The caller moves the position to `in-flight`; nothing here does.
+     */
+    onActivate: () => void;
+    /** The label in the idle position, in the product's own words. */
+    idleLabel: ReactNode;
+    /** The label while the work is running, in the product's own words. */
+    inFlightLabel: ReactNode;
+    /**
+     * The label after the work finished.
+     *
+     * Required rather than derived from the icon, because a check mark is a
+     * drawing and a control whose outcome is a drawing is a control whose outcome a
+     * screen reader never hears. Write the outcome: "Saved", "Published",
+     * "Enqueued".
+     */
+    succeededLabel: ReactNode;
+    /**
+     * The label after the work failed.
+     *
+     * Required, and it is the label a reader sees on a control they already pressed
+     * and already believe worked, so it has to be the sentence that tells them
+     * otherwise. "Not saved" is a control that is still the same control and now
+     * says the opposite; "Try again" is a different action and belongs on the retry
+     * beside it.
+     */
+    failedLabel: ReactNode;
+    /**
+     * The label of the retry control, which exists only in the failed position.
+     *
+     * Required, and the same word for every product's "try this again" is not
+     * something this package may choose: "Retry", "Save again" and "Reintentar" are
+     * three products' answers.
+     */
+    retryLabel: ReactNode;
+    /**
+     * The fill the control is drawn in.
+     *
+     * The four fills that make no claim about the outcome, and the reason the other
+     * two are absent is the Stated Ink Rule read from the other side. The failed
+     * position is not drawn destructive: destructive is for an action that cannot be
+     * undone, and a failed save is not that. Nor is it drawn `link`, which is a
+     * control inside a sentence and a lifecycle control is a sentence of its own.
+     * Nor is the failed position left as `default`, because a filled primary beside a
+     * failure is a control inviting a press that has already been shown not to work.
+     * The failure is carried by the label, the mark and the line beneath, and those
+     * are enough.
+     *
+     * @defaultValue 'default'
+     */
+    variant?: 'default' | 'secondary' | 'outline' | 'ghost';
+    /**
+     * The control's height. @defaultValue 'default'
+     *
+     * The four authored steps including `icon` are not offered, because a lifecycle
+     * control that has collapsed to a glyph has thrown away the one thing the
+     * lifecycle adds, which is the words that change as it runs.
+     */
+    size?: 'sm' | 'default' | 'lg';
+    /**
+     * Whether the control submits the form it sits in.
+     *
+     * Passed through rather than drawn, so a lifecycle control can be a form's submit
+     * button. Note what the Component does with it: a press from `in-flight` or
+     * `failed` is still refused, so a submit control here will not submit twice
+     * because the first submit is still running.
+     *
+     * @defaultValue 'button'
+     */
+    type?: 'button' | 'submit' | 'reset';
+    /**
+     * The name the control submits under, when it submits.
+     *
+     * A native attribute the Component forwards untouched, because a submit button's
+     * name is a fact about the caller's form and about nothing in this Component.
+     */
+    name?: string;
+    /**
+     * The form the control submits, when it is not inside one.
+     *
+     * Forwarded for the same reason as `name`, and it is the one native attribute
+     * worth forwarding on a control that can submit: a lifecycle button placed in a
+     * dialog's footer is outside the form it acts on.
+     */
+    form?: string;
+    /**
+     * Whether the control is unavailable for a reason of the caller's own.
+     *
+     * Drawn and not set, for the reason `Dropzone` states in full: a natively
+     * disabled control is out of the tab order, so a keyboard reader tabs onto where
+     * it was, presses Enter, and nothing happens with no announcement to explain it.
+     * This one keeps its place, keeps its ring and announces itself as unavailable.
+     * The cost is a tab stop that does nothing, which is the price every disabled
+     * control pays and the reason disabled controls are drawn rather than omitted.
+     */
+    disabled?: boolean;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * A button whose label, mark and meter follow an asynchronous outcome: idle, in
+ * flight, succeeded or failed, with a retry beside it after a failure.
+ *
+ * **It is a state machine and not a loading flag, and the difference from
+ * `Button` is larger than it first looks.** `Button` has no `loading` prop and no
+ * loading state of any kind: it renders a native `<button>` and takes `variant`
+ * and `size`, and that is the whole of its interface. So there is no overlap to
+ * argue about, and the honest reason this Item is not a `Button` with one more
+ * boolean is that the boolean was never there. What a caller does today is write
+ * three controls: a `Button` whose label swaps while a request runs, a second
+ * `Button` that appears when it fails, and a `Progress` or a `Spinner` beside the
+ * first. This is those three, and the reason they were three is that they are
+ * three positions of one line and `Button` is a control rather than a line. If a
+ * `loading` boolean is ever added to `Button`, the honest response is to narrow
+ * this Item to the two positions a boolean cannot express, the failure and the
+ * fraction, rather than to delete it.
+ *
+ * **A boolean has two answers and a lifecycle has four, and the two it cannot
+ * express are the two that cost the most.** A request that failed is not
+ * `loading: false`: it is a control the reader already pressed, which is now
+ * telling them their work was not saved, and it needs different words, a
+ * different mark and a different next action from a control that has never been
+ * pressed. Encoding that as a boolean plus a string puts four states across two
+ * props that do not know about each other, and every consumer redraws the
+ * combinations. The union puts them in one value, and adding a sixth state later
+ * is a compile error at every place that switches over it.
+ *
+ * **The determinate bar is legal motion and the reason is that it is bound to a
+ * real state transition.** The fill is `Progress`, which animates its width on the
+ * base duration and eases out; there is no keyframe, no loop and no cycle, because
+ * a bar that is moving because a number changed is state feedback under the first
+ * of the two motion laws and nothing else. A bar with no number is not drawn as a
+ * moving one: a caller that passes no `progress` gets the same component with
+ * `value={null}`, which is announced as indeterminate and is the truth about work
+ * of unknown length. The Component refuses to fill a bar it has no number for, and
+ * the refusal is a thrown diagnostic rather than a silently invented position.
+ *
+ * **`Progress` is composed and not drawn, and that is why the in-flight position
+ * has one indicator rather than two.** A determinate fraction and an indeterminate
+ * request are the same question asked with and without an answer, so they are the
+ * same Component, and the alternative is a bar in one position and a ring in the
+ * other, which is two answers to how far along a task is on one button. The width
+ * is bounded by `className` because width is layout, and everything else about the
+ * bar is Prism's.
+ *
+ * **A fraction is announced in the caller's words or not at all.** `Progress`
+ * exposes its value, minimum and maximum through ARIA, so a fraction between zero
+ * and one is announced as a decimal, and "0.42" is a measurement of nothing a
+ * reader can act on. So a state carrying `progress` must carry `progressText`, and
+ * the Component throws without it rather than letting a number through as an
+ * accessible name. Write the position as the reader would say it: "Uploading,
+ * 42 percent", "3 of 8 steps".
+ *
+ * **The outcome is announced, and the announcement is the transition rather than
+ * the control.** A reader who pressed a control and watched its label change has
+ * been answered; a reader who pressed it and looked away has not, and the
+ * succeeded position is the one that arrives with no other evidence on the page
+ * when the control that caused it has scrolled out of view. So the Component
+ * composes `LiveRegion` with the settled label in it, polite for a success and
+ * assertive for a failure, which is the politeness rule `LiveRegion` states and
+ * for its reasons: a save that landed waits its turn, and a save that was refused
+ * interrupts. The reason line beneath the control is deliberately not an alert, so
+ * the failure is announced once rather than twice in the same commit.
+ *
+ * **The region is mounted at the outcome rather than held empty, and the cost is
+ * real.** `LiveRegion` deliberately renders nothing when it has nothing to say,
+ * because a live region sitting on the page permanently announces unrelated
+ * changes of its ancestors, which is the noise the Component exists to avoid as
+ * well as to cause. The consequence is that this region is created at the moment
+ * of its content, and a live region created with its content is announced by most
+ * screen readers and not by all of them. A caller who needs the guarantee on every
+ * transition keeps a `LiveRegion` of their own beside this Component and passes
+ * the outcome into it, which is two lines and no override of anything here.
+ *
+ * **The retry is a second control and not a state of the first, because the two
+ * actions are not the same.** Pressing the control again after a failure is a
+ * claim that the same request is worth making again, and the caller may well have
+ * changed their mind; a control that quietly became the retry would make a reader
+ * who wants to send something different press it twice to find out. So the failed
+ * position draws the control, still labelled as the failed outcome, with a second
+ * control beside it. The cost is a row that is two controls wide in one position
+ * out of four, and a caller who has nowhere to put it composes the retry in their
+ * own layout rather than dropping the affordance.
+ *
+ * **It is a client Component**, because `Progress` is one, because the outcome is
+ * announced through a region whose behaviour the browser's mutation observer
+ * provides and whose mounting is React's, and because the only callback it takes
+ * is one the caller has to be in the client graph to supply. What that costs is
+ * the price of every client control, and it is worth naming because the surface
+ * invites a server render: a server Component can render the idle position and it
+ * will look right, and what it cannot do is move the position, show a fraction, or
+ * announce an outcome, because those are facts about what happens after the reader
+ * acts.
+ */
+declare function LifecycleButton({ state, onActivate, idleLabel, inFlightLabel, succeededLabel, failedLabel, retryLabel, variant, size, type, name, form, disabled, className, }: LifecycleButtonProps): import("react").JSX.Element;
+export { LifecycleButton };
+//# sourceMappingURL=lifecycle-button.d.ts.map

package/dist/components/ui/lifecycle-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-button.d.ts","sourceRoot":"","sources":["../../../src/components/ui/lifecycle-button.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAOtC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEhF;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB;AAC9B,0EAA0E;AACxE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE;AACnB;;;;;;;;;GASG;GACD;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;AAClE,yBAAyB;GACvB;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE;AACxB,yEAAyE;GACvE;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,KAAK,EAAE,oBAAoB,CAAA;IAC3B;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAA;IACpB,uEAAuE;IACvE,aAAa,EAAE,SAAS,CAAA;IACxB;;;;;;;OAOG;IACH,cAAc,EAAE,SAAS,CAAA;IACzB;;;;;;;;OAQG;IACH,WAAW,EAAE,SAAS,CAAA;IACtB;;;;;;OAMG;IACH,UAAU,EAAE,SAAS,CAAA;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAA;IACvD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,IAAI,CAAA;IAC9B;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;IACpC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,iBAAS,eAAe,CAAC,EACvB,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EACb,cAAc,EACd,WAAW,EACX,UAAU,EACV,OAAmB,EACnB,IAAgB,EAChB,IAAe,EACf,IAAI,EACJ,IAAI,EACJ,QAAgB,EAChB,SAAS,GACV,EAAE,oBAAoB,+BAsGtB;AAED,OAAO,EAAE,eAAe,EAAE,CAAA"}

package/dist/components/ui/lifecycle-button.js

@@ -0,0 +1,144 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleCheckIcon, RefreshCwIcon, TriangleAlertIcon } from 'lucide-react';
+import { Button } from './button.js';
+import { LiveRegion } from './live-region.js';
+import { Progress } from './progress.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The mark each settled position carries, and the ink it is drawn in.
+ *
+ * Two entries and not four, because the idle and in-flight positions carry the
+ * meter or nothing rather than a mark, and a ring or a bar beside a label that
+ * already says what is happening is a second copy of a sentence the reader can
+ * already see. Both marks are `aria-hidden` at the call site and the label carries
+ * the meaning, which is the order the whole package keeps: the attribute is the
+ * fact and the drawing is the reminder. The inks are the semantic state roles and
+ * not a ramp step, and the shapes differ as well as the colours so a reader who
+ * cannot separate them still reads which is which.
+ */
+const SETTLED_MARK = {
+    succeeded: { Mark: CircleCheckIcon, ink: 'text-success' },
+    failed: { Mark: TriangleAlertIcon, ink: 'text-destructive' },
+};
+/**
+ * A button whose label, mark and meter follow an asynchronous outcome: idle, in
+ * flight, succeeded or failed, with a retry beside it after a failure.
+ *
+ * **It is a state machine and not a loading flag, and the difference from
+ * `Button` is larger than it first looks.** `Button` has no `loading` prop and no
+ * loading state of any kind: it renders a native `<button>` and takes `variant`
+ * and `size`, and that is the whole of its interface. So there is no overlap to
+ * argue about, and the honest reason this Item is not a `Button` with one more
+ * boolean is that the boolean was never there. What a caller does today is write
+ * three controls: a `Button` whose label swaps while a request runs, a second
+ * `Button` that appears when it fails, and a `Progress` or a `Spinner` beside the
+ * first. This is those three, and the reason they were three is that they are
+ * three positions of one line and `Button` is a control rather than a line. If a
+ * `loading` boolean is ever added to `Button`, the honest response is to narrow
+ * this Item to the two positions a boolean cannot express, the failure and the
+ * fraction, rather than to delete it.
+ *
+ * **A boolean has two answers and a lifecycle has four, and the two it cannot
+ * express are the two that cost the most.** A request that failed is not
+ * `loading: false`: it is a control the reader already pressed, which is now
+ * telling them their work was not saved, and it needs different words, a
+ * different mark and a different next action from a control that has never been
+ * pressed. Encoding that as a boolean plus a string puts four states across two
+ * props that do not know about each other, and every consumer redraws the
+ * combinations. The union puts them in one value, and adding a sixth state later
+ * is a compile error at every place that switches over it.
+ *
+ * **The determinate bar is legal motion and the reason is that it is bound to a
+ * real state transition.** The fill is `Progress`, which animates its width on the
+ * base duration and eases out; there is no keyframe, no loop and no cycle, because
+ * a bar that is moving because a number changed is state feedback under the first
+ * of the two motion laws and nothing else. A bar with no number is not drawn as a
+ * moving one: a caller that passes no `progress` gets the same component with
+ * `value={null}`, which is announced as indeterminate and is the truth about work
+ * of unknown length. The Component refuses to fill a bar it has no number for, and
+ * the refusal is a thrown diagnostic rather than a silently invented position.
+ *
+ * **`Progress` is composed and not drawn, and that is why the in-flight position
+ * has one indicator rather than two.** A determinate fraction and an indeterminate
+ * request are the same question asked with and without an answer, so they are the
+ * same Component, and the alternative is a bar in one position and a ring in the
+ * other, which is two answers to how far along a task is on one button. The width
+ * is bounded by `className` because width is layout, and everything else about the
+ * bar is Prism's.
+ *
+ * **A fraction is announced in the caller's words or not at all.** `Progress`
+ * exposes its value, minimum and maximum through ARIA, so a fraction between zero
+ * and one is announced as a decimal, and "0.42" is a measurement of nothing a
+ * reader can act on. So a state carrying `progress` must carry `progressText`, and
+ * the Component throws without it rather than letting a number through as an
+ * accessible name. Write the position as the reader would say it: "Uploading,
+ * 42 percent", "3 of 8 steps".
+ *
+ * **The outcome is announced, and the announcement is the transition rather than
+ * the control.** A reader who pressed a control and watched its label change has
+ * been answered; a reader who pressed it and looked away has not, and the
+ * succeeded position is the one that arrives with no other evidence on the page
+ * when the control that caused it has scrolled out of view. So the Component
+ * composes `LiveRegion` with the settled label in it, polite for a success and
+ * assertive for a failure, which is the politeness rule `LiveRegion` states and
+ * for its reasons: a save that landed waits its turn, and a save that was refused
+ * interrupts. The reason line beneath the control is deliberately not an alert, so
+ * the failure is announced once rather than twice in the same commit.
+ *
+ * **The region is mounted at the outcome rather than held empty, and the cost is
+ * real.** `LiveRegion` deliberately renders nothing when it has nothing to say,
+ * because a live region sitting on the page permanently announces unrelated
+ * changes of its ancestors, which is the noise the Component exists to avoid as
+ * well as to cause. The consequence is that this region is created at the moment
+ * of its content, and a live region created with its content is announced by most
+ * screen readers and not by all of them. A caller who needs the guarantee on every
+ * transition keeps a `LiveRegion` of their own beside this Component and passes
+ * the outcome into it, which is two lines and no override of anything here.
+ *
+ * **The retry is a second control and not a state of the first, because the two
+ * actions are not the same.** Pressing the control again after a failure is a
+ * claim that the same request is worth making again, and the caller may well have
+ * changed their mind; a control that quietly became the retry would make a reader
+ * who wants to send something different press it twice to find out. So the failed
+ * position draws the control, still labelled as the failed outcome, with a second
+ * control beside it. The cost is a row that is two controls wide in one position
+ * out of four, and a caller who has nowhere to put it composes the retry in their
+ * own layout rather than dropping the affordance.
+ *
+ * **It is a client Component**, because `Progress` is one, because the outcome is
+ * announced through a region whose behaviour the browser's mutation observer
+ * provides and whose mounting is React's, and because the only callback it takes
+ * is one the caller has to be in the client graph to supply. What that costs is
+ * the price of every client control, and it is worth naming because the surface
+ * invites a server render: a server Component can render the idle position and it
+ * will look right, and what it cannot do is move the position, show a fraction, or
+ * announce an outcome, because those are facts about what happens after the reader
+ * acts.
+ */
+function LifecycleButton({ state, onActivate, idleLabel, inFlightLabel, succeededLabel, failedLabel, retryLabel, variant = 'default', size = 'default', type = 'button', name, form, disabled = false, className, }) {
+    const inFlight = state.phase === 'in-flight';
+    const failed = state.phase === 'failed';
+    const succeeded = state.phase === 'succeeded';
+    const unavailable = inFlight || disabled;
+    if (inFlight && state.progress !== undefined && state.progressText === undefined) {
+        throw new Error('LifecycleButton: the in-flight state carries a progress fraction and no progressText, so the bar would be ' +
+            'announced as a decimal between zero and one, which is a measurement of nothing a reader can act on. Pass ' +
+            'the position in the words the reader would say it, or drop progress and let the bar be indeterminate.');
+    }
+    const label = state.phase === 'idle'
+        ? idleLabel
+        : inFlight
+            ? inFlightLabel
+            : succeeded
+                ? succeededLabel
+                : failedLabel;
+    const settled = succeeded || failed;
+    const mark = settled ? SETTLED_MARK[state.phase] : null;
+    return (_jsxs("div", { "data-slot": "lifecycle-button", className: cn('inline-flex flex-col items-start gap-1.5', className), children: [_jsxs("div", { "data-slot": "lifecycle-button-actions", className: "flex items-center gap-2", children: [_jsxs(Button, { "data-slot": "lifecycle-button-control", type: type, variant: variant, size: size, name: name, form: form, "aria-disabled": unavailable || undefined, onClick: unavailable ? () => undefined : onActivate, children: [mark === null ? null : _jsx(mark.Mark, { className: mark.ink, "aria-hidden": "true" }), _jsx("span", { "data-slot": "lifecycle-button-label", children: label }), inFlight ? (_jsx(Progress, { "data-slot": "lifecycle-button-progress", 
+                                // The clamped fraction and the same component with no value, so the
+                                // two are one question asked with and without an answer rather than
+                                // a bar and a ring on one button.
+                                value: state.progress === undefined ? null : Math.min(1, Math.max(0, state.progress)), max: 1, valueText: state.progressText, className: "w-16" })) : null] }), failed ? (_jsxs(Button, { "data-slot": "lifecycle-button-retry", type: "button", variant: "outline", size: size, onClick: onActivate, children: [_jsx(RefreshCwIcon, { "aria-hidden": "true" }), retryLabel] })) : null] }), failed && state.reason !== undefined && state.reason !== null && state.reason !== false ? (_jsx("p", { "data-slot": "lifecycle-button-message", className: "text-destructive text-sm", children: state.reason })) : null, settled ? (_jsx(LiveRegion, { className: "sr-only", politeness: failed ? 'assertive' : 'polite', children: label })) : null] }));
+}
+export { LifecycleButton };

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

@@ -0,0 +1,165 @@
+import { type ReactNode } from 'react';
+/** One image in the rail, and the words that describe it. */
+type LightboxThumbnail = {
+    /** The image, at the size a thumbnail is drawn. */
+    src: string;
+    /** The caller's description of it, and the button's accessible name. */
+    alt: string;
+};
+/** The props the Lightbox accepts. */
+export interface LightboxProps {
+    /** Whether the dialog is open. */
+    open: boolean;
+    /** Called when the reader closes the dialog, by any route. */
+    onOpenChange: (open: boolean) => void;
+    /** The image being shown, at the size it should be shown at. */
+    src: string;
+    /**
+     * The image's description, and required.
+     *
+     * Required because an enlarged image is the whole point of this Component and
+     * an unnamed one is not enlarged, it is merely bigger: a lightbox with no
+     * description is a picture a reader can see more of and still not read, and the
+     * reader has paid a modal, a focus trap and an Escape key for it. It is also
+     * the name the dialog falls back to when the caller passes a caption this
+     * Component cannot turn into a title, so it is load bearing twice.
+     */
+    alt: string;
+    /**
+     * The sentence under the image, in the caller's words.
+     *
+     * A string here becomes the dialog's visible name as well as its caption,
+     * because one sentence naming a figure is better than the same sentence twice
+     * in two places. A node is drawn under the image and the dialog is named by
+     * `alt` instead, which is the cost of a node: a node may be an image, a list
+     * or a piece of formatting, and a dialog's name has to be a string.
+     */
+    caption?: ReactNode;
+    /**
+     * The other images, in order, and the rail of buttons that reaches them.
+     *
+     * The rail is drawn only when this is given and holds more than one, because a
+     * rail of one is a picture of the picture you are already looking at. When it
+     * is given, `src` and `alt` are expected to be the entry at the current index,
+     * and moving the rail asks for a new index rather than moving the image: the
+     * caller owns the data and this Component owns the words a reader hears.
+     */
+    thumbnails?: readonly LightboxThumbnail[];
+    /**
+     * Which image is showing, zero based. Omit it for an uncontrolled lightbox
+     * that remembers where it was.
+     *
+     * A number and not a required prop, matching `Carousel`: a lightbox with one
+     * image has nothing to move between, and a caller who passes `thumbnails`
+     * should pass this too, which is the arrangement the type cannot enforce and
+     * the documentation has to.
+     */
+    index?: number;
+    /** Called with the image the reader asked for. */
+    onIndexChange?: (index: number) => void;
+    /**
+     * The accessible name of the zoom control. Required.
+     *
+     * A prop and not a word, because this package ships no string a consumer
+     * cannot localise, and a control is the clearest case of one: a button whose
+     * label reads "Zoom" in a product whose interface says something else is a
+     * control the consumer cannot fix without patching the library. The same
+     * reasoning as `check-block-copy`'s account of the dialog's close button, which
+     * is the finding that made this a rule rather than a preference.
+     *
+     * One name for a two state control, and the state is announced with
+     * `aria-pressed`, so a reader hears the name and then whether the image is
+     * currently at actual size. That has a consequence for the word: it should be
+     * a noun for the thing being changed, such as "Image size", rather than a verb
+     * for one of the two directions, because a verb is a claim about what the
+     * press will do and the press does whichever of the two the state is not. A
+     * caller who wants two distinct names has to own the state to get them, which
+     * the two index props already let them do.
+     */
+    zoomLabel: string;
+    /** The accessible name of the control that shows the previous image. Required, for the same reason. */
+    previousLabel: string;
+    /** The accessible name of the control that shows the next image. Required, for the same reason. */
+    nextLabel: string;
+    /** The accessible name of the control that closes the dialog. Required, for the same reason. */
+    closeLabel: string;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * An image at full size, in a dialog, with its own words and its own way out.
+ *
+ * **This Item exists because an image the reader cannot enlarge is an image the
+ * reader cannot read.** That is the whole argument, and it is not a small one,
+ * because an image carries text for a great many products: a chart exported as
+ * a picture, a screenshot of a console, a diagram, a photograph of a receipt, a
+ * logo lockup with a wordmark in it. At 320 pixels wide none of that is
+ * readable, and a reader who cannot read it has been shown a thumbnail and told
+ * it was the thing. Zooming in the browser is the alternative every consumer
+ * reaches for, and it is a poor one for a reader who is not using a mouse, one
+ * for a touch device where the gesture is not discoverable, and one that leaves
+ * the page's own focus, Escape key and scroll position behind, so the reader
+ * comes back to a different place than they left. A dialog is the whole of that
+ * and it comes free from a component library.
+ *
+ * **The dialog is `Dialog`, not a re-derivation of it.** The focus trap, the
+ * restore of focus to whatever opened it, the Escape key, the outside press, the
+ * scroll lock and the portal are all already solved and all of them are solved
+ * badly twice as often as they are solved well. An image overlay built on
+ * `<div>` and a `keydown` listener gets the Escape key and no focus trap, so a
+ * keyboard reader tabs behind the image into a page they cannot see; and every
+ * one of those defects is invisible in review because the overlay works for the
+ * person writing it. So this Component composes `Dialog` and spends its own
+ * surface on the three things `Dialog` does not know about: the rail, the
+ * controls and the zoom.
+ *
+ * **The four labels are props because Prism does not ship the words.** That is
+ * `check-block-copy`'s finding about `Dialog`'s close button, and it is a
+ * finding about this Component too: a hardcoded label is copy a consumer cannot
+ * localise, so a product in any language but English inherits an English
+ * control in the middle of its own interface, and the only fix is a fork. They
+ * are required rather than optional even though a lightbox with no rail draws
+ * no previous and no next control, and the reasoning is worth stating because it
+ * looks like friction. A required prop is a question asked at build time; an
+ * optional one is a question nobody asks, and the lightbox that grew a rail
+ * later would be the release where the two missing labels are discovered. It
+ * also keeps the prop set stable, so adding thumbnails is not a breaking change
+ * to the type.
+ *
+ * **The zoom is a state, not a gesture.** It toggles between fitted and actual
+ * size and the frame scrolls once the image is larger than it is, so the reader
+ * pans with the scroll keys and the arrow keys the way they pan anywhere else.
+ * There is no pinch, no drag to pan and no double tap, and the reason is that
+ * each of those is a bespoke pointer model that has to be discovered, whereas a
+ * scrollable frame is a thing every reader already knows. The transition on the
+ * image is a state change the reader caused, which is the first motion law's own
+ * case, and it carries no `motion-safe:` guard because it does not need one:
+ * `packages/ui/src/styles.css` ends with one unlayered `prefers-reduced-motion`
+ * rule that stops every transition, so a reader who has asked for less motion
+ * gets the new size immediately and loses only the travel between the two.
+ *
+ * **The rail is a list of real buttons and the current one is named, not
+ * coloured.** A rail of thumbnails is the one place a lightbox most often gets
+ * this wrong: the selected thumbnail gets a border and nothing else, so a
+ * screen reader user is read six identical buttons and a reader in greyscale is
+ * shown a difference of one pixel. Here each button is named by its own `alt`,
+ * which is a description of that image rather than of the position, and the
+ * current one carries `aria-current`. The inner image is marked decorative with
+ * an empty `alt`, so the button's name is the description and not a doubled
+ * reading of the same pixels.
+ *
+ * **The current image is the caller's.** `src` and `alt` are props, so this
+ * Component cannot move the image, and every control here asks for an index
+ * rather than setting one. That is a real constraint on a caller who wants the
+ * lightbox to own the sequence, and the reason for it is the same as everywhere
+ * else in this package: the images are application data, and a Component that
+ * held them would be a Component every consumer whose gallery is not this shape
+ * had to reimplement. A caller that wants an uncontrolled lightbox passes
+ * `index` and `onIndexChange` and keeps the state; one that wants the lightbox
+ * to remember where it was omits both and gets the local one.
+ *
+ * It is a client Component, and only because `Dialog` is one.
+ */
+declare function Lightbox({ open, onOpenChange, src, alt, caption, thumbnails, index, onIndexChange, zoomLabel, previousLabel, nextLabel, closeLabel, className, }: LightboxProps): import("react").JSX.Element;
+export { Lightbox };
+//# sourceMappingURL=lightbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lightbox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/lightbox.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAK3D,6DAA6D;AAC7D,KAAK,iBAAiB,GAAG;IACvB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAA;IACb,8DAA8D;IAC9D,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACzC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,uGAAuG;IACvG,aAAa,EAAE,MAAM,CAAA;IACrB,mGAAmG;IACnG,SAAS,EAAE,MAAM,CAAA;IACjB,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,iBAAS,QAAQ,CAAC,EAChB,IAAI,EACJ,YAAY,EACZ,GAAG,EACH,GAAG,EACH,OAAO,EACP,UAAU,EACV,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,UAAU,EACV,SAAS,GACV,EAAE,aAAa,+BA+Kf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}