@vireocodedev/ui 0.2.0 → 0.2.1

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

@@ -0,0 +1,132 @@
+import type { VireoFormErrorDisplay, VireoFormErrorFormatter } from "../../../../../capabilities/forms/components/forms/VireoForm/VireoForm.types.js";
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { FormControl, FormHelperText, IconButton, InputLabel, ListItemText, MenuItem, OutlinedInput, Select, SelectProps, TextFieldProps } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormSelectFieldClasses, type VireoFormSelectFieldClassKey } from "./VireoFormSelectField.classes.js";
+import type { VIREO_FORM_SELECT_FIELD_NAME } from "./VireoFormSelectField.identity.js";
+/** Scalar values supported by `field.SelectField`. Objects remain represented by their stable option value. */
+export type VireoFormSelectFieldValue = string | number;
+export type VireoFormSelectFieldOwnerState = {
+    dirty: boolean;
+    disabled: boolean;
+    errorVisible: boolean;
+    hasValue: boolean;
+    invalid: boolean;
+    readOnly: boolean;
+    submitting: boolean;
+    touched: boolean;
+    validating: boolean;
+};
+export interface VireoFormSelectFieldRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldInputLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldHtmlInputSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldSelectSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldOptionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldOptionTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldClearButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSelectFieldFormHelperTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by the bound form select field. */
+export type VireoFormSelectFieldSlots = {
+    root: React.ElementType;
+    inputLabel: React.ElementType;
+    input: React.ElementType;
+    htmlInput: React.ElementType;
+    select: React.ElementType;
+    option: React.ElementType;
+    optionText: React.ElementType;
+    clearButton: React.ElementType;
+    formHelperText: React.ElementType;
+};
+/** Slot props exposed by the bound form select field. */
+export type VireoFormSelectFieldSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormSelectFieldSlots, {
+    /** @default FormControl */
+    root: SlotProps<typeof FormControl, VireoFormSelectFieldRootSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default InputLabel */
+    inputLabel: SlotProps<typeof InputLabel, VireoFormSelectFieldInputLabelSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default OutlinedInput; follows `variant` for standard and filled fields. */
+    input: SlotProps<typeof OutlinedInput, VireoFormSelectFieldInputSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default 'input' */
+    htmlInput: SlotProps<"input", VireoFormSelectFieldHtmlInputSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default Select */
+    select: SlotProps<typeof Select, VireoFormSelectFieldSelectSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default MenuItem */
+    option: SlotProps<typeof MenuItem, VireoFormSelectFieldOptionSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default ListItemText */
+    optionText: SlotProps<typeof ListItemText, VireoFormSelectFieldOptionTextSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default IconButton */
+    clearButton: SlotProps<typeof IconButton, VireoFormSelectFieldClearButtonSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+    /** @default FormHelperText */
+    formHelperText: SlotProps<typeof FormHelperText, VireoFormSelectFieldFormHelperTextSlotPropsOverrides, VireoFormSelectFieldOwnerState>;
+}>;
+type VireoFormSelectFieldComponentOwnedProp = "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 VireoFormSelectFieldInheritedProps = Omit<TextFieldProps, VireoFormSelectFieldComponentOwnedProp>;
+/** Props owned by the bound form select field. The field name and value remain owned by `form.Field`. */
+export type VireoFormSelectFieldOwnProps<TOption, TValue extends VireoFormSelectFieldValue> = VireoFormSelectFieldSlotsAndSlotProps & {
+    /** 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 by the form for one option. */
+    getOptionValue: (option: TOption) => TValue;
+    /** Renders one option and the selected-value presentation. */
+    renderOption: (option: TOption) => React.ReactNode;
+    /** Returns whether one option is unavailable. */
+    getOptionDisabled?: (option: TOption) => boolean;
+    /** Override or extend the utility classes applied to each slot and state. */
+    classes?: Partial<VireoFormSelectFieldClasses>;
+    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 `null`. */
+    placeholder?: React.ReactNode;
+    /** Prevents the selected value from being cleared. @default false */
+    disableClearable?: boolean;
+    /** Accessible label for the clear action. @default 'Clear selection' */
+    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 option and clear changes after cancelable slot handlers. */
+    onValueChange?: (value: TValue | null) => void;
+    readOnly?: boolean;
+    required?: boolean;
+};
+/** Props accepted by `field.SelectField`. */
+export type VireoFormSelectFieldProps<TOption = unknown, TValue extends VireoFormSelectFieldValue = VireoFormSelectFieldValue> = VireoFormSelectFieldOwnProps<TOption, TValue> & VireoFormSelectFieldInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_SELECT_FIELD_NAME]?: VireoThemeComponent<VireoFormSelectFieldProps, VireoFormSelectFieldClassKey, VireoFormSelectFieldOwnerState, Theme>;
+    }
+}
+export {};

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,13 @@
+import React from "react";
+import { type VireoFormSelectMultipleFieldProps, type VireoFormSelectMultipleFieldValue } from "./VireoFormSelectMultipleField.types.js";
+type VireoFormSelectMultipleFieldComponent = {
+    <TOption, TValue extends VireoFormSelectMultipleFieldValue>(props: VireoFormSelectMultipleFieldProps<TOption, TValue> & React.RefAttributes<HTMLDivElement>): React.ReactElement;
+    displayName?: string;
+};
+/**
+ * Binds an ordered array of typed options to the current TanStack Form field and shared validation policy.
+ *
+ * Consumers render it as `field.SelectMultipleField`; the raw runtime remains internal to the forms capability.
+ */
+export declare const VireoFormSelectMultipleField: VireoFormSelectMultipleFieldComponent;
+export {};

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

@@ -0,0 +1,10 @@
+/** Stable component name shared by every VireoFormSelectMultipleField integration point. */
+export declare const VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME = "VireoFormSelectMultipleField";
+/** Canonical public slots exposed by VireoFormSelectMultipleField, in rendered DOM order. */
+export declare const VIREO_FORM_SELECT_MULTIPLE_FIELD_SLOTS: readonly ["root", "inputLabel", "input", "htmlInput", "select", "selectionSummary", "option", "optionCheckbox", "optionText", "clearButton", "formHelperText"];
+/** Canonical interaction and validation states exposed as utility classes. */
+export declare const VIREO_FORM_SELECT_MULTIPLE_FIELD_STATES: readonly ["dirty", "touched", "invalid", "errorVisible", "validating", "submitting", "disabled", "readOnly", "hasValue"];
+/** Public slot names exposed by VireoFormSelectMultipleField. */
+export type VireoFormSelectMultipleFieldSlotName = (typeof VIREO_FORM_SELECT_MULTIPLE_FIELD_SLOTS)[number];
+/** Public state names exposed by VireoFormSelectMultipleField. */
+export type VireoFormSelectMultipleFieldStateName = (typeof VIREO_FORM_SELECT_MULTIPLE_FIELD_STATES)[number];

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

@@ -0,0 +1,28 @@
+/** Stable component name shared by every VireoFormSelectMultipleField integration point. */
+export const VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME = "VireoFormSelectMultipleField";
+/** Canonical public slots exposed by VireoFormSelectMultipleField, in rendered DOM order. */
+export const VIREO_FORM_SELECT_MULTIPLE_FIELD_SLOTS = [
+    "root",
+    "inputLabel",
+    "input",
+    "htmlInput",
+    "select",
+    "selectionSummary",
+    "option",
+    "optionCheckbox",
+    "optionText",
+    "clearButton",
+    "formHelperText",
+];
+/** Canonical interaction and validation states exposed as utility classes. */
+export const VIREO_FORM_SELECT_MULTIPLE_FIELD_STATES = [
+    "dirty",
+    "touched",
+    "invalid",
+    "errorVisible",
+    "validating",
+    "submitting",
+    "disabled",
+    "readOnly",
+    "hasValue",
+];

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

@@ -0,0 +1,272 @@
+import { createElement as _createElement } from "react";
+import { Fragment as _Fragment, 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 Close from "@mui/icons-material/Close";
+import { InputAdornment, unstable_composeClasses as composeClasses, } from "@mui/material";
+import { useTheme, useThemeProps } from "@mui/material/styles";
+import { useForkRef } from "@mui/material/utils";
+import { useStore } from "@tanstack/react-form";
+import React from "react";
+import { getVireoFormSelectMultipleFieldUtilityClass, } from "./VireoFormSelectMultipleField.classes.js";
+import { VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME, } from "./VireoFormSelectMultipleField.identity.js";
+import { VireoFormSelectMultipleFieldClearButton, VireoFormSelectMultipleFieldFilledInput, VireoFormSelectMultipleFieldFormHelperText, VireoFormSelectMultipleFieldInputLabel, VireoFormSelectMultipleFieldOption, VireoFormSelectMultipleFieldOptionCheckbox, VireoFormSelectMultipleFieldOptionText, VireoFormSelectMultipleFieldOutlinedInput, VireoFormSelectMultipleFieldRoot, VireoFormSelectMultipleFieldSelect, VireoFormSelectMultipleFieldSelectionSummary, VireoFormSelectMultipleFieldStandardInput, } from "./VireoFormSelectMultipleField.styled.js";
+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",
+        ],
+        inputLabel: ["inputLabel"],
+        input: ["input"],
+        htmlInput: ["htmlInput"],
+        select: ["select"],
+        selectionSummary: ["selectionSummary"],
+        option: ["option"],
+        optionCheckbox: ["optionCheckbox"],
+        optionText: ["optionText"],
+        clearButton: ["clearButton"],
+        formHelperText: ["formHelperText"],
+    }, getVireoFormSelectMultipleFieldUtilityClass, classes);
+}
+function isAriaInvalid(value) {
+    return value === true || value === "true";
+}
+function normalizeMaxDisplayedOptions(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 2;
+}
+function resolveHtmlInputThemeSx(theme, props, ownerState) {
+    const styleOverride = theme.components?.[VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME]?.styleOverrides?.htmlInput;
+    if (typeof styleOverride === "function") {
+        return styleOverride({ ...props, ownerState, theme });
+    }
+    return styleOverride;
+}
+function VireoFormSelectMultipleFieldImpl(inProps, forwardedRef) {
+    const props = useThemeProps({
+        props: inProps,
+        name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    });
+    const theme = useTheme();
+    const { className, classes: classesProp, clearIcon, clearLabel = "Clear selections", disabled = false, disableClearable = false, error = false, errorDisplay: errorDisplayProp, formatError: formatErrorProp, fullWidth = true, getOptionDisabled, getOptionValue, helperText = " ", inputRef, label, maxDisplayedOptions: maxDisplayedOptionsProp = 2, onBlur, onValueChange, options, placeholder, readOnly = false, renderOption, renderSelectedOptions, required = false, slotProps = {}, slots = {}, style, sx, variant = "outlined", ...other } = props;
+    const maxDisplayedOptions = normalizeMaxDisplayedOptions(maxDisplayedOptionsProp);
+    const field = useVireoFieldContext();
+    const formContext = useVireoFormContext();
+    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);
+    const errorDisplay = errorDisplayProp ?? formContext.errorDisplay;
+    const errorVisible = fieldState.invalid &&
+        shouldDisplayVireoFormError(errorDisplay, {
+            submissionAttempts: formContext.submissionAttempts,
+            touched: fieldState.touched,
+        });
+    const formattedError = errorVisible
+        ? formatFirstVireoFormError(fieldState.errors, formatErrorProp ?? formContext.formatError)
+        : undefined;
+    const ownerState = {
+        dirty: fieldState.dirty,
+        disabled,
+        errorVisible,
+        hasValue: fieldState.value.length > 0,
+        invalid: fieldState.invalid,
+        readOnly,
+        submitting,
+        touched: fieldState.touched,
+        validating: fieldState.validating,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const htmlInputThemeSx = resolveHtmlInputThemeSx(theme, props, ownerState);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const resolvedInputLabelSlotProps = resolveSlotProps(slotProps.inputLabel, ownerState);
+    const { className: inputLabelSlotClassName, shrink: inputLabelSlotShrink, ...inputLabelSlotOther } = resolvedInputLabelSlotProps;
+    const resolvedInputSlotProps = resolveSlotProps(slotProps.input, ownerState);
+    const { className: inputSlotClassName, endAdornment: inputSlotEndAdornment, readOnly: inputSlotReadOnly, ...inputSlotOther } = resolvedInputSlotProps;
+    const resolvedHtmlInputSlotProps = resolveSlotProps(slotProps.htmlInput, ownerState);
+    const { "aria-invalid": htmlInputAriaInvalid, className: htmlInputSlotClassName, ref: htmlInputSlotRef, sx: htmlInputSlotSx, ...htmlInputSlotOther } = resolvedHtmlInputSlotProps;
+    const resolvedSelectSlotProps = resolveSlotProps(slotProps.select, ownerState);
+    const { SelectDisplayProps: selectSlotDisplayProps, className: selectSlotClassName, displayEmpty: _selectSlotDisplayEmpty, inputProps: selectSlotInputProps, multiple: _selectSlotMultiple, native: _selectSlotNative, onBlur: selectSlotOnBlur, onChange: selectSlotOnChange, renderValue: _selectSlotRenderValue, ...selectSlotOther } = resolvedSelectSlotProps;
+    void _selectSlotDisplayEmpty;
+    void _selectSlotMultiple;
+    void _selectSlotNative;
+    void _selectSlotRenderValue;
+    const resolvedSelectionSummarySlotProps = resolveSlotProps(slotProps.selectionSummary, ownerState);
+    const { className: selectionSummarySlotClassName, ...selectionSummarySlotOther } = resolvedSelectionSummarySlotProps;
+    const resolvedOptionSlotProps = resolveSlotProps(slotProps.option, ownerState);
+    const { className: optionSlotClassName, disabled: optionSlotDisabled, ...optionSlotOther } = resolvedOptionSlotProps;
+    const resolvedOptionCheckboxSlotProps = resolveSlotProps(slotProps.optionCheckbox, ownerState);
+    const { className: optionCheckboxSlotClassName, ...optionCheckboxSlotOther } = resolvedOptionCheckboxSlotProps;
+    const resolvedOptionTextSlotProps = resolveSlotProps(slotProps.optionText, ownerState);
+    const { className: optionTextSlotClassName, ...optionTextSlotOther } = resolvedOptionTextSlotProps;
+    const resolvedClearButtonSlotProps = resolveSlotProps(slotProps.clearButton, ownerState);
+    const { children: clearButtonSlotChildren, className: clearButtonSlotClassName, onClick: clearButtonSlotOnClick, onMouseDown: clearButtonSlotOnMouseDown, ...clearButtonSlotOther } = resolvedClearButtonSlotProps;
+    const resolvedFormHelperTextSlotProps = resolveSlotProps(slotProps.formHelperText, ownerState);
+    const { className: formHelperTextSlotClassName, ...formHelperTextSlotOther } = resolvedFormHelperTextSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const nativeInputRef = useForkRef(inputRef, htmlInputSlotRef);
+    const selectedOptions = fieldState.value
+        .map(value => options.find(option => getOptionValue(option) === value))
+        .filter((option) => option !== undefined);
+    const displayedOptions = selectedOptions.slice(0, maxDisplayedOptions);
+    const hiddenCount = selectedOptions.length - displayedOptions.length;
+    const effectiveError = error || fieldState.invalid;
+    const effectiveHelperText = errorVisible ? formattedError : helperText;
+    const clearable = ownerState.hasValue && !disabled && !readOnly && !disableClearable;
+    const normalizeChangedValue = (value) => {
+        if (Array.isArray(value))
+            return value;
+        if (typeof value !== "string")
+            return [];
+        return value
+            .split(",")
+            .map(serialized => options.find(option => String(getOptionValue(option)) === serialized))
+            .filter((option) => option !== undefined)
+            .map(getOptionValue);
+    };
+    const handleChange = (event, child) => {
+        selectSlotOnChange?.(event, child);
+        if (event.defaultPrevented)
+            return;
+        const nextValue = normalizeChangedValue(event.target.value);
+        onValueChange?.(nextValue);
+        field.handleChange(nextValue);
+    };
+    const handleBlur = event => {
+        selectSlotOnBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        onBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        field.handleBlur();
+    };
+    const handleClearMouseDown = event => {
+        clearButtonSlotOnMouseDown?.(event);
+        if (event.defaultPrevented)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+    };
+    const handleClearClick = event => {
+        clearButtonSlotOnClick?.(event);
+        if (event.defaultPrevented)
+            return;
+        event.stopPropagation();
+        onValueChange?.([]);
+        field.handleChange([]);
+    };
+    const renderSelectedValue = () => {
+        const SelectionSummary = slots.selectionSummary ?? VireoFormSelectMultipleFieldSelectionSummary;
+        if (selectedOptions.length === 0) {
+            return placeholder === undefined ? null : (_jsx(SelectionSummary, { ...selectionSummarySlotOther, ownerState: ownerState, className: joinClassNames(classes.selectionSummary, selectionSummarySlotClassName), color: "text.secondary", component: "span", children: placeholder }));
+        }
+        let content;
+        if (renderSelectedOptions) {
+            content = renderSelectedOptions({
+                selectedOptions,
+                displayedOptions,
+                hiddenCount,
+                maxDisplayedOptions,
+            });
+        }
+        else if (maxDisplayedOptions === 0) {
+            content = `${selectedOptions.length} selected`;
+        }
+        else {
+            content = (_jsxs(_Fragment, { children: [displayedOptions.map((option, index) => (_jsxs(React.Fragment, { children: [index > 0 ? ", " : null, renderOption(option)] }, getOptionValue(option)))), hiddenCount > 0 ? ` +${hiddenCount}` : null] }));
+        }
+        return (_jsx(SelectionSummary, { ...selectionSummarySlotOther, ownerState: ownerState, className: joinClassNames(classes.selectionSummary, selectionSummarySlotClassName), component: "span", children: content }));
+    };
+    const clearAdornment = clearable ? (_jsx(InputAdornment, { position: "end", children: _jsx(VireoFormSelectMultipleFieldClearButton, { ...clearButtonSlotOther, as: slots.clearButton, ownerState: ownerState, "aria-label": clearLabel, className: joinClassNames(classes.clearButton, clearButtonSlotClassName), onClick: handleClearClick, onMouseDown: handleClearMouseDown, size: "small", children: clearButtonSlotChildren ?? clearIcon ?? _jsx(Close, { fontSize: "small" }) }) })) : null;
+    return (_jsx(VireoFormSelectMultipleFieldRoot, { ...other, ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), disabled: disabled, error: effectiveError, fullWidth: fullWidth, helperText: effectiveHelperText, inputRef: nativeInputRef, label: label, name: field.name, required: required, select: true, slots: {
+            root: slots.root,
+            inputLabel: slots.inputLabel ?? VireoFormSelectMultipleFieldInputLabel,
+            input: slots.input ??
+                (variant === "filled"
+                    ? VireoFormSelectMultipleFieldFilledInput
+                    : variant === "standard"
+                        ? VireoFormSelectMultipleFieldStandardInput
+                        : VireoFormSelectMultipleFieldOutlinedInput),
+            htmlInput: slots.htmlInput,
+            formHelperText: slots.formHelperText ?? VireoFormSelectMultipleFieldFormHelperText,
+            select: slots.select ?? VireoFormSelectMultipleFieldSelect,
+        }, slotProps: {
+            root: {
+                ...rootSlotOther,
+                style: { ...style, ...rootSlotStyle },
+                sx: mergeSx(sx, rootSlotSx),
+            },
+            inputLabel: {
+                ...inputLabelSlotOther,
+                className: joinClassNames(classes.inputLabel, inputLabelSlotClassName),
+                shrink: inputLabelSlotShrink ?? (ownerState.hasValue || placeholder !== undefined),
+            },
+            input: {
+                ...inputSlotOther,
+                className: joinClassNames(classes.input, inputSlotClassName),
+                endAdornment: (_jsxs(_Fragment, { children: [inputSlotEndAdornment, clearAdornment] })),
+                readOnly: readOnly || inputSlotReadOnly,
+            },
+            htmlInput: {
+                ...htmlInputSlotOther,
+                "aria-invalid": effectiveError || isAriaInvalid(htmlInputAriaInvalid) || undefined,
+                className: joinClassNames(classes.htmlInput, htmlInputSlotClassName),
+                sx: mergeSx(htmlInputThemeSx, htmlInputSlotSx),
+            },
+            select: {
+                ...selectSlotOther,
+                SelectDisplayProps: {
+                    ...selectSlotDisplayProps,
+                    "aria-invalid": effectiveError || isAriaInvalid(selectSlotDisplayProps?.["aria-invalid"]) || undefined,
+                },
+                className: joinClassNames(classes.select, selectSlotClassName),
+                displayEmpty: true,
+                inputProps: {
+                    ...selectSlotInputProps,
+                    "aria-invalid": effectiveError || isAriaInvalid(selectSlotInputProps?.["aria-invalid"]) || undefined,
+                    name: field.name,
+                    readOnly,
+                },
+                multiple: true,
+                native: false,
+                onBlur: handleBlur,
+                onChange: handleChange,
+                renderValue: renderSelectedValue,
+            },
+            formHelperText: {
+                ...formHelperTextSlotOther,
+                className: joinClassNames(classes.formHelperText, formHelperTextSlotClassName),
+            },
+        }, value: fieldState.value, variant: variant, children: options.map(option => {
+            const optionValue = getOptionValue(option);
+            const optionContent = renderOption(option);
+            const selected = fieldState.value.includes(optionValue);
+            return (_createElement(VireoFormSelectMultipleFieldOption, { ...optionSlotOther, as: slots.option, key: optionValue, ownerState: ownerState, className: joinClassNames(classes.option, optionSlotClassName), disabled: optionSlotDisabled || getOptionDisabled?.(option), value: optionValue },
+                _jsx(VireoFormSelectMultipleFieldOptionCheckbox, { ...optionCheckboxSlotOther, as: slots.optionCheckbox, ownerState: ownerState, "aria-hidden": "true", checked: selected, className: joinClassNames(classes.optionCheckbox, optionCheckboxSlotClassName), disableRipple: true, tabIndex: -1 }),
+                typeof optionContent === "string" ? (_jsx(VireoFormSelectMultipleFieldOptionText, { ...optionTextSlotOther, as: slots.optionText, ownerState: ownerState, className: joinClassNames(classes.optionText, optionTextSlotClassName), primary: optionContent })) : (optionContent)));
+        }) }));
+}
+/**
+ * Binds an ordered array of typed options to the current TanStack Form field and shared validation policy.
+ *
+ * Consumers render it as `field.SelectMultipleField`; the raw runtime remains internal to the forms capability.
+ */
+export const VireoFormSelectMultipleField = React.forwardRef(VireoFormSelectMultipleFieldImpl);
+VireoFormSelectMultipleField.displayName = VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME;

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

@@ -0,0 +1,18 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type CheckboxProps, type FilledInputProps, type FormHelperTextProps, type IconButtonProps, type InputLabelProps, type InputProps, type MenuItemProps, type OutlinedInputProps, type TextFieldProps, type TypographyProps } from "@mui/material";
+import type React from "react";
+import { type VireoFormSelectMultipleFieldOwnerState } from "./VireoFormSelectMultipleField.types.js";
+type VireoFormSelectMultipleFieldStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormSelectMultipleFieldOwnerState>;
+export declare const VireoFormSelectMultipleFieldRoot: VireoFormSelectMultipleFieldStyledSlotComponent<TextFieldProps>;
+export declare const VireoFormSelectMultipleFieldInputLabel: VireoFormSelectMultipleFieldStyledSlotComponent<InputLabelProps>;
+export declare const VireoFormSelectMultipleFieldOutlinedInput: VireoFormSelectMultipleFieldStyledSlotComponent<OutlinedInputProps>;
+export declare const VireoFormSelectMultipleFieldFilledInput: VireoFormSelectMultipleFieldStyledSlotComponent<FilledInputProps>;
+export declare const VireoFormSelectMultipleFieldStandardInput: VireoFormSelectMultipleFieldStyledSlotComponent<InputProps>;
+export declare const VireoFormSelectMultipleFieldSelect: React.ElementType;
+export declare const VireoFormSelectMultipleFieldSelectionSummary: VireoFormSelectMultipleFieldStyledSlotComponent<TypographyProps>;
+export declare const VireoFormSelectMultipleFieldOption: VireoFormSelectMultipleFieldStyledSlotComponent<MenuItemProps>;
+export declare const VireoFormSelectMultipleFieldOptionCheckbox: VireoFormSelectMultipleFieldStyledSlotComponent<CheckboxProps>;
+export declare const VireoFormSelectMultipleFieldOptionText: React.ElementType;
+export declare const VireoFormSelectMultipleFieldClearButton: VireoFormSelectMultipleFieldStyledSlotComponent<IconButtonProps>;
+export declare const VireoFormSelectMultipleFieldFormHelperText: VireoFormSelectMultipleFieldStyledSlotComponent<FormHelperTextProps>;
+export {};

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

@@ -0,0 +1,80 @@
+import { Checkbox, FilledInput, FormHelperText, IconButton, Input, InputLabel, ListItemText, MenuItem, OutlinedInput, Select, TextField, Typography, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME } from "./VireoFormSelectMultipleField.identity.js";
+export const VireoFormSelectMultipleFieldRoot = styled(TextField, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Root",
+    overridesResolver: ({ ownerState }, styles) => [
+        styles.root,
+        ownerState.dirty && styles.dirty,
+        ownerState.touched && styles.touched,
+        ownerState.invalid && styles.invalid,
+        ownerState.errorVisible && styles.errorVisible,
+        ownerState.validating && styles.validating,
+        ownerState.submitting && styles.submitting,
+        ownerState.disabled && styles.disabled,
+        ownerState.readOnly && styles.readOnly,
+        ownerState.hasValue && styles.hasValue,
+    ],
+})({});
+export const VireoFormSelectMultipleFieldInputLabel = styled(InputLabel, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "InputLabel",
+    overridesResolver: (_props, styles) => styles.inputLabel,
+})({});
+export const VireoFormSelectMultipleFieldOutlinedInput = styled(OutlinedInput, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Input",
+    overridesResolver: (_props, styles) => styles.input,
+})({});
+export const VireoFormSelectMultipleFieldFilledInput = styled(FilledInput, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Input",
+    overridesResolver: (_props, styles) => styles.input,
+})({});
+export const VireoFormSelectMultipleFieldStandardInput = styled(Input, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Input",
+    overridesResolver: (_props, styles) => styles.input,
+})({});
+export const VireoFormSelectMultipleFieldSelect = styled(Select, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Select",
+    overridesResolver: (_props, styles) => styles.select,
+})({});
+export const VireoFormSelectMultipleFieldSelectionSummary = styled(Typography, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "SelectionSummary",
+    overridesResolver: (_props, styles) => styles.selectionSummary,
+})({
+    display: "block",
+    minWidth: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+});
+export const VireoFormSelectMultipleFieldOption = styled(MenuItem, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "Option",
+    overridesResolver: (_props, styles) => styles.option,
+})({});
+export const VireoFormSelectMultipleFieldOptionCheckbox = styled(Checkbox, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "OptionCheckbox",
+    overridesResolver: (_props, styles) => styles.optionCheckbox,
+})({});
+export const VireoFormSelectMultipleFieldOptionText = styled(ListItemText, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "OptionText",
+    overridesResolver: (_props, styles) => styles.optionText,
+})({});
+export const VireoFormSelectMultipleFieldClearButton = styled(IconButton, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "ClearButton",
+    overridesResolver: (_props, styles) => styles.clearButton,
+})({ marginInlineEnd: 20 });
+export const VireoFormSelectMultipleFieldFormHelperText = styled(FormHelperText, {
+    name: VIREO_FORM_SELECT_MULTIPLE_FIELD_NAME,
+    slot: "FormHelperText",
+    overridesResolver: (_props, styles) => styles.formHelperText,
+})({});