@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/forms/state/vireoMultiStepStore/vireoMultiStepStore.d.ts

@@ -0,0 +1,64 @@
+import type { VireoMultiStepChangeEvent, VireoMultiStepDescriptor, VireoMultiStepNavigationResult, VireoMultiStepState, VireoMultiStepStepState } from "../../../../capabilities/forms/types/vireoMultiStep.types.js";
+import type { AnyFormApi } from "@tanstack/react-form";
+type Listener = () => void;
+export type VireoMultiStepRuntimeDescriptor = VireoMultiStepDescriptor<unknown, string>;
+export declare class VireoMultiStepStore {
+    readonly form: AnyFormApi;
+    private descriptors;
+    private listeners;
+    private visited;
+    private completed;
+    private errored;
+    private erroredStepValues;
+    private pendingRevalidationFields;
+    private revalidationScheduled;
+    private registeredSteps;
+    private errorSummaryElement?;
+    private currentStepId;
+    private direction;
+    private initialStepId;
+    private transitioning;
+    private transitionVersion;
+    private valueRevision;
+    private lastValues;
+    private pendingFocusStepId?;
+    private snapshot;
+    private unsubscribeForm?;
+    private onStepChange?;
+    constructor(form: AnyFormApi, descriptors: readonly VireoMultiStepRuntimeDescriptor[], initialStepId?: string, onStepChange?: (event: VireoMultiStepChangeEvent<string>) => void);
+    mount(): () => void;
+    update(descriptors: readonly VireoMultiStepRuntimeDescriptor[], onStepChange?: (event: VireoMultiStepChangeEvent<string>) => void): void;
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => VireoMultiStepState<string>;
+    getStepState: (id: string) => VireoMultiStepStepState<string> | undefined;
+    registerStep(id: string, element: HTMLElement | null): () => void;
+    registerErrorSummary(element: HTMLElement | null): () => void;
+    focusStep(id: string, retry?: boolean): void;
+    goToNextStep(): Promise<VireoMultiStepNavigationResult<string>>;
+    goToPreviousStep(): Promise<VireoMultiStepNavigationResult<string>>;
+    goToStep(requestedStepId: string): Promise<VireoMultiStepNavigationResult<string>>;
+    reset(): void;
+    handleInvalidSubmit(): Promise<void>;
+    private focusErrorSummary;
+    private navigateForward;
+    private validateStep;
+    private collectErrorPaths;
+    private changeStep;
+    private setCurrent;
+    private unchanged;
+    private handleFormChange;
+    private revalidateChangedErroredSteps;
+    private scheduleErroredStepRevalidation;
+    private refreshErrors;
+    private setStepErrored;
+    private getStepValues;
+    private reconcileActiveStep;
+    private getActiveDescriptors;
+    private rebuildSnapshot;
+    private emit;
+    private emitStepChange;
+    private getDirection;
+    private normalizeFields;
+    private assertStructure;
+}
+export {};

package/dist/capabilities/forms/state/vireoMultiStepStore/vireoMultiStepStore.js

@@ -0,0 +1,478 @@
+function normalizePath(path) {
+    return path.replace(/\[(\d+)\]/g, ".$1").replace(/^\./, "");
+}
+function ownsPath(owner, candidate) {
+    const normalizedOwner = normalizePath(owner);
+    const normalizedCandidate = normalizePath(candidate);
+    return normalizedCandidate === normalizedOwner || normalizedCandidate.startsWith(`${normalizedOwner}.`);
+}
+function hasErrors(meta) {
+    if (!meta || typeof meta !== "object" || !("errors" in meta))
+        return false;
+    return Array.isArray(meta.errors) && meta.errors.length > 0;
+}
+export class VireoMultiStepStore {
+    constructor(form, descriptors, initialStepId, onStepChange) {
+        this.listeners = new Set();
+        this.visited = new Set();
+        this.completed = new Set();
+        this.errored = new Set();
+        this.erroredStepValues = new Map();
+        this.pendingRevalidationFields = new Set();
+        this.revalidationScheduled = false;
+        this.registeredSteps = new Map();
+        this.direction = "forward";
+        this.transitioning = false;
+        this.transitionVersion = 0;
+        this.valueRevision = 0;
+        this.subscribe = (listener) => {
+            this.listeners.add(listener);
+            return () => this.listeners.delete(listener);
+        };
+        this.getSnapshot = () => this.snapshot;
+        this.getStepState = (id) => this.snapshot.steps.find(step => step.id === id);
+        this.form = form;
+        this.lastValues = form.state.values;
+        this.descriptors = descriptors.map(step => ({ ...step, fields: this.normalizeFields(step) }));
+        this.assertStructure();
+        const active = this.getActiveDescriptors();
+        if (active.length === 0)
+            throw new Error("A Vireo multi-step form requires at least one active step.");
+        const requestedInitial = active.find(step => step.id === initialStepId);
+        if (initialStepId && !requestedInitial && process.env.NODE_ENV !== "production") {
+            console.warn(`Vireo multi-step form initialStepId "${initialStepId}" is unavailable; using the first active step.`);
+        }
+        this.currentStepId = requestedInitial?.id ?? active[0].id;
+        this.initialStepId = this.currentStepId;
+        this.visited.add(this.currentStepId);
+        this.onStepChange = onStepChange;
+        this.rebuildSnapshot();
+    }
+    mount() {
+        if (!this.unsubscribeForm) {
+            this.lastValues = this.form.state.values;
+            this.unsubscribeForm = this.form.store.subscribe(() => this.handleFormChange());
+        }
+        return () => {
+            this.transitionVersion += 1;
+            this.pendingFocusStepId = undefined;
+            this.unsubscribeForm?.unsubscribe();
+            this.unsubscribeForm = undefined;
+            this.pendingRevalidationFields.clear();
+            this.revalidationScheduled = false;
+        };
+    }
+    update(descriptors, onStepChange) {
+        const nextStructure = descriptors.map(step => ({ id: step.id, fields: this.normalizeFields(step) }));
+        const currentStructure = this.descriptors.map(step => ({ id: step.id, fields: step.fields ?? [] }));
+        if (JSON.stringify(nextStructure) !== JSON.stringify(currentStructure)) {
+            if (process.env.NODE_ENV !== "production") {
+                console.error("Vireo multi-step form step ids, order, and field ownership must remain stable. Remount the form to change its structure.");
+            }
+            return;
+        }
+        this.descriptors = this.descriptors.map((step, index) => ({
+            ...step,
+            label: descriptors[index].label,
+            ariaLabel: descriptors[index].ariaLabel,
+            when: descriptors[index].when,
+        }));
+        this.onStepChange = onStepChange;
+        this.reconcileActiveStep("condition");
+        this.rebuildSnapshot();
+    }
+    registerStep(id, element) {
+        if (element) {
+            if (this.registeredSteps.has(id) &&
+                this.registeredSteps.get(id) !== element &&
+                process.env.NODE_ENV !== "production") {
+                console.warn(`Vireo multi-step form rendered more than one form.Step for "${id}".`);
+            }
+            this.registeredSteps.set(id, element);
+            if (this.pendingFocusStepId === id) {
+                window.requestAnimationFrame(() => this.focusStep(id, false));
+            }
+        }
+        return () => {
+            if (this.registeredSteps.get(id) === element)
+                this.registeredSteps.delete(id);
+        };
+    }
+    registerErrorSummary(element) {
+        this.errorSummaryElement = element ?? undefined;
+        return () => {
+            if (this.errorSummaryElement === element)
+                this.errorSummaryElement = undefined;
+        };
+    }
+    focusStep(id, retry = true) {
+        const step = this.registeredSteps.get(id);
+        if (!step) {
+            if (retry) {
+                window.requestAnimationFrame(() => {
+                    if (this.pendingFocusStepId === id)
+                        this.focusStep(id, false);
+                });
+            }
+            else if (this.pendingFocusStepId === id && process.env.NODE_ENV !== "production") {
+                console.warn(`Vireo multi-step form step "${id}" has no rendered form.Step content.`);
+            }
+            return;
+        }
+        step.focus();
+        step.scrollIntoView?.({ block: "nearest" });
+        if (this.pendingFocusStepId === id)
+            this.pendingFocusStepId = undefined;
+    }
+    async goToNextStep() {
+        const active = this.getActiveDescriptors();
+        const index = active.findIndex(step => step.id === this.currentStepId);
+        if (index >= active.length - 1)
+            return this.unchanged(this.currentStepId, "last-step");
+        return this.navigateForward(active[index + 1].id, "next");
+    }
+    async goToPreviousStep() {
+        if (this.transitioning)
+            return this.unchanged(this.currentStepId, "transition-pending");
+        const active = this.getActiveDescriptors();
+        const index = active.findIndex(step => step.id === this.currentStepId);
+        if (index <= 0)
+            return this.unchanged(this.currentStepId, "first-step");
+        const requested = active[index - 1].id;
+        return this.changeStep(requested, requested, "previous", "previous");
+    }
+    async goToStep(requestedStepId) {
+        if (this.transitioning)
+            return this.unchanged(requestedStepId, "transition-pending");
+        if (requestedStepId === this.currentStepId)
+            return this.unchanged(requestedStepId, "same-step");
+        const active = this.getActiveDescriptors();
+        const currentIndex = active.findIndex(step => step.id === this.currentStepId);
+        const requestedIndex = active.findIndex(step => step.id === requestedStepId);
+        if (requestedIndex < 0)
+            return this.unchanged(requestedStepId, "unavailable-step");
+        if (requestedIndex < currentIndex)
+            return this.changeStep(requestedStepId, requestedStepId, "direct", "direct");
+        return this.navigateForward(requestedStepId, "direct");
+    }
+    reset() {
+        const previous = this.currentStepId;
+        this.transitionVersion += 1;
+        this.transitioning = false;
+        this.visited.clear();
+        this.completed.clear();
+        this.errored.clear();
+        this.erroredStepValues.clear();
+        this.pendingRevalidationFields.clear();
+        const active = this.getActiveDescriptors();
+        this.currentStepId = active.some(step => step.id === this.initialStepId) ? this.initialStepId : active[0].id;
+        this.direction = this.getDirection(previous, this.currentStepId);
+        this.visited.add(this.currentStepId);
+        this.rebuildSnapshot();
+        this.emit();
+        if (previous !== this.currentStepId)
+            this.emitStepChange(previous, this.currentStepId, "reset");
+    }
+    async handleInvalidSubmit() {
+        const firstErrorPath = this.collectErrorPaths()[0];
+        if (!firstErrorPath) {
+            this.focusErrorSummary();
+            return;
+        }
+        const owner = this.getActiveDescriptors().find(step => (step.fields ?? []).some(field => ownsPath(field, firstErrorPath)));
+        if (!owner) {
+            this.focusErrorSummary();
+            return;
+        }
+        const previous = this.currentStepId;
+        if (owner.id !== previous) {
+            this.direction = this.getDirection(previous, owner.id);
+            this.setCurrent(owner.id);
+            this.emitStepChange(previous, owner.id, "validation-error");
+        }
+        window.requestAnimationFrame(() => {
+            const root = this.registeredSteps.get(owner.id);
+            const target = root?.querySelector('[aria-invalid="true"] [data-vireo-field-focus-target="true"], [aria-invalid="true"]:not([disabled]), [aria-invalid="true"] input:not([disabled])');
+            (target ?? root)?.focus();
+        });
+    }
+    focusErrorSummary() {
+        window.requestAnimationFrame(() => {
+            this.errorSummaryElement?.focus();
+            this.errorSummaryElement?.scrollIntoView?.({ block: "nearest" });
+        });
+    }
+    async navigateForward(requestedStepId, reason) {
+        if (this.transitioning)
+            return this.unchanged(requestedStepId, "transition-pending");
+        this.transitioning = true;
+        const transition = ++this.transitionVersion;
+        this.rebuildSnapshot();
+        this.emit();
+        try {
+            const validation = await this.validateStep(this.currentStepId, transition);
+            if (validation.cancelled)
+                return { status: "cancelled", stepId: this.currentStepId, requestedStepId, reason: validation.reason };
+            if (validation.errorPaths.length > 0) {
+                this.setStepErrored(this.currentStepId, true);
+                this.completed.delete(this.currentStepId);
+                this.rebuildSnapshot();
+                this.emit();
+                return { status: "invalid", stepId: this.currentStepId, requestedStepId, errorPaths: validation.errorPaths };
+            }
+            this.setStepErrored(this.currentStepId, false);
+            this.completed.add(this.currentStepId);
+            const active = this.getActiveDescriptors();
+            const currentIndex = active.findIndex(step => step.id === this.currentStepId);
+            const requestedIndex = active.findIndex(step => step.id === requestedStepId);
+            const incomplete = active.slice(currentIndex + 1, requestedIndex).find(step => !this.completed.has(step.id));
+            const destination = incomplete?.id ?? requestedStepId;
+            return this.changeStep(destination, requestedStepId, incomplete ? "incomplete-step" : reason, reason);
+        }
+        finally {
+            if (transition === this.transitionVersion) {
+                this.transitioning = false;
+                this.rebuildSnapshot();
+                this.emit();
+            }
+        }
+    }
+    async validateStep(stepId, transition) {
+        const step = this.descriptors.find(item => item.id === stepId);
+        if (!step)
+            return { cancelled: false, errorPaths: [] };
+        while (true) {
+            const revision = this.valueRevision;
+            await Promise.all((step.fields ?? []).map(field => this.form.validateField(field, "submit")));
+            if (transition !== this.transitionVersion)
+                return { cancelled: true, reason: "step-changed" };
+            if (revision !== this.valueRevision)
+                continue;
+            return { cancelled: false, errorPaths: this.collectErrorPaths(step.fields ?? []) };
+        }
+    }
+    collectErrorPaths(ownedFields) {
+        return Object.entries(this.form.state.fieldMeta)
+            .filter(([, meta]) => hasErrors(meta))
+            .map(([path]) => normalizePath(path))
+            .filter(path => !ownedFields || ownedFields.some(owner => ownsPath(owner, path)));
+    }
+    changeStep(stepId, requestedStepId, resultReason, eventReason) {
+        const previous = this.currentStepId;
+        this.pendingFocusStepId = stepId;
+        this.direction = this.getDirection(previous, stepId);
+        this.setCurrent(stepId);
+        this.emitStepChange(previous, stepId, eventReason);
+        window.requestAnimationFrame(() => this.focusStep(stepId));
+        return {
+            status: "changed",
+            previousStepId: previous,
+            stepId,
+            requestedStepId,
+            reachedRequestedStep: stepId === requestedStepId,
+            reason: resultReason,
+        };
+    }
+    setCurrent(stepId) {
+        this.currentStepId = stepId;
+        this.visited.add(stepId);
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    unchanged(requestedStepId, reason) {
+        return { status: "unchanged", stepId: this.currentStepId, requestedStepId, reason };
+    }
+    handleFormChange() {
+        const valuesChanged = this.form.state.values !== this.lastValues;
+        if (valuesChanged) {
+            this.lastValues = this.form.state.values;
+            this.valueRevision += 1;
+        }
+        this.revalidateChangedErroredSteps();
+        for (const step of this.descriptors) {
+            if (this.completed.has(step.id) &&
+                (step.fields ?? []).some(field => this.form.getFieldMeta(field)?.isDirty)) {
+                this.completed.delete(step.id);
+                this.visited.add(step.id);
+            }
+        }
+        this.reconcileActiveStep("condition");
+        this.refreshErrors();
+        this.rebuildSnapshot();
+        this.emit();
+    }
+    revalidateChangedErroredSteps() {
+        const changedSteps = this.descriptors.filter(step => {
+            if (!this.errored.has(step.id))
+                return false;
+            const values = this.getStepValues(step);
+            const previousValues = this.erroredStepValues.get(step.id);
+            if (previousValues && values.every((value, index) => Object.is(value, previousValues[index])))
+                return false;
+            this.erroredStepValues.set(step.id, values);
+            return true;
+        });
+        const fields = new Set(changedSteps.flatMap(step => step.fields ?? []));
+        if (fields.size === 0)
+            return;
+        fields.forEach(field => this.pendingRevalidationFields.add(field));
+        this.scheduleErroredStepRevalidation();
+    }
+    scheduleErroredStepRevalidation() {
+        if (this.revalidationScheduled)
+            return;
+        this.revalidationScheduled = true;
+        queueMicrotask(() => {
+            this.revalidationScheduled = false;
+            if (!this.unsubscribeForm || this.pendingRevalidationFields.size === 0)
+                return;
+            const fields = [...this.pendingRevalidationFields];
+            this.pendingRevalidationFields.clear();
+            // Field.handleChange performs its ordinary change validation after updating
+            // the form store. Run the step's submit validation in the next microtask so
+            // that this post-attempt revalidation is the final result for the new value.
+            void this.form.validate("submit", {
+                filterFieldNames: field => fields.some(owner => ownsPath(owner, String(field))),
+            });
+        });
+    }
+    refreshErrors() {
+        for (const step of this.descriptors) {
+            this.setStepErrored(step.id, (step.fields ?? []).some(field => this.collectErrorPaths([field]).length > 0));
+        }
+    }
+    setStepErrored(stepId, hasError) {
+        if (!hasError) {
+            this.errored.delete(stepId);
+            this.erroredStepValues.delete(stepId);
+            return;
+        }
+        this.errored.add(stepId);
+        if (this.erroredStepValues.has(stepId))
+            return;
+        const step = this.descriptors.find(descriptor => descriptor.id === stepId);
+        if (step)
+            this.erroredStepValues.set(stepId, this.getStepValues(step));
+    }
+    getStepValues(step) {
+        return (step.fields ?? []).map(field => this.form.getFieldValue(field));
+    }
+    reconcileActiveStep(reason) {
+        const active = this.getActiveDescriptors();
+        if (active.length === 0) {
+            if (process.env.NODE_ENV !== "production")
+                console.error("A Vireo multi-step form must always have at least one active step.");
+            return;
+        }
+        if (active.some(step => step.id === this.currentStepId))
+            return;
+        const declaredIndex = this.descriptors.findIndex(step => step.id === this.currentStepId);
+        const previous = [...active]
+            .reverse()
+            .find(step => this.descriptors.findIndex(item => item.id === step.id) < declaredIndex);
+        const destination = previous ??
+            active.find(step => this.descriptors.findIndex(item => item.id === step.id) > declaredIndex) ??
+            active[0];
+        const old = this.currentStepId;
+        this.direction = this.getDirection(old, destination.id);
+        this.currentStepId = destination.id;
+        this.visited.add(destination.id);
+        this.emitStepChange(old, destination.id, reason);
+    }
+    getActiveDescriptors() {
+        const values = this.form.state.values;
+        return this.descriptors.filter(step => !step.when || step.when(values));
+    }
+    rebuildSnapshot() {
+        const activeDescriptors = this.getActiveDescriptors();
+        const activeIds = new Set(activeDescriptors.map(step => step.id));
+        const steps = this.descriptors.map((step, declaredIndex) => {
+            const activeIndex = activeDescriptors.findIndex(item => item.id === step.id);
+            const isVisited = this.visited.has(step.id);
+            const isComplete = this.completed.has(step.id);
+            const hasError = this.errored.has(step.id);
+            return {
+                id: step.id,
+                label: step.label,
+                ariaLabel: step.ariaLabel,
+                fields: (step.fields ?? []),
+                declaredIndex,
+                activeIndex: activeIndex < 0 ? null : activeIndex,
+                isActive: activeIds.has(step.id),
+                isCurrent: step.id === this.currentStepId,
+                isVisited,
+                isComplete,
+                hasError,
+                canNavigate: activeIndex >= 0 && (isVisited || step.id === this.currentStepId),
+                status: !activeIds.has(step.id)
+                    ? null
+                    : hasError
+                        ? "error"
+                        : isComplete
+                            ? "complete"
+                            : isVisited
+                                ? "visited"
+                                : "upcoming",
+            };
+        });
+        const activeSteps = steps.filter(step => step.isActive);
+        const currentStepIndex = activeSteps.findIndex(step => step.id === this.currentStepId);
+        const currentStep = activeSteps[currentStepIndex] ?? activeSteps[0];
+        this.snapshot = {
+            steps,
+            activeSteps,
+            currentStep,
+            currentStepId: currentStep.id,
+            currentStepIndex,
+            direction: this.direction,
+            activeStepCount: activeSteps.length,
+            completedStepCount: activeSteps.filter(step => step.isComplete).length,
+            isFirstStep: currentStepIndex <= 0,
+            isLastStep: currentStepIndex >= activeSteps.length - 1,
+            isStepTransitioning: this.transitioning,
+            canGoPrevious: currentStepIndex > 0 && !this.transitioning,
+            canGoNext: currentStepIndex < activeSteps.length - 1 && !this.transitioning,
+            canSubmitCurrentStep: currentStepIndex === activeSteps.length - 1 && !this.transitioning,
+        };
+    }
+    emit() {
+        this.listeners.forEach(listener => listener());
+    }
+    emitStepChange(previousStepId, stepId, reason) {
+        const active = this.getActiveDescriptors();
+        const previousStepIndex = active.findIndex(step => step.id === previousStepId);
+        const stepIndex = active.findIndex(step => step.id === stepId);
+        this.onStepChange?.({
+            previousStepId,
+            stepId,
+            previousStepIndex,
+            stepIndex,
+            direction: this.getDirection(previousStepId, stepId),
+            reason,
+        });
+    }
+    getDirection(previousStepId, stepId) {
+        const previousIndex = this.descriptors.findIndex(step => step.id === previousStepId);
+        const stepIndex = this.descriptors.findIndex(step => step.id === stepId);
+        return stepIndex >= previousIndex ? "forward" : "backward";
+    }
+    normalizeFields(step) {
+        const normalized = [...new Set((step.fields ?? []).map(field => normalizePath(String(field))))];
+        return normalized.filter(field => !normalized.some(other => other !== field && ownsPath(other, field)));
+    }
+    assertStructure() {
+        const ids = new Set();
+        const owners = [];
+        for (const step of this.descriptors) {
+            if (ids.has(step.id))
+                throw new Error(`Vireo multi-step form step id "${step.id}" is duplicated.`);
+            ids.add(step.id);
+            for (const field of step.fields ?? []) {
+                const conflict = owners.find(owner => owner.stepId !== step.id && (ownsPath(owner.field, field) || ownsPath(field, owner.field)));
+                if (conflict)
+                    throw new Error(`Vireo multi-step field ownership overlaps between "${conflict.stepId}" and "${step.id}" at "${field}".`);
+                owners.push({ stepId: step.id, field });
+            }
+        }
+    }
+}

package/dist/capabilities/forms/types/vireoFile.types.d.ts

@@ -0,0 +1,9 @@
+import type React from "react";
+/** Responsive filename-overflow strategies shared by Vireo file fields. */
+export type VireoFormFileNameTruncation = "middle" | "end" | "none";
+/** Props supplied to an opt-in Vireo file preview renderer. */
+export type VireoFilePreviewRendererProps = {
+    file: File;
+};
+/** Component used to render an optional preview for a browser File. */
+export type VireoFilePreviewRenderer = React.ElementType<VireoFilePreviewRendererProps>;

package/dist/capabilities/forms/types/vireoFile.types.js

@@ -0,0 +1 @@
+export {};

package/dist/capabilities/forms/types/vireoMultiStep.types.d.ts

@@ -0,0 +1,98 @@
+import type { DeepKeys } from "@tanstack/react-form";
+import type React from "react";
+/** Metadata describing one stable step in a Vireo multi-step form. */
+export type VireoMultiStepDescriptor<TFormData, TStepId extends string = string> = {
+    id: TStepId;
+    label: React.ReactNode;
+    ariaLabel?: string;
+    fields?: readonly DeepKeys<TFormData>[];
+    when?: (values: TFormData) => boolean;
+};
+export type VireoMultiStepStatus = "upcoming" | "visited" | "complete" | "error";
+export type VireoMultiStepDirection = "forward" | "backward";
+/** Public state for one configured multi-step form step. */
+export type VireoMultiStepStepState<TStepId extends string = string> = {
+    id: TStepId;
+    label: React.ReactNode;
+    ariaLabel?: string;
+    fields: readonly string[];
+    declaredIndex: number;
+    activeIndex: number | null;
+    isActive: boolean;
+    isCurrent: boolean;
+    isVisited: boolean;
+    isComplete: boolean;
+    hasError: boolean;
+    canNavigate: boolean;
+    status: VireoMultiStepStatus | null;
+};
+/** Reactive public state exposed by a Vireo multi-step form. */
+export type VireoMultiStepState<TStepId extends string = string> = {
+    steps: readonly VireoMultiStepStepState<TStepId>[];
+    activeSteps: readonly VireoMultiStepStepState<TStepId>[];
+    currentStep: VireoMultiStepStepState<TStepId>;
+    currentStepId: TStepId;
+    currentStepIndex: number;
+    /** Direction of the most recent current-step change. */
+    direction: VireoMultiStepDirection;
+    activeStepCount: number;
+    completedStepCount: number;
+    isFirstStep: boolean;
+    isLastStep: boolean;
+    isStepTransitioning: boolean;
+    canGoPrevious: boolean;
+    canGoNext: boolean;
+    canSubmitCurrentStep: boolean;
+};
+export type VireoMultiStepChangeReason = "next" | "previous" | "direct" | "validation-error" | "condition" | "reset";
+export type VireoMultiStepChangeEvent<TStepId extends string = string> = {
+    previousStepId: TStepId;
+    stepId: TStepId;
+    previousStepIndex: number;
+    stepIndex: number;
+    direction: VireoMultiStepDirection;
+    reason: VireoMultiStepChangeReason;
+};
+export type VireoMultiStepNavigationResult<TStepId extends string = string> = {
+    status: "changed";
+    previousStepId: TStepId;
+    stepId: TStepId;
+    requestedStepId: TStepId;
+    reachedRequestedStep: boolean;
+    reason: "next" | "previous" | "direct" | "incomplete-step";
+} | {
+    status: "invalid";
+    stepId: TStepId;
+    requestedStepId: TStepId;
+    errorPaths: string[];
+} | {
+    status: "unchanged";
+    stepId: TStepId;
+    requestedStepId: TStepId;
+    reason: "first-step" | "last-step" | "same-step" | "unavailable-step" | "transition-pending";
+} | {
+    status: "cancelled";
+    stepId: TStepId;
+    requestedStepId: TStepId;
+    reason: "reset" | "step-changed" | "form-unmounted";
+};
+export type VireoFormMultiStepLocaleText = {
+    progressLabel: string;
+    previousButton: string;
+    nextButton: string;
+    stepCount: (context: {
+        current: number;
+        total: number;
+    }) => string;
+    currentStatus: string;
+    completeStatus: string;
+    errorStatus: string;
+    visitedStatus: string;
+    upcomingStatus: string;
+    openStepMenu: (context: {
+        label: string;
+        current: number;
+        total: number;
+    }) => string;
+};
+export declare const defaultVireoFormMultiStepLocaleText: VireoFormMultiStepLocaleText;

package/dist/capabilities/forms/types/vireoMultiStep.types.js

@@ -0,0 +1,12 @@
+export const defaultVireoFormMultiStepLocaleText = {
+    progressLabel: "Form progress",
+    previousButton: "Previous",
+    nextButton: "Next",
+    stepCount: ({ current, total }) => `Step ${current} of ${total}`,
+    currentStatus: "Current step",
+    completeStatus: "Complete",
+    errorStatus: "Contains errors",
+    visitedStatus: "Visited",
+    upcomingStatus: "Upcoming",
+    openStepMenu: ({ label, current, total }) => `${label}, step ${current} of ${total}. Open step menu`,
+};

package/dist/capabilities/forms/utils/vireoFile.d.ts

@@ -0,0 +1,5 @@
+import type { VireoFormFileNameTruncation } from "../../../capabilities/forms/types/vireoFile.types.js";
+export declare function formatVireoFileSize(bytes: number): string;
+export declare function acceptsVireoFile(file: Pick<File, "name" | "type">, accept?: string): boolean;
+export declare function acceptsVireoDragType(type: string, accept?: string): boolean;
+export declare function truncateVireoFileName(value: string, mode: VireoFormFileNameTruncation, availableWidth: number, measure: (candidate: string) => number): string;