@dashforge/tw 1.1.1 → 1.3.0

package/dist/src/components/Spinner/spinner.types.d.ts

@@ -26,7 +26,10 @@ export type SpinnerThickness = 'thin' | 'md' | 'thick';
  * under `prefers-reduced-motion`).
  */
 export interface SpinnerProps {
-    /** @default 'md' */
+    /**
+     * Diameter tier — xs:12px, sm:16px, md:20px, lg:24px, xl:32px.
+     * @default 'md'
+     */
     size?: SpinnerSize;
     /**
      * Intent color. **When omitted, inherits parent's text color via
@@ -35,7 +38,10 @@ export interface SpinnerProps {
      * for standalone usage on neutral surfaces.
      */
     color?: SpinnerColor;
-    /** @default 'md' */
+    /**
+     * SVG stroke-width — thin:1.5, md:2.25, thick:3.
+     * @default 'md'
+     */
     thickness?: SpinnerThickness;
     /**
      * Renders a faint "ghost ring" behind the spinning arc (20%
@@ -83,7 +89,21 @@ export interface SpinnerProps {
      * otherwise display-only.
      */
     visibleWhen?: (engine: Engine) => boolean;
+    /** Standard React `className` — appended to the root via `cn()`. */
     className?: string;
+    /** Root-element class shortcut (string or clsx-compatible value). Wins over variant classes via `tailwind-merge`. */
     sx?: ClassValue;
 }
+/**
+ * Subset of `<Spinner>` props theme-configurable via
+ * `theme.components.Spinner.defaults` (Option C).
+ */
+export type SpinnerVariantProps = Pick<SpinnerProps, 'size' | 'color' | 'thickness' | 'withTrack'>;
+declare module '@dashforge/tw-tokens' {
+    interface TWComponentDefaults {
+        Spinner?: {
+            defaults?: Partial<SpinnerVariantProps>;
+        };
+    }
+}
 //# sourceMappingURL=spinner.types.d.ts.map

package/dist/src/components/Spinner/spinner.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spinner.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Spinner/spinner.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAE3B,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IAErB,oBAAoB;IACpB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAGpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAM1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB"}
+{"version":3,"file":"spinner.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Spinner/spinner.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAE3B;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAGpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAM1C,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qHAAqH;IACrH,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,YAAY,EACZ,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,CAC7C,CAAC;AAEF,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,OAAO,CAAC,EAAE;YACR,QAAQ,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;SACzC,CAAC;KACH;CACF"}

package/dist/src/components/Stack/Stack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/Stack.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAqCnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,KAAK,oGAyCjB,CAAC"}
+{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/Stack.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA6CnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,KAAK,oGAgGjB,CAAC"}

package/dist/src/components/Stack/stack.types.d.ts

@@ -1,5 +1,23 @@
 import type { ElementType, HTMLAttributes, ReactNode } from 'react';
-import type { StackVariants } from './stack.variants.js';
+import type { StackGap, StackVariants } from './stack.variants.js';
+/**
+ * Subset of `<Stack>` props theme-configurable via
+ * `theme.components.Stack.defaults` (Option C).
+ *
+ * `gap` is deliberately overridden to the strict `StackGap` literal
+ * union rather than the `VariantProps`-widened `string` — see
+ * `stack.variants.ts` and issue #111 (G-27) for the widening bug.
+ */
+export type StackVariantProps = Pick<StackVariants, 'direction' | 'align' | 'justify' | 'wrap' | 'fullWidth' | 'fullHeight'> & {
+    gap?: StackGap;
+};
+declare module '@dashforge/tw-tokens' {
+    interface TWComponentDefaults {
+        Stack?: {
+            defaults?: Partial<StackVariantProps>;
+        };
+    }
+}
 /**
  * Props for `<Stack>` — flex container 1D, the layout primitive.
  *
@@ -21,7 +39,40 @@ import type { StackVariants } from './stack.variants.js';
  *   • 2D layout (rows AND columns)          → use <Grid>
  *   • Text styling                          → <Typography>
  */
-export interface StackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className'>, Pick<StackVariants, 'direction' | 'align' | 'justify' | 'gap' | 'wrap' | 'fullWidth' | 'fullHeight'> {
+export interface StackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className'> {
+    /**
+     * Flex direction.
+     * @default 'col'
+     */
+    direction?: StackVariants['direction'];
+    /** Cross-axis alignment (`items-*`). */
+    align?: StackVariants['align'];
+    /** Main-axis alignment (`justify-*`). */
+    justify?: StackVariants['justify'];
+    /**
+     * Gap between children — spacing token step. Accepts one of eleven
+     * numeric literals matching Box's spacing scale: `0 | 0.5 | 1 | 2 |
+     * 3 | 4 | 6 | 8 | 12 | 16 | 24`. Token strings (`'xs' | 'sm' | 'md'`)
+     * are **not** accepted — TypeScript rejects them at compile time,
+     * and a runtime pass through with an unknown value emits a
+     * dev-only `console.warn` (issue #111 / G-27).
+     */
+    gap?: StackGap;
+    /**
+     * Allow children to wrap to the next line (`flex-wrap`).
+     * @default false
+     */
+    wrap?: StackVariants['wrap'];
+    /**
+     * Stretch to fill the container's width.
+     * @default false
+     */
+    fullWidth?: StackVariants['fullWidth'];
+    /**
+     * Stretch to fill the container's height.
+     * @default false
+     */
+    fullHeight?: StackVariants['fullHeight'];
     /**
      * Node rendered N-1 times BETWEEN children — mirror of MUI Stack's
      * divider prop. Useful for visual separators (a `<hr>`, a thin

package/dist/src/components/Stack/stack.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/stack.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,UACf,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,EACjD,IAAI,CAAC,aAAa,EAChB,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAChD,WAAW,GAAG,YAAY,CAAC;IACvC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}
+{"version":3,"file":"stack.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/stack.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,aAAa,EACb,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CACxE,GAAG;IACF,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB,CAAC;AAEF,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,KAAK,CAAC,EAAE;YACN,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;SACvC,CAAC;KACH;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,UACf,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC;IACzD;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAEvC,wCAAwC;IACxC,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAE/B,yCAAyC;IACzC,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAEnC;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,QAAQ,CAAC;IAEf;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAEvC;;;OAGG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}

package/dist/src/components/Stack/stack.variants.d.ts

@@ -160,4 +160,27 @@ export declare const stackVariants: import("tailwind-variants").TVReturnType<{
     };
 }, undefined, "flex", unknown, unknown, undefined>>;
 export type StackVariants = VariantProps<typeof stackVariants>;
+/**
+ * The 11 accepted values for `<Stack gap>` — same set as Box's spacing
+ * axes (p, m, etc.). Exported so the JSDoc, the runtime dev-warn, and
+ * the `<Stack>` prop type all speak the same list.
+ *
+ * Why re-declared instead of derived from `stackVariants.variants.gap`
+ * via `VariantProps`: `tailwind-variants` 3.x widens variant value
+ * types to `string | undefined` when the variant object has mixed-type
+ * keys (numeric literals + string literals like `'0.5'`), which is why
+ * TS silently accepted `<Stack gap="md">` before #111 — that's the
+ * whole bug this literal union closes. Keep this list in sync with
+ * the `gap` object in the `variants` block above.
+ *
+ * @see Issue #111 — silent-fail when `gap` receives a token value that
+ * isn't on the numeric scale (G-27).
+ */
+export type StackGap = 0 | 0.5 | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16 | 24;
+/**
+ * Runtime allow-list, for the dev-warn to check against a passed
+ * `gap` value at render time. Same set as {@link StackGap}. Frozen
+ * so callers can't mutate the source of truth.
+ */
+export declare const STACK_GAP_VALUES: readonly StackGap[];
 //# sourceMappingURL=stack.variants.d.ts.map

package/dist/src/components/Stack/stack.variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/stack.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDAgDxB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"stack.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Stack/stack.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDAgDxB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,QAAQ,GAChB,CAAC,GACD,GAAG,GACH,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,EAAE,GACF,EAAE,GACF,EAAE,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,QAAQ,EAE9C,CAAC"}

package/dist/src/components/Stepper/Step.d.ts

@@ -0,0 +1,30 @@
+import type { StepProps } from './stepper.types.js';
+/**
+ * `<Step>` — a config-carrier child of `<Stepper>`.
+ *
+ * Renders NOTHING on its own — the parent `<Stepper>` walks its children
+ * with `React.Children.toArray`, extracts each `<Step>`'s props to build
+ * the visible sequence, and drives the strip + content rendering from
+ * there. This mirrors the MUI Tabs / Chakra Tabs "compound children as
+ * config" pattern.
+ *
+ * Placement rule (enforced by the parent's dev-warn): `<Step>` must be a
+ * DIRECT child of `<Stepper>`. Wrapping steps in a fragment is fine
+ * (`React.Children.toArray` flattens fragments); wrapping in an arbitrary
+ * `<div>` is not — the parent won't see the step and will skip it.
+ *
+ * @see StepProps for the full config surface.
+ */
+export declare function Step(_props: StepProps): null;
+export declare namespace Step {
+    var displayName: string;
+}
+/**
+ * Marker used by `<Stepper>` to recognize its own compound child type
+ * without pulling in `React.ReactElement<StepProps>` machinery. The
+ * parent traverses `React.Children.toArray(children)` and matches on
+ * `child.type === Step` — matching on `displayName` would be brittle
+ * against React tree cloning.
+ */
+export declare const __IS_STEP: unique symbol;
+//# sourceMappingURL=Step.d.ts.map

package/dist/src/components/Stepper/Step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../../src/components/Stepper/Step.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAE5C;yBAFe,IAAI;;;AAMpB;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,eAAmC,CAAC"}

package/dist/src/components/Stepper/Stepper.d.ts

@@ -0,0 +1,15 @@
+import type { StepperProps } from './stepper.types.js';
+/**
+ * `<Stepper>` — declarative multi-step navigation with compound `<Step>`
+ * children. The parent walks its children, extracts each `<Step>`'s
+ * props, filters by `visibleWhen`, and drives the strip + content
+ * rendering. Consumers reach the current step state + navigation API
+ * via the `useStep()` hook.
+ *
+ * See {@link StepperProps} for the full API surface.
+ */
+export declare function Stepper(props: StepperProps): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace Stepper {
+    var displayName: string;
+}
+//# sourceMappingURL=Stepper.d.ts.map

package/dist/src/components/Stepper/Stepper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stepper.d.ts","sourceRoot":"","sources":["../../../../src/components/Stepper/Stepper.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAEV,YAAY,EAIb,MAAM,oBAAoB,CAAC;AAqC5B;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,kDAia1C;yBAjae,OAAO"}

package/dist/src/components/Stepper/StepperContext.d.ts

@@ -0,0 +1,8 @@
+import type { UseStepReturn } from './stepper.types.js';
+/**
+ * Internal context wired by `<Stepper>` and read by `useStep()`. Not
+ * exported from the package — consumers reach the state only via the
+ * `useStep()` hook.
+ */
+export declare const StepperContext: import("react").Context<UseStepReturn | null>;
+//# sourceMappingURL=StepperContext.d.ts.map

package/dist/src/components/Stepper/StepperContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepperContext.d.ts","sourceRoot":"","sources":["../../../../src/components/Stepper/StepperContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,cAAc,+CAA4C,CAAC"}

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

@@ -0,0 +1,358 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { StepperVariants } from './stepper.variants.js';
+/**
+ * The lifecycle state of a single step within the visible sequence.
+ *
+ * - `pending`   — step comes AFTER the current step (not yet visited).
+ * - `current`   — the step the user is on right now.
+ * - `completed` — step was visited AND the consumer has advanced past it
+ *                 (implies `visitedSteps.has(step.name)` AND it is not
+ *                 the current step and is before it in the sequence).
+ * - `invalid`   — the step has an entry in `errors`, populated after a
+ *                 failed `goNext()` attempt (from `fields` trigger or
+ *                 `isValid` callback returning false).
+ * - `skipped`   — reserved for future non-linear skip semantics; unused
+ *                 in v1.
+ */
+export type StepState = 'pending' | 'current' | 'completed' | 'invalid' | 'skipped';
+/**
+ * Per-step error record surfaced on `useStep().errors`. Populated when
+ * `<Step fields={...}>` fails its RHF `trigger` call, or when a step's
+ * `isValid` callback returns `false`.
+ *
+ * The error routing pattern (Review step with clickable list) reads
+ * this array to render jump-links back to the step that failed.
+ */
+export interface StepError {
+    /** The step's `name` (unique key). */
+    step: string;
+    /** The step's `label` (for consumer-friendly display). */
+    label: ReactNode;
+    /** How the step became invalid. */
+    reason: 'fields' | 'isValid';
+    /** RHF `formState.errors` at the moment of the failed transition. */
+    errors: Record<string, unknown> | null;
+}
+/**
+ * Payload emitted to `<Stepper onStepInvalid>` when a `goNext()` attempt
+ * fails validation.
+ */
+export interface OnStepInvalidPayload {
+    /** The step that failed. */
+    step: string;
+    /** Its index within the visible sequence. */
+    index: number;
+    /** How it failed. */
+    reason: 'fields' | 'isValid';
+    /** RHF errors, if the failure came from `fields` trigger. */
+    errors: Record<string, unknown> | null;
+}
+/**
+ * The shape returned by `useStep()` — the consumer-facing API of the
+ * current Stepper context. Available to any component rendered inside
+ * a `<Stepper>` tree (typically the current `<Step>`'s children or a
+ * custom footer).
+ *
+ * The hook is the ONLY public path to the Stepper's internal state —
+ * consumers do NOT reach into the internal context directly.
+ */
+export interface UseStepReturn {
+    /** The current step's `name`. */
+    currentStep: string;
+    /** Its index within the visible sequence. */
+    currentStepIndex: number;
+    /**
+     * The filtered visible sequence, in declaration order. Steps whose
+     * `visibleWhen` returned `false` are absent.
+     */
+    visibleSteps: Array<{
+        name: string;
+        label: ReactNode;
+    }>;
+    /**
+     * Set of step names the user has visited so far. Reset by `reset()`,
+     * pre-populated by `initialStep` (every step before the initial one
+     * is treated as visited so a resumed wizard doesn't break the
+     * `allowJumpTo="visited"` gate).
+     */
+    visitedSteps: Set<string>;
+    /**
+     * Errors recorded from the most recent failed `goNext()` calls. Cleared
+     * for a step when it is re-visited AND successfully re-validated.
+     */
+    errors: StepError[];
+    /**
+     * Advance to the next step. Runs the current step's validation
+     * (`fields` trigger via `bridge.trigger` + optional `isValid` callback
+     * with AND semantics) and, on failure, records the error + fires
+     * `onStepInvalid`. On success beyond the last step, fires
+     * `onComplete()`.
+     *
+     * @returns `true` when the transition succeeded, `false` when blocked.
+     */
+    goNext: () => Promise<boolean>;
+    /**
+     * Go back one step. Does not run validation — pending steps between
+     * the current and the target are marked pending again, but the
+     * consumer's state (RHF values) is preserved.
+     */
+    goBack: () => void;
+    /**
+     * Jump directly to a step by name. Gated by `allowJumpTo`:
+     *   - `'visited'` — allowed only if `visitedSteps.has(name)`.
+     *   - `'none'`    — always rejected (silent no-op).
+     * The Review-step error-routing pattern uses this to send the user
+     * back to a failed step from the error summary.
+     */
+    goToStep: (name: string) => void;
+    /**
+     * Reset to `initialStep` (or the first visible step if `initialStep`
+     * is unset). Clears `visitedSteps` and `errors`.
+     */
+    reset: () => void;
+    /** `true` when the current step is the first in the visible sequence. */
+    isFirstStep: boolean;
+    /** `true` when the current step is the last in the visible sequence. */
+    isLastStep: boolean;
+    /**
+     * `true` when `goNext()` would succeed as of this render. Consumers
+     * can use this to render the Next button as `disabled`. Note this is
+     * a SYNC readout (based on `bridge.getError(field)` for each `fields`
+     * entry) — the `isValid` callback is NOT invoked here, since it may
+     * be async and consumers wouldn't want a render-time promise.
+     */
+    canGoNext: boolean;
+}
+/**
+ * Per-slot overrides — same shape as every other tw catalog entry.
+ */
+export interface StepperSlotProps {
+    root?: {
+        className?: string;
+    };
+    strip?: {
+        className?: string;
+    };
+    step?: {
+        className?: string;
+    };
+    indicator?: {
+        className?: string;
+    };
+    labelGroup?: {
+        className?: string;
+    };
+    label?: {
+        className?: string;
+    };
+    helperText?: {
+        className?: string;
+    };
+    optionalTag?: {
+        className?: string;
+    };
+    connector?: {
+        className?: string;
+    };
+    content?: {
+        className?: string;
+    };
+    footer?: {
+        className?: string;
+    };
+}
+/**
+ * Subset of `<Stepper>` props theme-configurable via
+ * `theme.components.Stepper.defaults` (Option C).
+ */
+export type StepperVariantProps = Pick<StepperVariants, 'color' | 'size' | 'orientation' | 'labelPlacement'>;
+declare module '@dashforge/tw-tokens' {
+    interface TWComponentDefaults {
+        Stepper?: {
+            defaults?: Partial<StepperVariantProps>;
+            slotProps?: StepperSlotProps;
+        };
+    }
+}
+/**
+ * Props for `<Step>` — a config-carrier child of `<Stepper>`.
+ *
+ * `<Step>` renders no DOM of its own; the parent `<Stepper>` walks the
+ * children, reads each `<Step>`'s props, and drives rendering from
+ * there. This mirrors the MUI / Chakra "compound children as config"
+ * pattern (`<Tabs><Tab /><Tab /></Tabs>`).
+ */
+export interface StepProps {
+    /**
+     * Unique step key. Also used by `visitedSteps`, `goToStep`, `errors`,
+     * and `initialStep`. Required — every step must have a distinct name.
+     */
+    name: string;
+    /** Short label rendered next to (or below) the indicator dot. */
+    label: ReactNode;
+    /**
+     * Secondary line rendered under the label. Optional.
+     * Common uses: "2 min", "Enter card info", "Optional".
+     */
+    helperText?: ReactNode;
+    /**
+     * Custom icon rendered inside the indicator dot for the `pending` and
+     * `current` states. Not shown when `completed` (a check mark takes
+     * over) or `invalid` (an alert-triangle icon takes over).
+     *
+     * MUI-parity — an escape hatch for domain-specific dots
+     * (`<Eye />` on a Review step, `<Cog />` on a Settings step).
+     */
+    icon?: ReactNode;
+    /**
+     * Marks the step as optional. `true` renders a default "Optional"
+     * italic caption below the label; passing a ReactNode substitutes the
+     * caption (`optional={<span>Skip if remote</span>}`). MUI-parity.
+     *
+     * NOTE: `optional` is display-only — it does NOT skip validation. A
+     * step that should be skippable at the flow level should use
+     * `visibleWhen` to hide itself, not `optional`.
+     */
+    optional?: boolean | ReactNode;
+    /**
+     * List of RHF field names to validate on `goNext()`. Runs
+     * `bridge.trigger(fields)` and blocks the transition if any field
+     * fails. Combined with `isValid` via **AND** semantics: both must
+     * pass for the step to be considered valid.
+     *
+     * Requires a wrapping `<DashForm>` — outside a form context this prop
+     * is a no-op (dev-warn).
+     */
+    fields?: string[];
+    /**
+     * Custom validation callback with AND-semantics against `fields`.
+     * Runs AFTER `fields` (only if `fields` passes). Return `false` (sync
+     * or async) to block the transition.
+     *
+     * Use for domain rules that can't be expressed as RHF field
+     * validators (e.g., "at least one item in the cart", "the payment
+     * gateway acknowledged the pre-auth").
+     */
+    isValid?: () => boolean | Promise<boolean>;
+    /**
+     * Reactive visibility predicate — catalog-uniform closure. Steps
+     * whose predicate returns `false` are excluded from `visibleSteps`,
+     * skipped by `goNext()` / `goBack()`, and hidden from the indicator
+     * strip. This is the primary hook for dynamic step composition
+     * (e.g., a "Legal address" step that only shows for EU customers).
+     */
+    visibleWhen?: (engine: Engine) => boolean;
+    /** RBAC gate — hides or disables the step. */
+    access?: AccessRequirement;
+    /** The step's content — rendered inside the `content` slot when active. */
+    children?: ReactNode;
+}
+/**
+ * Props for `<Stepper>` — the compound parent.
+ *
+ * @example Linear wizard with form-driven validation
+ * ```tsx
+ * <DashForm defaultValues={{ email: '', card: '' }}>
+ *   <Stepper name="cardActivation" onComplete={handleActivate}>
+ *     <Step name="account" label="Account" fields={['email']}>
+ *       <TextField name="email" label="Email" />
+ *     </Step>
+ *     <Step name="card" label="Card details" fields={['card']}>
+ *       <TextField name="card" label="Card number" />
+ *     </Step>
+ *     <Step name="review" label="Review">
+ *       <ReviewPanel />
+ *     </Step>
+ *   </Stepper>
+ * </DashForm>
+ * ```
+ *
+ * @example Dynamic step with `visibleWhen`
+ * ```tsx
+ * <Step
+ *   name="contract"
+ *   label="Contract"
+ *   visibleWhen={(engine) => engine.get('activation') === 'deferred'}
+ * >
+ *   ...
+ * </Step>
+ * ```
+ */
+export interface StepperProps {
+    /** Optional identifier — used for logging / test IDs. */
+    name?: string;
+    /**
+     * `<Step>` children. Non-`<Step>` children are dev-warned and
+     * ignored — the parent only recognizes its own compound child type.
+     */
+    children: ReactNode;
+    /**
+     * Name of the step to render on mount. Every step declared BEFORE
+     * `initialStep` in the visible sequence is marked as visited (so
+     * `allowJumpTo="visited"` allows the user to walk back through them).
+     *
+     * Common uses: resuming an interrupted wizard from persistent state,
+     * deep-linking to a specific step from a URL query.
+     *
+     * If the name doesn't match any visible step, falls back to the first
+     * visible step and dev-warns.
+     */
+    initialStep?: string;
+    /**
+     * Controls the `goToStep` (indicator-click) affordance:
+     *   - `'visited'` (default) — the user can jump only to steps they've
+     *                             already visited. Forward jumps are blocked
+     *                             because they'd bypass validation.
+     *   - `'none'`              — no jumping; navigation is strictly
+     *                             `goNext` / `goBack`.
+     *
+     * @default 'visited'
+     */
+    allowJumpTo?: 'visited' | 'none';
+    /**
+     * Fires when the user advances past the LAST visible step via
+     * `goNext()`. If this Stepper is wrapped in a `<DashForm>` and
+     * `onComplete` is omitted, the DashForm's own submit handler runs
+     * naturally on the consumer's Next button (typical pattern:
+     * `<Button type="submit">Finish</Button>` on the last step). Optional.
+     */
+    onComplete?: () => void;
+    /**
+     * Fires on every successful transition — moving forward, moving back,
+     * or jumping. Receives the previous step name, next step name, and
+     * the direction.
+     */
+    onStepChange?: (prev: string, next: string, reason: 'next' | 'back' | 'jump') => void;
+    /**
+     * Fires when `goNext()` blocks because validation failed. Useful for
+     * side-effects like scrolling the first invalid field into view or
+     * emitting a Snackbar toast.
+     */
+    onStepInvalid?: (payload: OnStepInvalidPayload) => void;
+    /** Colour intent applied to the indicator + connector fills. @default 'primary' */
+    color?: StepperVariants['color'];
+    /** Density knob (indicator diameter + label size). @default 'md' */
+    size?: StepperVariants['size'];
+    /** `horizontal` (default) or `vertical` strip layout. @default 'horizontal' */
+    orientation?: StepperVariants['orientation'];
+    /**
+     * `end` (label next to indicator, default) or `below` (label under
+     * the indicator, MUI `alternativeLabel` semantics). Horizontal only —
+     * ignored on `orientation='vertical'`.
+     * @default 'end'
+     */
+    labelPlacement?: StepperVariants['labelPlacement'];
+    /** Reactive visibility predicate for the whole Stepper. */
+    visibleWhen?: (engine: Engine) => boolean;
+    /** RBAC gate for the whole Stepper. */
+    access?: AccessRequirement;
+    /** Utility-class shortcut for `slotProps.root.className`. */
+    sx?: string;
+    /** Per-slot overrides. */
+    slotProps?: StepperSlotProps;
+    /** `data-testid` on the root wrapper. */
+    testId?: string;
+}
+//# sourceMappingURL=stepper.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Stepper/stepper.types.ts"],"names":[],"mappings":"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"}