@vireocodedev/ui 0.2.0 → 0.2.1

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

@@ -0,0 +1,157 @@
+import { createElement as _createElement } from "react";
+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 { 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 { getVireoFormRadioGroupFieldUtilityClass, } from "./VireoFormRadioGroupField.classes.js";
+import { VIREO_FORM_RADIO_GROUP_FIELD_NAME, } from "./VireoFormRadioGroupField.identity.js";
+import { VireoFormRadioGroupFieldFormControlLabel, VireoFormRadioGroupFieldFormHelperText, VireoFormRadioGroupFieldOptionLabel, VireoFormRadioGroupFieldRadio, VireoFormRadioGroupFieldRadioGroup, VireoFormRadioGroupFieldRoot, } from "./VireoFormRadioGroupField.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.row && "row",
+            ownerState.hasValue && "hasValue",
+        ],
+        radioGroup: ["radioGroup"],
+        formControlLabel: ["formControlLabel"],
+        radio: ["radio"],
+        optionLabel: ["optionLabel"],
+        formHelperText: ["formHelperText"],
+    }, getVireoFormRadioGroupFieldUtilityClass, classes);
+}
+function encodeOptionValue(value) {
+    return `${typeof value}:${String(value)}`;
+}
+function isAriaInvalid(value) {
+    return value === true || value === "true";
+}
+function joinIds(...ids) {
+    const joined = ids.filter(Boolean).join(" ");
+    return joined || undefined;
+}
+function VireoFormRadioGroupFieldImpl(inProps, forwardedRef) {
+    const props = useThemeProps({
+        props: inProps,
+        name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    });
+    const { "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, classes: classesProp, disabled = false, error = false, errorDisplay: errorDisplayProp, formatError: formatErrorProp, fullWidth = true, getOptionDisabled, getOptionValue, helperText = " ", labelPlacement = "end", onBlur, onChange, onValueChange, options, renderOption, required = false, row = false, slotProps = {}, slots = {}, style, sx, ...other } = props;
+    const field = useVireoFieldContext();
+    const formContext = useVireoFormContext();
+    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);
+    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 !== null,
+        invalid: fieldState.invalid,
+        row,
+        submitting,
+        touched: fieldState.touched,
+        validating: fieldState.validating,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const resolvedRadioGroupSlotProps = resolveSlotProps(slotProps.radioGroup, ownerState);
+    const { "aria-describedby": radioGroupSlotAriaDescribedBy, "aria-invalid": radioGroupSlotAriaInvalid, "aria-label": radioGroupSlotAriaLabel, "aria-labelledby": radioGroupSlotAriaLabelledBy, className: radioGroupSlotClassName, onBlur: radioGroupSlotOnBlur, onChange: radioGroupSlotOnChange, ...radioGroupSlotOther } = resolvedRadioGroupSlotProps;
+    const resolvedFormControlLabelSlotProps = resolveSlotProps(slotProps.formControlLabel, ownerState);
+    const { className: formControlLabelSlotClassName, disabled: formControlLabelSlotDisabled, ...formControlLabelSlotOther } = resolvedFormControlLabelSlotProps;
+    const resolvedRadioSlotProps = resolveSlotProps(slotProps.radio, ownerState);
+    const { checked: _radioSlotChecked, className: radioSlotClassName, defaultChecked: _radioSlotDefaultChecked, disabled: radioSlotDisabled, name: _radioSlotName, value: _radioSlotValue, ...radioSlotOther } = resolvedRadioSlotProps;
+    void _radioSlotChecked;
+    void _radioSlotDefaultChecked;
+    void _radioSlotName;
+    void _radioSlotValue;
+    const resolvedOptionLabelSlotProps = resolveSlotProps(slotProps.optionLabel, ownerState);
+    const { className: optionLabelSlotClassName, ...optionLabelSlotOther } = resolvedOptionLabelSlotProps;
+    const resolvedFormHelperTextSlotProps = resolveSlotProps(slotProps.formHelperText, ownerState);
+    const { className: formHelperTextSlotClassName, id: formHelperTextSlotId, ...formHelperTextSlotOther } = resolvedFormHelperTextSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const effectiveError = error || fieldState.invalid;
+    const effectiveHelperText = errorVisible ? formattedError : helperText;
+    const formHelperTextId = formHelperTextSlotId ?? generatedHelperTextId;
+    const groupDescribedBy = joinIds(ariaDescribedBy, radioGroupSlotAriaDescribedBy, effectiveHelperText !== undefined ? formHelperTextId : undefined);
+    const encodedValue = fieldState.value === null ? "" : encodeOptionValue(fieldState.value);
+    const handleChange = (event, nextEncodedValue) => {
+        const restoreCheckedValue = () => {
+            const group = event.currentTarget;
+            queueMicrotask(() => {
+                group.querySelectorAll('input[type="radio"]').forEach(input => {
+                    input.checked = input.value === encodedValue;
+                });
+            });
+        };
+        radioGroupSlotOnChange?.(event, nextEncodedValue);
+        if (event.defaultPrevented) {
+            restoreCheckedValue();
+            return;
+        }
+        onChange?.(event, nextEncodedValue);
+        if (event.defaultPrevented) {
+            restoreCheckedValue();
+            return;
+        }
+        const selectedOption = options.find(option => encodeOptionValue(getOptionValue(option)) === nextEncodedValue);
+        if (selectedOption === undefined)
+            return;
+        const nextValue = getOptionValue(selectedOption);
+        onValueChange?.(nextValue);
+        field.handleChange(nextValue);
+    };
+    const handleBlur = event => {
+        radioGroupSlotOnBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        onBlur?.(event);
+        if (event.defaultPrevented)
+            return;
+        field.handleBlur();
+    };
+    return (_jsxs(VireoFormRadioGroupFieldRoot, { ...other, ...rootSlotOther, as: slots.root, ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), disabled: disabled, error: effectiveError, fullWidth: fullWidth, required: required, style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [_jsx(VireoFormRadioGroupFieldRadioGroup, { ...radioGroupSlotOther, as: slots.radioGroup, ownerState: ownerState, "aria-describedby": groupDescribedBy, "aria-invalid": effectiveError || isAriaInvalid(radioGroupSlotAriaInvalid) || undefined, "aria-label": ariaLabel ?? radioGroupSlotAriaLabel, "aria-labelledby": ariaLabelledBy ?? radioGroupSlotAriaLabelledBy, className: joinClassNames(classes.radioGroup, radioGroupSlotClassName), name: field.name, onBlur: handleBlur, onChange: handleChange, row: row, value: encodedValue, children: options.map(option => {
+                    const optionValue = getOptionValue(option);
+                    const optionDisabled = disabled ||
+                        radioSlotDisabled === true ||
+                        formControlLabelSlotDisabled === true ||
+                        getOptionDisabled?.(option);
+                    return (_createElement(VireoFormRadioGroupFieldFormControlLabel, { ...formControlLabelSlotOther, as: slots.formControlLabel, key: encodeOptionValue(optionValue), ownerState: ownerState, className: joinClassNames(classes.formControlLabel, formControlLabelSlotClassName), control: _jsx(VireoFormRadioGroupFieldRadio, { ...radioSlotOther, as: slots.radio, ownerState: ownerState, className: joinClassNames(classes.radio, radioSlotClassName), disabled: optionDisabled, name: field.name, required: required, value: encodeOptionValue(optionValue) }), disabled: optionDisabled, disableTypography: true, label: _jsx(VireoFormRadioGroupFieldOptionLabel, { ...optionLabelSlotOther, as: slots.optionLabel, ownerState: ownerState, className: joinClassNames(classes.optionLabel, optionLabelSlotClassName), component: "span", children: renderOption(option) }), labelPlacement: labelPlacement, value: encodeOptionValue(optionValue) }));
+                }) }), effectiveHelperText !== undefined && (_jsx(VireoFormRadioGroupFieldFormHelperText, { ...formHelperTextSlotOther, as: slots.formHelperText, id: formHelperTextId, ownerState: ownerState, className: joinClassNames(classes.formHelperText, formHelperTextSlotClassName), children: effectiveHelperText }))] }));
+}
+/**
+ * Binds typed scalar radio options to the current TanStack Form field and shared validation policy.
+ *
+ * Consumers render it as `field.RadioGroupField`; the raw runtime remains internal to the forms capability.
+ */
+export const VireoFormRadioGroupField = React.forwardRef(VireoFormRadioGroupFieldImpl);
+VireoFormRadioGroupField.displayName = VIREO_FORM_RADIO_GROUP_FIELD_NAME;

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

@@ -0,0 +1,11 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type FormControlLabelProps, type FormControlProps, type FormHelperTextProps, type RadioGroupProps, type RadioProps, type TypographyProps } from "@mui/material";
+import { type VireoFormRadioGroupFieldOwnerState } from "./VireoFormRadioGroupField.types.js";
+type VireoFormRadioGroupFieldStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormRadioGroupFieldOwnerState>;
+export declare const VireoFormRadioGroupFieldRoot: VireoFormRadioGroupFieldStyledSlotComponent<FormControlProps>;
+export declare const VireoFormRadioGroupFieldRadioGroup: VireoFormRadioGroupFieldStyledSlotComponent<RadioGroupProps>;
+export declare const VireoFormRadioGroupFieldFormControlLabel: VireoFormRadioGroupFieldStyledSlotComponent<FormControlLabelProps>;
+export declare const VireoFormRadioGroupFieldRadio: VireoFormRadioGroupFieldStyledSlotComponent<RadioProps>;
+export declare const VireoFormRadioGroupFieldOptionLabel: VireoFormRadioGroupFieldStyledSlotComponent<TypographyProps>;
+export declare const VireoFormRadioGroupFieldFormHelperText: VireoFormRadioGroupFieldStyledSlotComponent<FormHelperTextProps>;
+export {};

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

@@ -0,0 +1,46 @@
+import { FormControl, FormControlLabel, FormHelperText, Radio, RadioGroup, Typography, } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FORM_RADIO_GROUP_FIELD_NAME } from "./VireoFormRadioGroupField.identity.js";
+export const VireoFormRadioGroupFieldRoot = styled(FormControl, {
+    name: VIREO_FORM_RADIO_GROUP_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.row && styles.row,
+        props.ownerState.hasValue && styles.hasValue,
+    ],
+})({});
+export const VireoFormRadioGroupFieldRadioGroup = styled(RadioGroup, {
+    name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    slot: "RadioGroup",
+    overridesResolver: (_props, styles) => styles.radioGroup,
+})({});
+export const VireoFormRadioGroupFieldFormControlLabel = styled(FormControlLabel, {
+    name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    slot: "FormControlLabel",
+    overridesResolver: (_props, styles) => styles.formControlLabel,
+})({});
+export const VireoFormRadioGroupFieldRadio = styled(Radio, {
+    name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    slot: "Radio",
+    overridesResolver: (_props, styles) => styles.radio,
+})({});
+export const VireoFormRadioGroupFieldOptionLabel = styled(Typography, {
+    name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    slot: "OptionLabel",
+    overridesResolver: (_props, styles) => styles.optionLabel,
+})({});
+export const VireoFormRadioGroupFieldFormHelperText = styled(FormHelperText, {
+    name: VIREO_FORM_RADIO_GROUP_FIELD_NAME,
+    slot: "FormHelperText",
+    overridesResolver: (_props, styles) => styles.formHelperText,
+})(({ theme }) => ({
+    marginInline: theme.spacing(1.75),
+}));

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

@@ -0,0 +1,115 @@
+import type { VireoFormErrorDisplay, VireoFormErrorFormatter } from "../../../../../capabilities/forms/components/forms/VireoForm/VireoForm.types.js";
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { FormControl, FormControlLabel, FormControlLabelProps, FormControlProps, FormHelperText, Radio, RadioGroup, RadioGroupProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormRadioGroupFieldClasses, type VireoFormRadioGroupFieldClassKey } from "./VireoFormRadioGroupField.classes.js";
+import type { VIREO_FORM_RADIO_GROUP_FIELD_NAME } from "./VireoFormRadioGroupField.identity.js";
+/** Scalar values supported by `field.RadioGroupField`. Objects remain represented by their stable option value. */
+export type VireoFormRadioGroupFieldValue = string | number;
+export type VireoFormRadioGroupFieldOwnerState = {
+    dirty: boolean;
+    disabled: boolean;
+    errorVisible: boolean;
+    hasValue: boolean;
+    invalid: boolean;
+    row: boolean;
+    submitting: boolean;
+    touched: boolean;
+    validating: boolean;
+};
+export interface VireoFormRadioGroupFieldRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormRadioGroupFieldRadioGroupSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormRadioGroupFieldFormControlLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormRadioGroupFieldRadioSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormRadioGroupFieldOptionLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormRadioGroupFieldFormHelperTextSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by the bound form radio-group field. */
+export type VireoFormRadioGroupFieldSlots = {
+    root: React.ElementType;
+    radioGroup: React.ElementType;
+    formControlLabel: React.ElementType;
+    radio: React.ElementType;
+    optionLabel: React.ElementType;
+    formHelperText: React.ElementType;
+};
+/** Slot props exposed by the bound form radio-group field. */
+export type VireoFormRadioGroupFieldSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormRadioGroupFieldSlots, {
+    /** @default FormControl */
+    root: SlotProps<typeof FormControl, VireoFormRadioGroupFieldRootSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+    /** @default RadioGroup */
+    radioGroup: SlotProps<typeof RadioGroup, VireoFormRadioGroupFieldRadioGroupSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+    /** @default FormControlLabel */
+    formControlLabel: SlotProps<typeof FormControlLabel, VireoFormRadioGroupFieldFormControlLabelSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+    /** @default Radio */
+    radio: SlotProps<typeof Radio, VireoFormRadioGroupFieldRadioSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+    /** @default Typography */
+    optionLabel: SlotProps<typeof Typography, VireoFormRadioGroupFieldOptionLabelSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+    /** @default FormHelperText */
+    formHelperText: SlotProps<typeof FormHelperText, VireoFormRadioGroupFieldFormHelperTextSlotPropsOverrides, VireoFormRadioGroupFieldOwnerState>;
+}>;
+type VireoFormRadioGroupFieldComponentOwnedProp = "aria-describedby" | "aria-label" | "aria-labelledby" | "children" | "classes" | "component" | "defaultValue" | "disabled" | "error" | "fullWidth" | "name" | "onBlur" | "onChange" | "required" | "row" | "slotProps" | "slots" | "value";
+/** Props VireoFormRadioGroupField inherits from its default root after excluding component-owned props. */
+export type VireoFormRadioGroupFieldInheritedProps = Omit<FormControlProps, VireoFormRadioGroupFieldComponentOwnedProp>;
+/** Accessible naming contract for the radio group itself. */
+export type VireoFormRadioGroupFieldAccessibleNameProps = {
+    "aria-label": string;
+    "aria-labelledby"?: string;
+} | {
+    "aria-label"?: undefined;
+    "aria-labelledby": string;
+};
+/** Props owned by the bound form radio-group field. The field name and value remain owned by `form.Field`. */
+export type VireoFormRadioGroupFieldOwnProps<TOption, TValue extends VireoFormRadioGroupFieldValue> = VireoFormRadioGroupFieldSlotsAndSlotProps & {
+    /** Options rendered by the group. */
+    options: readonly TOption[];
+    /** Returns the stable unique scalar value stored by the form for one option. */
+    getOptionValue: (option: TOption) => TValue;
+    /** Renders the visible label for one option. */
+    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<VireoFormRadioGroupFieldClasses>;
+    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;
+    /** Places option controls horizontally. @default false */
+    row?: boolean;
+    /** @default 'end' */
+    labelPlacement?: FormControlLabelProps["labelPlacement"];
+    onBlur?: NonNullable<RadioGroupProps["onBlur"]>;
+    onChange?: NonNullable<RadioGroupProps["onChange"]>;
+    /** Observes accepted option changes after cancelable handlers. */
+    onValueChange?: (value: TValue) => void;
+    required?: boolean;
+    "aria-describedby"?: string;
+};
+/** Props accepted by `field.RadioGroupField`. */
+export type VireoFormRadioGroupFieldProps<TOption = unknown, TValue extends VireoFormRadioGroupFieldValue = VireoFormRadioGroupFieldValue> = VireoFormRadioGroupFieldOwnProps<TOption, TValue> & VireoFormRadioGroupFieldAccessibleNameProps & VireoFormRadioGroupFieldInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_RADIO_GROUP_FIELD_NAME]?: VireoThemeComponent<VireoFormRadioGroupFieldProps, VireoFormRadioGroupFieldClassKey, VireoFormRadioGroupFieldOwnerState, Theme>;
+    }
+}
+export {};

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,12 @@
+import React from "react";
+/** Groups related form content under an accessible heading and a container-responsive layout. */
+export declare const VireoFormSection: React.ForwardRefExoticComponent<import("./VireoFormSection.types.js").VireoFormSectionSlotsAndSlotProps & {
+    children: React.ReactNode;
+    classes?: Partial<import("./VireoFormSection.classes.js").VireoFormSectionClasses>;
+    description?: React.ReactNode;
+    headingLevel?: import("./VireoFormSection.types.js").VireoFormSectionHeadingLevel;
+    layout?: import("./VireoFormSection.types.js").VireoFormSectionLayout;
+    label: React.ReactNode;
+    maxColumns?: import("./VireoFormSection.types.js").VireoFormSectionMaxColumns;
+    variant?: import("./VireoFormSection.types.js").VireoFormSectionVariant;
+} & import("./VireoFormSection.types.js").VireoFormSectionInheritedProps & React.RefAttributes<HTMLElement>>;

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

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoFormSection integration point. */
+export declare const VIREO_FORM_SECTION_NAME = "VireoFormSection";
+/** Canonical public slots exposed by VireoFormSection, in rendered DOM order. */
+export declare const VIREO_FORM_SECTION_SLOTS: readonly ["root", "header", "label", "description", "content", "layout"];
+/** Public slot names exposed by VireoFormSection. */
+export type VireoFormSectionSlotName = (typeof VIREO_FORM_SECTION_SLOTS)[number];

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

@@ -0,0 +1,11 @@
+/** Stable component name shared by every VireoFormSection integration point. */
+export const VIREO_FORM_SECTION_NAME = "VireoFormSection";
+/** Canonical public slots exposed by VireoFormSection, in rendered DOM order. */
+export const VIREO_FORM_SECTION_SLOTS = [
+    "root",
+    "header",
+    "label",
+    "description",
+    "content",
+    "layout",
+];

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

@@ -0,0 +1,53 @@
+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 { getVireoFormSectionUtilityClass } from "./VireoFormSection.classes.js";
+import { VIREO_FORM_SECTION_NAME } from "./VireoFormSection.identity.js";
+import { VireoFormSectionContent, VireoFormSectionDescription, VireoFormSectionHeader, VireoFormSectionLabel, VireoFormSectionLayout, VireoFormSectionRoot, } from "./VireoFormSection.styled.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        header: ["header"],
+        label: ["label"],
+        description: ["description"],
+        content: ["content"],
+        layout: ["layout"],
+    }, getVireoFormSectionUtilityClass, classes);
+}
+/** Groups related form content under an accessible heading and a container-responsive layout. */
+export const VireoFormSection = React.forwardRef(function VireoFormSection(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_SECTION_NAME });
+    const { children, className, classes: classesProp, description, headingLevel = 2, label, layout = "grid", maxColumns = 2, slotProps = {}, slots = {}, style, sx, variant = "divided", ...other } = props;
+    const ownerState = {
+        hasDescription: description !== undefined && description !== null,
+        headingLevel,
+        layout,
+        maxColumns,
+        variant,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const generatedId = React.useId();
+    const generatedHeadingId = `${generatedId}-heading`;
+    const generatedDescriptionId = `${generatedId}-description`;
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedHeaderSlotProps = resolveSlotProps(slotProps.header, ownerState);
+    const resolvedLabelSlotProps = resolveSlotProps(slotProps.label, ownerState);
+    const resolvedDescriptionSlotProps = resolveSlotProps(slotProps.description, ownerState);
+    const resolvedContentSlotProps = resolveSlotProps(slotProps.content, ownerState);
+    const resolvedLayoutSlotProps = resolveSlotProps(slotProps.layout, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const { className: headerSlotClassName, ...headerSlotOther } = resolvedHeaderSlotProps;
+    const { className: labelSlotClassName, id: labelSlotId, ...labelSlotOther } = resolvedLabelSlotProps;
+    const { className: descriptionSlotClassName, id: descriptionSlotId, ...descriptionSlotOther } = resolvedDescriptionSlotProps;
+    const { className: contentSlotClassName, ...contentSlotOther } = resolvedContentSlotProps;
+    const { className: layoutSlotClassName, ...layoutSlotOther } = resolvedLayoutSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const headingId = labelSlotId ?? generatedHeadingId;
+    const descriptionId = descriptionSlotId ?? generatedDescriptionId;
+    const headingTag = `h${headingLevel}`;
+    return (_jsxs(VireoFormSectionRoot, { ...other, ...rootSlotOther, as: slots.root ?? "section", ref: rootRef, ownerState: ownerState, "aria-labelledby": headingId, "aria-describedby": ownerState.hasDescription ? descriptionId : undefined, "data-variant": variant, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [_jsxs(VireoFormSectionHeader, { ...headerSlotOther, as: slots.header, ownerState: ownerState, className: joinClassNames(classes.header, headerSlotClassName), children: [_jsx(VireoFormSectionLabel, { ...labelSlotOther, as: slots.label ?? headingTag, ownerState: ownerState, id: headingId, className: joinClassNames(classes.label, labelSlotClassName), children: label }), ownerState.hasDescription && (_jsx(VireoFormSectionDescription, { ...descriptionSlotOther, as: slots.description, component: "p", ownerState: ownerState, id: descriptionId, className: joinClassNames(classes.description, descriptionSlotClassName), children: description }))] }), _jsx(VireoFormSectionContent, { ...contentSlotOther, as: slots.content, ownerState: ownerState, className: joinClassNames(classes.content, contentSlotClassName), children: _jsx(VireoFormSectionLayout, { ...layoutSlotOther, as: slots.layout, ownerState: ownerState, className: joinClassNames(classes.layout, layoutSlotClassName), children: children }) })] }));
+});
+VireoFormSection.displayName = VIREO_FORM_SECTION_NAME;

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

@@ -0,0 +1,11 @@
+import type { StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type TypographyProps } from "@mui/material";
+import type { VireoFormSectionOwnerState } from "./VireoFormSection.types.js";
+type VireoFormSectionStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormSectionOwnerState>;
+export declare const VireoFormSectionRoot: VireoFormSectionStyledSlotComponent<BoxProps>;
+export declare const VireoFormSectionHeader: VireoFormSectionStyledSlotComponent<BoxProps>;
+export declare const VireoFormSectionLabel: VireoFormSectionStyledSlotComponent<TypographyProps>;
+export declare const VireoFormSectionDescription: VireoFormSectionStyledSlotComponent<TypographyProps>;
+export declare const VireoFormSectionContent: VireoFormSectionStyledSlotComponent<BoxProps>;
+export declare const VireoFormSectionLayout: VireoFormSectionStyledSlotComponent<BoxProps>;
+export {};

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

@@ -0,0 +1,82 @@
+import { Box, Typography } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FORM_SECTION_NAME } from "./VireoFormSection.identity.js";
+export const VireoFormSectionRoot = styled(Box, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Root",
+    overridesResolver: (_p, s) => s.root,
+})(({ theme, ownerState }) => ({
+    containerName: "vireo-form-section",
+    containerType: "inline-size",
+    display: "flex",
+    flexDirection: "column",
+    gap: theme.spacing(2),
+    minWidth: 0,
+    ...(ownerState.variant === "divided" && {
+        [`&[data-variant="divided"] + &[data-variant="divided"]`]: {
+            borderTop: `1px solid ${theme.palette.divider}`,
+            paddingTop: theme.spacing(3),
+        },
+    }),
+}));
+export const VireoFormSectionHeader = styled(Box, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Header",
+    overridesResolver: (_p, s) => s.header,
+})(({ theme }) => ({
+    display: "flex",
+    flexDirection: "column",
+    gap: theme.spacing(1),
+    minWidth: 0,
+}));
+export const VireoFormSectionLabel = styled(Typography, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Label",
+    overridesResolver: (_p, s) => s.label,
+})({ fontSize: "1.125rem", fontWeight: 600, lineHeight: "1.75rem" });
+export const VireoFormSectionDescription = styled(Typography, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Description",
+    overridesResolver: (_p, s) => s.description,
+})(({ theme }) => ({ color: theme.palette.text.secondary }));
+export const VireoFormSectionContent = styled(Box, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Content",
+    overridesResolver: (_p, s) => s.content,
+})(({ theme, ownerState }) => ({
+    containerName: "vireo-form-section-content",
+    containerType: "inline-size",
+    minWidth: 0,
+    ...(ownerState.variant === "outlined" && {
+        backgroundColor: `var(--mui-palette-surface-base, ${theme.palette.background.paper})`,
+        border: `1px solid ${theme.palette.divider}`,
+        borderRadius: theme.shape.borderRadius,
+        padding: theme.spacing(2),
+        "@container vireo-form-section (min-width: 30rem)": {
+            padding: theme.spacing(3),
+        },
+    }),
+}));
+export const VireoFormSectionLayout = styled(Box, {
+    name: VIREO_FORM_SECTION_NAME,
+    slot: "Layout",
+    overridesResolver: (_p, s) => s.layout,
+})(({ theme, ownerState }) => ({
+    display: ownerState.layout === "grid" ? "grid" : "flex",
+    flexDirection: ownerState.layout === "stack" ? "column" : undefined,
+    gap: theme.spacing(2),
+    gridTemplateColumns: ownerState.layout === "grid" ? "minmax(0, 1fr)" : undefined,
+    minWidth: 0,
+    ...(ownerState.layout === "grid" &&
+        ownerState.maxColumns >= 2 && {
+        "@container vireo-form-section-content (min-width: 36rem)": {
+            gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
+        },
+    }),
+    ...(ownerState.layout === "grid" &&
+        ownerState.maxColumns >= 3 && {
+        "@container vireo-form-section-content (min-width: 60rem)": {
+            gridTemplateColumns: "repeat(3, minmax(0, 1fr))",
+        },
+    }),
+}));

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

@@ -0,0 +1,76 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Box, BoxProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import type { VireoFormSectionClasses, VireoFormSectionClassKey } from "./VireoFormSection.classes.js";
+import type { VIREO_FORM_SECTION_NAME, VireoFormSectionSlotName } from "./VireoFormSection.identity.js";
+export type VireoFormSectionHeadingLevel = 2 | 3 | 4 | 5 | 6;
+export type VireoFormSectionLayout = "grid" | "stack";
+export type VireoFormSectionMaxColumns = 1 | 2 | 3;
+export type VireoFormSectionVariant = "divided" | "outlined" | "plain";
+export type VireoFormSectionOwnerState = {
+    hasDescription: boolean;
+    headingLevel: VireoFormSectionHeadingLevel;
+    layout: VireoFormSectionLayout;
+    maxColumns: VireoFormSectionMaxColumns;
+    variant: VireoFormSectionVariant;
+};
+export interface VireoFormSectionRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSectionHeaderSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSectionLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSectionDescriptionSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSectionContentSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormSectionLayoutSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export type VireoFormSectionSlots = {
+    [T in VireoFormSectionSlotName]: React.ElementType;
+};
+export type VireoFormSectionSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormSectionSlots, {
+    /** @default 'section' */
+    root: SlotProps<typeof Box, VireoFormSectionRootSlotPropsOverrides, VireoFormSectionOwnerState>;
+    /** @default Box */
+    header: SlotProps<typeof Box, VireoFormSectionHeaderSlotPropsOverrides, VireoFormSectionOwnerState>;
+    /** @default Typography */
+    label: SlotProps<typeof Typography, VireoFormSectionLabelSlotPropsOverrides, VireoFormSectionOwnerState>;
+    /** @default Typography */
+    description: SlotProps<typeof Typography, VireoFormSectionDescriptionSlotPropsOverrides, VireoFormSectionOwnerState>;
+    /** @default Box */
+    content: SlotProps<typeof Box, VireoFormSectionContentSlotPropsOverrides, VireoFormSectionOwnerState>;
+    /** @default Box */
+    layout: SlotProps<typeof Box, VireoFormSectionLayoutSlotPropsOverrides, VireoFormSectionOwnerState>;
+}>;
+export type VireoFormSectionOwnProps = VireoFormSectionSlotsAndSlotProps & {
+    children: React.ReactNode;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoFormSectionClasses>;
+    /** Supporting text associated with the named section. */
+    description?: React.ReactNode;
+    /** Semantic heading level used for the section label. @default 2 */
+    headingLevel?: VireoFormSectionHeadingLevel;
+    /** Controls whether fields use a responsive grid or an always-stacked layout. @default 'grid' */
+    layout?: VireoFormSectionLayout;
+    /** Accessible section heading. */
+    label: React.ReactNode;
+    /** Maximum number of responsive grid columns. @default 2 */
+    maxColumns?: VireoFormSectionMaxColumns;
+    /** Controls the section's visual separation from surrounding form content. @default 'divided' */
+    variant?: VireoFormSectionVariant;
+};
+export type VireoFormSectionInheritedProps = Omit<BoxProps<"section">, "children" | "component" | "ref">;
+export type VireoFormSectionProps = VireoFormSectionOwnProps & VireoFormSectionInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_SECTION_NAME]?: VireoThemeComponent<VireoFormSectionProps, VireoFormSectionClassKey, VireoFormSectionOwnerState, Theme>;
+    }
+}

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

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

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

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