@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/components/ui/intensity-grid.js

@@ -0,0 +1,211 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The fill each step is drawn in, from the contract's roles and no other.
+ *
+ * The same five entries `ContributionGraph` draws from, spelled here because that
+ * module keeps its maps to itself, and the honest cost is the one it states: a
+ * change to the intensity scale is two edits rather than one. What keeps the
+ * restatement from drifting is the annotation, because both maps are typed
+ * `Record<IntensityLevel, string>`, so a sixth step would be a type error at the
+ * map rather than a cell that silently falls through to no ink.
+ *
+ * Step zero is the `muted` surface rather than a pale primary, so "nothing here" is
+ * visibly a different thing from "a little here". The other four are the same
+ * `primary` role at four alpha steps, which is one token at four strengths: a ramp
+ * of five authored colours would have been a second set of colour tokens for a
+ * scale the alpha modifier already expresses, and it would not have moved with a
+ * scoped pack boundary the way an alpha step on one semantic role does.
+ */
+const LEVEL_FILL = {
+    0: 'bg-muted',
+    1: 'bg-primary/25',
+    2: 'bg-primary/50',
+    3: 'bg-primary/75',
+    4: 'bg-primary',
+};
+/**
+ * A cell's share of the largest value drawn, as a percentage of it.
+ *
+ * A non-finite value is zero rather than `NaN`, because a value that went missing
+ * is data that is wrong and not a value that is small, and letting it into the
+ * maximum would stretch the scale around every other cell in the grid. It is drawn
+ * as the empty cell and named like any other, so a bad reading looks like nothing
+ * rather than like everything, which is the one way this Component can be wrong
+ * without saying so.
+ */
+function shareOf(value, max) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (max <= 0)
+        return 0;
+    return (value / max) * 100;
+}
+/**
+ * A matrix of two categorical axes, drawn as cells under one sequential scale.
+ *
+ * **Neither axis is a scale, and that is the whole difference from `Chart`.** A
+ * chart places a mark at a position on a continuous domain and a cell has no
+ * position: "Kiln Wharf in March" is not half way between anything, so there is no
+ * horizontal scale to draw and no vertical one to read, and `Chart`'s `mark` prop
+ * cannot type it because a mark is a way of drawing a position. So this Component
+ * draws no axis, ticks nothing, and derives its scale from the values rather than
+ * from a range the caller states. Everything below is a consequence of that rather
+ * than a preference.
+ *
+ * **What it is for, and how it differs from `ContributionGraph`.** Both draw a grid
+ * of cells filled by intensity, and the resemblance is close enough to be worth
+ * being exact about. A ContributionGraph is a calendar: its rows are the seven
+ * days, its columns are the weeks, and it works both out from the dates it was
+ * given, so a caller passes days and gets a window. This Component is two sets of
+ * categories the caller already holds, and it has no calendar, no window, no window
+ * arithmetic and no date key. Four differences follow, each from that one:
+ *
+ *   1. **The axes are named by the caller.** A month and an estate are not seven
+ *      days and a week, and there is no rule here that generates them.
+ *   2. **A pair with no cell is legal and is the common case.** A calendar has a
+ *      cell for every day in its window, so an unreported day is the interesting
+ *      state there. A matrix owes no completeness, so an absent pair is ordinary
+ *      and draws as the empty cell.
+ *   3. **The drawing is symmetric and the reading is not.** A calendar is read by
+ *      scanning a column, which is why its caller may choose which day each row
+ *      starts on. Here the row is the header and the column is the reading order,
+ *      so there is no `weekStartsOn` to pass because there is no week to start.
+ *   4. **The bands are the caller's and a calendar's are not.** `ContributionGraph`
+ *      grades against the largest count in the window because a count of commits is
+ *      a count of commits. Here the measure is unknown to Prism, so the bands are
+ *      required, and that is the difference a reader of this file is most likely to
+ *      get wrong.
+ *
+ * **The scale is derived, a band's meaning is not, and the gap between them is the
+ * honest cost.** Prism works out the largest value in the grid and reads every
+ * cell as a share of it, so the caller passes magnitudes and divides nothing. It
+ * cannot do the other half: it cannot see that forty findings on one estate is a
+ * crisis and the same forty on another is Tuesday, so `bands` is required and its
+ * entries are the caller's judgement about what each band means. **Prism cannot
+ * verify that the caller's scale is sequential.** A caller who passes a diverging
+ * scale, a categorical one, or values normalised into a range of their own
+ * invention gets a grid that reads as intensity and is not one, and nothing in the
+ * rendered output says so: there is no key, because a key would assert an ordering
+ * this Component has no way to check. The caller who wants one composes it from the
+ * same `bands` array the cells were graded with, which is why that array is data
+ * and not a callback.
+ *
+ * **The shade is redundant and never the only channel, and there is no printed
+ * number.** Every cell is a picture of a measurement and is named by `cellLabel`, so
+ * the value is spoken in the caller's own words. What Prism refuses is the other
+ * half of that sentence: a printed value in every cell. A matrix of forty cells
+ * with a number in each is a table with shading on it, and the shading is the
+ * channel the reader cannot scan, so the numbers would be covering the reason the
+ * figure exists. The cost is real, and it is the reason `CohortGrid` is a different
+ * Item: a reader who cannot rank five shades has no route to the value here at all,
+ * which is the right trade for a matrix scanned at a glance and the wrong one for a
+ * retention table read cell by cell.
+ *
+ * **A value outside the scale is clamped and counted, not thrown.** A cell above
+ * the largest value cannot exist, since the largest value sets the top, and a value
+ * below zero is a diverging measure rather than an intensity. Both are drawn at the
+ * floor or the ceiling of the scale and counted on the element as `data-clamped`,
+ * which is the arrangement `Chart` uses for a value past the end of its axis, and
+ * the count is what makes an under-specified scale visible to the caller who wrote
+ * it. `table` is the Component for a measure whose middle means something.
+ *
+ * **Four inputs throw, and a drawn lie is worse than a refusal.** No rows, no
+ * columns or no cells is a frame carrying no claim, a cell naming an axis that was
+ * not given is a measurement with nowhere to go, and two cells in one place is one
+ * measurement drawn over another with the earlier one left in the data and out of
+ * the picture. Each is a bug in the caller's code rather than a state a reader
+ * reaches, and each is reported in a console where the caller will see it. A cell
+ * whose value is not a finite number is the exception and is deliberately not one of
+ * the four: it draws as the empty cell, because a cell that says nothing and a cell
+ * whose number went missing look the same and no gate can tell them apart.
+ *
+ * **Nothing here moves, and the reason is the shade.** A hover state on a cell has
+ * to change something about the cell, and everything available is a change to the
+ * value: a wash behind it changes what the fill composites against, which is the
+ * measurement, and a border on one cell changes its neighbours' widths by a pixel.
+ * So the figure is static by construction rather than by restraint, which is also
+ * the cheapest way to satisfy a motion law that permits only state feedback.
+ *
+ * **It is a server Component, and `cellLabel` does not make it a client one.** A
+ * function prop is only a problem when it has to cross a boundary to be called, and
+ * this one never does: it is called during the render that received it, on the
+ * server, by this Component. That is the arrangement `ContributionGraph` ships and
+ * the reason its Demo is a server module too. The one consequence a caller has to
+ * know is that the function has to be written where the grid is rendered, so a grid
+ * inside an interactive panel must be composed inside that panel's own client tree,
+ * which is the price of a matrix that costs no client code at all.
+ */
+function IntensityGrid({ className, rows, columns, cells, label, cellLabel, bands, ...props }) {
+    if (rows.length === 0 || columns.length === 0 || cells.length === 0) {
+        throw new Error('IntensityGrid: one of rows, columns or cells is empty, so the figure is a frame with nothing in ' +
+            'it. A matrix needs at least one row, at least one column and one cell, and its axes are the ' +
+            "caller own categories rather than anything this Component generates. Pass the measurements you " +
+            'have; an axis with nothing in it is a query that did not come back.');
+    }
+    const placed = cells.map((cell) => {
+        const row = rows.find((entry) => entry.key === cell.rowKey);
+        const column = columns.find((entry) => entry.key === cell.columnKey);
+        if (row === undefined || column === undefined) {
+            throw new Error(`IntensityGrid: a cell names the row '${cell.rowKey}' and the column '${cell.columnKey}', and ` +
+                'one of them is not among the rows and columns you gave. A cell with nowhere to sit is a ' +
+                'measurement nobody would ever see, so this stops rather than dropping it and leaving you to ' +
+                'believe the whole matrix was drawn.');
+        }
+        return { cell, row, column };
+    });
+    /*
+     * Nested rather than keyed on a joined string, because a caller's keys are its
+     * own and a row key of `Kiln Wharf` beside a column key of `March` collides with
+     * a row of `Kiln` beside a column of `Wharf March`. A matrix is a table keyed on
+     * two columns, and keying it on one string is a bug waiting for the first caller
+     * whose keys contain spaces.
+     */
+    const byRow = new Map();
+    for (const entry of placed) {
+        const forRow = byRow.get(entry.cell.rowKey);
+        if (forRow === undefined) {
+            byRow.set(entry.cell.rowKey, new Map([[entry.cell.columnKey, entry]]));
+            continue;
+        }
+        if (forRow.has(entry.cell.columnKey)) {
+            throw new Error(`IntensityGrid: the row '${entry.cell.rowKey}' and the column '${entry.cell.columnKey}' have ` +
+                'more than one cell. A matrix has one measurement per pair, and drawing the last of them would ' +
+                'leave the earlier one in the data and out of the picture with nothing saying so. Combine them ' +
+                'into the one cell that pair should carry.');
+        }
+        forRow.set(entry.cell.columnKey, entry);
+    }
+    const max = placed.reduce((tallest, entry) => Number.isFinite(entry.cell.value) && entry.cell.value > tallest ? entry.cell.value : tallest, 0);
+    return (_jsxs("figure", { "data-slot": "intensity-grid", "data-rows": rows.length, "data-columns": columns.length, "aria-label": label, className: cn('flex w-full flex-col gap-1.5', className), ...props, children: [_jsxs("div", { "data-slot": "intensity-axis", className: "flex items-end gap-2", children: [_jsx("span", { "data-slot": "intensity-gutter", "aria-hidden": "true", className: "w-32 shrink-0" }), columns.map((column) => (_jsx("span", { "data-slot": "intensity-column", className: "text-muted-foreground min-w-0 flex-1 truncate text-center text-xs", children: column.label }, column.key)))] }), rows.map((row) => (_jsxs("div", { "data-slot": "intensity-row", className: "flex items-center gap-2", children: [_jsx("span", { "data-slot": "intensity-row-label", className: "w-32 shrink-0 truncate text-xs font-medium", children: row.label }), columns.map((column) => {
+                        const found = byRow.get(row.key)?.get(column.key);
+                        if (found === undefined) {
+                            /*
+                              A pair with no cell. Hidden from assistive technology because there
+                              is nothing to name: an absence is not a zero and not a row, and the
+                              same rule `ContributionGraph` applies to a day nobody reported.
+                            */
+                            return (_jsx("span", { "data-slot": "intensity-cell", "data-row": row.key, "data-column": column.key, "data-state": "absent", "aria-hidden": "true", className: cn('h-6 min-w-0 flex-1 rounded-sm', LEVEL_FILL[0]) }, column.key));
+                        }
+                        const { cell } = found;
+                        const share = shareOf(cell.value, max);
+                        const held = Math.min(100, Math.max(0, share));
+                        // Read in the order the bands were given, and the first one containing
+                        // the share wins, so a caller with an overlapping scale says which band
+                        // takes precedence by saying it first.
+                        const band = bands.find((entry) => held >= entry.from && held <= entry.to);
+                        const level = band?.level ?? 0;
+                        return (_jsx("span", { "data-slot": "intensity-cell", "data-row": row.key, "data-column": column.key, "data-level": level, "data-state": band === undefined ? 'ungraded' : undefined, "data-clamped": held === share ? undefined : 'true', 
+                            /*
+                              A cell is a picture of a measurement rather than text, so it takes
+                              the image role and the caller's own sentence for it. That name is
+                              the redundant channel over the shade. An ungraded cell keeps its
+                              name, so a reader hears the number and sees the absence, which is
+                              the honest pair: the caller's scale does not cover this cell and
+                              the drawing says so rather than substituting a step that means
+                              something else.
+                            */
+                            role: "img", "aria-label": cellLabel({ cell, row, column }), className: cn('h-6 min-w-0 flex-1 rounded-sm', LEVEL_FILL[level]) }, column.key));
+                    })] }, row.key)))] }));
+}
+export { IntensityGrid };

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