@vireocodedev/ui 0.2.0 → 0.2.1

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

@@ -0,0 +1,130 @@
+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 { useVireoTanStackFormContext } from "../../../../../capabilities/forms/contexts/VireoFormHookContexts/VireoFormHookContexts.js";
+import { useOptionalVireoMultiStepContext } from "../../../../../capabilities/forms/contexts/VireoMultiStepContext/VireoMultiStepContext.js";
+import { defaultVireoFormErrorFormatter } 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 { getVireoFormErrorSummaryUtilityClass, } from "./VireoFormErrorSummary.classes.js";
+import { VIREO_FORM_ERROR_SUMMARY_NAME } from "./VireoFormErrorSummary.identity.js";
+import { VireoFormErrorSummaryContent, VireoFormErrorSummaryGroup, VireoFormErrorSummaryGroupLabel, VireoFormErrorSummaryIcon, VireoFormErrorSummaryItem, VireoFormErrorSummaryItemButton, VireoFormErrorSummaryList, VireoFormErrorSummaryRoot, VireoFormErrorSummaryTitle, } from "./VireoFormErrorSummary.styled.js";
+import { defaultVireoFormErrorSummaryLocaleText, } from "./VireoFormErrorSummary.types.js";
+function useUtilityClasses(_ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        icon: ["icon"],
+        content: ["content"],
+        title: ["title"],
+        group: ["group"],
+        groupLabel: ["groupLabel"],
+        list: ["list"],
+        item: ["item"],
+        itemButton: ["itemButton"],
+    }, getVireoFormErrorSummaryUtilityClass, classes);
+}
+function focusField(root, path) {
+    const escaped = typeof CSS !== "undefined" && CSS.escape ? CSS.escape(path) : path.replace(/["\\]/g, "\\$&");
+    const target = root
+        ?.closest("form")
+        ?.querySelector(`[name="${escaped}"], [data-vireo-field-name="${escaped}"]`);
+    target?.focus();
+    target?.scrollIntoView?.({ block: "nearest" });
+}
+/** Summarizes form and field validation errors and links mapped errors back to their controls and steps. */
+export const VireoFormErrorSummary = React.forwardRef(function VireoFormErrorSummary(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_ERROR_SUMMARY_NAME });
+    const { className, classes: classesProp, localeText, scope = "form", slotProps = {}, slots = {}, style, sx, title, ...other } = props;
+    const form = useVireoTanStackFormContext();
+    const formPolicy = useVireoFormContext();
+    const multiStep = useOptionalVireoMultiStepContext();
+    const formState = useStore(form.store, state => ({
+        errors: state.errors,
+        fieldMeta: state.fieldMeta,
+    }));
+    const multiState = React.useSyncExternalStore(multiStep?.controller.subscribe ?? (() => () => undefined), multiStep?.controller.getSnapshot ?? (() => undefined), multiStep?.controller.getSnapshot ?? (() => undefined));
+    const formatter = formPolicy.formatError ?? defaultVireoFormErrorFormatter;
+    const resolvedLocaleText = { ...defaultVireoFormErrorSummaryLocaleText, ...localeText };
+    const errors = React.useMemo(() => {
+        const result = [];
+        const seen = new Set();
+        const push = (error, path) => {
+            const message = formatter(error);
+            if (!message)
+                return;
+            const key = `${path ?? ""}\0${message}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            const step = path
+                ? multiState?.activeSteps.find(candidate => candidate.fields.some(field => path === field || path.startsWith(`${field}.`)))
+                : undefined;
+            result.push({ message, path, stepId: step?.id });
+        };
+        for (const error of formState.errors)
+            push(error);
+        if (scope === "all") {
+            for (const [path, meta] of Object.entries(formState.fieldMeta)) {
+                if (!meta || typeof meta !== "object" || !("errors" in meta) || !Array.isArray(meta.errors))
+                    continue;
+                for (const error of meta.errors)
+                    push(error, path);
+            }
+        }
+        return result;
+    }, [formState.errors, formState.fieldMeta, formatter, multiState, scope]);
+    const groups = React.useMemo(() => {
+        const result = [];
+        const rootErrors = errors.filter(error => !error.path);
+        if (rootErrors.length)
+            result.push({ id: "form", label: resolvedLocaleText.formGroupLabel, errors: rootErrors });
+        for (const step of multiState?.activeSteps ?? []) {
+            const stepErrors = errors.filter(error => error.stepId === step.id);
+            if (stepErrors.length)
+                result.push({ id: step.id, label: step.label, errors: stepErrors });
+        }
+        const other = errors.filter(error => error.path && !error.stepId);
+        if (other.length)
+            result.push({ id: "other", label: resolvedLocaleText.otherGroupLabel, errors: other });
+        return result;
+    }, [errors, multiState, resolvedLocaleText.formGroupLabel, resolvedLocaleText.otherGroupLabel]);
+    const ownerState = { errorCount: errors.length, scope };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const rootElementRef = React.useRef(null);
+    React.useEffect(() => multiStep?.controller.registerErrorSummary(rootElementRef.current), [multiStep]);
+    const resolvedRoot = resolveSlotProps(slotProps.root, ownerState);
+    const resolvedIcon = resolveSlotProps(slotProps.icon, ownerState);
+    const resolvedContent = resolveSlotProps(slotProps.content, ownerState);
+    const resolvedTitle = resolveSlotProps(slotProps.title, ownerState);
+    const resolvedGroup = resolveSlotProps(slotProps.group, ownerState);
+    const resolvedGroupLabel = resolveSlotProps(slotProps.groupLabel, ownerState);
+    const resolvedList = resolveSlotProps(slotProps.list, ownerState);
+    const resolvedItem = resolveSlotProps(slotProps.item, ownerState);
+    const resolvedItemButton = resolveSlotProps(slotProps.itemButton, ownerState);
+    const { className: rootClassName, ref: rootSlotRef, style: rootStyle, sx: rootSx, ...rootOther } = resolvedRoot;
+    const { className: iconClassName, ...iconOther } = resolvedIcon;
+    const { className: contentClassName, ...contentOther } = resolvedContent;
+    const { className: titleClassName, ...titleOther } = resolvedTitle;
+    const { className: groupClassName, ...groupOther } = resolvedGroup;
+    const { className: groupLabelClassName, ...groupLabelOther } = resolvedGroupLabel;
+    const { className: listClassName, ...listOther } = resolvedList;
+    const { className: itemClassName, ...itemOther } = resolvedItem;
+    const { className: itemButtonClassName, onClick: itemButtonOnClick, ...itemButtonOther } = resolvedItemButton;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef, rootElementRef);
+    if (errors.length === 0)
+        return null;
+    return (_jsx(VireoFormErrorSummaryRoot, { ...other, ...rootOther, as: slots.root, ref: rootRef, ownerState: ownerState, role: "alert", severity: "error", tabIndex: -1, "data-vireo-error-summary": "true", icon: _jsx(VireoFormErrorSummaryIcon, { ...iconOther, as: slots.icon ?? "span", ownerState: ownerState, "aria-hidden": "true", className: joinClassNames(classes.icon, iconClassName), children: "!" }), className: joinClassNames(classes.root, className, rootClassName), style: { ...style, ...rootStyle }, sx: mergeSx(sx, rootSx), children: _jsxs(VireoFormErrorSummaryContent, { ...contentOther, as: slots.content, ownerState: ownerState, className: joinClassNames(classes.content, contentClassName), children: [_jsx(VireoFormErrorSummaryTitle, { ...titleOther, as: slots.title, component: "h2", ownerState: ownerState, className: joinClassNames(classes.title, titleClassName), children: title ?? resolvedLocaleText.title({ count: errors.length }) }), groups.map(group => (_createElement(VireoFormErrorSummaryGroup, { ...groupOther, as: slots.group, key: group.id, ownerState: ownerState, className: joinClassNames(classes.group, groupClassName) },
+                    _jsx(VireoFormErrorSummaryGroupLabel, { ...groupLabelOther, as: slots.groupLabel, component: "h3", ownerState: ownerState, className: joinClassNames(classes.groupLabel, groupLabelClassName), children: group.label }),
+                    _jsx(VireoFormErrorSummaryList, { ...listOther, as: slots.list ?? "ul", ownerState: ownerState, className: joinClassNames(classes.list, listClassName), children: group.errors.map((error, index) => (_createElement(VireoFormErrorSummaryItem, { ...itemOther, as: slots.item ?? "li", key: `${error.path ?? "form"}-${index}`, ownerState: ownerState, className: joinClassNames(classes.item, itemClassName) }, error.path ? (_jsx(VireoFormErrorSummaryItemButton, { ...itemButtonOther, as: slots.itemButton, ownerState: ownerState, "aria-label": resolvedLocaleText.navigateToError({ message: error.message }), onClick: event => {
+                                itemButtonOnClick?.(event);
+                                if (event.defaultPrevented)
+                                    return;
+                                const navigate = error.stepId && multiStep ? multiStep.controller.goToStep(error.stepId) : Promise.resolve();
+                                void navigate.finally(() => window.requestAnimationFrame(() => focusField(rootElementRef.current, error.path)));
+                            }, className: joinClassNames(classes.itemButton, itemButtonClassName), children: error.message })) : (error.message)))) }))))] }) }));
+});
+VireoFormErrorSummary.displayName = VIREO_FORM_ERROR_SUMMARY_NAME;

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

@@ -0,0 +1,14 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type AlertProps, type BoxProps, type ButtonBaseProps, type TypographyProps } from "@mui/material";
+import { type VireoFormErrorSummaryOwnerState } from "./VireoFormErrorSummary.types.js";
+type VireoFormErrorSummaryStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormErrorSummaryOwnerState>;
+export declare const VireoFormErrorSummaryRoot: VireoFormErrorSummaryStyledSlotComponent<AlertProps>;
+export declare const VireoFormErrorSummaryIcon: VireoFormErrorSummaryStyledSlotComponent<BoxProps>;
+export declare const VireoFormErrorSummaryContent: VireoFormErrorSummaryStyledSlotComponent<BoxProps>;
+export declare const VireoFormErrorSummaryTitle: VireoFormErrorSummaryStyledSlotComponent<TypographyProps>;
+export declare const VireoFormErrorSummaryGroup: VireoFormErrorSummaryStyledSlotComponent<BoxProps>;
+export declare const VireoFormErrorSummaryGroupLabel: VireoFormErrorSummaryStyledSlotComponent<TypographyProps>;
+export declare const VireoFormErrorSummaryList: VireoFormErrorSummaryStyledSlotComponent<BoxProps>;
+export declare const VireoFormErrorSummaryItem: VireoFormErrorSummaryStyledSlotComponent<BoxProps>;
+export declare const VireoFormErrorSummaryItemButton: VireoFormErrorSummaryStyledSlotComponent<ButtonBaseProps>;
+export {};

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

@@ -0,0 +1,51 @@
+import { VIREO_MOTION_TOKENS } from "../../../../../core/public.js";
+import { Alert, Box, ButtonBase, Typography, } from "@mui/material";
+import { keyframes, styled } from "@mui/material/styles";
+import { VIREO_FORM_ERROR_SUMMARY_NAME } from "./VireoFormErrorSummary.identity.js";
+const enterErrorSummary = keyframes({
+    from: { opacity: 0, transform: `translateY(-${VIREO_MOTION_TOKENS.distance.micro}px)` },
+    to: { opacity: 1, transform: "translateY(0)" },
+});
+export const VireoFormErrorSummaryRoot = styled(Alert, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})({
+    animation: `${enterErrorSummary} ${VIREO_MOTION_TOKENS.duration.enter}ms ${VIREO_MOTION_TOKENS.easing.enter}`,
+    "@media (prefers-reduced-motion: reduce)": {
+        animation: "none",
+    },
+});
+export const VireoFormErrorSummaryIcon = styled(Box, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "Icon",
+    overridesResolver: (_props, styles) => styles.icon,
+})(({ theme }) => ({ fontWeight: theme.typography.fontWeightBold }));
+export const VireoFormErrorSummaryContent = styled(Box, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "Content",
+    overridesResolver: (_props, styles) => styles.content,
+})({ width: "100%" });
+export const VireoFormErrorSummaryTitle = styled(Typography, { name: VIREO_FORM_ERROR_SUMMARY_NAME, slot: "Title", overridesResolver: (_props, styles) => styles.title })(({ theme }) => ({ fontWeight: theme.typography.fontWeightBold }));
+export const VireoFormErrorSummaryGroup = styled(Box, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "Group",
+    overridesResolver: (_props, styles) => styles.group,
+})(({ theme }) => ({ marginTop: theme.spacing(1) }));
+export const VireoFormErrorSummaryGroupLabel = styled(Typography, { name: VIREO_FORM_ERROR_SUMMARY_NAME, slot: "GroupLabel", overridesResolver: (_props, styles) => styles.groupLabel })(({ theme }) => ({ fontWeight: theme.typography.fontWeightMedium }));
+export const VireoFormErrorSummaryList = styled(Box, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "List",
+    overridesResolver: (_props, styles) => styles.list,
+})(({ theme }) => ({ margin: 0, paddingInlineStart: theme.spacing(2.5) }));
+export const VireoFormErrorSummaryItem = styled(Box, {
+    name: VIREO_FORM_ERROR_SUMMARY_NAME,
+    slot: "Item",
+    overridesResolver: (_props, styles) => styles.item,
+})({});
+export const VireoFormErrorSummaryItemButton = styled(ButtonBase, { name: VIREO_FORM_ERROR_SUMMARY_NAME, slot: "ItemButton", overridesResolver: (_props, styles) => styles.itemButton })(({ theme }) => ({
+    borderRadius: theme.shape.borderRadius,
+    color: "inherit",
+    textAlign: "start",
+    textDecoration: "underline",
+}));

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

@@ -0,0 +1,87 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { Alert, AlertProps, Box, ButtonBase, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import type { VireoFormErrorSummaryClasses, VireoFormErrorSummaryClassKey } from "./VireoFormErrorSummary.classes.js";
+import type { VIREO_FORM_ERROR_SUMMARY_NAME, VireoFormErrorSummarySlotName } from "./VireoFormErrorSummary.identity.js";
+export type VireoFormErrorSummaryScope = "form" | "all";
+export type VireoFormErrorSummaryLocaleText = {
+    title: (context: {
+        count: number;
+    }) => string;
+    formGroupLabel: string;
+    otherGroupLabel: string;
+    navigateToError: (context: {
+        message: string;
+    }) => string;
+};
+export declare const defaultVireoFormErrorSummaryLocaleText: VireoFormErrorSummaryLocaleText;
+export type VireoFormErrorSummaryOwnerState = {
+    errorCount: number;
+    scope: VireoFormErrorSummaryScope;
+};
+export interface VireoFormErrorSummaryRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryIconSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryContentSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryTitleSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryGroupSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryGroupLabelSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryListSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryItemSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFormErrorSummaryItemButtonSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export type VireoFormErrorSummarySlots = {
+    [T in VireoFormErrorSummarySlotName]: React.ElementType;
+};
+export type VireoFormErrorSummarySlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormErrorSummarySlots, {
+    /** @default Alert */
+    root: SlotProps<typeof Alert, VireoFormErrorSummaryRootSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default 'span' */
+    icon: SlotProps<typeof Box, VireoFormErrorSummaryIconSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default Box */
+    content: SlotProps<typeof Box, VireoFormErrorSummaryContentSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default Typography */
+    title: SlotProps<typeof Typography, VireoFormErrorSummaryTitleSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default Box */
+    group: SlotProps<typeof Box, VireoFormErrorSummaryGroupSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default Typography */
+    groupLabel: SlotProps<typeof Typography, VireoFormErrorSummaryGroupLabelSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default 'ul' */
+    list: SlotProps<typeof Box, VireoFormErrorSummaryListSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default 'li' */
+    item: SlotProps<typeof Box, VireoFormErrorSummaryItemSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+    /** @default ButtonBase */
+    itemButton: SlotProps<typeof ButtonBase, VireoFormErrorSummaryItemButtonSlotPropsOverrides, VireoFormErrorSummaryOwnerState>;
+}>;
+export type VireoFormErrorSummaryOwnProps = VireoFormErrorSummarySlotsAndSlotProps & {
+    classes?: Partial<VireoFormErrorSummaryClasses>;
+    localeText?: Partial<VireoFormErrorSummaryLocaleText>;
+    /** Includes only form-level errors or every field error grouped by step. @default 'form' */
+    scope?: VireoFormErrorSummaryScope;
+    /** Replaces the generated error-count heading. */
+    title?: React.ReactNode;
+};
+export type VireoFormErrorSummaryInheritedProps = Omit<AlertProps, "children" | "icon" | "ref" | "severity" | "slotProps" | "slots" | "title">;
+export type VireoFormErrorSummaryProps = VireoFormErrorSummaryOwnProps & VireoFormErrorSummaryInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_ERROR_SUMMARY_NAME]?: VireoThemeComponent<VireoFormErrorSummaryProps, VireoFormErrorSummaryClassKey, VireoFormErrorSummaryOwnerState, Theme>;
+    }
+}

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

@@ -0,0 +1,6 @@
+export const defaultVireoFormErrorSummaryLocaleText = {
+    title: ({ count }) => (count === 1 ? "1 error needs attention" : `${count} errors need attention`),
+    formGroupLabel: "Form",
+    otherGroupLabel: "Other",
+    navigateToError: ({ message }) => `Go to error: ${message}`,
+};

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

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

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

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

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

@@ -0,0 +1,9 @@
+import { type VireoFormFileFieldSlotName } from "./VireoFormFileField.identity.js";
+/** Utility classes available to VireoFormFileField. */
+export type VireoFormFileFieldClasses = Record<VireoFormFileFieldSlotName | "empty" | "populated" | "dragActive" | "dragReject" | "rejected" | "invalid" | "disabled" | "readOnly", string>;
+/** Valid keys for VireoFormFileField utility classes and theme style overrides. */
+export type VireoFormFileFieldClassKey = keyof VireoFormFileFieldClasses;
+/** Returns the generated utility class name for a VireoFormFileField slot or state. */
+export declare function getVireoFormFileFieldUtilityClass(slot: string): string;
+/** Generated utility class names keyed by each public VireoFormFileField class key. */
+export declare const vireoFormFileFieldClasses: VireoFormFileFieldClasses;

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

@@ -0,0 +1,18 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_FORM_FILE_FIELD_NAME, VIREO_FORM_FILE_FIELD_SLOTS, } from "./VireoFormFileField.identity.js";
+/** Returns the generated utility class name for a VireoFormFileField slot or state. */
+export function getVireoFormFileFieldUtilityClass(slot) {
+    return generateUtilityClass(VIREO_FORM_FILE_FIELD_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoFormFileField class key. */
+export const vireoFormFileFieldClasses = generateUtilityClasses(VIREO_FORM_FILE_FIELD_NAME, [
+    ...VIREO_FORM_FILE_FIELD_SLOTS,
+    "empty",
+    "populated",
+    "dragActive",
+    "dragReject",
+    "rejected",
+    "invalid",
+    "disabled",
+    "readOnly",
+]);

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

@@ -0,0 +1,4 @@
+import React from "react";
+import type { VireoFormFileFieldProps } from "./VireoFormFileField.types.js";
+/** Binds single-file picker, drop, rejection, metadata, and optional preview behavior to `form.Field`. */
+export declare const VireoFormFileField: React.ForwardRefExoticComponent<Omit<VireoFormFileFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoFormFileField integration point. */
+export declare const VIREO_FORM_FILE_FIELD_NAME = "VireoFormFileField";
+/** Canonical public slots exposed by VireoFormFileField, in rendered DOM order. */
+export declare const VIREO_FORM_FILE_FIELD_SLOTS: readonly ["root", "selection", "input", "selectButton", "metadata", "fileName", "fileSize", "clearButton", "dropOverlay", "previewContainer", "helperText"];
+/** Public slot names exposed by VireoFormFileField. */
+export type VireoFormFileFieldSlotName = (typeof VIREO_FORM_FILE_FIELD_SLOTS)[number];

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

@@ -0,0 +1,16 @@
+/** Stable component name shared by every VireoFormFileField integration point. */
+export const VIREO_FORM_FILE_FIELD_NAME = "VireoFormFileField";
+/** Canonical public slots exposed by VireoFormFileField, in rendered DOM order. */
+export const VIREO_FORM_FILE_FIELD_SLOTS = [
+    "root",
+    "selection",
+    "input",
+    "selectButton",
+    "metadata",
+    "fileName",
+    "fileSize",
+    "clearButton",
+    "dropOverlay",
+    "previewContainer",
+    "helperText",
+];

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

@@ -0,0 +1,256 @@
+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 { acceptsVireoDragType, acceptsVireoFile, formatVireoFileSize, truncateVireoFileName, } from "../../../../../capabilities/forms/utils/vireoFile.js";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import CloseIcon from "@mui/icons-material/Close";
+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 { getVireoFormFileFieldUtilityClass } from "./VireoFormFileField.classes.js";
+import { VIREO_FORM_FILE_FIELD_NAME } from "./VireoFormFileField.identity.js";
+import { VireoFormFileFieldClearButton, VireoFormFileFieldDropOverlay, VireoFormFileFieldFileName, VireoFormFileFieldFileSize, VireoFormFileFieldHelperText, VireoFormFileFieldInput, VireoFormFileFieldMetadata, VireoFormFileFieldPreviewContainer, VireoFormFileFieldRoot, VireoFormFileFieldSelectButton, VireoFormFileFieldSelection, } from "./VireoFormFileField.styled.js";
+function useUtilityClasses(ownerState, classes) {
+    return composeClasses({
+        root: [
+            "root",
+            ownerState.empty && "empty",
+            ownerState.populated && "populated",
+            ownerState.dragActive && "dragActive",
+            ownerState.dragReject && "dragReject",
+            ownerState.rejected && "rejected",
+            ownerState.invalid && "invalid",
+            ownerState.disabled && "disabled",
+            ownerState.readOnly && "readOnly",
+        ],
+        selection: ["selection"],
+        input: ["input"],
+        selectButton: ["selectButton"],
+        metadata: ["metadata"],
+        fileName: ["fileName"],
+        fileSize: ["fileSize"],
+        clearButton: ["clearButton"],
+        dropOverlay: ["dropOverlay"],
+        previewContainer: ["previewContainer"],
+        helperText: ["helperText"],
+    }, getVireoFormFileFieldUtilityClass, classes);
+}
+function resolveMessage(value, ...args) {
+    return typeof value === "function" ? value(...args) : value;
+}
+function useDisplayedFileName(fileName, mode, hasTrailingMetadata) {
+    const elementRef = React.useRef(null);
+    const containerRef = React.useRef(null);
+    const trailingMetadataRef = React.useRef(null);
+    const [displayed, setDisplayed] = React.useState(fileName ?? "");
+    React.useLayoutEffect(() => {
+        const element = elementRef.current;
+        const container = containerRef.current;
+        if (!element || !container || !fileName) {
+            setDisplayed(fileName ?? "");
+            return;
+        }
+        const update = () => {
+            const trailingMetadata = trailingMetadataRef.current;
+            const containerStyle = window.getComputedStyle(container);
+            const gap = trailingMetadata ? Number.parseFloat(containerStyle.columnGap || containerStyle.gap) || 0 : 0;
+            const width = Math.max(0, container.clientWidth - (trailingMetadata?.clientWidth ?? 0) - gap);
+            if (width <= 0) {
+                setDisplayed(fileName);
+                return;
+            }
+            const style = window.getComputedStyle(element);
+            const canvas = document.createElement("canvas");
+            const context = canvas.getContext("2d");
+            if (!context) {
+                setDisplayed(fileName);
+                return;
+            }
+            context.font = style.font || `${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+            setDisplayed(truncateVireoFileName(fileName, mode, width, candidate => context.measureText(candidate).width));
+        };
+        update();
+        if (typeof ResizeObserver !== "function")
+            return;
+        const observer = new ResizeObserver(update);
+        observer.observe(container);
+        observer.observe(element);
+        if (trailingMetadataRef.current)
+            observer.observe(trailingMetadataRef.current);
+        return () => observer.disconnect();
+    }, [fileName, hasTrailingMetadata, mode]);
+    return { containerRef, displayed, elementRef, trailingMetadataRef };
+}
+/** Binds single-file picker, drop, rejection, metadata, and optional preview behavior to `form.Field`. */
+export const VireoFormFileField = React.forwardRef(function VireoFormFileField(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_FILE_FIELD_NAME });
+    const { accept, capture, chooseFileLabel = "Choose file", className, classes: classesProp, clearable = true, clearFileLabel = "Clear selected file", disabled = false, disableDrop = false, dropActiveText = "Drop file here", emptyText = "No file selected", error = false, errorDisplay: errorDisplayProp, fileNameTruncation = "middle", fileTooLargeText = (_file, maximum) => `File must be ${formatVireoFileSize(maximum)} or smaller.`, formatError: formatErrorProp, formatFileSize = formatVireoFileSize, helperText = " ", hideFileSize = false, inputRef, maxSize, onFileRejected, previewRenderer: PreviewRenderer, readOnly = false, replaceFileLabel = "Replace file", required = false, slotProps = {}, slots = {}, style, sx, unsupportedTypeText = "This file type is not accepted.", ...other } = props;
+    const field = useVireoFieldContext();
+    const formContext = useVireoFormContext();
+    const fieldState = useStore(field.store, current => ({
+        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 [rejection, setRejection] = React.useState();
+    const [dragActive, setDragActive] = React.useState(false);
+    const [dragReject, setDragReject] = React.useState(false);
+    const dragDepth = React.useRef(0);
+    const nativeInput = React.useRef(null);
+    const generatedInputId = React.useId();
+    const generatedHelperId = React.useId();
+    const value = typeof File !== "undefined" && fieldState.value instanceof File ? fieldState.value : null;
+    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 rejectionMessage = rejection
+        ? rejection.reason === "type"
+            ? resolveMessage(unsupportedTypeText, rejection.file)
+            : resolveMessage(fileTooLargeText, rejection.file, maxSize ?? 0)
+        : undefined;
+    const effectiveHelperText = rejectionMessage ?? formattedError ?? helperText;
+    const ownerState = {
+        disabled,
+        dragActive,
+        dragReject,
+        empty: value === null,
+        errorVisible,
+        invalid: error || fieldState.invalid,
+        populated: value !== null,
+        readOnly,
+        rejected: rejection !== undefined,
+        submitting,
+        touched: fieldState.touched,
+        validating: fieldState.validating,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const { containerRef: metadataRef, displayed: displayedFileName, elementRef: fileNameRef, trailingMetadataRef: fileSizeRef, } = useDisplayedFileName(value?.name, fileNameTruncation, value !== null && !hideFileSize);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const resolvedSelectionSlotProps = resolveSlotProps(slotProps.selection, ownerState);
+    const { className: selectionSlotClassName, ...selectionSlotOther } = resolvedSelectionSlotProps;
+    const resolvedInputSlotProps = resolveSlotProps(slotProps.input, ownerState);
+    const { className: inputSlotClassName, id: inputSlotId, onChange: inputSlotOnChange, ref: inputSlotRef, ...inputSlotOther } = resolvedInputSlotProps;
+    const resolvedSelectButtonSlotProps = resolveSlotProps(slotProps.selectButton, ownerState);
+    const { className: selectButtonSlotClassName, onBlur: selectButtonSlotOnBlur, onClick: selectButtonSlotOnClick, ...selectButtonSlotOther } = resolvedSelectButtonSlotProps;
+    const resolvedMetadataSlotProps = resolveSlotProps(slotProps.metadata, ownerState);
+    const { className: metadataSlotClassName, ref: metadataSlotRef, ...metadataSlotOther } = resolvedMetadataSlotProps;
+    const resolvedFileNameSlotProps = resolveSlotProps(slotProps.fileName, ownerState);
+    const { className: fileNameSlotClassName, ref: fileNameSlotRef, ...fileNameSlotOther } = resolvedFileNameSlotProps;
+    const resolvedFileSizeSlotProps = resolveSlotProps(slotProps.fileSize, ownerState);
+    const { className: fileSizeSlotClassName, ref: fileSizeSlotRef, ...fileSizeSlotOther } = resolvedFileSizeSlotProps;
+    const resolvedClearButtonSlotProps = resolveSlotProps(slotProps.clearButton, ownerState);
+    const { className: clearButtonSlotClassName, onClick: clearButtonSlotOnClick, ...clearButtonSlotOther } = resolvedClearButtonSlotProps;
+    const resolvedDropOverlaySlotProps = resolveSlotProps(slotProps.dropOverlay, ownerState);
+    const { className: dropOverlaySlotClassName, ...dropOverlaySlotOther } = resolvedDropOverlaySlotProps;
+    const resolvedPreviewContainerSlotProps = resolveSlotProps(slotProps.previewContainer, ownerState);
+    const { className: previewContainerSlotClassName, ...previewContainerSlotOther } = resolvedPreviewContainerSlotProps;
+    const resolvedHelperTextSlotProps = resolveSlotProps(slotProps.helperText, ownerState);
+    const { className: helperTextSlotClassName, id: helperTextSlotId, ...helperTextSlotOther } = resolvedHelperTextSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const mergedInputRef = useForkRef(nativeInput, inputRef, inputSlotRef);
+    const mergedMetadataRef = useForkRef(metadataRef, metadataSlotRef);
+    const mergedFileNameRef = useForkRef(fileNameRef, fileNameSlotRef);
+    const mergedFileSizeRef = useForkRef(fileSizeRef, fileSizeSlotRef);
+    const inputId = inputSlotId ?? generatedInputId;
+    const helperId = helperTextSlotId ?? generatedHelperId;
+    const interactive = !disabled && !readOnly;
+    React.useEffect(() => {
+        if (nativeInput.current)
+            nativeInput.current.value = "";
+    }, [value]);
+    const reject = React.useCallback((file, reason) => {
+        const next = { file, reason };
+        setRejection(next);
+        onFileRejected?.(next);
+    }, [onFileRejected]);
+    const selectFile = React.useCallback((file) => {
+        if (!acceptsVireoFile(file, accept))
+            return reject(file, "type");
+        if (maxSize !== undefined && file.size > maxSize)
+            return reject(file, "size");
+        setRejection(undefined);
+        field.handleChange(file);
+    }, [accept, field, maxSize, reject]);
+    const handleInputChange = event => {
+        inputSlotOnChange?.(event);
+        if (!event.defaultPrevented && interactive) {
+            const file = event.currentTarget.files?.[0];
+            if (file)
+                selectFile(file);
+        }
+        event.currentTarget.value = "";
+    };
+    const handleSelectClick = event => {
+        selectButtonSlotOnClick?.(event);
+        if (!event.defaultPrevented && interactive)
+            nativeInput.current?.click();
+    };
+    const handleClearClick = event => {
+        clearButtonSlotOnClick?.(event);
+        if (event.defaultPrevented || !interactive)
+            return;
+        setRejection(undefined);
+        field.handleChange(null);
+        if (nativeInput.current)
+            nativeInput.current.value = "";
+    };
+    const handleDragEnter = event => {
+        if (!interactive || disableDrop || !event.dataTransfer.types.includes("Files"))
+            return;
+        event.preventDefault();
+        dragDepth.current += 1;
+        const type = event.dataTransfer.items[0]?.type ?? "";
+        setDragReject(!acceptsVireoDragType(type, accept));
+        setDragActive(true);
+    };
+    const handleDragOver = event => {
+        if (!interactive || disableDrop || !event.dataTransfer.types.includes("Files"))
+            return;
+        event.preventDefault();
+        event.dataTransfer.dropEffect = "copy";
+    };
+    const handleDragLeave = event => {
+        if (!dragActive)
+            return;
+        event.preventDefault();
+        dragDepth.current = Math.max(0, dragDepth.current - 1);
+        if (dragDepth.current === 0) {
+            setDragActive(false);
+            setDragReject(false);
+        }
+    };
+    const handleDrop = event => {
+        if (!interactive || disableDrop)
+            return;
+        event.preventDefault();
+        dragDepth.current = 0;
+        setDragActive(false);
+        setDragReject(false);
+        const file = event.dataTransfer.files[0];
+        if (file)
+            selectFile(file);
+    };
+    return (_jsxs(VireoFormFileFieldRoot, { ...other, ...rootSlotOther, as: slots.root ?? "div", ref: rootRef, ownerState: ownerState, "aria-disabled": disabled || undefined, "aria-readonly": readOnly || undefined, className: joinClassNames(classes.root, className, rootSlotClassName), onDragEnter: handleDragEnter, onDragLeave: handleDragLeave, onDragOver: handleDragOver, onDrop: handleDrop, style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: [_jsxs(VireoFormFileFieldSelection, { ...selectionSlotOther, as: slots.selection, ownerState: ownerState, className: joinClassNames(classes.selection, selectionSlotClassName), children: [_jsx(VireoFormFileFieldInput, { ...inputSlotOther, as: slots.input ?? "input", ref: mergedInputRef, ownerState: ownerState, accept: accept, "aria-describedby": effectiveHelperText ? helperId : undefined, "aria-invalid": ownerState.rejected || ownerState.invalid || undefined, capture: capture, className: joinClassNames(classes.input, inputSlotClassName), disabled: disabled, id: inputId, multiple: false, name: field.name, onChange: handleInputChange, required: required, tabIndex: -1, type: "file" }), _jsx(VireoFormFileFieldSelectButton, { ...selectButtonSlotOther, as: slots.selectButton, ownerState: ownerState, "aria-controls": inputId, className: joinClassNames(classes.selectButton, selectButtonSlotClassName), disabled: !interactive, onBlur: event => {
+                            selectButtonSlotOnBlur?.(event);
+                            if (!event.defaultPrevented)
+                                field.handleBlur();
+                        }, onClick: handleSelectClick, variant: "outlined", children: value ? replaceFileLabel : chooseFileLabel }), _jsxs(VireoFormFileFieldMetadata, { ...metadataSlotOther, as: slots.metadata, ref: mergedMetadataRef, ownerState: ownerState, className: joinClassNames(classes.metadata, metadataSlotClassName), children: [_jsx(VireoFormFileFieldFileName, { ...fileNameSlotOther, as: slots.fileName, ref: mergedFileNameRef, ownerState: ownerState, "aria-label": value?.name, className: joinClassNames(classes.fileName, fileNameSlotClassName), title: value?.name, variant: "body2", children: value ? displayedFileName : emptyText }), value && !hideFileSize && (_jsx(VireoFormFileFieldFileSize, { ...fileSizeSlotOther, as: slots.fileSize, ref: mergedFileSizeRef, ownerState: ownerState, className: joinClassNames(classes.fileSize, fileSizeSlotClassName), variant: "caption", children: formatFileSize(value.size) }))] }), value && clearable && (_jsx(VireoFormFileFieldClearButton, { ...clearButtonSlotOther, as: slots.clearButton, ownerState: ownerState, "aria-label": clearFileLabel, className: joinClassNames(classes.clearButton, clearButtonSlotClassName), disabled: !interactive, onClick: handleClearClick, size: "small", children: _jsx(CloseIcon, { fontSize: "small" }) }))] }), dragActive && (_jsx(VireoFormFileFieldDropOverlay, { ...dropOverlaySlotOther, as: slots.dropOverlay, ownerState: ownerState, "aria-hidden": "true", className: joinClassNames(classes.dropOverlay, dropOverlaySlotClassName), children: dragReject
+                    ? typeof unsupportedTypeText === "function"
+                        ? "This file type is not accepted."
+                        : unsupportedTypeText
+                    : dropActiveText })), value && PreviewRenderer && (_jsx(VireoFormFileFieldPreviewContainer, { ...previewContainerSlotOther, as: slots.previewContainer, ownerState: ownerState, className: joinClassNames(classes.previewContainer, previewContainerSlotClassName), children: _jsx(PreviewRenderer, { file: value }) })), effectiveHelperText !== undefined && effectiveHelperText !== null && (_jsx(VireoFormFileFieldHelperText, { ...helperTextSlotOther, as: slots.helperText, ownerState: ownerState, className: joinClassNames(classes.helperText, helperTextSlotClassName), error: ownerState.rejected || ownerState.invalid, id: helperId, role: ownerState.rejected ? "alert" : undefined, children: effectiveHelperText }))] }));
+});
+VireoFormFileField.displayName = VIREO_FORM_FILE_FIELD_NAME;