@nanisoft/prism-ui 0.13.0 → 0.15.0

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

package/dist/components/ui/steps.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The disc a step's mark is drawn in, one per state.
+ *
+ * The three states differ by shape before they differ by colour: a filled disc
+ * for a step that is done, an outlined one for the step the reader is on, and a
+ * filled muted one for a step ahead. That is the whole discipline behind a
+ * component that is read as feedback, and it is why the state is not a colour
+ * here either: a filled mint disc and a mint outline are the same picture
+ * narrowed to one channel, and a reader who cannot separate them is being told
+ * the same thing about two different steps.
+ */
+const MARKER = {
+    complete: 'bg-primary text-primary-foreground border-primary',
+    current: 'bg-background text-foreground border-primary',
+    upcoming: 'bg-muted text-muted-foreground border-border',
+};
+/** An index held inside the sequence, so a `current` past either end lands on a real step. */
+function clamp(value, total) {
+    if (total <= 0)
+        return 0;
+    return Math.min(Math.max(Math.trunc(value), 0), total - 1);
+}
+/**
+ * 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.
+ */
+function Steps({ steps, current, label, className }) {
+    // An empty sequence is an empty list rather than a throw. The invariant below
+    // is about a rail with a position, and a caller with no steps has no position
+    // to disagree about; the cost is an empty rail, which is what was asked for.
+    if (steps.length === 0) {
+        return _jsx("ol", { "data-slot": "steps", "aria-label": label, className: cn('flex w-full', className) });
+    }
+    const at = clamp(current, steps.length);
+    const resolved = steps.map((step, index) => step.state ?? (index < at ? 'complete' : index === at ? 'current' : 'upcoming'));
+    const placed = resolved.filter((state) => state === 'current').length;
+    if (placed !== 1) {
+        // The message reaches a developer in a console and is never rendered, which
+        // is why it is a sentence and why the copy gate exempts it. It names both
+        // halves of the failure because they have different fixes: two currents is a
+        // caller who marked two steps, and none is a caller who marked the step
+        // `current` points at as something else.
+        throw new Error(`Steps: ${placed} step(s) resolved to the current state, and exactly one must. ` +
+            'Set `current` to the index of the step the reader is on, and pass `state` only ' +
+            'on a step that was reached out of band.');
+    }
+    const last = steps.length - 1;
+    return (_jsx("ol", { "data-slot": "steps", "data-current": at, "aria-label": label, className: cn('flex w-full flex-col gap-4 sm:flex-row sm:gap-0', className), children: steps.map((step, index) => {
+            const state = resolved[index];
+            const here = index === at;
+            return (_jsxs("li", { "data-slot": "step", "data-state": state, "aria-current": here ? 'step' : undefined, className: cn('flex items-start', index === last ? 'flex-none' : 'flex-1'), children: [_jsxs("div", { "data-slot": "step-marker-row", className: "flex w-full items-center gap-2", children: [_jsx("span", { "data-slot": "step-marker", className: cn('inline-flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-sm font-medium tabular-nums', MARKER[state]), children: _jsx("span", { "aria-hidden": "true", children: index + 1 }) }), index === last ? null : (_jsx("span", { "data-slot": "step-rule", "data-filled": state === 'upcoming' ? undefined : 'true', "aria-hidden": "true", className: cn('h-0.5 flex-1 rounded-full', 
+                                // Filled up to the step the reader is on and empty after it,
+                                // which is the whole indicator: one element saying how far
+                                // through they are, where a filled bar per step says "done"
+                                // once per step and leaves the arithmetic to the reader.
+                                state === 'upcoming' ? 'bg-border' : 'bg-primary') }))] }), _jsxs("div", { "data-slot": "step-text", className: "mt-2 min-w-0 sm:pr-4", children: [_jsx("p", { "data-slot": "step-label", className: cn('text-sm font-medium', state === 'upcoming' ? 'text-muted-foreground' : 'text-foreground'), children: step.label }), step.description === undefined ? null : (_jsx("p", { "data-slot": "step-description", className: "text-muted-foreground mt-0.5 text-sm", children: step.description }))] })] }, index));
+        }) }));
+}
+export { Steps };

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

@@ -36,6 +36,14 @@ export interface SwitchProps extends Omit<ComponentProps<'span'>, 'onChange'> {
  * step: enabling notifications, turning a feature on. The control renders a
  * hidden native input, so it submits with a form, and Space toggles it while
  * focused. When the change needs an explicit save, use a Checkbox instead.
+ *
+ * **A coarse pointer gets the 44px floor as a band, and the pill is untouched.** The
+ * pill is 20 by 36 and the only control in this package whose shape does not suit a
+ * step: `h-11 w-11` would be a 44px switch, which is a switch nobody draws, and
+ * growing only the width would move the thumb's `translate-x-4` travel with the box.
+ * A band reaches the same 44px around the pill as drawn, and a switch sits alone in a
+ * settings row with empty space above and below it, so the fourteen pixels the band
+ * adds in each direction land on nothing a reader was aiming at.
  */
 declare function Switch({ className, ...props }: SwitchProps): import("react").JSX.Element;
 export { Switch };

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

@@ -1 +1 @@
-{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC3E,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,iBAAS,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,WAAW,+BAyBnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/ui/switch.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC3E,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,WAAW,+BA4BnD;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/switch.js

@@ -9,8 +9,19 @@ import { cn } from '../../lib/utils.js';
  * step: enabling notifications, turning a feature on. The control renders a
  * hidden native input, so it submits with a form, and Space toggles it while
  * focused. When the change needs an explicit save, use a Checkbox instead.
+ *
+ * **A coarse pointer gets the 44px floor as a band, and the pill is untouched.** The
+ * pill is 20 by 36 and the only control in this package whose shape does not suit a
+ * step: `h-11 w-11` would be a 44px switch, which is a switch nobody draws, and
+ * growing only the width would move the thumb's `translate-x-4` travel with the box.
+ * A band reaches the same 44px around the pill as drawn, and a switch sits alone in a
+ * settings row with empty space above and below it, so the fourteen pixels the band
+ * adds in each direction land on nothing a reader was aiming at.
  */
 function Switch({ className, ...props }) {
-    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", className: cn('border-transparent bg-input shadow-xs inline-flex h-5 w-9 shrink-0 items-center rounded-full border p-0.5 outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'data-[checked]:bg-primary data-[unchecked]:bg-input', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:cursor-not-allowed disabled:opacity-50', className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 rounded-full shadow-xs', 'transition-transform duration-base ease-out', 'data-[checked]:translate-x-4 data-[unchecked]:translate-x-0') }) }));
+    return (_jsx(SwitchPrimitive.Root, { "data-slot": "switch", className: cn('border-transparent bg-input shadow-xs relative inline-flex h-5 w-9 shrink-0 items-center rounded-full border p-0.5 outline-none', 'transition-[color,box-shadow,background-color] duration-fast ease-out', 'data-[checked]:bg-primary data-[unchecked]:bg-input', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:cursor-not-allowed disabled:opacity-50', 
+        // `relative` is here only to give the band a containing block. The pill has no
+        // positioned ancestor and none of its own offsets, so this moves nothing.
+        'pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-[""]', className), ...props, children: _jsx(SwitchPrimitive.Thumb, { "data-slot": "switch-thumb", className: cn('bg-background pointer-events-none block size-4 rounded-full shadow-xs', 'transition-transform duration-base ease-out', 'data-[checked]:translate-x-4 data-[unchecked]:translate-x-0') }) }));
 }
 export { Switch };