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

package/stepper/state.js

@@ -0,0 +1,325 @@
+// Ported from Angular CDK stepper (src/cdk/stepper/stepper.ts `CdkStepper` / `CdkStep`, v22.2.2), MIT, © Google LLC.
+// The step state machine: selected index (controlled / uncontrolled), linear mode (previous steps must be completed or
+// optional), editable / optional / completed / error states, `stepControl` validation, interacted tracking, reset,
+// indicator type, navigability, content position (animation direction) and the header key manager (FocusKeyManager:
+// wrap, Home / End, vertical orientation for vertical steppers, RTL).
+// Rivet:
+// - serializable state (signals + plain data + the caller's callbacks) instead of directive instances: `CdkStepper`
+//   → `createStepperState` (region state), `CdkStep` → `createStepState`; methods → free functions (`selectStep`,
+//   `stepperNext`, `stepperPrevious`, `stepperReset`, `stepCompleted`, `stepIndicatorType`, …). No closures are created
+//   here (a `.ts` module is not resumable); read the functions inside bindings / handlers of the `.tsx` parts.
+// - `ContentChildren(CdkStep)` → steps register in creation order (`registerStep`; server render order = DOM order)
+//   and unregister on disposal; a step's index is its position in `state.steps` (read in bindings: removal re-indexes).
+// - `StepControl` = an object of accessors / booleans (`{ valid, invalid?, pending?, reset? }`) instead of Angular's
+//   `AbstractControl` / signal-forms `Field` (any form library fits: `@rivetjs/forms`, a hand-made `computed`).
+// - `STEPPER_GLOBAL_OPTIONS` (`showError`, `displayDefaultIndicatorType`) → Stepper options (`showError`,
+//   `displayDefaultIndicatorType`), the injection token has no counterpart (pass them per stepper / via a wrapper).
+// - `selectedIndexChange` → `onSelectedIndexChange` (+ two-way Signal `selectedIndex`), `selectionChange` →
+//   `onSelectionChange` (`StepperSelectionEvent` with the step states instead of step instances), step
+//   `interacted` output → `onInteracted`.
+// - `_keyManager` → `focusIndex` signal (the header that takes Tab; `null` = the selected one) + `stepperHeaderKeyDown`
+//   over the header elements in DOM order (`keys` `nextIndex`; no instance survives on a resumed page).
+// - out-of-bounds `selectedIndex` assignments throw as upstream's dev mode (always: there is no prod switch here).
+// Deviations: a step's `completed` / `hasError` / `editable` given as an accessor is read live and never overridden by
+//   `reset()` (upstream writes the override; Rivet cannot write a caller's accessor) — pass a Signal or a value to let
+//   `reset()` clear it.
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { controllable, controlledValue, setControlledValue } from "../interactions/controllable.js";
+import { nextIndex } from "../keys/index.js";
+/** The different states of the steps (upstream `STEP_STATE`). */
+export const STEP_STATE = {
+    NUMBER: "number",
+    EDIT: "edit",
+    DONE: "done",
+    ERROR: "error",
+};
+const isSignal = (v) => typeof v === "function" && typeof v.set === "function";
+const read = (v) => (typeof v === "function" ? v() : v);
+/** A signal for a plain value, the caller's Signal / accessor as is (`completed`, `hasError`, `editable`). */
+const own = (value, fallback) => value === undefined ? signal(fallback) : typeof value === "function" ? value : signal(value);
+const write = (target, value) => {
+    if (isSignal(target))
+        target.set(value);
+};
+/** Creates the stepper state (region state: a re-created region of a resumed page keeps it). */
+export function createStepperState(id, props = {}) {
+    return _regionState(() => ({
+        id,
+        selected: controllable(props.selectedIndex, props.defaultSelectedIndex ?? 0, props.onSelectedIndexChange),
+        steps: signal([]),
+        focusIndex: signal(null),
+        linear: props.linear ?? false,
+        orientation: props.orientation ?? "horizontal",
+        showError: props.showError,
+        displayDefaultIndicatorType: props.displayDefaultIndicatorType !== false,
+        semantics: props.semantics ?? "tabs",
+        readOnly: (props.semantics ?? "tabs") === "list" && !!props.isReadOnly,
+        onSelectionChange: props.onSelectionChange,
+    }));
+}
+/** Creates one step's state (region state). Register it with `registerStep`. */
+export function createStepState(props = {}) {
+    return _regionState(() => ({
+        interacted: signal(false),
+        completedOverride: own(props.completed, null),
+        customError: own(props.hasError, null),
+        editable: own(props.editable, true),
+        optional: props.optional ?? false,
+        state: props.state,
+        stepControl: props.stepControl,
+        label: props.label,
+        errorMessage: props.errorMessage,
+        onInteracted: props.onInteracted,
+    }));
+}
+/** Adds `step` to the stepper (once; creation order). */
+export function registerStep(state, step) {
+    const steps = untrack(state.steps);
+    if (!steps.includes(step))
+        state.steps.set([...steps, step]);
+}
+/** Removes `step`; a selection past the end moves back one step (upstream `steps.changes` handler). */
+export function unregisterStep(state, step) {
+    const steps = untrack(state.steps).filter((s) => s !== step);
+    state.steps.set(steps);
+    const selected = controlledValue(state.selected);
+    if (selected >= steps.length && selected > 0) {
+        if (!state.selected.isControlled || state.selected.isSignal)
+            state.selected.value.set(Math.max(selected - 1, 0));
+    }
+}
+// -------------------------------------------------------------------------------------------------
+// Reads (bindings)
+// -------------------------------------------------------------------------------------------------
+/** The selected index (reads the signal). */
+export const stepperSelectedIndex = (state) => state.selected.value();
+/** Number of registered steps (reads the signal). */
+export const stepCount = (state) => state.steps().length;
+/** Index of `step` (-1 before registration; reads the signal). */
+export const stepIndex = (state, step) => state.steps().indexOf(step);
+/** The orientation (live). */
+export const stepperOrientation = (state) => read(state.orientation);
+/** Whether `step` is the selected one (upstream `isSelected`). */
+export const stepIsSelected = (state, step) => stepIndex(state, step) === stepperSelectedIndex(state);
+/** Whether `step` is the last registered step. */
+export const stepIsLast = (state, step) => {
+    const steps = state.steps();
+    return steps.length > 0 && steps[steps.length - 1] === step;
+};
+function controlValid(control) {
+    return !!read(control.valid);
+}
+function controlInvalid(control) {
+    return control.invalid !== undefined ? !!read(control.invalid) : !read(control.valid);
+}
+function controlPending(control) {
+    return control.pending !== undefined ? !!read(control.pending) : false;
+}
+/** Upstream `completed` getter: the override, else interacted and valid. */
+export function stepCompleted(step) {
+    const override = step.completedOverride();
+    const interacted = step.interacted();
+    if (override != null)
+        return override;
+    return interacted && (!step.stepControl || controlValid(step.stepControl));
+}
+/** Upstream `hasError` getter: the custom error, else interacted and the control invalid. */
+export function stepHasError(step) {
+    const custom = step.customError();
+    return custom == null ? step.interacted() && !!step.stepControl && controlInvalid(step.stepControl) : custom;
+}
+/** Upstream `_showError`: the stepper's `showError`, else whether `hasError` was set explicitly. */
+export function stepShowError(state, step) {
+    return state.showError ?? step.customError() != null;
+}
+/** Whether the step is editable. */
+export const stepEditable = (step) => step.editable();
+/** Whether the step is optional. */
+export const stepOptional = (step) => !!read(step.optional);
+/** Type of indicator shown for the step (upstream `indicatorType`). */
+export function stepIndicatorType(state, step) {
+    const selected = stepIsSelected(state, step);
+    const completed = stepCompleted(step);
+    const defaultState = read(step.state) ?? STEP_STATE.NUMBER;
+    const editable = step.editable();
+    if (stepShowError(state, step) && stepHasError(step) && !selected)
+        return STEP_STATE.ERROR;
+    if (state.displayDefaultIndicatorType) {
+        if (!completed || selected)
+            return STEP_STATE.NUMBER;
+        return editable ? STEP_STATE.EDIT : STEP_STATE.DONE;
+    }
+    if (completed && !selected)
+        return STEP_STATE.DONE;
+    if (completed && selected)
+        return defaultState;
+    return editable && selected ? STEP_STATE.EDIT : defaultState;
+}
+/** Whether the user can navigate to the step (upstream `isNavigable`). */
+export function stepIsNavigable(state, step) {
+    return stepCompleted(step) || stepIsSelected(state, step) || !read(state.linear);
+}
+/** Position of a step's content relative to the selected one (upstream `_getAnimationDirection`). */
+export function stepContentPosition(state, index, direction = "ltr") {
+    const position = index - stepperSelectedIndex(state);
+    if (position < 0)
+        return direction === "rtl" ? "next" : "previous";
+    if (position > 0)
+        return direction === "rtl" ? "previous" : "next";
+    return "current";
+}
+/** Index of the header that takes Tab (upstream `_getFocusIndex`). */
+export const stepperFocusIndex = (state) => state.focusIndex() ?? stepperSelectedIndex(state);
+/** Id of a step's header (upstream `_getStepLabelId`). */
+export const stepLabelId = (state, index) => `${state.id}-label-${index}`;
+/** Id of a step's content (upstream `_getStepContentId`). */
+export const stepContentId = (state, index) => `${state.id}-content-${index}`;
+// -------------------------------------------------------------------------------------------------
+// Actions (handlers)
+// -------------------------------------------------------------------------------------------------
+/** Upstream `_markAsInteracted`. */
+export function markStepInteracted(step) {
+    if (!untrack(step.interacted)) {
+        step.interacted.set(true);
+        step.onInteracted?.();
+    }
+}
+function anyControlsInvalidOrPending(state, index) {
+    if (!untrack(() => read(state.linear)) || index < 0)
+        return false;
+    return untrack(() => state
+        .steps()
+        .slice(0, index)
+        .some((step) => {
+        const control = step.stepControl;
+        const isIncomplete = control ? controlInvalid(control) || controlPending(control) || !step.interacted() : !stepCompleted(step);
+        return isIncomplete && !read(step.optional) && !step.completedOverride();
+    }));
+}
+/** Whether `index` is a valid step index (upstream `_isValidIndex`). */
+export function isValidStepIndex(state, index) {
+    const count = untrack(state.steps).length;
+    return index > -1 && (count === 0 || index < count);
+}
+/**
+ * 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 function selectStep(state, index) {
+    const steps = untrack(state.steps);
+    if (!steps.length) {
+        // Upstream: before the steps exist the index is stored as is.
+        if (!state.selected.isControlled || state.selected.isSignal)
+            state.selected.value.set(index);
+        else
+            state.selected.onChange?.(index);
+        return;
+    }
+    if (!isValidStepIndex(state, index))
+        throw new Error("cdkStepper: Cannot assign out-of-bounds value to `selectedIndex`.");
+    const current = controlledValue(state.selected);
+    if (current === index)
+        return;
+    const currentStep = steps[current];
+    if (currentStep)
+        markStepInteracted(currentStep);
+    if (!anyControlsInvalidOrPending(state, index) && (index >= current || untrack(steps[index].editable)))
+        updateSelectedIndex(state, index);
+}
+function updateSelectedIndex(state, index) {
+    const steps = untrack(state.steps);
+    const previous = controlledValue(state.selected);
+    state.onSelectionChange?.({
+        selectedIndex: index,
+        previouslySelectedIndex: previous,
+        selectedStep: steps[index],
+        previouslySelectedStep: steps[previous],
+    });
+    // Upstream: focus inside the stepper moves to the new header (else the key manager only updates its active item).
+    const header = focusedStepperHeaders(state);
+    state.focusIndex.set(null);
+    setControlledValue(state.selected, index);
+    if (header)
+        header[index]?.focus();
+}
+/** Upstream `next()`: selects the next step (the last one stays). */
+export function stepperNext(state) {
+    selectStep(state, Math.min(controlledValue(state.selected) + 1, untrack(state.steps).length - 1));
+}
+/** Upstream `previous()`: selects the previous step. */
+export function stepperPrevious(state) {
+    selectStep(state, Math.max(controlledValue(state.selected) - 1, 0));
+}
+/** Upstream `CdkStep.reset()`: interacted, completed / error overrides and the step control. */
+export function stepReset(step) {
+    step.interacted.set(false);
+    if (untrack(step.completedOverride) != null)
+        write(step.completedOverride, false);
+    if (untrack(step.customError) != null)
+        write(step.customError, false);
+    step.stepControl?.reset?.();
+}
+/** Upstream `reset()`: back to the first step (no validation) and every step reset. */
+export function stepperReset(state) {
+    if (controlledValue(state.selected) !== 0)
+        updateSelectedIndex(state, 0);
+    for (const step of untrack(state.steps))
+        stepReset(step);
+}
+/**
+ * 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 function markVisitedSteps(state) {
+    const selected = controlledValue(state.selected);
+    if (!untrack(() => read(state.linear)) || selected <= 0)
+        return;
+    for (const step of untrack(state.steps).slice(0, selected))
+        markStepInteracted(step);
+}
+// -------------------------------------------------------------------------------------------------
+// Keyboard (upstream `_onKeydown` + FocusKeyManager)
+// -------------------------------------------------------------------------------------------------
+/** Header elements of the stepper in DOM order (tabs semantics: `[data-rv-step-header="<id>"]`). */
+export function stepperHeaders(root, state) {
+    return [...root.querySelectorAll(`[data-rv-step-header="${state.id}"]`)];
+}
+function focusedStepperHeaders(state) {
+    if (typeof document === "undefined")
+        return null;
+    const active = document.activeElement;
+    const root = active?.closest?.(`[data-rv-stepper="${state.id}"]`);
+    return root ? stepperHeaders(root, state) : null;
+}
+/** Keys the header key manager handles (a `data-rk` value: held while the handler chunk loads). */
+export function stepperKeys(orientation) {
+    return orientation === "vertical" ? "ArrowDown ArrowUp ArrowLeft ArrowRight Home End Enter Space" : "ArrowLeft ArrowRight Home End Enter Space";
+}
+/**
+ * `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 function stepperHeaderKeyDown(state, event, direction = "ltr") {
+    const header = event.currentTarget;
+    const root = header.closest(`[data-rv-stepper="${state.id}"]`);
+    if (!root)
+        return;
+    const headers = stepperHeaders(root, state);
+    const active = headers.indexOf(header);
+    const hasModifier = event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+    if (active < 0 || hasModifier)
+        return;
+    if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        selectStep(state, active);
+        return;
+    }
+    const vertical = read(state.orientation) === "vertical";
+    const next = nextIndex(headers.length, active, event.key, { orientation: vertical ? "both" : "horizontal", wrap: true, homeEnd: true, dir: direction });
+    if (next == null)
+        return;
+    event.preventDefault();
+    state.focusIndex.set(next);
+    headers[next]?.focus();
+}

package/switch/behaviour.d.ts

@@ -0,0 +1,12 @@
+import type { ToggleState } from "../state/toggle.js";
+import { type AriaToggleProps, type InputRef, type ToggleAria } from "../checkbox/behaviour.jsx";
+/** RA `AriaSwitchProps`. */
+export interface AriaSwitchProps extends AriaToggleProps {
+}
+/** RA `SwitchAria`. */
+export type SwitchAria = ToggleAria;
+/**
+ * Provides the behavior and accessibility implementation for a switch component.
+ * A switch is similar to a checkbox, but represents on/off values as opposed to selection.
+ */
+export declare function switchProps(props: AriaSwitchProps, state: ToggleState, inputRef?: InputRef): SwitchAria;

package/switch/behaviour.jsx

@@ -0,0 +1,9 @@
+import { toggleProps } from "../checkbox/behaviour.jsx";
+/**
+ * Provides the behavior and accessibility implementation for a switch component.
+ * A switch is similar to a checkbox, but represents on/off values as opposed to selection.
+ */
+export function switchProps(props, state, inputRef) {
+    const res = toggleProps(props, state, inputRef);
+    return { ...res, inputProps: { ...res.inputProps, role: "switch", checked: () => state.selected() } };
+}

package/switch/index.d.ts

@@ -0,0 +1,150 @@
+import { type ToggleState } from "../state/toggle.js";
+import { type HoverEvents } from "../interactions/hover.jsx";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type ContextValue, type RACValidation, type RefValue, type RenderProps, type SlotProps } from "../slots/index.jsx";
+import { type InputRef } from "../checkbox/behaviour.jsx";
+import { type AriaSwitchProps } from "./behaviour.jsx";
+export interface SwitchProps extends Omit<AriaSwitchProps, "children" | "validationBehavior" | "isRequired" | "isInvalid" | "validate" | "validationErrors">, HoverEvents, RenderProps<SwitchRenderProps>, DOMRenderProps<"label", SwitchRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLLabelElement>, "onClick" | "style"> {
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-Switch'
+     */
+    class?: RenderProps<SwitchRenderProps>["class"];
+    /** A ref for the HTML input element. */
+    inputRef?: InputRef;
+    ref?: RefValue<HTMLLabelElement>;
+}
+export interface SwitchFieldProps extends Omit<AriaSwitchProps, "children" | "validationBehavior" | "validationErrors">, RACValidation, RenderProps<SwitchFieldRenderProps>, DOMRenderProps<"div", SwitchFieldRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLDivElement>, "onClick" | "style"> {
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-SwitchField'
+     */
+    class?: RenderProps<SwitchFieldRenderProps>["class"];
+    /** A ref for the HTML input element. */
+    inputRef?: InputRef;
+    ref?: RefValue<HTMLDivElement>;
+}
+export interface SwitchButtonProps extends HoverEvents, RenderProps<SwitchButtonRenderProps>, DOMRenderProps<"label", SwitchButtonRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLLabelElement>, "style"> {
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-SwitchButton'
+     */
+    class?: RenderProps<SwitchButtonRenderProps>["class"];
+    ref?: RefValue<HTMLLabelElement>;
+}
+export interface SwitchRenderProps {
+    /**
+     * Whether the switch is selected.
+     *
+     * @selector [data-selected]
+     */
+    isSelected: () => boolean;
+    /**
+     * Whether the switch is currently hovered with a mouse.
+     *
+     * @selector [data-hovered]
+     */
+    isHovered: () => boolean;
+    /**
+     * Whether the switch is currently in a pressed state.
+     *
+     * @selector [data-pressed]
+     */
+    isPressed: () => boolean;
+    /**
+     * Whether the switch is focused, either via a mouse or keyboard.
+     *
+     * @selector [data-focused]
+     */
+    isFocused: () => boolean;
+    /**
+     * Whether the switch is keyboard focused.
+     *
+     * @selector [data-focus-visible]
+     */
+    isFocusVisible: () => boolean;
+    /**
+     * Whether the switch is disabled.
+     *
+     * @selector [data-disabled]
+     */
+    isDisabled: () => boolean;
+    /**
+     * Whether the switch is read only.
+     *
+     * @selector [data-readonly]
+     */
+    isReadOnly: () => boolean;
+    /** State of the switch. */
+    state: ToggleState;
+}
+export interface SwitchFieldRenderProps {
+    /**
+     * Whether the switch is selected.
+     *
+     * @selector [data-selected]
+     */
+    isSelected: () => boolean;
+    /**
+     * Whether the switch is disabled.
+     *
+     * @selector [data-disabled]
+     */
+    isDisabled: () => boolean;
+    /**
+     * Whether the switch is read only.
+     *
+     * @selector [data-readonly]
+     */
+    isReadOnly: () => boolean;
+    /**
+     * Whether the switch is invalid.
+     *
+     * @selector [data-invalid]
+     */
+    isInvalid: () => boolean;
+    /**
+     * Whether the switch is required.
+     *
+     * @selector [data-required]
+     */
+    isRequired: () => boolean;
+    /** State of the switch. */
+    state: ToggleState;
+}
+export interface SwitchButtonRenderProps extends SwitchRenderProps {
+    /**
+     * Whether the switch is invalid.
+     *
+     * @selector [data-invalid]
+     */
+    isInvalid: () => boolean;
+    /**
+     * Whether the switch is required.
+     *
+     * @selector [data-required]
+     */
+    isRequired: () => boolean;
+}
+/** RAC `SwitchContext`. */
+export declare const SwitchContext: import("@rivetjs/reactivity").Context<ContextValue<SwitchProps, HTMLLabelElement>>;
+/** RAC `SwitchFieldContext`. */
+export declare const SwitchFieldContext: import("@rivetjs/reactivity").Context<ContextValue<SwitchFieldProps, HTMLDivElement>>;
+/** RAC `ToggleStateContext`. */
+export declare const ToggleStateContext: import("@rivetjs/reactivity").Context<ToggleState | null>;
+/**
+ * A switch allows a user to turn a setting on or off.
+ */
+export declare function Switch(props: SwitchProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/**
+ * A switch allows a user to turn a setting on or off, with support for validation and help text.
+ */
+export declare function SwitchField(props: SwitchFieldProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;
+/**
+ * A switch button is the clickable area of a switch, including the indicator and label.
+ */
+export declare function SwitchButton(props: SwitchButtonProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;