@danxbot/ui 2.2.2 → 2.3.0

package/dist/types/components/checklist/StatusChecklist.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from "react";
+import type { StatusOption } from "../StatusSelect";
+import type { ChecklistItem, ChecklistState, ChecklistTally } from "./types";
+export type { ChecklistItem, ChecklistState, ChecklistTally };
+export interface StatusChecklistProps<Key extends string = string> {
+    /**
+     * What this list IS — "Evidence for the March filing".
+     *
+     * Names the group, so somebody landing on it by keyboard learns what the
+     * counts are counting. Required for the same reason `KanbanBoard.label` is.
+     */
+    label: string;
+    /** The consumer's vocabulary, in the order the summary and groups read. */
+    states: readonly StatusOption<Key>[];
+    items: readonly ChecklistItem<Key>[];
+    /**
+     * `state` groups the rows under their state's heading; `given` renders them
+     * in the order supplied.
+     *
+     * GROUPED IS THE DEFAULT, and that is the opposite of what a checklist
+     * usually wants. A checklist you work down top to bottom should stay in its
+     * given order — but this control's stated job is to make the shape of the gap
+     * legible, and an interleaved list makes the reader do the sorting in their
+     * head while the summary above already claims to have done it for them.
+     * `given` is there for the case where the order is itself meaningful — a
+     * sequence, a priority, a filing order — because then regrouping destroys
+     * information the consumer put in deliberately.
+     */
+    order?: "state" | "given";
+    /** Shown when `items` is empty. `EmptyState` supplies the shape. */
+    emptyTitle?: ReactNode;
+    emptyDescription?: ReactNode;
+    emptyAction?: ReactNode;
+    emptyIcon?: ReactNode;
+    className?: string;
+}
+export declare function StatusChecklist<Key extends string = string>({ label, states, items, order, emptyTitle, emptyDescription, emptyAction, emptyIcon, className, }: StatusChecklistProps<Key>): import("react").JSX.Element;

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

@@ -0,0 +1,3 @@
+export type { ChecklistItem, ChecklistState, ChecklistTally } from "./types";
+export { tallyChecklist } from "./tally";
+export { StatusChecklist, type StatusChecklistProps } from "./StatusChecklist";

package/dist/types/components/checklist/tally.d.ts

@@ -0,0 +1,19 @@
+import type { StatusOption } from "../StatusSelect";
+import type { ChecklistItem, ChecklistTally } from "./types";
+/**
+ * Split `items` across the declared `states`, in the order the states were
+ * given.
+ *
+ * Every state appears in the result, INCLUDING EMPTY ONES. A zero is
+ * information — "nothing is blocking" is the single most useful thing this
+ * control ever says — and a chip that vanishes at zero is invisible at exactly
+ * the moment its emptiness is the news, while also making the summary row
+ * change width every time an item moves. The BODY is the other way round: see
+ * `StatusChecklist`.
+ *
+ * Throws rather than tolerating: an unknown state key, a duplicate state, a
+ * duplicate item id, or no states at all. Each of those renders as something
+ * plausible if allowed through — an item silently dropped from a list whose
+ * whole purpose is to be exhaustive is the worst failure this component has.
+ */
+export declare function tallyChecklist<Key extends string>(states: readonly StatusOption<Key>[], items: readonly ChecklistItem<Key>[]): ChecklistTally<Key>[];

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { StatusOption } from "../StatusSelect";
+export type ChecklistState<Key extends string = string> = StatusOption<Key>;
+export interface ChecklistItem<Key extends string = string> {
+    id: string;
+    /** What the item IS. The row's own text — never replaced by an aria-label. */
+    label: ReactNode;
+    /** Must be the `value` of one of the declared states. An unknown key throws. */
+    state: Key;
+    /** A second line: who it is with, when it was asked for, why it is missing. */
+    detail?: ReactNode;
+    /**
+     * A control for this row — "Request it", "Open", "Mark received".
+     *
+     * A slot rather than a `{label, onClick}` prop, for the same reason
+     * `RecordCard.badges` is one: whether the action is a button, a link, a menu
+     * or a spinner belongs to the surface, and every shape this prop could grow
+     * to cover would be a library release for a decision the consumer had
+     * already made.
+     */
+    action?: ReactNode;
+}
+/** One state, its option, and everything in it — in the declared order. */
+export interface ChecklistTally<Key extends string = string> {
+    option: StatusOption<Key>;
+    count: number;
+    items: ChecklistItem<Key>[];
+}

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

@@ -0,0 +1,44 @@
+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;
+    /**
+     * 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 beside 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.
+     */
+    orientation?: "horizontal" | "vertical";
+    /** The CURRENT step's content. */
+    children?: ReactNode;
+    className?: string;
+}
+export declare function Stepper({ label, steps, current, onCurrentChange, onFinish, backLabel, nextLabel, finishLabel, orientation, children, className, }: StepperProps): import("react").JSX.Element;

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

@@ -0,0 +1,48 @@
+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, and the first 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,70 @@
+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;
+    /**
+     * 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.
+ *
+ * Five, not two, because "finished", "you are here", "you skipped it", "not
+ * reached yet" and "this is what is stopping you" call for four 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 = 
+/** `complete: true`. */
+"complete"
+/** Carries a `blocked` reason. Beats every other reading — see `stepStatus`. */
+ | "blocked"
+/** The cursor is on it. */
+ | "current"
+/** Behind the cursor and not complete: passed over. */
+ | "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 and not complete. */
+    skipped: number;
+}

package/dist/types/index.d.ts

@@ -41,6 +41,8 @@ export { RecordCard, type RecordCardProps, type RecordCardMetric, } from "./comp
 export { Tabs, TabList, Tab, TabPanel, type TabsProps, type TabListProps, type TabProps, type TabPanelProps, } from "./components/Tabs";
 export { Accordion, AccordionItem, type AccordionProps, type AccordionItemProps, } from "./components/Accordion";
 export { Breadcrumb, Pagination, type BreadcrumbProps, type PaginationProps, type Crumb, } from "./components/Navigation";
+export { Stepper, stepStatus, stepperProgress, advanceBlockReason, assertSteps, type StepperProps, type Step, type StepStatus, type StepperProgress, } from "./components/stepper";
+export { StatusChecklist, tallyChecklist, type StatusChecklistProps, type ChecklistItem, type ChecklistState, type ChecklistTally, } from "./components/checklist";
 export { Toggle, ToggleGroup, Toolbar, ToolbarSeparator, type ToggleProps, type ToggleGroupProps, type ToolbarProps, } from "./components/Toggle";
 export { Separator, ScrollArea, Collapsible, EmptyState, Timeline, type SeparatorProps, type ScrollAreaProps, type CollapsibleProps, type EmptyStateProps, type TimelineProps, type TimelineItem, } from "./components/Surface";
 export { PanelGroup, Panel, PanelResizer, type PanelGroupProps, type PanelProps, type PanelResizerProps, type PanelDirection, type PanelNarrowMode, } from "./components/Panel";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",