@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/item.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * A row in a list or a set: media, a text block, a value and trailing controls.
+ *
+ * **It is the row, and the list is the caller's.** That is the one decision worth
+ * making here, and it is a decision against making this a data-driven list. An
+ * Item renders one row and nothing about what encloses it, because the same row
+ * appears in a `<ul>`, in a definition list, in a card grid and in a table cell,
+ * and a Component that owned the list would have to own all four. A caller writes
+ * the list element its content actually is and puts rows in it; what they stop
+ * writing is the row.
+ *
+ * So a caller writes `<li><Item key={id} entry={row} /></li>` and gets a real list
+ * item, the count and the position in the accessibility tree, and a row whose
+ * geometry cannot drift from the row below it. The wrapper is one element, and
+ * the row is the part that was being re-derived in every list in this package.
+ *
+ * **The trailing controls are never the only route to the row.** `href` is a
+ * field on the row rather than something the actions have to carry, so the
+ * primary line is a real anchor a reader can tab to, see where it goes before
+ * taking it, and open in a new context. A row of forty with its only destination
+ * behind a kebab menu is a list a screen reader user cannot read, because the
+ * menu's contents are not in the document until the menu is open.
+ *
+ * **The title is not stretched over the whole row.** The obvious treatment for a
+ * clickable row is an anchor with `position: absolute; inset: 0` and the actions
+ * raised above it, which makes the entire row a hit target. It is refused for the
+ * focus indicator: the ring belongs to the anchor, and an anchor stretched over a
+ * row is a box that has sized itself to the text inside it, so the ring a keyboard
+ * reader sees is a ring around the words rather than around the thing they are
+ * about. Prism's rings are per element at full strength, and a ring that does not
+ * bound the thing it names is not an indicator.
+ *
+ * **The selected row is marked, not only tinted.** `aria-current` carries the
+ * state and the surface repeats it for a reader who reads by eye, which is the
+ * same order the whole package keeps meaning in: the attribute is the fact and
+ * the colour is the reminder.
+ *
+ * It is a server Component. It holds no state, runs no effect and attaches no
+ * handler, so a list of two hundred rows costs no JavaScript at all.
+ */
+function Item({ entry, className, ...props }) {
+    const { id, title, description, meta, href, media, actions, selected } = entry;
+    const hasActions = actions !== undefined && actions !== null && actions !== false;
+    return (_jsxs("div", { "data-slot": "item", "data-item": id, "data-selected": selected ? 'true' : undefined, "aria-current": selected ? 'true' : undefined, className: cn('flex items-center gap-3 px-3 py-2', 
+        // The row is only interactive when there is something to interact with, so
+        // the hover surface is conditional. A hover tint on a row that does
+        // nothing is a promise the row does not keep, and a reader learns to
+        // ignore the tint on every row in the list.
+        href === undefined ? '' : 'hover:bg-muted', selected ? 'bg-muted' : '', className), ...props, children: [media === undefined || media === null || media === false ? null : (
+            /*
+             * Media is left in the accessibility tree. An avatar and a thumbnail both
+             * carry information a row's text does not, and hiding the slot would make
+             * the caller's `alt` unreachable; a caller whose media really is
+             * decoration passes an `aria-hidden` image and decides that for itself,
+             * which is the only party that knows.
+             */
+            _jsx("div", { "data-slot": "item-media", className: "bg-muted flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-md [&_img]:size-full [&_img]:object-cover", children: media })), _jsxs("div", { "data-slot": "item-content", className: "flex min-w-0 flex-1 flex-col gap-0.5", children: [_jsx("span", { "data-slot": "item-title", className: "min-w-0 truncate text-sm font-medium", children: href === undefined ? (title) : (_jsx("a", { "data-slot": "item-link", href: href, className: cn('hover:underline focus-visible:ring-ring rounded-sm outline-none focus-visible:ring-[3px]'), children: title })) }), description === undefined || description === null || description === false ? null : (_jsx("span", { "data-slot": "item-description", className: "text-muted-foreground min-w-0 truncate text-sm", children: description }))] }), meta === undefined || meta === null || meta === false ? null : (_jsx("span", { "data-slot": "item-meta", className: "text-muted-foreground shrink-0 text-sm tabular-nums", children: meta })), hasActions ? (_jsx("div", { "data-slot": "item-actions", className: "flex shrink-0 items-center gap-1", children: actions })) : null] }));
+}
+export { Item };

package/dist/components/ui/kbd.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * An inline label for a keyboard key or shortcut.
  *

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

@@ -0,0 +1,58 @@
+import type { ComponentProps } from 'react';
+/** The props the Label accepts. */
+export interface LabelProps extends ComponentProps<'label'> {
+    /**
+     * Whether the control this label names has to be filled in.
+     *
+     * It draws a mark and it says nothing to a screen reader, because the control's
+     * own `required` is what is announced. A mark that were read out would reach a
+     * reader as the field's name followed by a glyph, which is a name with a
+     * decoration on the end of it, and it is the wrong place for a requirement: the
+     * requirement is enforced by the control and reported by it.
+     *
+     * Put `required` on the control as well as here. This prop is what the reader
+     * can see; that one is what the form enforces.
+     */
+    required?: boolean;
+    /**
+     * The mark that shows a required field.
+     *
+     * A default rather than a fixed character, because the convention is the
+     * reader's: an asterisk, a word, a dagger, nothing at all and a note in the
+     * legend instead. A Component that chose one would ship one locale's convention
+     * into every consumer's product.
+     */
+    requiredText?: string;
+    /**
+     * Whether the control this label names is unavailable.
+     *
+     * The label dims with the control rather than staying at full strength, because
+     * a label at full strength over a greyed field reads as a field that has merely
+     * been styled. It is a statement about the field the reader is looking at, and
+     * the two states should not disagree.
+     */
+    disabled?: boolean;
+}
+/**
+ * The accessible name of a control, on its own.
+ *
+ * **`FieldLabel` is this, inside a field.** A label is needed wherever a control
+ * is, and a form binding is one place: a dialog's single input, a table's filter
+ * row, a settings line that has no group around it because there is nothing to
+ * group. `FieldLabel` draws the same thing and is the right choice beside a
+ * `Field`; this is the right choice when there is no field, and taking the field
+ * apart to get at its label would be rearranging a layout to reach one element of
+ * it.
+ *
+ * **It is a native `<label>` and the association is programmatic.** Pass the
+ * control's `id` as `htmlFor` so the name is attached rather than merely adjacent,
+ * because adjacent text is not a name: it is read by nobody when the reader tabs
+ * to the control, and a visible label with no `for` is a caption.
+ *
+ * **It is a server Component.** It reads props and renders, so a form built from
+ * it costs no client JavaScript for its labels, and that is most of what a form
+ * is.
+ */
+declare function Label({ className, required, requiredText, disabled, children, ...props }: LabelProps): import("react").JSX.Element;
+export { Label };
+//# sourceMappingURL=label.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../../src/components/ui/label.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C,mCAAmC;AACnC,MAAM,WAAW,UAAW,SAAQ,cAAc,CAAC,OAAO,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,QAAgB,EAChB,YAAkB,EAClB,QAAgB,EAChB,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,UAAU,+BAuBZ;AAED,OAAO,EAAE,KAAK,EAAE,CAAA"}

package/dist/components/ui/label.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The accessible name of a control, on its own.
+ *
+ * **`FieldLabel` is this, inside a field.** A label is needed wherever a control
+ * is, and a form binding is one place: a dialog's single input, a table's filter
+ * row, a settings line that has no group around it because there is nothing to
+ * group. `FieldLabel` draws the same thing and is the right choice beside a
+ * `Field`; this is the right choice when there is no field, and taking the field
+ * apart to get at its label would be rearranging a layout to reach one element of
+ * it.
+ *
+ * **It is a native `<label>` and the association is programmatic.** Pass the
+ * control's `id` as `htmlFor` so the name is attached rather than merely adjacent,
+ * because adjacent text is not a name: it is read by nobody when the reader tabs
+ * to the control, and a visible label with no `for` is a caption.
+ *
+ * **It is a server Component.** It reads props and renders, so a form built from
+ * it costs no client JavaScript for its labels, and that is most of what a form
+ * is.
+ */
+function Label({ className, required = false, requiredText = '*', disabled = false, children, ...props }) {
+    return (_jsxs("label", { "data-slot": "label", "data-required": required || undefined, "data-disabled": disabled || undefined, className: cn('text-foreground text-sm leading-none font-medium', 
+        // No fill of its own, so there is no ink of its own to state: the label
+        // inherits whatever the surface it sits on already uses.
+        disabled && 'text-muted-foreground', className), ...props, children: [children, required ? (_jsx("span", { "data-slot": "label-required", "aria-hidden": "true", className: "text-destructive ms-1", children: requiredText })) : null] }));
+}
+export { Label };

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