@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/stepper/index.jsx

@@ -0,0 +1,405 @@
+// Ported from Angular CDK stepper (src/cdk/stepper/{stepper.ts,step-header.ts,step-label.ts,stepper-button.ts}, v22.2.2)
+// + the accessible markup of Angular Material's stepper (src/material/stepper/stepper.html), MIT, © Google LLC.
+// A wizard-like workflow divided into steps: `Stepper` (state + root) > `StepList` (header strip) > `Step` (one step:
+// state, context) > `StepHeader` (selects the step) / `StepLabel`; `StepPanel` (the step's content); `StepperNext` /
+// `StepperPrevious` buttons. State machine + keyboard = `./state.ts`.
+// Rivet:
+// - components instead of directives: `CdkStepper` → `Stepper` (+ `StepList`: Material's header container),
+//   `CdkStep` → `Step`, `CdkStepHeader` → `StepHeader`, `CdkStepLabel` → `StepLabel`, Material's content containers →
+//   `StepPanel`, `CdkStepperNext` / `CdkStepperPrevious` → `StepperNext` / `StepperPrevious` (cdk `Button`, `type`
+//   default `"submit"` / `"button"` as upstream). RAC-style render props (accessors), `class` / `style` functions,
+//   `render` (DOMRenderProps), `*Context` tokens (`rv-stepper`, `rv-step`), `GlobalDOMAttributes` on every part.
+// - ARIA (upstream recommends Material's tabbed view): `semantics="tabs"` (default) = Material: horizontal → `StepList`
+//   `role="tablist"` + `aria-orientation`, headers `role="tab"` + `aria-selected` + `aria-controls`, panels `tabpanel`;
+//   vertical → headers `role="button"` + `aria-expanded` + `aria-current="step"`, panels `role="region"`; roving
+//   tabindex (the selected / last focused header), non-navigable headers `aria-disabled="true"`, arrow keys (+ Home /
+//   End, wrap, RTL) through `stepperHeaderKeyDown`, Enter / Space select. Rivet `semantics="list"` = an ordered list
+//   (`Stepper` → `ol`, `Step` → `li` with `aria-current="step"`), headers are native `<button type="button">`s in the
+//   Tab order (progress indicators / timelines without panels); `isReadOnly` renders them as plain `div`s.
+// - `aria-posinset` / `aria-setsize` are not written (Material does): the set size is unknown while the server renders
+//   the first steps; browsers derive both from the tabs inside the tablist (step wrappers are generic elements).
+// - inactive panels are `hidden` + `inert` (Material: `inert` + CSS); `data-position` (`previous` / `current` /
+//   `next`, RTL-aware, upstream `_getAnimationDirection`) on every panel for transitions.
+// - resumable: nothing runs at load (no effect, no listener); the root carries `preload="visible"` (its handlers +
+//   the bindings they update are fetched / evaluated when the stepper is visible, so the first click / key is
+//   synchronous on slow networks).
+import { createContext, onCleanup, provide, untrack, useContext } from "@rivetjs/reactivity";
+import { Provider } from "@rivetjs/runtime/dom";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { Button } from "../button/index.jsx";
+import { useLocale } from "../i18n/index.js";
+import { dataBool, focusStateBlur, focusStateFocus, hoverStateEnter, hoverStateLeave } from "../utils/data-attrs.jsx";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { createId } from "../utils/id.js";
+import { renderProps as resolveRenderProps } from "../slots/index.jsx";
+import { createStepState, createStepperState, markStepInteracted, registerStep, selectStep, stepCompleted, stepContentId, stepContentPosition, stepCount, stepEditable, stepHasError, stepIndex, stepIndicatorType, stepIsLast, stepIsNavigable, stepIsSelected, stepLabelId, stepOptional, stepperFocusIndex, stepperHeaderKeyDown, stepperKeys, stepperNext, stepperOrientation, stepperPrevious, stepperReset, stepperSelectedIndex, stepShowError, unregisterStep, } from "./state.js";
+export * from "./state.js";
+// =================================================================================================
+// Contexts
+// =================================================================================================
+/** The state of the nearest `Stepper` (`null` outside one). */
+export const StepperContext = resumableContext(createContext(null, { id: "rv-stepper" }));
+export const StepContext = resumableContext(createContext(null, { id: "rv-step" }));
+/** The nearest `Stepper`'s API. */
+export function useStepper() {
+    const state = useContext(StepperContext);
+    if (!state)
+        throw new Error("useStepper must be used within a Stepper.");
+    return {
+        state,
+        selectedIndex: () => stepperSelectedIndex(state),
+        stepCount: () => stepCount(state),
+        orientation: () => stepperOrientation(state),
+        select: (index) => selectStep(state, index),
+        next: () => stepperNext(state),
+        previous: () => stepperPrevious(state),
+        reset: () => stepperReset(state),
+    };
+}
+/** The nearest `Step`'s render props (throws outside a `Step`). */
+export function useStep() {
+    const ctx = useContext(StepContext);
+    if (!ctx)
+        throw new Error("useStep must be used within a Step.");
+    return stepValues(ctx.stepper, ctx.step);
+}
+function stepValues(stepper, step) {
+    return {
+        index: () => stepIndex(stepper, step),
+        isSelected: () => stepIsSelected(stepper, step),
+        isCompleted: () => stepCompleted(step),
+        hasError: () => stepShowError(stepper, step) && stepHasError(step),
+        isNavigable: () => stepIsNavigable(stepper, step),
+        isOptional: () => stepOptional(step),
+        isEditable: () => stepEditable(step),
+        isLast: () => stepIsLast(stepper, step),
+        state: () => stepIndicatorType(stepper, step),
+        orientation: () => stepperOrientation(stepper),
+    };
+}
+function stepperOf() {
+    const state = useContext(StepperContext);
+    if (!state)
+        throw new Error("Stepper parts must be used within a Stepper.");
+    return state;
+}
+function stepOf(part) {
+    const ctx = useContext(StepContext);
+    if (!ctx)
+        throw new Error(`${part} must be used within a Step.`);
+    return ctx;
+}
+/** The stepper root: owns the state (upstream `CdkStepper`). `div` (tabs semantics) or `ol` (list semantics). */
+export function Stepper(props) {
+    const { class: cls, style, children, render, ref } = props;
+    const id = props.id ?? createId();
+    const state = createStepperState(id, props);
+    const values = {
+        selectedIndex: () => stepperSelectedIndex(state),
+        stepCount: () => stepCount(state),
+        orientation: () => stepperOrientation(state),
+    };
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-Stepper" });
+    const dom = globalDOMProps(props, ["style"]);
+    const list = state.semantics === "list";
+    const ariaLabel = props["aria-label"];
+    const ariaLabelledby = props["aria-labelledby"];
+    const readOnly = state.readOnly;
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id,
+            "aria-label": list ? ariaLabel : undefined,
+            "aria-labelledby": list ? ariaLabelledby : undefined,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-rv-stepper": id,
+            "data-orientation": () => stepperOrientation(state),
+            "data-selected-index": () => stepperSelectedIndex(state),
+            "data-readonly": dataBool(readOnly),
+            children: () => (<Provider token={StepperContext} value={state}>
+          {rp.children()}
+        </Provider>),
+        };
+        return render(attrs, values);
+    }
+    if (list) {
+        return (<ol {...dom} ref={ref} id={id} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} class={rp.class()} style={rp.style()} data-rv-stepper={id} data-orientation={stepperOrientation(state)} data-selected-index={stepperSelectedIndex(state)} data-readonly={dataBool(readOnly)} preload="visible">
+        {provide(StepperContext, state, () => rp.children())}
+      </ol>);
+    }
+    return (<div {...dom} ref={ref} id={id} class={rp.class()} style={rp.style()} data-rv-stepper={id} data-orientation={stepperOrientation(state)} data-selected-index={stepperSelectedIndex(state)} preload="visible">
+      {provide(StepperContext, state, () => rp.children())}
+    </div>);
+}
+/**
+ * The header strip (Material's header container): `role="tablist"` + `aria-orientation` for a horizontal tabs
+ * stepper, a plain `div` otherwise. `aria-label` / `aria-labelledby` land here.
+ */
+export function StepList(props) {
+    const state = stepperOf();
+    const { class: cls, style, children, render, ref } = props;
+    const values = {
+        selectedIndex: () => stepperSelectedIndex(state),
+        stepCount: () => stepCount(state),
+        orientation: () => stepperOrientation(state),
+    };
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-StepList" });
+    const dom = globalDOMProps(props, ["style"]);
+    const tabs = state.semantics === "tabs";
+    const ariaLabel = props["aria-label"];
+    const ariaLabelledby = props["aria-labelledby"];
+    const id = props.id;
+    const role = () => (tabs && stepperOrientation(state) === "horizontal" ? "tablist" : undefined);
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id,
+            role: () => role(),
+            "aria-orientation": () => (role() ? "horizontal" : undefined),
+            "aria-label": ariaLabel,
+            "aria-labelledby": ariaLabelledby,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-orientation": () => stepperOrientation(state),
+            children: () => rp.children(),
+        };
+        return render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} id={id} role={role()} aria-orientation={role() ? "horizontal" : undefined} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} class={rp.class()} style={rp.style()} data-orientation={stepperOrientation(state)}>
+      {rp.children()}
+    </div>);
+}
+/** One step (upstream `CdkStep`): registers with the stepper, provides `StepContext`. `div` or `li` (list semantics). */
+export function Step(props) {
+    const stepper = stepperOf();
+    const { class: cls, style, children, render, ref } = props;
+    const step = createStepState(props);
+    registerStep(stepper, step);
+    // Upstream ngAfterViewInit: a linear stepper starting past this step marks it visited (navigable back to).
+    untrack(() => {
+        if ((typeof stepper.linear === "function" ? stepper.linear() : stepper.linear) && stepper.steps().indexOf(step) < stepper.selected.value())
+            markStepInteracted(step);
+    });
+    onCleanup(() => unregisterStep(stepper, step));
+    const values = stepValues(stepper, step);
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-Step" });
+    const dom = globalDOMProps(props, ["style"]);
+    const list = stepper.semantics === "list";
+    const ctx = { stepper, step };
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id: props.id,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "aria-current": () => (list && values.isSelected() ? "step" : undefined),
+            "data-index": () => values.index(),
+            "data-selected": () => dataBool(values.isSelected()),
+            "data-completed": () => dataBool(values.isCompleted()),
+            "data-invalid": () => dataBool(values.hasError()),
+            "data-disabled": () => dataBool(!values.isNavigable()),
+            "data-optional": () => dataBool(values.isOptional()),
+            "data-editable": () => dataBool(values.isEditable()),
+            "data-state": () => values.state(),
+            "data-orientation": () => values.orientation(),
+            children: () => (<Provider token={StepContext} value={ctx}>
+          {rp.children()}
+        </Provider>),
+        };
+        return render(attrs, values);
+    }
+    if (list) {
+        return (<li {...dom} ref={ref} id={props.id} class={rp.class()} style={rp.style()} aria-current={values.isSelected() ? "step" : undefined} data-index={values.index()} data-selected={dataBool(values.isSelected())} data-completed={dataBool(values.isCompleted())} data-invalid={dataBool(values.hasError())} data-disabled={dataBool(!values.isNavigable())} data-optional={dataBool(values.isOptional())} data-editable={dataBool(values.isEditable())} data-state={values.state()} data-orientation={values.orientation()}>
+        {provide(StepContext, ctx, () => rp.children())}
+      </li>);
+    }
+    return (<div {...dom} ref={ref} id={props.id} class={rp.class()} style={rp.style()} data-index={values.index()} data-selected={dataBool(values.isSelected())} data-completed={dataBool(values.isCompleted())} data-invalid={dataBool(values.hasError())} data-disabled={dataBool(!values.isNavigable())} data-optional={dataBool(values.isOptional())} data-editable={dataBool(values.isEditable())} data-state={values.state()} data-orientation={values.orientation()}>
+      {provide(StepContext, ctx, () => rp.children())}
+    </div>);
+}
+/** Global DOM events the header handles itself (its handler runs first, then the user's). */
+const HEADER_OWNED = ["onClick", "onPointerEnter", "onPointerLeave", "style"];
+/**
+ * The step's header (upstream `CdkStepHeader` + Material's header attributes): click / Enter / Space select the step
+ * (validation permitting), arrows move focus between headers (tabs semantics). Default content: the step `label`.
+ */
+export function StepHeader(props) {
+    const { stepper, step } = stepOf("StepHeader");
+    const { class: cls, style, children, render, ref, onClick, onPointerEnter, onPointerLeave } = props;
+    const values = stepValues(stepper, step);
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-StepHeader", defaultChildren: step.label });
+    const dom = globalDOMProps(props, HEADER_OWNED);
+    const direction = useLocale().direction;
+    const list = stepper.semantics === "list";
+    const ariaLabel = props["aria-label"];
+    const ariaLabelledby = ariaLabel ? undefined : props["aria-labelledby"];
+    const readOnly = stepper.readOnly;
+    const interaction = {};
+    const vertical = () => stepperOrientation(stepper) === "vertical";
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id: () => stepLabelId(stepper, values.index()),
+            type: list && !readOnly ? "button" : undefined,
+            role: () => (list ? undefined : vertical() ? "button" : "tab"),
+            tabindex: () => (list ? undefined : stepperFocusIndex(stepper) === values.index() ? 0 : -1),
+            "aria-selected": () => (list || vertical() ? undefined : values.isSelected() ? "true" : "false"),
+            "aria-current": () => (!list && vertical() && values.isSelected() ? "step" : undefined),
+            "aria-expanded": () => (!list && vertical() ? (values.isSelected() ? "true" : "false") : undefined),
+            "aria-controls": () => (list ? undefined : stepContentId(stepper, values.index())),
+            "aria-disabled": () => (readOnly || values.isNavigable() ? undefined : "true"),
+            "aria-label": ariaLabel,
+            "aria-labelledby": ariaLabelledby,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-rv-step-header": stepper.id,
+            "data-rk": list ? undefined : stepperKeys(stepperOrientation(stepper)),
+            "data-selected": () => dataBool(values.isSelected()),
+            "data-completed": () => dataBool(values.isCompleted()),
+            "data-invalid": () => dataBool(values.hasError()),
+            "data-disabled": () => dataBool(!values.isNavigable()),
+            "data-state": () => values.state(),
+            onClick: (event) => {
+                if (!readOnly)
+                    selectStep(stepper, stepIndex(stepper, step));
+                onClick?.(event);
+            },
+            onKeyDown: (event) => {
+                if (!list)
+                    stepperHeaderKeyDown(stepper, event, direction);
+            },
+            onPointerEnter: (event) => {
+                hoverStateEnter(interaction, event);
+                onPointerEnter?.(event);
+            },
+            onPointerLeave: (event) => {
+                hoverStateLeave(interaction, event);
+                onPointerLeave?.(event);
+            },
+            onFocus: (event) => focusStateFocus(interaction, event),
+            onBlur: (event) => focusStateBlur(interaction, event),
+            children: () => rp.children(),
+        };
+        return render(attrs, values);
+    }
+    if (readOnly) {
+        return (<div {...dom} ref={ref} id={stepLabelId(stepper, values.index())} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} class={rp.class()} style={rp.style()} data-selected={dataBool(values.isSelected())} data-completed={dataBool(values.isCompleted())} data-invalid={dataBool(values.hasError())} data-state={values.state()}>
+        {rp.children()}
+      </div>);
+    }
+    if (list) {
+        return (<button {...dom} ref={ref} type="button" id={stepLabelId(stepper, values.index())} aria-disabled={values.isNavigable() ? undefined : "true"} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} class={rp.class()} style={rp.style()} data-rv-step-header={stepper.id} data-selected={dataBool(values.isSelected())} data-completed={dataBool(values.isCompleted())} data-invalid={dataBool(values.hasError())} data-disabled={dataBool(!values.isNavigable())} data-state={values.state()} onClick={(event) => {
+                selectStep(stepper, stepIndex(stepper, step));
+                onClick?.(event);
+            }} onPointerEnter={(event) => {
+                hoverStateEnter(interaction, event);
+                onPointerEnter?.(event);
+            }} onPointerLeave={(event) => {
+                hoverStateLeave(interaction, event);
+                onPointerLeave?.(event);
+            }} onFocus={(event) => focusStateFocus(interaction, event)} onBlur={(event) => focusStateBlur(interaction, event)}>
+        {rp.children()}
+      </button>);
+    }
+    return (<div {...dom} ref={ref} id={stepLabelId(stepper, values.index())} role={vertical() ? "button" : "tab"} tabIndex={stepperFocusIndex(stepper) === values.index() ? 0 : -1} aria-selected={vertical() ? undefined : values.isSelected() ? "true" : "false"} aria-current={vertical() && values.isSelected() ? "step" : undefined} aria-expanded={vertical() ? (values.isSelected() ? "true" : "false") : undefined} aria-controls={stepContentId(stepper, values.index())} aria-disabled={values.isNavigable() ? undefined : "true"} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} class={rp.class()} style={rp.style()} data-rv-step-header={stepper.id} data-rk={stepperKeys(stepperOrientation(stepper))} data-selected={dataBool(values.isSelected())} data-completed={dataBool(values.isCompleted())} data-invalid={dataBool(values.hasError())} data-disabled={dataBool(!values.isNavigable())} data-state={values.state()} onClick={(event) => {
+            selectStep(stepper, stepIndex(stepper, step));
+            onClick?.(event);
+        }} onKeyDown={(event) => stepperHeaderKeyDown(stepper, event, direction)} onPointerEnter={(event) => {
+            hoverStateEnter(interaction, event);
+            onPointerEnter?.(event);
+        }} onPointerLeave={(event) => {
+            hoverStateLeave(interaction, event);
+            onPointerLeave?.(event);
+        }} onFocus={(event) => focusStateFocus(interaction, event)} onBlur={(event) => focusStateBlur(interaction, event)}>
+      {rp.children()}
+    </div>);
+}
+/** The step's label (upstream `CdkStepLabel`): a `div` inside the header, with the step's state attributes. */
+export function StepLabel(props) {
+    const { stepper, step } = stepOf("StepLabel");
+    const { class: cls, style, children, render, ref } = props;
+    const values = stepValues(stepper, step);
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-StepLabel", defaultChildren: step.label });
+    const dom = globalDOMProps(props, ["style"]);
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id: props.id,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-selected": () => dataBool(values.isSelected()),
+            "data-invalid": () => dataBool(values.hasError()),
+            children: () => rp.children(),
+        };
+        return render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} id={props.id} class={rp.class()} style={rp.style()} data-selected={dataBool(values.isSelected())} data-invalid={dataBool(values.hasError())}>
+      {rp.children()}
+    </div>);
+}
+/**
+ * The content of a step (Material's content containers): `role="tabpanel"` (horizontal) / `"region"` (vertical),
+ * labelled by the header; hidden + inert unless its step is selected; `data-position` previous / current / next.
+ */
+export function StepPanel(props) {
+    const stepper = stepperOf();
+    const ctx = useContext(StepContext);
+    const fixed = props.index;
+    const owner = ctx?.stepper === stepper ? ctx.step : undefined;
+    const { class: cls, style, children, render, ref } = props;
+    const direction = useLocale().direction;
+    const index = () => (fixed !== undefined ? fixed : owner ? stepIndex(stepper, owner) : -1);
+    const values = {
+        index,
+        isSelected: () => stepperSelectedIndex(stepper) === index(),
+        position: () => stepContentPosition(stepper, index(), direction),
+        orientation: () => stepperOrientation(stepper),
+    };
+    const rp = resolveRenderProps({ class: cls, style, children, values, defaultClassName: "rv-StepPanel" });
+    const dom = globalDOMProps(props, ["style", "hidden", "inert"]);
+    const tabs = stepper.semantics === "tabs";
+    if (render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id: () => stepContentId(stepper, index()),
+            role: () => (!tabs ? undefined : stepperOrientation(stepper) === "vertical" ? "region" : "tabpanel"),
+            "aria-labelledby": () => stepLabelId(stepper, index()),
+            hidden: () => !values.isSelected() || undefined,
+            inert: () => !values.isSelected() || undefined,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-position": () => values.position(),
+            "data-selected": () => dataBool(values.isSelected()),
+            children: () => rp.children(),
+        };
+        return render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} id={stepContentId(stepper, index())} role={!tabs ? undefined : stepperOrientation(stepper) === "vertical" ? "region" : "tabpanel"} aria-labelledby={stepLabelId(stepper, index())} hidden={!values.isSelected()} inert={!values.isSelected()} class={rp.class()} style={rp.style()} data-position={values.position()} data-selected={dataBool(values.isSelected())}>
+      {rp.children()}
+    </div>);
+}
+/** Moves to the next step (upstream `CdkStepperNext`; `type` default `"submit"`). */
+export function StepperNext(props) {
+    const stepper = stepperOf();
+    const userPress = props.onPress;
+    return (<Button type="submit" {...props} onPress={(event) => {
+            stepperNext(stepper);
+            userPress?.(event);
+        }}/>);
+}
+/** Moves to the previous step (upstream `CdkStepperPrevious`; `type` default `"button"`). */
+export function StepperPrevious(props) {
+    const stepper = stepperOf();
+    const userPress = props.onPress;
+    return (<Button type="button" {...props} onPress={(event) => {
+            stepperPrevious(stepper);
+            userPress?.(event);
+        }}/>);
+}

package/stepper/state.d.ts

@@ -0,0 +1,200 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+import type { Direction } from "../bidi/index.js";
+/** Position state of the content of each step (upstream `StepContentPositionState`), used for transitions. */
+export type StepContentPositionState = "previous" | "current" | "next";
+/** Possible orientation of a stepper (upstream `StepperOrientation`). */
+export type StepperOrientation = "horizontal" | "vertical";
+/**
+ * ARIA pattern of the stepper (Rivet). `"tabs"` (default, Angular Material's accessible stepper): the header strip is a
+ * `tablist`, headers are `tab`s with roving tabindex + arrow keys (horizontal) or `button`s with `aria-expanded` /
+ * `aria-current="step"` (vertical), panels `tabpanel` / `region`. `"list"`: an ordered list (`ol` / `li`) with
+ * `aria-current="step"`; interactive headers are native buttons in the Tab order (progress indicators without panels).
+ */
+export type StepperSemantics = "tabs" | "list";
+/** A plain value or an accessor (read live). */
+export type MaybeAccessor<T> = T | (() => T);
+/**
+ * Validation hook of a step (upstream `StepControl`: an `AbstractControl` / signal-forms `Field`). Values may be
+ * accessors (read live) or booleans; `invalid` defaults to `!valid`, `pending` to `false`.
+ */
+export interface StepControl {
+    valid: MaybeAccessor<boolean>;
+    invalid?: MaybeAccessor<boolean>;
+    pending?: MaybeAccessor<boolean>;
+    /** Called by `stepperReset` / `stepReset` (clear the form). */
+    reset?: () => void;
+}
+/** The state of each step (upstream `StepState`). */
+export type StepState = "number" | "edit" | "done" | "error" | (string & {});
+/** The different states of the steps (upstream `STEP_STATE`). */
+export declare const STEP_STATE: {
+    readonly NUMBER: "number";
+    readonly EDIT: "edit";
+    readonly DONE: "done";
+    readonly ERROR: "error";
+};
+/** Change event emitted on selection changes (upstream `StepperSelectionEvent`). */
+export interface StepperSelectionEvent {
+    /** Index of the step now selected. */
+    selectedIndex: number;
+    /** Index of the step previously selected. */
+    previouslySelectedIndex: number;
+    /** The step now selected. */
+    selectedStep: StepItemState | undefined;
+    /** The step previously selected. */
+    previouslySelectedStep: StepItemState | undefined;
+}
+/** Stepper options (upstream `CdkStepper` inputs + `StepperOptions`). */
+export interface StepperStateProps {
+    /** The index of the selected step: a value (controlled), a two-way Signal, or an accessor. */
+    selectedIndex?: number | Signal<number> | (() => number);
+    /** Initial selected index (uncontrolled). @default 0 */
+    defaultSelectedIndex?: number;
+    /** Called with the new index when the selection changes (upstream `selectedIndexChange`). */
+    onSelectedIndexChange?: (index: number) => void;
+    /** Called when the selected step changes (upstream `selectionChange`). */
+    onSelectionChange?: (event: StepperSelectionEvent) => void;
+    /** Whether the validity of previous steps should be checked (upstream `linear`; read at event time). @default false */
+    linear?: MaybeAccessor<boolean>;
+    /** Orientation of the stepper (upstream `orientation`; read live). @default "horizontal" */
+    orientation?: MaybeAccessor<StepperOrientation>;
+    /** Whether the stepper shows an error state (upstream `StepperOptions.showError`). */
+    showError?: boolean;
+    /** Whether the default indicator type is used (upstream `StepperOptions.displayDefaultIndicatorType`). @default true */
+    displayDefaultIndicatorType?: boolean;
+    /** Rivet: ARIA pattern (read once). @default "tabs" */
+    semantics?: StepperSemantics;
+    /** Rivet, list semantics: headers are display only (plain elements, no handlers). @default false */
+    isReadOnly?: boolean;
+}
+/** Stepper state (serializable). */
+export interface StepperState {
+    /** Id prefix of the header / content ids (upstream `_groupId`). */
+    readonly id: string;
+    /** Selected index (`controllable`). */
+    readonly selected: ControlledState<number>;
+    /** Registered steps of this stepper, in order. */
+    readonly steps: Signal<StepItemState[]>;
+    /** Index of the header that takes Tab (upstream key manager `activeItemIndex`); `null` = the selected step's. */
+    readonly focusIndex: Signal<number | null>;
+    readonly linear: MaybeAccessor<boolean>;
+    readonly orientation: MaybeAccessor<StepperOrientation>;
+    readonly showError: boolean | undefined;
+    readonly displayDefaultIndicatorType: boolean;
+    readonly semantics: StepperSemantics;
+    /** List semantics: display-only headers (`isReadOnly`). */
+    readonly readOnly: boolean;
+    readonly onSelectionChange: ((event: StepperSelectionEvent) => void) | undefined;
+}
+/** Step options (upstream `CdkStep` inputs). */
+export interface StepStateProps {
+    /** Validation hook (upstream `stepControl`); takes precedence over `completed` for completion. */
+    stepControl?: StepControl;
+    /** Plain text label of the step. */
+    label?: string;
+    /** Error message shown when the step has an error. */
+    errorMessage?: string;
+    /** Custom state of the step (upstream `state`: the indicator type when completed / not editable). */
+    state?: MaybeAccessor<StepState | undefined>;
+    /** Whether the user can return to this step once it has been marked as completed. @default true */
+    editable?: boolean | Signal<boolean> | (() => boolean);
+    /** Whether the completion of the step is optional. @default false */
+    optional?: MaybeAccessor<boolean>;
+    /** Overrides the completed state (upstream `completed`): a value, a two-way Signal or an accessor. */
+    completed?: boolean | Signal<boolean> | (() => boolean);
+    /** Overrides the error state (upstream `hasError`): a value, a two-way Signal or an accessor. */
+    hasError?: boolean | Signal<boolean> | (() => boolean);
+    /** Called the first time the user attempts to move away from the step (upstream `interacted` output). */
+    onInteracted?: () => void;
+}
+/** One step's state (serializable). */
+export interface StepItemState {
+    readonly interacted: Signal<boolean>;
+    /** Upstream `_completedOverride` (`null`: derived). An accessor `completed` is read here, never written. */
+    readonly completedOverride: Signal<boolean | null> | (() => boolean | null);
+    /** Upstream `_customError` (`null`: derived from `stepControl`). */
+    readonly customError: Signal<boolean | null> | (() => boolean | null);
+    /** Upstream `_editable`. */
+    readonly editable: Signal<boolean> | (() => boolean);
+    readonly optional: MaybeAccessor<boolean>;
+    readonly state: MaybeAccessor<StepState | undefined>;
+    readonly stepControl: StepControl | undefined;
+    readonly label: string | undefined;
+    readonly errorMessage: string | undefined;
+    readonly onInteracted: (() => void) | undefined;
+}
+/** Creates the stepper state (region state: a re-created region of a resumed page keeps it). */
+export declare function createStepperState(id: string, props?: StepperStateProps): StepperState;
+/** Creates one step's state (region state). Register it with `registerStep`. */
+export declare function createStepState(props?: StepStateProps): StepItemState;
+/** Adds `step` to the stepper (once; creation order). */
+export declare function registerStep(state: StepperState, step: StepItemState): void;
+/** Removes `step`; a selection past the end moves back one step (upstream `steps.changes` handler). */
+export declare function unregisterStep(state: StepperState, step: StepItemState): void;
+/** The selected index (reads the signal). */
+export declare const stepperSelectedIndex: (state: StepperState) => number;
+/** Number of registered steps (reads the signal). */
+export declare const stepCount: (state: StepperState) => number;
+/** Index of `step` (-1 before registration; reads the signal). */
+export declare const stepIndex: (state: StepperState, step: StepItemState) => number;
+/** The orientation (live). */
+export declare const stepperOrientation: (state: StepperState) => StepperOrientation;
+/** Whether `step` is the selected one (upstream `isSelected`). */
+export declare const stepIsSelected: (state: StepperState, step: StepItemState) => boolean;
+/** Whether `step` is the last registered step. */
+export declare const stepIsLast: (state: StepperState, step: StepItemState) => boolean;
+/** Upstream `completed` getter: the override, else interacted and valid. */
+export declare function stepCompleted(step: StepItemState): boolean;
+/** Upstream `hasError` getter: the custom error, else interacted and the control invalid. */
+export declare function stepHasError(step: StepItemState): boolean;
+/** Upstream `_showError`: the stepper's `showError`, else whether `hasError` was set explicitly. */
+export declare function stepShowError(state: StepperState, step: StepItemState): boolean;
+/** Whether the step is editable. */
+export declare const stepEditable: (step: StepItemState) => boolean;
+/** Whether the step is optional. */
+export declare const stepOptional: (step: StepItemState) => boolean;
+/** Type of indicator shown for the step (upstream `indicatorType`). */
+export declare function stepIndicatorType(state: StepperState, step: StepItemState): StepState;
+/** Whether the user can navigate to the step (upstream `isNavigable`). */
+export declare function stepIsNavigable(state: StepperState, step: StepItemState): boolean;
+/** Position of a step's content relative to the selected one (upstream `_getAnimationDirection`). */
+export declare function stepContentPosition(state: StepperState, index: number, direction?: Direction): StepContentPositionState;
+/** Index of the header that takes Tab (upstream `_getFocusIndex`). */
+export declare const stepperFocusIndex: (state: StepperState) => number;
+/** Id of a step's header (upstream `_getStepLabelId`). */
+export declare const stepLabelId: (state: StepperState, index: number) => string;
+/** Id of a step's content (upstream `_getStepContentId`). */
+export declare const stepContentId: (state: StepperState, index: number) => string;
+/** Upstream `_markAsInteracted`. */
+export declare function markStepInteracted(step: StepItemState): void;
+/** Whether `index` is a valid step index (upstream `_isValidIndex`). */
+export declare function isValidStepIndex(state: StepperState, index: number): boolean;
+/**
+ * Upstream `selectedIndex` setter: marks the current step interacted, then selects `index` unless a previous step of a
+ * linear stepper is invalid / pending / not completed, or `index` is before the current step and not editable.
+ * Throws for an out-of-bounds index once steps are registered.
+ */
+export declare function selectStep(state: StepperState, index: number): void;
+/** Upstream `next()`: selects the next step (the last one stays). */
+export declare function stepperNext(state: StepperState): void;
+/** Upstream `previous()`: selects the previous step. */
+export declare function stepperPrevious(state: StepperState): void;
+/** Upstream `CdkStep.reset()`: interacted, completed / error overrides and the step control. */
+export declare function stepReset(step: StepItemState): void;
+/** Upstream `reset()`: back to the first step (no validation) and every step reset. */
+export declare function stepperReset(state: StepperState): void;
+/**
+ * Upstream `ngAfterViewInit`: a linear stepper starting past step 0 marks the visited steps interacted (so they can be
+ * navigated back to). Call once the steps are registered.
+ */
+export declare function markVisitedSteps(state: StepperState): void;
+/** Header elements of the stepper in DOM order (tabs semantics: `[data-rv-step-header="<id>"]`). */
+export declare function stepperHeaders(root: ParentNode, state: StepperState): HTMLElement[];
+/** Keys the header key manager handles (a `data-rk` value: held while the handler chunk loads). */
+export declare function stepperKeys(orientation: StepperOrientation): string;
+/**
+ * `keydown` on a step header (tabs semantics): Enter / Space (no modifier) select the focused header's step; arrows
+ * move focus (horizontal: Left / Right; vertical: all four), wrapping, Home / End; RTL reverses Left / Right.
+ */
+export declare function stepperHeaderKeyDown(state: StepperState, event: KeyboardEvent, direction?: Direction): void;