@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/forms/components/forms/VireoFormSelectMultipleField/VireoFormSelectMultipleField.types.d.ts

@@ -0,0 +1,158 @@
+import type { VireoFormErrorDisplay, VireoFormErrorFormatter } from "../../../../../capabilities/forms/components/forms/VireoForm/VireoForm.types.js";
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Checkbox, FormControl, FormHelperText, IconButton, InputLabel, ListItemText, MenuItem, OutlinedInput, Select, SelectProps, TextFieldProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormSelectMultipleFieldClasses, type VireoFormSelectMultipleFieldClassKey } from "./VireoFormSelectMultipleField.classes.js";
+import type { VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME } from "./VireoFormSelectMultipleField.identity.js";
+/** Scalar option identifiers stored in arrays by `field.SelectMultipleField`. */
+export type VireoFormSelectMultipleFieldValue = string | number;
+export type VireoFormSelectMultipleFieldOwnerState = {
+    dirty: boolean;
+    disabled: boolean;
+    errorVisible: boolean;
+    hasValue: boolean;
+    invalid: boolean;
+    readOnly: boolean;
+    submitting: boolean;
+    touched: boolean;
+    validating: boolean;
+};
+export type VireoFormSelectMultipleFieldRenderSelectedOptionsParams<TOption> = {
+    /** Every recognized selected option, in the bound value array's order. */
+    selectedOptions: readonly TOption[];
+    /** The leading options included by `maxDisplayedOptions`. */
+    displayedOptions: readonly TOption[];
+    /** Number of recognized selected options omitted from `displayedOptions`. */
+    hiddenCount: number;
+    /** Resolved non-negative compact-summary limit. */
+    maxDisplayedOptions: number;
+};
+export interface VireoFormSelectMultipleFieldRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldInputLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldHtmlInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldSelectSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldSelectionSummarySlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldOptionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldOptionCheckboxSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldOptionTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldClearButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectMultipleFieldFormHelperTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by the bound form multiple-select field. */
+export type VireoFormSelectMultipleFieldSlots = {
+    root: React.ElementType;
+    inputLabel: React.ElementType;
+    input: React.ElementType;
+    htmlInput: React.ElementType;
+    select: React.ElementType;
+    selectionSummary: React.ElementType;
+    option: React.ElementType;
+    optionCheckbox: React.ElementType;
+    optionText: React.ElementType;
+    clearButton: React.ElementType;
+    formHelperText: React.ElementType;
+};
+/** Slot props exposed by the bound form multiple-select field. */
+export type VireoFormSelectMultipleFieldSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormSelectMultipleFieldSlots, {
+    /** @default FormControl */
+    root: SlotProps<typeof FormControl, VireoFormSelectMultipleFieldRootSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default InputLabel */
+    inputLabel: SlotProps<typeof InputLabel, VireoFormSelectMultipleFieldInputLabelSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default OutlinedInput; follows `variant` for standard and filled fields. */
+    input: SlotProps<typeof OutlinedInput, VireoFormSelectMultipleFieldInputSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default 'input' */
+    htmlInput: SlotProps<"input", VireoFormSelectMultipleFieldHtmlInputSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default Select */
+    select: SlotProps<typeof Select, VireoFormSelectMultipleFieldSelectSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default Typography */
+    selectionSummary: SlotProps<typeof Typography, VireoFormSelectMultipleFieldSelectionSummarySlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default MenuItem */
+    option: SlotProps<typeof MenuItem, VireoFormSelectMultipleFieldOptionSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default Checkbox */
+    optionCheckbox: SlotProps<typeof Checkbox, VireoFormSelectMultipleFieldOptionCheckboxSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default ListItemText */
+    optionText: SlotProps<typeof ListItemText, VireoFormSelectMultipleFieldOptionTextSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default IconButton */
+    clearButton: SlotProps<typeof IconButton, VireoFormSelectMultipleFieldClearButtonSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+    /** @default FormHelperText */
+    formHelperText: SlotProps<typeof FormHelperText, VireoFormSelectMultipleFieldFormHelperTextSlotPropsOverrides, VireoFormSelectMultipleFieldOwnerState>;
+}>;
+type VireoFormSelectMultipleFieldComponentOwnedProp = "FormHelperTextProps" | "InputLabelProps" | "InputProps" | "SelectProps" | "children" | "classes" | "defaultValue" | "disabled" | "error" | "fullWidth" | "helperText" | "inputProps" | "inputRef" | "maxRows" | "minRows" | "multiline" | "name" | "onBlur" | "onChange" | "required" | "rows" | "select" | "slotProps" | "slots" | "type" | "value";
+/** Props inherited from MUI TextField after excluding form-owned and Vireo-owned props. */
+export type VireoFormSelectMultipleFieldInheritedProps = Omit<TextFieldProps, VireoFormSelectMultipleFieldComponentOwnedProp>;
+/** Props owned by the bound form multiple-select field. The field name and array value remain owned by `form.Field`. */
+export type VireoFormSelectMultipleFieldOwnProps<TOption, TValue extends VireoFormSelectMultipleFieldValue> = VireoFormSelectMultipleFieldSlotsAndSlotProps & {
+    /** Accessible label used by the visible select control. */
+    label: React.ReactNode;
+    /** Options rendered by the field. */
+    options: readonly TOption[];
+    /** Returns the stable non-empty scalar value stored for one option. */
+    getOptionValue: (option: TOption) => TValue;
+    /** Renders one dropdown option and the default selected-value summary item. */
+    renderOption: (option: TOption) => React.ReactNode;
+    /** Replaces the complete selected-value presentation. */
+    renderSelectedOptions?: (params: VireoFormSelectMultipleFieldRenderSelectedOptionsParams<TOption>) => React.ReactNode;
+    /** Maximum option labels shown by the compact default summary. @default 2 */
+    maxDisplayedOptions?: number;
+    /** Returns whether one option is unavailable. */
+    getOptionDisabled?: (option: TOption) => boolean;
+    /** Override or extend the utility classes applied to each slot and state. */
+    classes?: Partial<VireoFormSelectMultipleFieldClasses>;
+    disabled?: boolean;
+    /** Adds an error presentation state without suppressing validation errors. */
+    error?: boolean;
+    /** Overrides the enclosing form's error-display policy for this field. */
+    errorDisplay?: VireoFormErrorDisplay;
+    /** Overrides the enclosing form's validation-error formatter for this field. */
+    formatError?: VireoFormErrorFormatter;
+    /** @default true */
+    fullWidth?: boolean;
+    /** Shown when no visible validation error takes precedence. Defaults to a reserved line; pass `null` to remove it. @default ' ' */
+    helperText?: React.ReactNode;
+    /** Text rendered when the bound value is empty. */
+    placeholder?: React.ReactNode;
+    /** Prevents all selected values from being cleared at once. @default false */
+    disableClearable?: boolean;
+    /** Accessible label for the clear-all action. @default 'Clear selections' */
+    clearLabel?: string;
+    /** Replaces the default clear icon without replacing the button slot. */
+    clearIcon?: React.ReactNode;
+    /** Ref forwarded to MUI's select input. */
+    inputRef?: SelectProps<TValue[]>["inputRef"];
+    onBlur?: NonNullable<SelectProps<TValue[]>["onBlur"]>;
+    /** Observes accepted selection and clear-all changes after cancelable slot handlers. */
+    onValueChange?: (value: TValue[]) => void;
+    readOnly?: boolean;
+    required?: boolean;
+};
+/** Props accepted by `field.SelectMultipleField`. */
+export type VireoFormSelectMultipleFieldProps<TOption = unknown, TValue extends VireoFormSelectMultipleFieldValue = VireoFormSelectMultipleFieldValue> = VireoFormSelectMultipleFieldOwnProps<TOption, TValue> & VireoFormSelectMultipleFieldInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME]?: VireoThemeComponent<VireoFormSelectMultipleFieldProps, VireoFormSelectMultipleFieldClassKey, VireoFormSelectMultipleFieldOwnerState, Theme>;
+    }
+}
+export {};

package/dist/capabilities/forms/components/forms/VireoFormSelectMultipleField/VireoFormSelectMultipleField.types.js

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

package/dist/capabilities/forms/components/forms/VireoFormSelectMultipleField/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoFormSelectMultipleField.js";
+export * from "./VireoFormSelectMultipleField.classes.js";
+export * from "./VireoFormSelectMultipleField.types.js";

package/dist/capabilities/forms/components/forms/VireoFormSelectMultipleField/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoFormSelectMultipleField.js";
+export * from "./VireoFormSelectMultipleField.classes.js";
+export * from "./VireoFormSelectMultipleField.types.js";

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.classes.d.ts

@@ -0,0 +1,9 @@
+import { type VireoFormStepSlotName } from "./VireoFormStep.identity.js";
+/** Utility classes available to VireoFormStep. */
+export type VireoFormStepClasses = Record<VireoFormStepSlotName, string>;
+/** Valid keys for VireoFormStep utility classes and theme style overrides. */
+export type VireoFormStepClassKey = keyof VireoFormStepClasses;
+/** Returns the generated utility class name for a VireoFormStep slot or state. */
+export declare function getVireoFormStepUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoFormStep class key. */
+export declare const vireoFormStepClasses: VireoFormStepClasses;

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.classes.js

@@ -0,0 +1,10 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_FORM_STEP_NAME, VIREO_FORM_STEP_SLOTS } from "./VireoFormStep.identity.js";
+/** Returns the generated utility class name for a VireoFormStep slot or state. */
+export function getVireoFormStepUtilityClass(slot) {
+    return generateUtilityClass(VIREO_FORM_STEP_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoFormStep class key. */
+export const vireoFormStepClasses = generateUtilityClasses(VIREO_FORM_STEP_NAME, [
+    ...VIREO_FORM_STEP_SLOTS,
+]);

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import { type VireoFormStepProps } from "./VireoFormStep.types.js";
+/** Renders the currently active configured step as an independently labelled form region. */
+export declare const VireoFormStep: React.ForwardRefExoticComponent<Omit<VireoFormStepProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.identity.d.ts

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoFormStep integration point. */
+export declare const VIREO_FORM_STEP_NAME = "VireoFormStep";
+/** Canonical public slots exposed by VireoFormStep, in rendered DOM order. */
+export declare const VIREO_FORM_STEP_SLOTS: readonly ["root", "label"];
+/** Public slot names exposed by VireoFormStep. */
+export type VireoFormStepSlotName = (typeof VIREO_FORM_STEP_SLOTS)[number];

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.identity.js

@@ -0,0 +1,4 @@
+/** Stable component name shared by every VireoFormStep integration point. */
+export const VIREO_FORM_STEP_NAME = "VireoFormStep";
+/** Canonical public slots exposed by VireoFormStep, in rendered DOM order. */
+export const VIREO_FORM_STEP_SLOTS = ["root", "label"];

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { unstable_composeClasses as composeClasses } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import React from "react";
+import { useVireoMultiStepContext } from "../../../../../capabilities/forms/contexts/VireoMultiStepContext/VireoMultiStepContext.js";
+import { getVireoFormStepUtilityClass } from "./VireoFormStep.classes.js";
+import { VIREO_FORM_STEP_NAME } from "./VireoFormStep.identity.js";
+import { VireoFormStepLabel, VireoFormStepRoot } from "./VireoFormStep.styled.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        label: ["label"],
+    }, getVireoFormStepUtilityClass, classes);
+}
+/** Renders the currently active configured step as an independently labelled form region. */
+export const VireoFormStep = React.forwardRef(function VireoFormStep(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_STEP_NAME });
+    const { children, className, classes: classesProp, id, slotProps = {}, slots = {}, style, sx, ...other } = props;
+    const { controller, keepMounted } = useVireoMultiStepContext();
+    const state = React.useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const step = state.steps.find(item => item.id === id);
+    if (!step && process.env.NODE_ENV !== "production") {
+        console.warn(`Vireo form.Step received unknown step id "${id}".`);
+    }
+    const ownerState = {
+        active: step?.isActive ?? false,
+        current: step?.isCurrent ?? false,
+        direction: state.direction,
+        keepMounted,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedLabelSlotProps = resolveSlotProps(slotProps.label, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const internalRef = React.useRef(null);
+    const rootRef = useForkRef(forwardedRef, rootSlotRef, internalRef);
+    const { className: labelSlotClassName, ...labelSlotOther } = resolvedLabelSlotProps;
+    const generatedLabelId = React.useId();
+    const labelId = `vireo-form-step-${generatedLabelId}`;
+    React.useLayoutEffect(() => controller.registerStep(id, internalRef.current), [controller, id, step?.isCurrent, step?.isActive, keepMounted]);
+    if (!step?.isActive || (!step.isCurrent && !keepMounted))
+        return null;
+    return (_jsxs(VireoFormStepRoot, { ...other, ...rootSlotOther, as: slots.root ?? "section", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), "aria-labelledby": step.ariaLabel ? undefined : labelId, "aria-label": step.ariaLabel, hidden: !step.isCurrent, tabIndex: -1, children: [!step.ariaLabel && (_jsx(VireoFormStepLabel, { ...labelSlotOther, as: slots.label, id: labelId, ownerState: ownerState, className: joinClassNames(classes.label, labelSlotClassName), children: step.label })), children] }));
+});
+VireoFormStep.displayName = VIREO_FORM_STEP_NAME;

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.styled.d.ts

@@ -0,0 +1,7 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type TypographyProps } from "@mui/material";
+import { type VireoFormStepOwnerState } from "./VireoFormStep.types.js";
+type VireoFormStepStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormStepOwnerState>;
+export declare const VireoFormStepRoot: VireoFormStepStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepLabel: VireoFormStepStyledSlotComponent<TypographyProps>;
+export {};

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.styled.js

@@ -0,0 +1,42 @@
+import { VIREO_MOTION_TOKENS } from "../../../../../core/public.js";
+import { Box, Typography } from "@mui/material";
+import { keyframes, styled } from "@mui/material/styles";
+import { VIREO_FORM_STEP_NAME } from "./VireoFormStep.identity.js";
+const enterForward = keyframes({
+    from: { opacity: 0, transform: `translateX(${VIREO_MOTION_TOKENS.distance.component}px)` },
+    to: { opacity: 1, transform: "translateX(0)" },
+});
+const enterBackward = keyframes({
+    from: { opacity: 0, transform: `translateX(-${VIREO_MOTION_TOKENS.distance.component}px)` },
+    to: { opacity: 1, transform: "translateX(0)" },
+});
+export const VireoFormStepRoot = styled(Box, {
+    name: VIREO_FORM_STEP_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})(({ ownerState }) => ({
+    minWidth: 0,
+    outline: 0,
+    ...(ownerState.current && {
+        animation: `${ownerState.direction === "forward" ? enterForward : enterBackward} ${VIREO_MOTION_TOKENS.duration.enter}ms ${VIREO_MOTION_TOKENS.easing.enter}`,
+    }),
+    "@media (prefers-reduced-motion: reduce)": {
+        animation: "none",
+    },
+}));
+export const VireoFormStepLabel = styled(Typography, {
+    name: VIREO_FORM_STEP_NAME,
+    slot: "Label",
+    overridesResolver: (_props, styles) => styles.label,
+})({
+    border: 0,
+    clip: "rect(0 0 0 0)",
+    clipPath: "inset(50%)",
+    height: 1,
+    margin: -1,
+    overflow: "hidden",
+    padding: 0,
+    position: "absolute",
+    whiteSpace: "nowrap",
+    width: 1,
+});

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.types.d.ts

@@ -0,0 +1,47 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { VireoMultiStepDirection } from "../../../../../capabilities/forms/types/vireoMultiStep.types.js";
+import type { BoxProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormStepClasses, type VireoFormStepClassKey } from "./VireoFormStep.classes.js";
+import type { VIREO_FORM_STEP_NAME, VireoFormStepSlotName } from "./VireoFormStep.identity.js";
+export type VireoFormStepOwnerState = {
+    active: boolean;
+    current: boolean;
+    direction: VireoMultiStepDirection;
+    keepMounted: boolean;
+};
+export interface VireoFormStepRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormStepLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoFormStep}. */
+export type VireoFormStepSlots = {
+    [TSlotName in VireoFormStepSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoFormStep}. */
+export type VireoFormStepSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormStepSlots, {
+    /** @default 'div' */
+    root: SlotProps<"section", VireoFormStepRootSlotPropsOverrides, VireoFormStepOwnerState>;
+    /** @default Typography */
+    label: SlotProps<typeof Typography, VireoFormStepLabelSlotPropsOverrides, VireoFormStepOwnerState>;
+}>;
+/** Props owned by {@link VireoFormStep}. */
+export type VireoFormStepOwnProps = VireoFormStepSlotsAndSlotProps & {
+    children?: React.ReactNode;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoFormStepClasses>;
+    /** Stable configured step id. */
+    id: string;
+};
+/** Props VireoFormStep inherits from its default root after excluding component-owned props. */
+export type VireoFormStepInheritedProps = Omit<BoxProps<"section">, "children" | "component" | "id">;
+/** Props accepted by {@link VireoFormStep}. */
+export type VireoFormStepProps = VireoFormStepOwnProps & VireoFormStepInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_STEP_NAME]?: VireoThemeComponent<VireoFormStepProps, VireoFormStepClassKey, VireoFormStepOwnerState, Theme>;
+    }
+}

package/dist/capabilities/forms/components/forms/VireoFormStep/VireoFormStep.types.js

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

package/dist/capabilities/forms/components/forms/VireoFormStep/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./VireoFormStep.js";
+export * from "./VireoFormStep.classes.js";
+export * from "./VireoFormStep.types.js";

package/dist/capabilities/forms/components/forms/VireoFormStep/index.js

@@ -0,0 +1,3 @@
+export * from "./VireoFormStep.js";
+export * from "./VireoFormStep.classes.js";
+export * from "./VireoFormStep.types.js";

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.classes.d.ts

@@ -0,0 +1,9 @@
+import { type VireoFormStepProgressSlotName } from "./VireoFormStepProgress.identity.js";
+/** Utility classes available to VireoFormStepProgress. */
+export type VireoFormStepProgressClasses = Record<VireoFormStepProgressSlotName, string>;
+/** Valid keys for VireoFormStepProgress utility classes and theme style overrides. */
+export type VireoFormStepProgressClassKey = keyof VireoFormStepProgressClasses;
+/** Returns the generated utility class name for a VireoFormStepProgress slot or state. */
+export declare function getVireoFormStepProgressUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoFormStepProgress class key. */
+export declare const vireoFormStepProgressClasses: VireoFormStepProgressClasses;

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.classes.js

@@ -0,0 +1,8 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_FORM_STEP_PROGRESS_NAME, VIREO_FORM_STEP_PROGRESS_SLOTS, } from "./VireoFormStepProgress.identity.js";
+/** Returns the generated utility class name for a VireoFormStepProgress slot or state. */
+export function getVireoFormStepProgressUtilityClass(slot) {
+    return generateUtilityClass(VIREO_FORM_STEP_PROGRESS_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoFormStepProgress class key. */
+export const vireoFormStepProgressClasses = generateUtilityClasses(VIREO_FORM_STEP_PROGRESS_NAME, [...VIREO_FORM_STEP_PROGRESS_SLOTS]);

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+/** Shows accessible, container-responsive progress and optional direct navigation for a bound multi-step form. */
+export declare const VireoFormStepProgress: React.ForwardRefExoticComponent<import("./VireoFormStepProgress.types.js").VireoFormStepProgressSlotsAndSlotProps & {
+    compactBreakpoint?: number;
+    classes?: Partial<import("./VireoFormStepProgress.classes.js").VireoFormStepProgressClasses>;
+    layout?: import("./VireoFormStepProgress.types.js").VireoFormStepProgressLayout;
+    navigation?: import("./VireoFormStepProgress.types.js").VireoFormStepProgressNavigation;
+} & import("./VireoFormStepProgress.types.js").VireoFormStepProgressInheritedProps & React.RefAttributes<HTMLDivElement>>;

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.identity.d.ts

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoFormStepProgress integration point. */
+export declare const VIREO_FORM_STEP_PROGRESS_NAME = "VireoFormStepProgress";
+/** Canonical public slots exposed by VireoFormStepProgress, in rendered DOM order. */
+export declare const VIREO_FORM_STEP_PROGRESS_SLOTS: readonly ["root", "list", "step", "stepButton", "statusIcon", "stepLabel", "connector", "compactRoot", "compactTrigger", "compactLabel", "compactCount", "compactProgress", "menu", "menuItem"];
+/** Public slot names exposed by VireoFormStepProgress. */
+export type VireoFormStepProgressSlotName = (typeof VIREO_FORM_STEP_PROGRESS_SLOTS)[number];

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.identity.js

@@ -0,0 +1,19 @@
+/** Stable component name shared by every VireoFormStepProgress integration point. */
+export const VIREO_FORM_STEP_PROGRESS_NAME = "VireoFormStepProgress";
+/** Canonical public slots exposed by VireoFormStepProgress, in rendered DOM order. */
+export const VIREO_FORM_STEP_PROGRESS_SLOTS = [
+    "root",
+    "list",
+    "step",
+    "stepButton",
+    "statusIcon",
+    "stepLabel",
+    "connector",
+    "compactRoot",
+    "compactTrigger",
+    "compactLabel",
+    "compactCount",
+    "compactProgress",
+    "menu",
+    "menuItem",
+];

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createElement as _createElement } from "react";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { unstable_composeClasses as composeClasses } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import React from "react";
+import { useVireoMultiStepContext } from "../../../../../capabilities/forms/contexts/VireoMultiStepContext/VireoMultiStepContext.js";
+import { getVireoFormStepProgressUtilityClass, } from "./VireoFormStepProgress.classes.js";
+import { VIREO_FORM_STEP_PROGRESS_NAME } from "./VireoFormStepProgress.identity.js";
+import { VireoFormStepProgressCompactCount, VireoFormStepProgressCompactLabel, VireoFormStepProgressCompactProgress, VireoFormStepProgressCompactRoot, VireoFormStepProgressCompactTrigger, VireoFormStepProgressConnector, VireoFormStepProgressList, VireoFormStepProgressMenu, VireoFormStepProgressMenuItem, VireoFormStepProgressRoot, VireoFormStepProgressStatusIcon, VireoFormStepProgressStep, VireoFormStepProgressStepButton, VireoFormStepProgressStepLabel, } from "./VireoFormStepProgress.styled.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        list: ["list"],
+        step: ["step"],
+        stepButton: ["stepButton"],
+        statusIcon: ["statusIcon"],
+        stepLabel: ["stepLabel"],
+        connector: ["connector"],
+        compactRoot: ["compactRoot"],
+        compactTrigger: ["compactTrigger"],
+        compactLabel: ["compactLabel"],
+        compactCount: ["compactCount"],
+        compactProgress: ["compactProgress"],
+        menu: ["menu"],
+        menuItem: ["menuItem"],
+    }, getVireoFormStepProgressUtilityClass, classes);
+}
+function stepLabel(step, index) {
+    if (step.ariaLabel)
+        return step.ariaLabel;
+    return typeof step.label === "string" ? step.label : `Step ${index + 1}`;
+}
+function statusLabel(step, localeText) {
+    if (step.hasError)
+        return localeText.errorStatus;
+    if (step.isCurrent)
+        return localeText.currentStatus;
+    if (step.isComplete)
+        return localeText.completeStatus;
+    if (step.isVisited)
+        return localeText.visitedStatus;
+    return localeText.upcomingStatus;
+}
+function statusContent(step, index) {
+    if (step.hasError)
+        return "!";
+    if (step.isComplete)
+        return "✓";
+    return index + 1;
+}
+/** Shows accessible, container-responsive progress and optional direct navigation for a bound multi-step form. */
+export const VireoFormStepProgress = React.forwardRef(function VireoFormStepProgress(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_STEP_PROGRESS_NAME });
+    const { className, classes: classesProp, compactBreakpoint = 600, layout = "responsive", navigation = "visited", slotProps = {}, slots = {}, style, sx, ...other } = props;
+    const { controller, localeText } = useVireoMultiStepContext();
+    const state = React.useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const [menuAnchor, setMenuAnchor] = React.useState(null);
+    const ownerState = { compactBreakpoint, layout, navigation };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedListSlotProps = resolveSlotProps(slotProps.list, ownerState);
+    const resolvedCompactRootSlotProps = resolveSlotProps(slotProps.compactRoot, ownerState);
+    const resolvedCompactTriggerSlotProps = resolveSlotProps(slotProps.compactTrigger, ownerState);
+    const resolvedCompactLabelSlotProps = resolveSlotProps(slotProps.compactLabel, ownerState);
+    const resolvedCompactCountSlotProps = resolveSlotProps(slotProps.compactCount, ownerState);
+    const resolvedCompactProgressSlotProps = resolveSlotProps(slotProps.compactProgress, ownerState);
+    const resolvedMenuSlotProps = resolveSlotProps(slotProps.menu, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const { className: listSlotClassName, ...listSlotOther } = resolvedListSlotProps;
+    const { className: compactRootSlotClassName, ...compactRootSlotOther } = resolvedCompactRootSlotProps;
+    const { className: compactTriggerSlotClassName, onClick: compactTriggerSlotOnClick, ...compactTriggerSlotOther } = resolvedCompactTriggerSlotProps;
+    const { className: compactLabelSlotClassName, ...compactLabelSlotOther } = resolvedCompactLabelSlotProps;
+    const { className: compactCountSlotClassName, ...compactCountSlotOther } = resolvedCompactCountSlotProps;
+    const { className: compactProgressSlotClassName, ...compactProgressSlotOther } = resolvedCompactProgressSlotProps;
+    const { className: menuSlotClassName, onClose: menuSlotOnClose, ...menuSlotOther } = resolvedMenuSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const current = state.currentStep;
+    const navigableSteps = state.activeSteps.filter(step => {
+        if (step.isCurrent || navigation === "none")
+            return false;
+        if (navigation === "all")
+            return true;
+        return step.canNavigate;
+    });
+    const currentLabel = stepLabel(current, state.currentStepIndex);
+    const stepCount = localeText.stepCount({ current: state.currentStepIndex + 1, total: state.activeStepCount });
+    const progress = state.activeStepCount === 0 ? 0 : ((state.currentStepIndex + 1) / state.activeStepCount) * 100;
+    const renderStep = (step, index) => {
+        const stepOwnerState = { ...ownerState, step };
+        const resolvedStepSlotProps = resolveSlotProps(slotProps.step, stepOwnerState);
+        const resolvedStepButtonSlotProps = resolveSlotProps(slotProps.stepButton, stepOwnerState);
+        const resolvedStatusIconSlotProps = resolveSlotProps(slotProps.statusIcon, stepOwnerState);
+        const resolvedStepLabelSlotProps = resolveSlotProps(slotProps.stepLabel, stepOwnerState);
+        const resolvedConnectorSlotProps = resolveSlotProps(slotProps.connector, stepOwnerState);
+        const { className: stepSlotClassName, ...stepSlotOther } = resolvedStepSlotProps;
+        const { className: stepButtonSlotClassName, onClick: stepButtonSlotOnClick, ...stepButtonSlotOther } = resolvedStepButtonSlotProps;
+        const { className: statusIconSlotClassName, ...statusIconSlotOther } = resolvedStatusIconSlotProps;
+        const { className: stepLabelSlotClassName, ...stepLabelSlotOther } = resolvedStepLabelSlotProps;
+        const { className: connectorSlotClassName, ...connectorSlotOther } = resolvedConnectorSlotProps;
+        const label = stepLabel(step, index);
+        const canNavigate = !step.isCurrent && navigation !== "none" && (navigation === "all" || step.canNavigate);
+        return (_createElement(VireoFormStepProgressStep, { ...stepSlotOther, as: slots.step ?? "li", key: step.id, ownerState: stepOwnerState, className: joinClassNames(classes.step, stepSlotClassName) },
+            _jsxs(VireoFormStepProgressStepButton, { ...stepButtonSlotOther, as: slots.stepButton, ownerState: stepOwnerState, "aria-current": step.isCurrent ? "step" : undefined, "aria-label": `${label}, ${statusLabel(step, localeText)}`, disabled: !canNavigate, onClick: event => {
+                    stepButtonSlotOnClick?.(event);
+                    if (!event.defaultPrevented && canNavigate)
+                        void controller.goToStep(step.id);
+                }, className: joinClassNames(classes.stepButton, stepButtonSlotClassName), children: [_jsx(VireoFormStepProgressStatusIcon, { ...statusIconSlotOther, as: slots.statusIcon ?? "span", ownerState: stepOwnerState, "aria-hidden": "true", className: joinClassNames(classes.statusIcon, statusIconSlotClassName), children: statusContent(step, index) }), _jsx(VireoFormStepProgressStepLabel, { ...stepLabelSlotOther, as: slots.stepLabel ?? "span", ownerState: stepOwnerState, className: joinClassNames(classes.stepLabel, stepLabelSlotClassName), children: step.label })] }),
+            index < state.activeSteps.length - 1 && (_jsx(VireoFormStepProgressConnector, { ...connectorSlotOther, as: slots.connector ?? "span", ownerState: stepOwnerState, "aria-hidden": "true", className: joinClassNames(classes.connector, connectorSlotClassName) }))));
+    };
+    return (_jsxs(VireoFormStepProgressRoot, { ...other, ...rootSlotOther, as: slots.root ?? "nav", ref: rootRef, ownerState: ownerState, "aria-label": other["aria-label"] ?? localeText.progressLabel, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [_jsx(VireoFormStepProgressList, { ...listSlotOther, as: slots.list ?? "ol", ownerState: ownerState, className: joinClassNames(classes.list, listSlotClassName), style: { "--vireo-step-count": state.activeStepCount }, children: state.activeSteps.map(renderStep) }), _jsxs(VireoFormStepProgressCompactRoot, { ...compactRootSlotOther, as: slots.compactRoot, ownerState: ownerState, className: joinClassNames(classes.compactRoot, compactRootSlotClassName), children: [navigableSteps.length > 0 ? (_jsxs(VireoFormStepProgressCompactTrigger, { ...compactTriggerSlotOther, as: slots.compactTrigger, ownerState: ownerState, "aria-label": localeText.openStepMenu({
+                            label: currentLabel,
+                            current: state.currentStepIndex + 1,
+                            total: state.activeStepCount,
+                        }), onClick: event => {
+                            compactTriggerSlotOnClick?.(event);
+                            if (!event.defaultPrevented)
+                                setMenuAnchor(event.currentTarget);
+                        }, className: joinClassNames(classes.compactTrigger, compactTriggerSlotClassName), children: [_jsx(VireoFormStepProgressCompactLabel, { ...compactLabelSlotOther, as: slots.compactLabel ?? "span", ownerState: ownerState, className: joinClassNames(classes.compactLabel, compactLabelSlotClassName), children: current.label }), _jsx(VireoFormStepProgressCompactCount, { ...compactCountSlotOther, as: slots.compactCount ?? "span", ownerState: ownerState, className: joinClassNames(classes.compactCount, compactCountSlotClassName), children: stepCount })] })) : (_jsxs("div", { children: [_jsx(VireoFormStepProgressCompactLabel, { ...compactLabelSlotOther, as: slots.compactLabel ?? "span", ownerState: ownerState, className: joinClassNames(classes.compactLabel, compactLabelSlotClassName), children: current.label }), " ", _jsx(VireoFormStepProgressCompactCount, { ...compactCountSlotOther, as: slots.compactCount ?? "span", ownerState: ownerState, className: joinClassNames(classes.compactCount, compactCountSlotClassName), children: stepCount })] })), _jsx(VireoFormStepProgressCompactProgress, { ...compactProgressSlotOther, as: slots.compactProgress, ownerState: ownerState, "aria-label": stepCount, variant: "determinate", value: progress, className: joinClassNames(classes.compactProgress, compactProgressSlotClassName) })] }), _jsx(VireoFormStepProgressMenu, { ...menuSlotOther, as: slots.menu, ownerState: ownerState, anchorEl: menuAnchor, open: Boolean(menuAnchor), onClose: (event, reason) => {
+                    menuSlotOnClose?.(event, reason);
+                    setMenuAnchor(null);
+                }, className: joinClassNames(classes.menu, menuSlotClassName), children: navigableSteps.map(step => {
+                    const index = state.activeSteps.findIndex(candidate => candidate.id === step.id);
+                    const stepOwnerState = { ...ownerState, step };
+                    const resolvedMenuItemSlotProps = resolveSlotProps(slotProps.menuItem, stepOwnerState);
+                    const { className: menuItemSlotClassName, onClick: menuItemSlotOnClick, ...menuItemSlotOther } = resolvedMenuItemSlotProps;
+                    return (_createElement(VireoFormStepProgressMenuItem, { ...menuItemSlotOther, as: slots.menuItem, key: step.id, ownerState: stepOwnerState, onClick: event => {
+                            menuItemSlotOnClick?.(event);
+                            if (!event.defaultPrevented) {
+                                setMenuAnchor(null);
+                                void controller.goToStep(step.id);
+                            }
+                        }, className: joinClassNames(classes.menuItem, menuItemSlotClassName) },
+                        _jsx(VireoFormStepProgressStatusIcon, { ownerState: stepOwnerState, "aria-hidden": "true", children: statusContent(step, index) }),
+                        step.label));
+                }) })] }));
+});
+VireoFormStepProgress.displayName = VIREO_FORM_STEP_PROGRESS_NAME;

package/dist/capabilities/forms/components/forms/VireoFormStepProgress/VireoFormStepProgress.styled.d.ts

@@ -0,0 +1,19 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type ButtonBaseProps, type LinearProgressProps, type MenuItemProps, type MenuProps, type TypographyProps } from "@mui/material";
+import { type VireoFormStepProgressOwnerState } from "./VireoFormStepProgress.types.js";
+type VireoFormStepProgressStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormStepProgressOwnerState>;
+export declare const VireoFormStepProgressRoot: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressList: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressStep: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressStepButton: VireoFormStepProgressStyledSlotComponent<ButtonBaseProps>;
+export declare const VireoFormStepProgressStatusIcon: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressStepLabel: VireoFormStepProgressStyledSlotComponent<TypographyProps>;
+export declare const VireoFormStepProgressConnector: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressCompactRoot: VireoFormStepProgressStyledSlotComponent<BoxProps>;
+export declare const VireoFormStepProgressCompactTrigger: VireoFormStepProgressStyledSlotComponent<ButtonBaseProps>;
+export declare const VireoFormStepProgressCompactLabel: VireoFormStepProgressStyledSlotComponent<TypographyProps>;
+export declare const VireoFormStepProgressCompactCount: VireoFormStepProgressStyledSlotComponent<TypographyProps>;
+export declare const VireoFormStepProgressCompactProgress: VireoFormStepProgressStyledSlotComponent<LinearProgressProps>;
+export declare const VireoFormStepProgressMenu: VireoFormStepProgressStyledSlotComponent<MenuProps>;
+export declare const VireoFormStepProgressMenuItem: VireoFormStepProgressStyledSlotComponent<MenuItemProps>;
+export type { BoxProps, ButtonBaseProps, LinearProgressProps, MenuItemProps, MenuProps, TypographyProps };