@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,99 @@
+import type { ComponentProps, ReactNode } from 'react';
+/**
+ * The five tones a Status's dot can take.
+ *
+ * A tone is a judgement the caller makes, and this Component has the same reason
+ * `MeterTone` gives for holding the same judgement at arm's length: it can see
+ * the state, and it cannot see whether the state is urgent. A Status is asked
+ * for far more often than a Meter is, and for smaller things, which is exactly
+ * the case where a Component that coloured itself would be making a claim about
+ * the caller's product with the least evidence. A deploy is `info` on a status
+ * page and `success` in a release note; a disk is `warning` at 80 percent and
+ * `destructive` at 95, and the number does not know which of the two the
+ * consumer is looking at.
+ *
+ * **The set is the semantic contract's, and the JSDoc has to say what that
+ * costs.** The contract publishes three state roles, `success`, `warning` and
+ * `destructive`, and it publishes no informational one, so `info` here borrows
+ * `brand-ink`, which is the only cool role in the contract that means "not an
+ * alarm". The cost is named rather than hidden: in a pack whose brand hue is also
+ * its emphasis hue, an `info` dot and an emphasised mark are the same colour. The
+ * alternative was a fourth state role in the token contract, which is a
+ * decision about the tokens rather than about a Component, and a Component that
+ * invented the role would have had a second source of truth for colour. The
+ * other alternative, dropping `info` from the set, would have made the ordinary
+ * states of a product, in progress, scheduled, degraded, unreachable, expressible
+ * only as `neutral` and `warning`, which are both wrong.
+ *
+ * `neutral` is the tone for a state with nothing to alarm about, and it is drawn
+ * in the muted foreground rather than the full ink. A dot in the foreground
+ * colour reads as an emphasis mark rather than as a state, and a row of neutral
+ * states is a row of things the reader should look at.
+ */
+export type StatusTone = 'neutral' | 'info' | 'success' | 'warning' | 'destructive';
+/**
+ * A dot in one of five tones, and the caller's words beside it.
+ *
+ * **The dot is the tone and the label is the caller's.** The split is the whole
+ * design. A Component that knew what the words were would be a Component making
+ * a claim about a product it knows nothing about, so it takes the tone and the
+ * caller takes the sentence, and neither one can be derived from the other
+ * without a lie.
+ *
+ * **The label is required, and the reason is the colour.** A status with no words
+ * is a coloured dot, and a coloured dot is invisible to a reader who cannot
+ * separate the tones and unreadable to a screen reader whatever the tones are.
+ * There is a Component for the other half of that idea, an indicator that is
+ * decorative beside a state the surrounding sentence already names, and it is a
+ * different Item because a name it did not receive is a name the consumer has to
+ * supply. This one refuses to render unlabelled rather than rendering something
+ * every consumer inherits.
+ *
+ * **The tone is required rather than defaulted.** There is no `neutral` default
+ * for the same reason `MeterTone` states, and this Component inherits that
+ * argument in full: a tone is a judgement about urgency that only the caller can
+ * make, and a Component that picked one would be picking it for four products at
+ * once. A default here is the quietest way to ship a claim, because it looks
+ * like a convenience and behaves like an opinion.
+ *
+ * **The tone is never the only signal.** Every dot here is `aria-hidden` and the
+ * label carries the meaning, so a reader who cannot separate `warning` from
+ * `destructive` still reads which is which. That is also why the tone list can
+ * stay as small as it is: a wider list would be a wider set of colours a reader
+ * has to learn and a maintainer has to keep true, and the words are what make
+ * each one legible. The cost is stated rather than hidden: `warning` is amber and
+ * measures about 2.1:1 against the default pack's light background, so on a light
+ * surface that one dot is a tint rather than a mark. The label beside it is what
+ * carries the state, which is the trade this design makes everywhere.
+ *
+ * It is a server Component: no hook, no state, and a status that changes is
+ * something the surrounding surface re-renders, not something this Component
+ * animates.
+ */
+declare function Status({ className, tone, label, size, ...props }: {
+    /**
+     * Which of the five tones the dot takes. Required rather than defaulted, for
+     * the reason `StatusTone` states in full.
+     */
+    tone: StatusTone;
+    /**
+     * The words naming the state, in the product's own vocabulary.
+     *
+     * Required, and deliberately not derived from `tone`: a product that says
+     * "Degraded" and a product that says "Partially unavailable" are both
+     * describing the same tone, and neither word is Prism's to choose.
+     */
+    label: ReactNode;
+    /**
+     * The size of the dot and of the label together. @defaultValue 'md'
+     *
+     * Two steps and not one, because a status appears at two scales in practice: in
+     * a dense table row, where a `md` dot competes with the numbers beside it, and
+     * beside a heading, where `sm` is hard to find. Sizing the pair together is
+     * deliberate, because a small dot beside a large label is a status the reader
+     * is meant to read rather than one they are meant to spot.
+     */
+    size?: 'sm' | 'md';
+} & Omit<ComponentProps<'span'>, 'children'>): import("react").JSX.Element;
+export { Status };
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/components/ui/status.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAuBnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,IAAI,EACJ,KAAK,EACL,IAAW,EACX,GAAG,KAAK,EACT,EAAE;IACD;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;CACnB,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,+BAiB3C;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/status.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/** The dot each tone is drawn in, from the semantic roles and no other. */
+const TONE_DOT = {
+    neutral: 'bg-muted-foreground',
+    info: 'bg-brand-ink',
+    success: 'bg-success',
+    warning: 'bg-warning',
+    destructive: 'bg-destructive',
+};
+/** The dot's diameter, per size, as an authored `size-*` step. */
+const SIZE_DOT = {
+    sm: 'size-1.5',
+    md: 'size-2',
+};
+/** The label's type-scale step, per size, because the pair is sized together. */
+const SIZE_LABEL = {
+    sm: 'text-xs',
+    md: 'text-sm',
+};
+/**
+ * A dot in one of five tones, and the caller's words beside it.
+ *
+ * **The dot is the tone and the label is the caller's.** The split is the whole
+ * design. A Component that knew what the words were would be a Component making
+ * a claim about a product it knows nothing about, so it takes the tone and the
+ * caller takes the sentence, and neither one can be derived from the other
+ * without a lie.
+ *
+ * **The label is required, and the reason is the colour.** A status with no words
+ * is a coloured dot, and a coloured dot is invisible to a reader who cannot
+ * separate the tones and unreadable to a screen reader whatever the tones are.
+ * There is a Component for the other half of that idea, an indicator that is
+ * decorative beside a state the surrounding sentence already names, and it is a
+ * different Item because a name it did not receive is a name the consumer has to
+ * supply. This one refuses to render unlabelled rather than rendering something
+ * every consumer inherits.
+ *
+ * **The tone is required rather than defaulted.** There is no `neutral` default
+ * for the same reason `MeterTone` states, and this Component inherits that
+ * argument in full: a tone is a judgement about urgency that only the caller can
+ * make, and a Component that picked one would be picking it for four products at
+ * once. A default here is the quietest way to ship a claim, because it looks
+ * like a convenience and behaves like an opinion.
+ *
+ * **The tone is never the only signal.** Every dot here is `aria-hidden` and the
+ * label carries the meaning, so a reader who cannot separate `warning` from
+ * `destructive` still reads which is which. That is also why the tone list can
+ * stay as small as it is: a wider list would be a wider set of colours a reader
+ * has to learn and a maintainer has to keep true, and the words are what make
+ * each one legible. The cost is stated rather than hidden: `warning` is amber and
+ * measures about 2.1:1 against the default pack's light background, so on a light
+ * surface that one dot is a tint rather than a mark. The label beside it is what
+ * carries the state, which is the trade this design makes everywhere.
+ *
+ * It is a server Component: no hook, no state, and a status that changes is
+ * something the surrounding surface re-renders, not something this Component
+ * animates.
+ */
+function Status({ className, tone, label, size = 'md', ...props }) {
+    return (_jsxs("span", { "data-slot": "status", className: cn('inline-flex max-w-full items-center gap-1.5', className), ...props, children: [_jsx("span", { "data-slot": "status-dot", "aria-hidden": "true", className: cn('shrink-0 rounded-full', SIZE_DOT[size], TONE_DOT[tone]) }), _jsx("span", { "data-slot": "status-label", className: SIZE_LABEL[size], children: label })] }));
+}
+export { Status };

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

@@ -0,0 +1,155 @@
+/**
+ * The props the Stepper accepts.
+ *
+ * A declared interface rather than a forwarded native one. There is no element
+ * here to forward to, because the Component draws a group of two controls and
+ * owns the bounds both of them read, and a forwarded `onChange` would be a second
+ * way to say what a press does.
+ */
+export interface StepperProps {
+    /**
+     * The value both controls move.
+     *
+     * Required, and a number rather than `number | null`. An empty value is a value
+     * `NumberField` reports, because a typed scalar has to be able to say "nothing
+     * yet". A pair of controls has nothing to step from: pressing a control on an
+     * empty field would have to invent the first value, and a Component that
+     * invents one is a Component that has guessed the caller's unit. A caller whose
+     * quantity starts empty holds nothing, and reaches for `NumberField`.
+     */
+    value: number;
+    /**
+     * Called with the value a press produced.
+     *
+     * Required, and controlled: the Component holds no value of its own, because a
+     * value held inside a control and a value held by the caller are two numbers
+     * that disagree the moment a second control reads the same one. The pair here
+     * and the `NumberField` beside it are the ordinary case of exactly that.
+     */
+    onValueChange: (value: number) => void;
+    /**
+     * The accessible name of the joined pair.
+     *
+     * Required, and it names the pair rather than either half: a screen reader
+     * announces the group first, so "Quantity" is what tells the reader which of the
+     * two controls they are in before either of them speaks.
+     */
+    label: string;
+    /**
+     * The accessible names of the two controls.
+     *
+     * Required as a pair, and the words are the caller's because a stepper's
+     * controls are icons and an icon has no name. "Increase the number of seats",
+     * "Decrease the monthly budget". Prism would get "increase" right for a
+     * quantity and wrong for at least one of every four products that install it.
+     */
+    labels: {
+        increment: string;
+        decrement: string;
+    };
+    /**
+     * The smallest value the pair will hold.
+     *
+     * A press below it is refused and the decrement draws itself unavailable, which
+     * are two answers to one question: the value never leaves the range, and the
+     * reader is told where the range is rather than discovering it by pressing.
+     * Without a minimum there is no boundary for the pair to report, so this and
+     * `max` are what turn two buttons into a control over a range.
+     */
+    min?: number;
+    /** The largest value the pair will hold. The same contract as `min`. */
+    max?: number;
+    /**
+     * The amount one press changes the value by. @defaultValue 1
+     *
+     * A step of zero is refused by being a no-op rather than by a diagnostic,
+     * because a zero step is a caller's arithmetic mistake rather than a claim this
+     * Component would be making on the caller's behalf, and a control that does
+     * nothing is already the answer to it.
+     */
+    step?: number;
+    /**
+     * Whether the pair ignores interaction.
+     *
+     * Set natively on both controls, and the reason is the frame rather than a
+     * preference. `ButtonGroup` draws the joined shape by suppressing each child's
+     * own ring and squaring each child's corners, which leaves no place between the
+     * group and the control to put a wrapper that could draw an unavailable state
+     * without breaking the join. So the state is the native one, and the cost of
+     * that choice is stated on the Component.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the value may be read but not moved.
+     *
+     * Refuses both controls rather than one, because a half-stepper over a value
+     * nobody may change is a control with a live half and a dead half, and the
+     * reader has no way to tell which half is the wrong one.
+     */
+    readOnly?: boolean;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+}
+/**
+ * An increment and a decrement joined as one control, both of them holding the
+ * same range.
+ *
+ * **Two controls that must agree, and the agreement is the Component.** A caller
+ * who composes two `Button`s gets two controls that know nothing about each other:
+ * one clamps and one does not, or both clamp against different bounds, or the
+ * increment is drawn as available one render after the value reaches the maximum.
+ * The bounds here are two props read once by both controls and by the handler
+ * that computes the next value, so the two halves cannot drift: there is no
+ * second place for a bound to be written.
+ *
+ * **At a boundary the control draws itself unavailable rather than doing nothing
+ * silently, and that is the difference between a stepper and two buttons.** A
+ * press that quietly fails is the worst outcome available to a control: the
+ * reader has pressed something, the page has not changed, and nothing has said
+ * why. So the half that has reached its bound is visibly dimmed and is no longer
+ * in the tab order, and the reader learns the range from the shape of the control
+ * rather than from an error. **The cost is stated rather than smoothed over: a
+ * natively disabled control leaves the tab order**, so a stepper sitting at its
+ * maximum is one tab stop rather than two. Here that is the right trade and not a
+ * compromise, because the only way the value moves is the other half or the
+ * caller's own field, so a tab stop on the spent half could tell a reader
+ * something and could not let them do anything with it.
+ *
+ * **The wrapper that would let the pair draw an unavailable state does not exist,
+ * and the reason is the composition.** `TextFormatToolbar` dims a command by
+ * putting the surface on a wrapper span it owns, because that Component draws its
+ * own frame and has room for one. `ButtonGroup` draws this frame instead, and it
+ * draws it by suppressing each child's own ring and squaring each child's corners,
+ * so anything placed between the group and a control would either lose the join or
+ * clip the corners Prism just squared. That is why `disabled` goes to the native
+ * attribute here and the JSDoc on `disabled` says so: the state had to be the
+ * native one or the shape would have gone.
+ *
+ * **The pair clamps and does not snap to the step grid, and that is a decision
+ * about whose number it is.** A value that is already off the grid, `7` against a
+ * `min` of `0` and a `step` of `5`, moves to `10` and not to `5`. Snapping would
+ * mean the first press rewrites a number the reader did not touch, which is the
+ * same defect `NumberField` avoids by moving from wherever the value is. The cost
+ * is that a value can sit off the grid indefinitely, and a caller who needs the
+ * grid enforced validates it in their own submit handler.
+ *
+ * **It is `number-field`'s pair and not `number-field`, and the difference is
+ * where the value is typed.** `NumberField` is a typed scalar: it holds the
+ * value in an input, the reader can write it, and its two steppers are a
+ * secondary route to a number they are not the only way to reach. This is the
+ * paired affordance on its own, for a value the caller displays in its own terms:
+ * a quantity in a cart line, a count in a table cell, an amount whose unit only
+ * the caller knows. The honest cost of that split is that this Component cannot
+ * show the value it is changing, because a number without a unit is a guess, so a
+ * caller who wants the figure beside the pair draws it themselves. A caller who
+ * wants one control to hold the figure and the pair composes `NumberField`, whose
+ * steppers are already inside its own frame.
+ *
+ * **It is a client Component** because both controls call back and the clamps run
+ * in the press. What that costs is the price of every interactive control: a
+ * static page cannot render a stepper at all, which is correct, because a stepper
+ * is a control and a control that cannot be pressed is a picture of one.
+ */
+declare function Stepper({ value, onValueChange, label, labels, min, max, step, disabled, readOnly, className, }: StepperProps): import("react").JSX.Element;
+export { Stepper };
+//# sourceMappingURL=stepper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.d.ts","sourceRoot":"","sources":["../../../src/components/ui/stepper.tsx"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAChD;;;;;;;;OAQG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,iBAAS,OAAO,CAAC,EACf,KAAK,EACL,aAAa,EACb,KAAK,EACL,MAAM,EACN,GAAG,EACH,GAAG,EACH,IAAQ,EACR,QAAgB,EAChB,QAAgB,EAChB,SAAS,GACV,EAAE,YAAY,+BA2Cd;AAED,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/dist/components/ui/stepper.js

@@ -0,0 +1,83 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MinusIcon, PlusIcon } from 'lucide-react';
+import { Button } from './button.js';
+import { ButtonGroup } from './button-group.js';
+/**
+ * An increment and a decrement joined as one control, both of them holding the
+ * same range.
+ *
+ * **Two controls that must agree, and the agreement is the Component.** A caller
+ * who composes two `Button`s gets two controls that know nothing about each other:
+ * one clamps and one does not, or both clamp against different bounds, or the
+ * increment is drawn as available one render after the value reaches the maximum.
+ * The bounds here are two props read once by both controls and by the handler
+ * that computes the next value, so the two halves cannot drift: there is no
+ * second place for a bound to be written.
+ *
+ * **At a boundary the control draws itself unavailable rather than doing nothing
+ * silently, and that is the difference between a stepper and two buttons.** A
+ * press that quietly fails is the worst outcome available to a control: the
+ * reader has pressed something, the page has not changed, and nothing has said
+ * why. So the half that has reached its bound is visibly dimmed and is no longer
+ * in the tab order, and the reader learns the range from the shape of the control
+ * rather than from an error. **The cost is stated rather than smoothed over: a
+ * natively disabled control leaves the tab order**, so a stepper sitting at its
+ * maximum is one tab stop rather than two. Here that is the right trade and not a
+ * compromise, because the only way the value moves is the other half or the
+ * caller's own field, so a tab stop on the spent half could tell a reader
+ * something and could not let them do anything with it.
+ *
+ * **The wrapper that would let the pair draw an unavailable state does not exist,
+ * and the reason is the composition.** `TextFormatToolbar` dims a command by
+ * putting the surface on a wrapper span it owns, because that Component draws its
+ * own frame and has room for one. `ButtonGroup` draws this frame instead, and it
+ * draws it by suppressing each child's own ring and squaring each child's corners,
+ * so anything placed between the group and a control would either lose the join or
+ * clip the corners Prism just squared. That is why `disabled` goes to the native
+ * attribute here and the JSDoc on `disabled` says so: the state had to be the
+ * native one or the shape would have gone.
+ *
+ * **The pair clamps and does not snap to the step grid, and that is a decision
+ * about whose number it is.** A value that is already off the grid, `7` against a
+ * `min` of `0` and a `step` of `5`, moves to `10` and not to `5`. Snapping would
+ * mean the first press rewrites a number the reader did not touch, which is the
+ * same defect `NumberField` avoids by moving from wherever the value is. The cost
+ * is that a value can sit off the grid indefinitely, and a caller who needs the
+ * grid enforced validates it in their own submit handler.
+ *
+ * **It is `number-field`'s pair and not `number-field`, and the difference is
+ * where the value is typed.** `NumberField` is a typed scalar: it holds the
+ * value in an input, the reader can write it, and its two steppers are a
+ * secondary route to a number they are not the only way to reach. This is the
+ * paired affordance on its own, for a value the caller displays in its own terms:
+ * a quantity in a cart line, a count in a table cell, an amount whose unit only
+ * the caller knows. The honest cost of that split is that this Component cannot
+ * show the value it is changing, because a number without a unit is a guess, so a
+ * caller who wants the figure beside the pair draws it themselves. A caller who
+ * wants one control to hold the figure and the pair composes `NumberField`, whose
+ * steppers are already inside its own frame.
+ *
+ * **It is a client Component** because both controls call back and the clamps run
+ * in the press. What that costs is the price of every interactive control: a
+ * static page cannot render a stepper at all, which is correct, because a stepper
+ * is a control and a control that cannot be pressed is a picture of one.
+ */
+function Stepper({ value, onValueChange, label, labels, min, max, step = 1, disabled = false, readOnly = false, className, }) {
+    const atMin = typeof min === 'number' && value <= min;
+    const atMax = typeof max === 'number' && value >= max;
+    // One clamp, read by both halves. A pair with two clamps is a pair with two
+    // answers, and which of them ran is invisible to the reader and to the caller.
+    const move = (direction) => {
+        const next = value + step * direction;
+        let out = next;
+        if (typeof min === 'number' && out < min)
+            out = min;
+        if (typeof max === 'number' && out > max)
+            out = max;
+        onValueChange(out);
+    };
+    const unavailable = disabled || readOnly;
+    return (_jsxs(ButtonGroup, { className: className, label: label, children: [_jsx(Button, { "data-slot": "stepper-decrement", type: "button", variant: "outline", size: "icon", disabled: unavailable || atMin, onClick: () => move(-1), "aria-label": labels.decrement, children: _jsx(MinusIcon, { "aria-hidden": "true" }) }), _jsx(Button, { "data-slot": "stepper-increment", type: "button", variant: "outline", size: "icon", disabled: unavailable || atMax, onClick: () => move(1), "aria-label": labels.increment, children: _jsx(PlusIcon, { "aria-hidden": "true" }) })] }));
+}
+export { Stepper };

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

@@ -0,0 +1,141 @@
+/** Where a step stands relative to the one the reader is on. */
+type StepState = 'complete' | 'current' | 'upcoming';
+/**
+ * One step in a sequence.
+ *
+ * `label` is the step, in the caller's words: a short noun or verb phrase, the
+ * thing that is either done or not. `description` is the qualifier, and it is a
+ * separate field because the two answer different questions and have different
+ * readers. A label is what a reader scanning the rail is looking for, and it has
+ * to survive at the width a step gets in a six step row. A description is what a
+ * reader who has arrived at this step wants, and it can be a sentence. Putting
+ * both in one field means one of the two is truncated, and the one that is
+ * truncated is chosen by the width of the container rather than by the reader.
+ */
+export type Step = {
+    /** The step, in the caller's words. */
+    label: string;
+    /** The qualifier under the label, for a reader who has arrived here. */
+    description?: string;
+    /**
+     * This step's state, overriding the one derived from its index and `current`.
+     *
+     * Derived is the default and the override is the exception, in that order,
+     * because the derived answer is the one that cannot disagree with `current`.
+     * Read the reasoning on `Steps` before passing one; the short version is that
+     * an override is a second source of truth about a position, and a second
+     * source of truth is what the rest of this package is organised to avoid.
+     */
+    state?: StepState;
+};
+/** The props the Steps accepts. */
+export interface StepsProps {
+    /**
+     * The sequence, in order. The order is the claim: a reader who is told these
+     * are steps is told there is a route through them, so a list passed in an
+     * order the process does not have is a wrong diagram rather than a layout
+     * problem.
+     */
+    steps: readonly Step[];
+    /**
+     * The index of the step the reader is on, zero based.
+     *
+     * Required and clamped rather than optional, because a sequence with no
+     * position is a list and a list is a different Component. The clamp is what
+     * makes a caller's off-by-one harmless: a `current` past the end or below zero
+     * lands on the nearest real step rather than on nothing, and the alternative
+     * was a throw on a value that is only wrong by one.
+     */
+    current: number;
+    /**
+     * The name of the sequence, read over the rail.
+     *
+     * Optional, and the reason it is optional rather than required is that this
+     * Component's whole job is the position: `steps` and `current` are the two
+     * facts it cannot do without, and a rail that is one list among many on a
+     * page takes its name from the heading the caller has already put above it.
+     * A page with two rails that look alike is a page where a reader cannot tell
+     * which process they are in, and a checkout and an import both have four
+     * steps, so a caller with more than one on a page should pass it. A prop the
+     * rail cannot function without would have been the wrong shape here; a prop
+     * that removes a genuine ambiguity is the right one, so it is there and
+     * nothing on it depends.
+     */
+    label?: string;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * An ordered indicator of where a reader is in a sequence.
+ *
+ * **The state is derived from the index and `current`, and the derivation is the
+ * answer that cannot disagree.** A caller's `current` is one number and the
+ * states before and after it are consequences of it, so the three can never
+ * drift: move `current` and every mark moves with it, and there is no
+ * combination of `current` and `state` a caller can pass that says step one is
+ * behind them and step two is also behind them. That is not a convenience. The
+ * failure is invisible in review and visible only in use, on the screen where
+ * the reader is looking at a rail that says they have finished the thing they
+ * are doing, and there is no way for a reader to tell which of the two marks is
+ * the one to believe.
+ *
+ * **The override exists for a sequence that is not the process.** A checkout
+ * where a reviewer approved a line out of band, a migration where one stage was
+ * completed by hand last night, a form where the reader has already answered
+ * the question that step two would have asked. In those cases the position and
+ * the state are two different facts, and a derived mark would draw a claim the
+ * data contradicts. So `state` is a prop, and the cost of it is named: it is a
+ * second source of truth about a position, which is the thing this package is
+ * organised to avoid, so it is an override per step rather than a mode, and the
+ * derivation still decides every step the caller said nothing about. A caller
+ * that overrides everything has replaced the rule with their own and gained
+ * nothing but the type.
+ *
+ * **Exactly one step is current, and it is enforced rather than described.** Two
+ * steps marked current is a rail with two answers to "where am I", and no step
+ * marked current is a rail with none, which is the state a reader cannot act on
+ * at all. Both are checked against the resolved list rather than against the
+ * declaration, because the interesting case is neither of them directly: a
+ * caller who marks the step `current` points at as something else has removed
+ * the only mark that said where they were, and no declaration in the data
+ * mentions a current step at all. So the resolved states are counted and a count
+ * that is not one is a thrown diagnostic rather than a drawing. A derivation
+ * alone can never produce that count, so the diagnostic only ever fires on a
+ * caller's own declarations, which is the arrangement that keeps it a real
+ * signal rather than a nuisance.
+ *
+ * **The rule between the steps is the honest indicator, and the reason is that
+ * the alternatives restate the same fact.** A filled bar under every completed
+ * step says "this one is done" once per step, so a reader looking at a
+ * six step rail is given the same sentence six times and has to combine them
+ * themselves to learn the one thing they came for, which is how much is behind
+ * them. The connector carries that fact once and carries something the bars
+ * cannot: it measures the space between two stages, so it is the only element
+ * that shows the sequence has a length at all. It is filled up to the step the
+ * reader is on and empty after it, which is also why it is the element that
+ * makes a long sequence readable at a glance. A bar per step was rejected on
+ * that ground, and a number per step was rejected earlier, because a number is
+ * a count of where the reader is and not a measure of how far they have come.
+ *
+ * **`aria-current` goes on the current step and nowhere else, because a colour
+ * is not a position in a sequence.** It is the only attribute on the rail that
+ * states the position to a reader who cannot see the rail, and putting it
+ * anywhere else is a claim about a step that is not the one the reader is on.
+ * The three states are not announced, and that is deliberate rather than an
+ * omission: they are consequences of the position, so a reader moving by list
+ * item is already told "item two of six" and then "current", and from those two
+ * the states of the other five follow. Announcing them would mean this
+ * Component shipping the words "complete" and "upcoming" into every consumer's
+ * product, which is the same defect the copy gate holds the close button of a
+ * dialog for. The ordinal on each disc is the one thing that is hidden, and for
+ * the mirror of that reason: the list semantics already say which item this is,
+ * and a spoken number in front of every label is noise to a reader who is
+ * reading the steps rather than counting them.
+ *
+ * **It is a server Component.** No hook, no state, no effect, and the rail is
+ * arithmetic over props, so it costs a consumer nothing in client JavaScript and
+ * renders identically with scripting off, in a print stylesheet and to a crawler.
+ */
+declare function Steps({ steps, current, label, className }: StepsProps): import("react").JSX.Element;
+export { Steps };
+//# sourceMappingURL=steps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../src/components/ui/steps.tsx"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,KAAK,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IACtB;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,iBAAS,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,UAAU,+BA4G9D;AAED,OAAO,EAAE,KAAK,EAAE,CAAA"}