@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/components/stepper/Stepper.d.ts

@@ -0,0 +1,79 @@
+import { type ReactNode } from "react";
+import type { Step, StepStatus, StepperProgress } from "./types";
+export type { Step, StepStatus, StepperProgress };
+export interface StepperProps {
+    /**
+     * What this flow IS — "Case intake", "Deployment".
+     *
+     * It names the ordered list, which is how somebody arriving at the rail
+     * learns what the sequence is for. Required rather than optional for the same
+     * reason `KanbanBoard.label` is: an unnamed list announces as "list" and
+     * gives nobody a reason to be in it.
+     */
+    label: string;
+    steps: readonly Step[];
+    /** 0-based. Out of range throws — see `assertSteps`. */
+    current: number;
+    /**
+     * Move the cursor.
+     *
+     * ABSENT MAKES THE WHOLE RAIL A READ-OUT: no step is clickable and no
+     * forward/back control is drawn. The configuration is the switch, the same
+     * way `UseCaseCard` only becomes editable when handed `onStatusChange`. A
+     * consumer driving its own buttons omits this and keeps the rail.
+     */
+    onCurrentChange?: (index: number) => void;
+    /**
+     * Draw the built-in Back / Next / Finish row. Default `true`.
+     *
+     * `false` keeps the rail clickable (`onCurrentChange` still fires for a click
+     * on an earlier step, and only for that) and draws no row, so a consumer
+     * whose content owns its own forward / back movement, such as a step that
+     * pages through several screens, renders its own buttons without a second
+     * row of them. Without it the only way to drop the row was to drop
+     * `onCurrentChange`, which also made the rail a read-out, and a rail click on
+     * the adjacent earlier step is indistinguishable from the built-in Back
+     * button (both call `onCurrentChange(current - 1)`).
+     *
+     * Nothing prints a step's `blocked` reason when the row is hidden: it is
+     * rendered beside the forward control. The consumer's own forward control
+     * reads it from `advanceBlockReason` and shows it.
+     */
+    showControls?: boolean;
+    /**
+     * What the last step's forward control does. Absent means no control is drawn
+     * on the last step — a wizard whose final action lives in its own form.
+     */
+    onFinish?: () => void;
+    backLabel?: string;
+    nextLabel?: string;
+    finishLabel?: string;
+    /**
+     * `vertical` stacks the rail above long-form content. `horizontal` is the
+     * default because a sequence reads left to right, which is also the only
+     * layout in which the connector between two steps means anything.
+     *
+     * DX-4963: `side` puts the rail in a column BESIDE the content from the `lg` breakpoint (1024px) up, where a long flow
+     * (nine steps) reads best and every label is whole, and stacks it above the content like `vertical` below that.
+     */
+    orientation?: "horizontal" | "vertical" | "side";
+    /**
+     * DX-4963 - the one-line form for a narrow screen: "Step 3 of 9: Project" in a button that opens the full list under it (and
+     * closes again when the step changes). `true` always, `"auto"` wherever the full rail would not fit (below the `sm` breakpoint, 640px; with
+     * `orientation="side"` below `lg`, 1024px, DX-4968: between the two the stacked list would push the step's own content off the first
+     * screen), `false` (the default) never. Nine steps stacked is about 530px tall; this keeps the step's own content on the first screen.
+     */
+    compact?: boolean | "auto";
+    /**
+     * DXUI-100 - draw the step you are on as the one that matters: it is larger and fully opaque, every other step is smaller
+     * and faded, and each label is centred on its marker (the default aligns a label with the top of its marker, which reads
+     * wrongly beside a marker of another size). Default `false`: a stepper that does not name it is drawn as before.
+     *
+     * Nothing is removed from a faded step: its status glyph, hint and spoken state are all still there, only quieter.
+     */
+    emphasizeCurrent?: boolean;
+    /** The CURRENT step's content. */
+    children?: ReactNode;
+    className?: string;
+}
+export declare function Stepper({ label, steps, current, onCurrentChange, showControls, onFinish, backLabel, nextLabel, finishLabel, orientation, compact, emphasizeCurrent, children, className, }: StepperProps): import("react").JSX.Element;

package/dist/types/components/stepper/derive.d.ts

@@ -0,0 +1,49 @@
+import type { Step, StepStatus, StepperProgress } from "./types";
+/**
+ * Reject a flow that cannot be rendered honestly, loudly.
+ *
+ * Every one of these is unreachable through the component's own UI and silent
+ * if allowed through: an empty rail renders as a blank strip, an out-of-range
+ * cursor renders no current step at all, duplicate ids give React two elements
+ * with one key (which reconciles them into each other on the next change), and
+ * an empty `blocked` string disables the forward button while printing nothing
+ * beside it.
+ */
+export declare function assertSteps(steps: readonly Step[], current: number): void;
+/**
+ * What one step IS, given where the cursor is.
+ *
+ * PRECEDENCE: failed, blocked, current, complete, unverified, skipped, incomplete, upcoming. DX-4973 puts `failed` first.
+ * The next rule is the interesting one. `blocked` outranks
+ * everything, including `complete`, wherever the step sits. Data saying both
+ * is contradictory, and when a record contradicts itself the exception is what
+ * the reader needs — the same call `ProvenanceBadge` makes when it stays quiet
+ * on the ordinary case and loud on every other one. An affirmative that hides
+ * an obstruction is the worse of the two possible mistakes.
+ *
+ * Note that a `blocked` reason on a step OTHER than the current one still
+ * renders as blocked but gates nothing: only the current step's reason can stop
+ * forward movement (see `advanceBlockReason`). That is deliberate — a flow can
+ * legitimately want to say "and this one ahead needs a signature" without
+ * claiming that is why you are stuck right now.
+ */
+export declare function stepStatus(steps: readonly Step[], current: number, index: number): StepStatus;
+/**
+ * Why forward movement is refused, or `null` when it is not.
+ *
+ * ONLY THE CURRENT STEP GATES. A reason on a step you are not standing on is
+ * information about that step, not a claim about this one.
+ *
+ * `null` is the only "not blocked" value — an empty string is rejected at
+ * `assertSteps` rather than treated as absent, so a falsy check here cannot
+ * turn a reason that failed to load into permission to proceed.
+ */
+export declare function advanceBlockReason(steps: readonly Step[], current: number): string | null;
+/**
+ * Position and completion, as two numbers that are allowed to disagree.
+ *
+ * This exists so a consumer that genuinely wants a bar builds it from a named
+ * number instead of guessing which one a bar meant. The component itself draws
+ * no percentage — see the note on `Stepper`.
+ */
+export declare function stepperProgress(steps: readonly Step[], current: number): StepperProgress;

package/dist/types/components/stepper/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./derive";
+export { Stepper, type StepperProps } from "./Stepper";

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

@@ -0,0 +1,118 @@
+import type { ReactNode } from "react";
+export interface Step {
+    id: string;
+    /** Shown on the rail and spoken as the step's name. */
+    label: string;
+    /** What this step is for. One line, under the label. */
+    hint?: ReactNode;
+    /**
+     * Finished.
+     *
+     * ABSENT MEANS NOT COMPLETE. There is no third state, and none is invented:
+     * nobody has ever needed to record that they do not know whether a step was
+     * finished. This is the same call `RoadmapItem.built` makes about an absent
+     * track key, and it is what keeps `!step.complete` from having two readings.
+     */
+    complete?: boolean;
+    /**
+     * Passed on purpose without doing it: an optional step the person chose to leave, or one that was acknowledged and not filled in.
+     * DX-4963.
+     *
+     * It is NOT a fault. A step behind the cursor that is merely `incomplete` is the one thing a rail marks in danger red, because
+     * something was missed; a `skipped` step was a decision, so it gets a grey marker, its own spoken word, and a neutral chip, and it
+     * is never counted in the red one. `complete` outranks it (a step that was skipped and then done is done), and `blocked` and the
+     * cursor outrank both. Like `complete`, absent means false.
+     */
+    skipped?: boolean;
+    /**
+     * Done, but there is nothing a server could test, so it cannot be called a tested success. DX-4968.
+     *
+     * The VALUE is the words, supplied by the caller ("Saved, not tested", "Confirmed when the token is saved"): the library cannot
+     * know what a flow's steps are for, and "skipped" would be false for a step that was done. The words are printed under the label
+     * and spoken as the step's state. It is its own neutral state: a grey marker with its own glyph, never the green of a tested
+     * result, never the red of a missed step, and counted in neither chip (`StepperProgress.unverified` carries the number for a
+     * caller that wants it). `complete` outranks it, and the cursor and `blocked` outrank both; it outranks `skipped`.
+     * An empty string throws, for the same reason an empty `blocked` does: the words ARE the spoken state.
+     */
+    unverified?: string;
+    /**
+     * A check of this step ran and FAILED, and what it said. DX-4973.
+     *
+     * The VALUE is the reason, supplied by the caller ("Asana refused the token", "The bot is not in that channel"): the library cannot
+     * know what a flow checks, and the words are printed in red under the label and spoken as the step's state (so start with what
+     * happened, because no fixed word like "failed" is added). It is the one red marker a step can carry on purpose, distinct from
+     * `blocked` (cannot start yet, amber, and the only one that gates the forward control), `unverified` (done, nothing to test, grey),
+     * `skipped` (left on purpose, grey) and `incomplete` (passed over, red cross). A failed step does NOT gate forward movement by
+     * itself: add `blocked` as well when it must. It outranks every other state, `blocked` and the cursor included, because a failure is
+     * the thing a reader must not miss; it is counted in `StepperProgress.failed` and in neither chip. An empty string throws.
+     */
+    failed?: string;
+    /**
+     * Why the flow cannot move on from here. Absent means it can.
+     *
+     * Written for the person who would have pressed the button — "two documents
+     * are still missing", not "invalid". It is rendered beside the forward
+     * control rather than only disabling it, because a dead button with no
+     * sentence next to it is indistinguishable from a broken one.
+     *
+     * AN EMPTY STRING THROWS, and that is a deliberate divergence from
+     * `KanbanLane.refusal`, which accepts one. There the reason is supporting
+     * detail on a lane that is already visibly refusing; here the sentence IS the
+     * mechanism — an empty one produces exactly the mute disabled button this
+     * prop exists to prevent, so it is rejected loudly instead of rendered as
+     * nothing.
+     */
+    blocked?: string;
+}
+/**
+ * What a step IS right now — derived from the steps and the cursor, never
+ * stored.
+ *
+ * Eight, not two, because "finished", "you are here", "done but unproven", "you left it on purpose",
+ * "you missed it", "not reached yet" and "this is what is stopping you" call for
+ * different next actions and one absence of action. Collapsing them to a boolean is what
+ * produces a rail where a skipped step and an untouched one look identical.
+ */
+export type StepStatus = 
+/** Carries `failed` words: a check ran and refused it. Beats every other reading, `blocked` included. Red. DX-4973. */
+"failed"
+/** `complete: true`. */
+ | "complete"
+/** Carries a `blocked` reason. Beats every other reading — see `stepStatus`. */
+ | "blocked"
+/** The cursor is on it. */
+ | "current"
+/** Carries `unverified` words and is not complete: done, with no result to show. Neutral, never a fault. DX-4968. */
+ | "unverified"
+/** `skipped: true` and not complete: left on purpose. Neutral, never a fault. DX-4963. */
+ | "skipped"
+/** Behind the cursor, not complete and marked neither `skipped` nor `unverified`: passed over by accident. */
+ | "incomplete"
+/** Ahead of the cursor. Not a fault — simply not reached. */
+ | "upcoming";
+/**
+ * The two numbers a stepper header is tempted to average into one bar.
+ *
+ * `position` is where the cursor is; `complete` is how many are finished. They
+ * disagree the moment anybody moves past a step without finishing it, and
+ * `skipped` is that disagreement stated as a number rather than hidden inside
+ * a percentage.
+ */
+export interface StepperProgress {
+    /** 1-based, for reading: "Step 3 of 5". */
+    position: number;
+    total: number;
+    /** How many steps are `complete`, anywhere in the flow. */
+    complete: number;
+    /**
+     * Behind the cursor, not complete and marked none of `skipped`, `unverified` or `failed`: the steps missed, the ones the red chip counts. (Renamed in meaning by
+     * DX-4963: a step the person skipped on purpose is `acknowledged`, not counted here.)
+     */
+    skipped: number;
+    /** Steps marked `skipped` that are not complete, anywhere in the flow: left on purpose, counted in the neutral chip. DX-4963. */
+    acknowledged: number;
+    /** Steps carrying `failed` words, anywhere in the flow. Counted in no chip. DX-4973. */
+    failed: number;
+    /** Steps carrying `unverified` words that are not complete, anywhere in the flow: done, with nothing to test. Counted in no chip. DX-4968. */
+    unverified: number;
+}