@vireocodedev/ui 0.2.0 → 0.2.1

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

@@ -0,0 +1,27 @@
+/** Stable component name shared by every VireoFormCounterField integration point. */
+export const VIREO_FORM_COUNTER_FIELD_NAME = "VireoFormCounterField";
+/** Canonical public slots exposed by VireoFormCounterField, in rendered DOM order. */
+export const VIREO_FORM_COUNTER_FIELD_SLOTS = [
+    "root",
+    "input",
+    "decrementButton",
+    "decrementIcon",
+    "htmlInput",
+    "incrementButton",
+    "incrementIcon",
+    "formHelperText",
+];
+/** Canonical interaction and validation states exposed as utility classes. */
+export const VIREO_FORM_COUNTER_FIELD_STATES = [
+    "dirty",
+    "touched",
+    "invalid",
+    "errorVisible",
+    "validating",
+    "submitting",
+    "disabled",
+    "readOnly",
+    "hasValue",
+    "atMin",
+    "atMax",
+];

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

@@ -0,0 +1,309 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useVireoFormContext } from "../../../../../capabilities/forms/contexts/VireoFormContext/VireoFormContext.js";
+import { useVireoFieldContext } from "../../../../../capabilities/forms/contexts/VireoFormHookContexts/VireoFormHookContexts.js";
+import { formatFirstVireoFormError, shouldDisplayVireoFormError } from "../../../../../capabilities/forms/utils/vireoFormErrors.js";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { InputAdornment, unstable_composeClasses as composeClasses, } from "@mui/material";
+import { useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import { useStore } from "@tanstack/react-form";
+import React from "react";
+import { getVireoFormCounterFieldUtilityClass, } from "./VireoFormCounterField.classes.js";
+import { VIREO_FORM_COUNTER_FIELD_NAME } from "./VireoFormCounterField.identity.js";
+import { VireoFormCounterFieldDecrementButton, VireoFormCounterFieldDecrementIcon, VireoFormCounterFieldFormHelperText, VireoFormCounterFieldHtmlInput, VireoFormCounterFieldIncrementButton, VireoFormCounterFieldIncrementIcon, VireoFormCounterFieldInput, VireoFormCounterFieldRoot, } from "./VireoFormCounterField.styled.js";
+const EDITABLE_NUMBER_PATTERN = /^-?\d*(?:\.\d*)?$/;
+const COMPLETE_NUMBER_PATTERN = /^-?(?:\d+|\d*\.\d+)$/;
+function useUtilityClasses(ownerState, classes) {
+    return composeClasses({
+        root: [
+            "root",
+            ownerState.dirty && "dirty",
+            ownerState.touched && "touched",
+            ownerState.invalid && "invalid",
+            ownerState.errorVisible && "errorVisible",
+            ownerState.validating && "validating",
+            ownerState.submitting && "submitting",
+            ownerState.disabled && "disabled",
+            ownerState.readOnly && "readOnly",
+            ownerState.hasValue && "hasValue",
+            ownerState.atMin && "atMin",
+            ownerState.atMax && "atMax",
+        ],
+        input: ["input"],
+        decrementButton: ["decrementButton"],
+        decrementIcon: ["decrementIcon"],
+        htmlInput: ["htmlInput"],
+        incrementButton: ["incrementButton"],
+        incrementIcon: ["incrementIcon"],
+        formHelperText: ["formHelperText"],
+    }, getVireoFormCounterFieldUtilityClass, classes);
+}
+function assertFiniteConfiguration(name, value) {
+    if (value !== undefined && !Number.isFinite(value)) {
+        throw new Error(`${VIREO_FORM_COUNTER_FIELD_NAME} ${name} must be a finite number.`);
+    }
+}
+function validateConfiguration(step, min, max) {
+    assertFiniteConfiguration("step", step);
+    assertFiniteConfiguration("min", min);
+    assertFiniteConfiguration("max", max);
+    if (step <= 0)
+        throw new Error(`${VIREO_FORM_COUNTER_FIELD_NAME} step must be greater than zero.`);
+    if (min !== undefined && max !== undefined && min > max) {
+        throw new Error(`${VIREO_FORM_COUNTER_FIELD_NAME} min must be less than or equal to max.`);
+    }
+}
+function clampValue(value, min, max) {
+    return Math.min(max ?? value, Math.max(min ?? value, value));
+}
+function normalizeNumber(value) {
+    const normalized = Number(value.toPrecision(15));
+    return Object.is(normalized, -0) ? 0 : normalized;
+}
+function steppedValue(value, direction, step, min, max) {
+    const baseline = value ?? 0;
+    return normalizeNumber(clampValue(baseline + direction * step, min, max));
+}
+function formatValue(value) {
+    return value === null ? "" : String(Object.is(value, -0) ? 0 : value);
+}
+function joinIds(...ids) {
+    const joined = ids.filter(Boolean).join(" ");
+    return joined || undefined;
+}
+function isAriaInvalid(value) {
+    return value === true || value === "true";
+}
+/**
+ * Binds an editable, button-stepped numeric counter to the current TanStack Form `number | null` field.
+ *
+ * Consumers render it as `field.CounterField`; the raw runtime remains internal to the forms capability.
+ */
+export const VireoFormCounterField = React.forwardRef(function VireoFormCounterField(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_COUNTER_FIELD_NAME });
+    const { "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, classes: classesProp, decrementLabel = "Decrease", disabled = false, error = false, errorDisplay: errorDisplayProp, formatError: formatErrorProp, fullWidth = true, helperText = " ", incrementLabel = "Increase", inputRef, max, min, onBlur, onChange, onValueChange, readOnly = false, required = false, size = "medium", slotProps = {}, slots = {}, step = 1, style, sx, ...other } = props;
+    validateConfiguration(step, min, max);
+    const field = useVireoFieldContext();
+    const formContext = useVireoFormContext();
+    const generatedInputId = React.useId();
+    const generatedHelperTextId = React.useId();
+    const fieldState = useStore(field.store, current => ({
+        dirty: current.meta.isDirty,
+        errors: current.meta.errors,
+        invalid: !current.meta.isValid,
+        touched: current.meta.isTouched,
+        validating: current.meta.isValidating,
+        value: current.value,
+    }));
+    const submitting = useStore(field.form.store, current => current.isSubmitting);
+    if (fieldState.value !== null && !Number.isFinite(fieldState.value)) {
+        throw new Error(`${VIREO_FORM_COUNTER_FIELD_NAME} requires a finite number or null field value.`);
+    }
+    const [inputValue, setInputValue] = React.useState(() => formatValue(fieldState.value));
+    React.useEffect(() => {
+        setInputValue(current => {
+            if (COMPLETE_NUMBER_PATTERN.test(current) && Object.is(normalizeNumber(Number(current)), fieldState.value)) {
+                return current;
+            }
+            return formatValue(fieldState.value);
+        });
+    }, [fieldState.value]);
+    const errorDisplay = errorDisplayProp ?? formContext.errorDisplay;
+    const validationErrorVisible = fieldState.invalid &&
+        shouldDisplayVireoFormError(errorDisplay, {
+            submissionAttempts: formContext.submissionAttempts,
+            touched: fieldState.touched,
+        });
+    const formattedError = validationErrorVisible
+        ? formatFirstVireoFormError(fieldState.errors, formatErrorProp ?? formContext.formatError)
+        : undefined;
+    const hasValue = fieldState.value !== null;
+    const atMin = hasValue && min !== undefined && fieldState.value <= min;
+    const atMax = hasValue && max !== undefined && fieldState.value >= max;
+    const decrementDisabled = disabled || readOnly || atMin;
+    const incrementDisabled = disabled || readOnly || atMax;
+    const ownerState = {
+        atMax,
+        atMin,
+        decrementDisabled,
+        dirty: fieldState.dirty,
+        disabled,
+        errorVisible: error || validationErrorVisible,
+        fullWidth,
+        hasValue,
+        incrementDisabled,
+        invalid: fieldState.invalid,
+        max,
+        min,
+        readOnly,
+        required,
+        size,
+        step,
+        submitting,
+        touched: fieldState.touched,
+        validating: fieldState.validating,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { "aria-label": _rootSlotAriaLabel, "aria-labelledby": _rootSlotAriaLabelledBy, className: rootSlotClassName, onBlur: rootSlotOnBlur, ref: rootSlotRef, role: _rootSlotRole, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    void _rootSlotAriaLabel;
+    void _rootSlotAriaLabelledBy;
+    void _rootSlotRole;
+    const resolvedInputSlotProps = resolveSlotProps(slotProps.input, ownerState);
+    const { className: inputSlotClassName, endAdornment: _inputSlotEndAdornment, inputComponent: _inputSlotInputComponent, inputProps: _inputSlotInputProps, onChange: inputSlotOnChange, onKeyDown: inputSlotOnKeyDown, onWheel: inputSlotOnWheel, ref: inputSlotRef, startAdornment: _inputSlotStartAdornment, value: _inputSlotValue, ...inputSlotOther } = resolvedInputSlotProps;
+    void _inputSlotEndAdornment;
+    void _inputSlotInputComponent;
+    void _inputSlotInputProps;
+    void _inputSlotStartAdornment;
+    void _inputSlotValue;
+    const resolvedDecrementButtonSlotProps = resolveSlotProps(slotProps.decrementButton, ownerState);
+    const { "aria-controls": _decrementSlotAriaControls, "aria-label": _decrementSlotAriaLabel, children: _decrementSlotChildren, className: decrementButtonSlotClassName, disabled: _decrementSlotDisabled, onClick: decrementButtonSlotOnClick, ref: decrementButtonSlotRef, type: _decrementSlotType, ...decrementButtonSlotOther } = resolvedDecrementButtonSlotProps;
+    void _decrementSlotAriaControls;
+    void _decrementSlotAriaLabel;
+    void _decrementSlotChildren;
+    void _decrementSlotDisabled;
+    void _decrementSlotType;
+    const resolvedDecrementIconSlotProps = resolveSlotProps(slotProps.decrementIcon, ownerState);
+    const { "aria-hidden": _decrementIconSlotAriaHidden, children: _decrementIconSlotChildren, className: decrementIconSlotClassName, ref: decrementIconSlotRef, ...decrementIconSlotOther } = resolvedDecrementIconSlotProps;
+    void _decrementIconSlotAriaHidden;
+    void _decrementIconSlotChildren;
+    const resolvedHtmlInputSlotProps = resolveSlotProps(slotProps.htmlInput, ownerState);
+    const { "aria-describedby": htmlInputSlotAriaDescribedBy, "aria-invalid": htmlInputSlotAriaInvalid, "aria-label": _htmlInputSlotAriaLabel, "aria-labelledby": _htmlInputSlotAriaLabelledBy, className: htmlInputSlotClassName, id: htmlInputSlotId, inputMode: _htmlInputSlotInputMode, onChange: htmlInputSlotOnChange, onKeyDown: htmlInputSlotOnKeyDown, onWheel: htmlInputSlotOnWheel, readOnly: _htmlInputSlotReadOnly, ref: htmlInputSlotRef, role: _htmlInputSlotRole, type: _htmlInputSlotType, value: _htmlInputSlotValue, ...htmlInputSlotOther } = resolvedHtmlInputSlotProps;
+    void _htmlInputSlotAriaLabel;
+    void _htmlInputSlotAriaLabelledBy;
+    void _htmlInputSlotInputMode;
+    void _htmlInputSlotReadOnly;
+    void _htmlInputSlotRole;
+    void _htmlInputSlotType;
+    void _htmlInputSlotValue;
+    const resolvedIncrementButtonSlotProps = resolveSlotProps(slotProps.incrementButton, ownerState);
+    const { "aria-controls": _incrementSlotAriaControls, "aria-label": _incrementSlotAriaLabel, children: _incrementSlotChildren, className: incrementButtonSlotClassName, disabled: _incrementSlotDisabled, onClick: incrementButtonSlotOnClick, ref: incrementButtonSlotRef, type: _incrementSlotType, ...incrementButtonSlotOther } = resolvedIncrementButtonSlotProps;
+    void _incrementSlotAriaControls;
+    void _incrementSlotAriaLabel;
+    void _incrementSlotChildren;
+    void _incrementSlotDisabled;
+    void _incrementSlotType;
+    const resolvedIncrementIconSlotProps = resolveSlotProps(slotProps.incrementIcon, ownerState);
+    const { "aria-hidden": _incrementIconSlotAriaHidden, children: _incrementIconSlotChildren, className: incrementIconSlotClassName, ref: incrementIconSlotRef, ...incrementIconSlotOther } = resolvedIncrementIconSlotProps;
+    void _incrementIconSlotAriaHidden;
+    void _incrementIconSlotChildren;
+    const resolvedHelperTextSlotProps = resolveSlotProps(slotProps.formHelperText, ownerState);
+    const { className: helperTextSlotClassName, id: helperTextSlotId, ...helperTextSlotOther } = resolvedHelperTextSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const nativeInputRef = useForkRef(inputRef, htmlInputSlotRef);
+    const inputId = htmlInputSlotId ?? generatedInputId;
+    const helperTextId = helperTextSlotId ?? generatedHelperTextId;
+    const effectiveHelperText = validationErrorVisible ? formattedError : helperText;
+    const describedBy = joinIds(ariaDescribedBy, htmlInputSlotAriaDescribedBy, effectiveHelperText !== undefined ? helperTextId : undefined);
+    const effectiveError = error || validationErrorVisible;
+    const emitValue = (nextValue) => {
+        const normalizedValue = nextValue === null ? null : normalizeNumber(nextValue);
+        if (Object.is(normalizedValue, fieldState.value))
+            return;
+        onValueChange?.(normalizedValue);
+        field.handleChange(normalizedValue);
+    };
+    const performStep = (direction) => {
+        if (disabled || readOnly || (direction < 0 ? atMin : atMax))
+            return;
+        const nextValue = steppedValue(fieldState.value, direction, step, min, max);
+        setInputValue(formatValue(nextValue));
+        emitValue(nextValue);
+    };
+    const handleChange = event => {
+        htmlInputSlotOnChange?.(event);
+        if (event.defaultPrevented)
+            return;
+        inputSlotOnChange?.(event);
+        if (event.defaultPrevented)
+            return;
+        onChange?.(event);
+        if (event.defaultPrevented || disabled || readOnly)
+            return;
+        const nextInputValue = event.target.value.replace(/,/g, ".");
+        if (!EDITABLE_NUMBER_PATTERN.test(nextInputValue))
+            return;
+        setInputValue(nextInputValue);
+        if (nextInputValue === "") {
+            emitValue(null);
+            return;
+        }
+        if (!COMPLETE_NUMBER_PATTERN.test(nextInputValue))
+            return;
+        const parsedValue = Number(nextInputValue);
+        if (!Number.isFinite(parsedValue))
+            return;
+        const clampedValue = normalizeNumber(clampValue(parsedValue, min, max));
+        if (!Object.is(clampedValue, parsedValue))
+            setInputValue(formatValue(clampedValue));
+        emitValue(clampedValue);
+    };
+    const handleKeyDown = event => {
+        htmlInputSlotOnKeyDown?.(event);
+        if (event.defaultPrevented)
+            return;
+        inputSlotOnKeyDown?.(event);
+        if (event.defaultPrevented || disabled || readOnly)
+            return;
+        if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
+            return;
+        event.preventDefault();
+        performStep(event.key === "ArrowUp" ? 1 : -1);
+    };
+    const handleWheel = event => {
+        htmlInputSlotOnWheel?.(event);
+        if (event.defaultPrevented)
+            return;
+        inputSlotOnWheel?.(event);
+        if (!event.defaultPrevented)
+            event.preventDefault();
+    };
+    const handleRootBlur = event => {
+        if (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))
+            return;
+        rootSlotOnBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        onBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        setInputValue(formatValue(field.state.value));
+        field.handleBlur();
+    };
+    const handleDecrementClick = event => {
+        decrementButtonSlotOnClick?.(event);
+        if (!event.defaultPrevented)
+            performStep(-1);
+    };
+    const handleIncrementClick = event => {
+        incrementButtonSlotOnClick?.(event);
+        if (!event.defaultPrevented)
+            performStep(1);
+    };
+    const decrementAdornment = (_jsx(InputAdornment, { position: "start", children: _jsx(VireoFormCounterFieldDecrementButton, { ...decrementButtonSlotOther, as: slots.decrementButton, ref: decrementButtonSlotRef, ownerState: ownerState, "aria-controls": inputId, "aria-label": decrementLabel, className: joinClassNames(classes.decrementButton, decrementButtonSlotClassName), disabled: decrementDisabled, onClick: handleDecrementClick, size: size, type: "button", children: _jsx(VireoFormCounterFieldDecrementIcon, { ...decrementIconSlotOther, as: slots.decrementIcon, ref: decrementIconSlotRef, ownerState: ownerState, "aria-hidden": "true", className: joinClassNames(classes.decrementIcon, decrementIconSlotClassName), fontSize: size }) }) }));
+    const incrementAdornment = (_jsx(InputAdornment, { position: "end", children: _jsx(VireoFormCounterFieldIncrementButton, { ...incrementButtonSlotOther, as: slots.incrementButton, ref: incrementButtonSlotRef, ownerState: ownerState, "aria-controls": inputId, "aria-label": incrementLabel, className: joinClassNames(classes.incrementButton, incrementButtonSlotClassName), disabled: incrementDisabled, onClick: handleIncrementClick, size: size, type: "button", children: _jsx(VireoFormCounterFieldIncrementIcon, { ...incrementIconSlotOther, as: slots.incrementIcon, ref: incrementIconSlotRef, ownerState: ownerState, "aria-hidden": "true", className: joinClassNames(classes.incrementIcon, incrementIconSlotClassName), fontSize: size }) }) }));
+    const HtmlInputComponent = (slots.htmlInput ?? VireoFormCounterFieldHtmlInput);
+    return (_jsxs(VireoFormCounterFieldRoot, { ...other, ...rootSlotOther, as: slots.root, ref: rootRef, ownerState: ownerState, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: joinClassNames(classes.root, className, rootSlotClassName), disabled: disabled, error: effectiveError, fullWidth: fullWidth, onBlur: handleRootBlur, required: required, role: "group", style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [_jsx(VireoFormCounterFieldInput, { ...inputSlotOther, as: slots.input, ref: inputSlotRef, ownerState: ownerState, className: joinClassNames(classes.input, inputSlotClassName), disabled: disabled, endAdornment: incrementAdornment, error: effectiveError, fullWidth: fullWidth, inputComponent: HtmlInputComponent, inputProps: {
+                    ...htmlInputSlotOther,
+                    ownerState,
+                    "aria-describedby": describedBy,
+                    "aria-invalid": error || fieldState.invalid || isAriaInvalid(htmlInputSlotAriaInvalid) || undefined,
+                    "aria-label": ariaLabel,
+                    "aria-labelledby": ariaLabelledBy,
+                    "aria-readonly": readOnly || undefined,
+                    "aria-required": required || undefined,
+                    "aria-valuemax": max,
+                    "aria-valuemin": min,
+                    "aria-valuenow": fieldState.value ?? undefined,
+                    className: joinClassNames(classes.htmlInput, htmlInputSlotClassName),
+                    "data-vireo-field-focus-target": "true",
+                    id: inputId,
+                    inputMode: "decimal",
+                    onKeyDown: handleKeyDown,
+                    onWheel: handleWheel,
+                    readOnly,
+                    role: "spinbutton",
+                    type: "text",
+                }, inputRef: nativeInputRef, name: field.name, onChange: handleChange, readOnly: readOnly, size: size, startAdornment: decrementAdornment, value: inputValue }), effectiveHelperText !== undefined && (_jsx(VireoFormCounterFieldFormHelperText, { ...helperTextSlotOther, as: slots.formHelperText, id: helperTextId, ownerState: ownerState, className: joinClassNames(classes.formHelperText, helperTextSlotClassName), children: effectiveHelperText }))] }));
+});
+VireoFormCounterField.displayName = VIREO_FORM_COUNTER_FIELD_NAME;

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

@@ -0,0 +1,14 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type FormControlProps, type FormHelperTextProps, type IconButtonProps, type OutlinedInputProps, type SvgIconProps } from "@mui/material";
+import type React from "react";
+import type { VireoFormCounterFieldOwnerState } from "./VireoFormCounterField.types.js";
+type StyledComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormCounterFieldOwnerState>;
+export declare const VireoFormCounterFieldRoot: StyledComponent<FormControlProps>;
+export declare const VireoFormCounterFieldInput: StyledComponent<OutlinedInputProps>;
+export declare const VireoFormCounterFieldDecrementButton: StyledComponent<IconButtonProps>;
+export declare const VireoFormCounterFieldDecrementIcon: StyledComponent<SvgIconProps>;
+export declare const VireoFormCounterFieldHtmlInput: StyledComponent<React.ComponentPropsWithoutRef<"input">>;
+export declare const VireoFormCounterFieldIncrementButton: StyledComponent<IconButtonProps>;
+export declare const VireoFormCounterFieldIncrementIcon: StyledComponent<SvgIconProps>;
+export declare const VireoFormCounterFieldFormHelperText: StyledComponent<FormHelperTextProps>;
+export {};

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

@@ -0,0 +1,75 @@
+import AddIcon from "@mui/icons-material/Add";
+import RemoveIcon from "@mui/icons-material/Remove";
+import { FormControl, FormHelperText, IconButton, OutlinedInput, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FORM_COUNTER_FIELD_NAME } from "./VireoFormCounterField.identity.js";
+export const VireoFormCounterFieldRoot = styled(FormControl, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "Root",
+    overridesResolver: (props, styles) => [
+        styles.root,
+        props.ownerState.dirty && styles.dirty,
+        props.ownerState.touched && styles.touched,
+        props.ownerState.invalid && styles.invalid,
+        props.ownerState.errorVisible && styles.errorVisible,
+        props.ownerState.validating && styles.validating,
+        props.ownerState.submitting && styles.submitting,
+        props.ownerState.disabled && styles.disabled,
+        props.ownerState.readOnly && styles.readOnly,
+        props.ownerState.hasValue && styles.hasValue,
+        props.ownerState.atMin && styles.atMin,
+        props.ownerState.atMax && styles.atMax,
+    ],
+})(({ ownerState }) => ({ minWidth: 0, ...(ownerState.fullWidth && { width: "100%" }) }));
+export const VireoFormCounterFieldInput = styled(OutlinedInput, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "Input",
+    overridesResolver: (_props, styles) => styles.input,
+})(({ ownerState }) => ({
+    minWidth: 0,
+    ...(ownerState.fullWidth && { width: "100%" }),
+    "& .MuiInputAdornment-root": { margin: 0, maxHeight: "none" },
+}));
+export const VireoFormCounterFieldDecrementButton = styled(IconButton, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "DecrementButton",
+    overridesResolver: (_props, styles) => styles.decrementButton,
+})(({ ownerState }) => ({
+    flex: "0 0 auto",
+    minHeight: ownerState.size === "small" ? 32 : 40,
+    minWidth: ownerState.size === "small" ? 32 : 40,
+}));
+export const VireoFormCounterFieldDecrementIcon = styled(RemoveIcon, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "DecrementIcon",
+    overridesResolver: (_props, styles) => styles.decrementIcon,
+})({});
+export const VireoFormCounterFieldHtmlInput = styled("input", {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "HtmlInput",
+    overridesResolver: (_props, styles) => styles.htmlInput,
+})({
+    appearance: "textfield",
+    fontVariantNumeric: "tabular-nums",
+    minWidth: 0,
+    textAlign: "center",
+});
+export const VireoFormCounterFieldIncrementButton = styled(IconButton, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "IncrementButton",
+    overridesResolver: (_props, styles) => styles.incrementButton,
+})(({ ownerState }) => ({
+    flex: "0 0 auto",
+    minHeight: ownerState.size === "small" ? 32 : 40,
+    minWidth: ownerState.size === "small" ? 32 : 40,
+}));
+export const VireoFormCounterFieldIncrementIcon = styled(AddIcon, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "IncrementIcon",
+    overridesResolver: (_props, styles) => styles.incrementIcon,
+})({});
+export const VireoFormCounterFieldFormHelperText = styled(FormHelperText, {
+    name: VIREO_FORM_COUNTER_FIELD_NAME,
+    slot: "FormHelperText",
+    overridesResolver: (_props, styles) => styles.formHelperText,
+})(({ theme }) => ({ marginInline: theme.spacing(1.75) }));

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

@@ -0,0 +1,139 @@
+import type { VireoFormErrorDisplay, VireoFormErrorFormatter } from "../../../../../capabilities/forms/components/forms/VireoForm/VireoForm.types.js";
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { FormControl, FormControlProps, FormHelperText, IconButton, OutlinedInput, SvgIcon } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormCounterFieldClasses, type VireoFormCounterFieldClassKey } from "./VireoFormCounterField.classes.js";
+import type { VIREO_FORM_COUNTER_FIELD_NAME } from "./VireoFormCounterField.identity.js";
+export type VireoFormCounterFieldSize = "small" | "medium";
+export type VireoFormCounterFieldOwnerState = {
+    atMax: boolean;
+    atMin: boolean;
+    decrementDisabled: boolean;
+    dirty: boolean;
+    disabled: boolean;
+    errorVisible: boolean;
+    fullWidth: boolean;
+    hasValue: boolean;
+    incrementDisabled: boolean;
+    invalid: boolean;
+    max: number | undefined;
+    min: number | undefined;
+    readOnly: boolean;
+    required: boolean;
+    size: VireoFormCounterFieldSize;
+    step: number;
+    submitting: boolean;
+    touched: boolean;
+    validating: boolean;
+};
+export interface VireoFormCounterFieldRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldDecrementButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldDecrementIconSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldHtmlInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldIncrementButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldIncrementIconSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormCounterFieldFormHelperTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by the bound counter field. */
+export type VireoFormCounterFieldSlots = {
+    root: React.ElementType;
+    input: React.ElementType;
+    decrementButton: React.ElementType;
+    decrementIcon: React.ElementType;
+    htmlInput: React.ElementType;
+    incrementButton: React.ElementType;
+    incrementIcon: React.ElementType;
+    formHelperText: React.ElementType;
+};
+/** Slot props exposed by the bound counter field. */
+export type VireoFormCounterFieldSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormCounterFieldSlots, {
+    /** @default FormControl */
+    root: SlotProps<typeof FormControl, VireoFormCounterFieldRootSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default OutlinedInput */
+    input: SlotProps<typeof OutlinedInput, VireoFormCounterFieldInputSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default IconButton */
+    decrementButton: SlotProps<typeof IconButton, VireoFormCounterFieldDecrementButtonSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default RemoveIcon */
+    decrementIcon: SlotProps<typeof SvgIcon, VireoFormCounterFieldDecrementIconSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default 'input' */
+    htmlInput: SlotProps<"input", VireoFormCounterFieldHtmlInputSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default IconButton */
+    incrementButton: SlotProps<typeof IconButton, VireoFormCounterFieldIncrementButtonSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default AddIcon */
+    incrementIcon: SlotProps<typeof SvgIcon, VireoFormCounterFieldIncrementIconSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+    /** @default FormHelperText */
+    formHelperText: SlotProps<typeof FormHelperText, VireoFormCounterFieldFormHelperTextSlotPropsOverrides, VireoFormCounterFieldOwnerState>;
+}>;
+type ComponentOwnedProp = "aria-describedby" | "aria-label" | "aria-labelledby" | "children" | "classes" | "component" | "defaultValue" | "disabled" | "error" | "fullWidth" | "name" | "onBlur" | "onChange" | "ref" | "required" | "size" | "slotProps" | "slots" | "value";
+/** Props VireoFormCounterField inherits from its default root after excluding component-owned props. */
+export type VireoFormCounterFieldInheritedProps = Omit<FormControlProps, ComponentOwnedProp>;
+/** Accessible naming contract for the counter and its numeric input. */
+export type VireoFormCounterFieldAccessibleNameProps = {
+    "aria-label": string;
+    "aria-labelledby"?: string;
+} | {
+    "aria-label"?: undefined;
+    "aria-labelledby": string;
+};
+/** Props owned by the bound counter field. The field name and value remain owned by `form.Field`. */
+export type VireoFormCounterFieldOwnProps = VireoFormCounterFieldSlotsAndSlotProps & {
+    classes?: Partial<VireoFormCounterFieldClasses>;
+    disabled?: boolean;
+    /** Accessible label for the decrement control. @default 'Decrease' */
+    decrementLabel?: string;
+    /** 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;
+    /** Accessible label for the increment control. @default 'Increase' */
+    incrementLabel?: string;
+    /** Ref forwarded to the native numeric text input. */
+    inputRef?: React.Ref<HTMLInputElement>;
+    /** Largest value emitted by user interaction. */
+    max?: number;
+    /** Smallest value emitted by user interaction. */
+    min?: number;
+    onBlur?: React.FocusEventHandler<HTMLDivElement>;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+    /** Called after a complete edit or step resolves to a different stored value. */
+    onValueChange?: (value: number | null) => void;
+    readOnly?: boolean;
+    required?: boolean;
+    /** @default 'medium' */
+    size?: VireoFormCounterFieldSize;
+    /** Positive finite amount used by buttons and Arrow keys. @default 1 */
+    step?: number;
+    /** Additional description IDs applied to the numeric input. */
+    "aria-describedby"?: string;
+};
+/** Props accepted by `field.CounterField`. */
+export type VireoFormCounterFieldProps = VireoFormCounterFieldOwnProps & VireoFormCounterFieldAccessibleNameProps & VireoFormCounterFieldInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_COUNTER_FIELD_NAME]?: VireoThemeComponent<VireoFormCounterFieldProps, VireoFormCounterFieldClassKey, VireoFormCounterFieldOwnerState, Theme>;
+    }
+}
+export {};

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+import React from "react";
+/** Summarizes form and field validation errors and links mapped errors back to their controls and steps. */
+export declare const VireoFormErrorSummary: React.ForwardRefExoticComponent<import("./VireoFormErrorSummary.types.js").VireoFormErrorSummarySlotsAndSlotProps & {
+    classes?: Partial<import("./VireoFormErrorSummary.classes.js").VireoFormErrorSummaryClasses>;
+    localeText?: Partial<import("./VireoFormErrorSummary.types.js").VireoFormErrorSummaryLocaleText>;
+    scope?: import("./VireoFormErrorSummary.types.js").VireoFormErrorSummaryScope;
+    title?: React.ReactNode;
+} & import("./VireoFormErrorSummary.types.js").VireoFormErrorSummaryInheritedProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoFormErrorSummary integration point. */
+export declare const VIREO_FORM_ERROR_SUMMARY_NAME = "VireoFormErrorSummary";
+/** Canonical public slots exposed by VireoFormErrorSummary, in rendered DOM order. */
+export declare const VIREO_FORM_ERROR_SUMMARY_SLOTS: readonly ["root", "icon", "content", "title", "group", "groupLabel", "list", "item", "itemButton"];
+/** Public slot names exposed by VireoFormErrorSummary. */
+export type VireoFormErrorSummarySlotName = (typeof VIREO_FORM_ERROR_SUMMARY_SLOTS)[number];

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

@@ -0,0 +1,14 @@
+/** Stable component name shared by every VireoFormErrorSummary integration point. */
+export const VIREO_FORM_ERROR_SUMMARY_NAME = "VireoFormErrorSummary";
+/** Canonical public slots exposed by VireoFormErrorSummary, in rendered DOM order. */
+export const VIREO_FORM_ERROR_SUMMARY_SLOTS = [
+    "root",
+    "icon",
+    "content",
+    "title",
+    "group",
+    "groupLabel",
+    "list",
+    "item",
+    "itemButton",
+];