@vireocodedev/ui 0.2.0 → 0.2.1

package/dist/capabilities/country/public.d.ts

@@ -0,0 +1,5 @@
+export { COUNTRY_CODES } from "./constants/countryCodes.constants.js";
+export * from "./components/data-display/VireoCountryFlag/index.js";
+export { CountryCodeSchema, isCountryCode, type CountryCode } from "./models/countryCode.models.js";
+export type { CountryNameOptions } from "./types/country.types.js";
+export { getCountryName } from "./utils/countryNames.utils.js";

package/dist/capabilities/country/public.js

@@ -0,0 +1,4 @@
+export { COUNTRY_CODES } from "./constants/countryCodes.constants.js";
+export * from "./components/data-display/VireoCountryFlag/index.js";
+export { CountryCodeSchema, isCountryCode } from "./models/countryCode.models.js";
+export { getCountryName } from "./utils/countryNames.utils.js";

package/dist/capabilities/country/types/country.types.d.ts

@@ -0,0 +1,6 @@
+import type { CountryCode } from "../../../capabilities/country/models/countryCode.models.js";
+/** Options for resolving a localized country or territory display name. */
+export type CountryNameOptions = {
+    /** Already-localized names that take precedence over Vireo and platform data. */
+    overrides?: Partial<Record<CountryCode, string>>;
+};

package/dist/capabilities/country/types/country.types.js

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

package/dist/capabilities/country/utils/countryNames.utils.d.ts

@@ -0,0 +1,4 @@
+import type { CountryCode } from "../../../capabilities/country/models/countryCode.models.js";
+import type { CountryNameOptions } from "../../../capabilities/country/types/country.types.js";
+/** Resolves a localized display name for a supported country-flag-icons identifier. */
+export declare function getCountryName(countryCode: CountryCode, locale: string, options?: CountryNameOptions): string;

package/dist/capabilities/country/utils/countryNames.utils.js

@@ -0,0 +1,56 @@
+import { COUNTRY_ENGLISH_NAMES, COUNTRY_EXCEPTIONAL_NAMES, COUNTRY_NAME_CATALOG_LOCALES, } from "../../../capabilities/country/constants/countryNames.constants.js";
+const DISPLAY_NAMES_CACHE = new Map();
+const COUNTRY_NAME_CATALOG_LOCALE_SET = new Set(COUNTRY_NAME_CATALOG_LOCALES);
+function resolveLocale(locale) {
+    if (locale.toLowerCase() === "cnr") {
+        return { canonicalLocale: "sr-ME", catalogLocale: "cnr" };
+    }
+    try {
+        const [canonicalLocale] = Intl.getCanonicalLocales(locale);
+        if (!canonicalLocale) {
+            return { canonicalLocale: "en", catalogLocale: "en" };
+        }
+        const baseLocale = canonicalLocale.split("-")[0]?.toLowerCase();
+        const catalogLocale = baseLocale && COUNTRY_NAME_CATALOG_LOCALE_SET.has(baseLocale)
+            ? baseLocale
+            : undefined;
+        if (typeof Intl.DisplayNames !== "function")
+            return { canonicalLocale, catalogLocale };
+        if (Intl.DisplayNames.supportedLocalesOf([canonicalLocale]).length === 0) {
+            return { canonicalLocale: "en", catalogLocale: "en" };
+        }
+        return {
+            canonicalLocale,
+            catalogLocale,
+        };
+    }
+    catch {
+        return { canonicalLocale: "en", catalogLocale: "en" };
+    }
+}
+function getDisplayNames(locale) {
+    if (typeof Intl.DisplayNames !== "function")
+        return undefined;
+    const cached = DISPLAY_NAMES_CACHE.get(locale);
+    if (cached)
+        return cached;
+    try {
+        const displayNames = new Intl.DisplayNames([locale], { fallback: "none", type: "region" });
+        DISPLAY_NAMES_CACHE.set(locale, displayNames);
+        return displayNames;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolves a localized display name for a supported country-flag-icons identifier. */
+export function getCountryName(countryCode, locale, options = {}) {
+    const override = options.overrides?.[countryCode];
+    if (override !== undefined)
+        return override;
+    const { canonicalLocale, catalogLocale } = resolveLocale(locale);
+    if (catalogLocale && countryCode in COUNTRY_EXCEPTIONAL_NAMES[catalogLocale]) {
+        return COUNTRY_EXCEPTIONAL_NAMES[catalogLocale][countryCode];
+    }
+    return getDisplayNames(canonicalLocale)?.of(countryCode) ?? COUNTRY_ENGLISH_NAMES[countryCode] ?? countryCode;
+}

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.classes.d.ts

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

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.classes.js

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

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { type VireoFileImagePreviewProps } from "./VireoFileImagePreview.types.js";
+/**
+ * Renders an opt-in, object-URL-backed preview for a browser image File.
+ */
+export declare const VireoFileImagePreview: React.ForwardRefExoticComponent<Omit<VireoFileImagePreviewProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.identity.d.ts

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

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.identity.js

@@ -0,0 +1,4 @@
+/** Stable component name shared by every VireoFileImagePreview integration point. */
+export const VIREO_FILE_IMAGE_PREVIEW_NAME = "VireoFileImagePreview";
+/** Canonical public slots exposed by VireoFileImagePreview, in rendered DOM order. */
+export const VIREO_FILE_IMAGE_PREVIEW_SLOTS = ["root", "image", "fallback"];

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } 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 { getVireoFileImagePreviewUtilityClass, } from "./VireoFileImagePreview.classes.js";
+import { VIREO_FILE_IMAGE_PREVIEW_NAME } from "./VireoFileImagePreview.identity.js";
+import { VireoFileImagePreviewFallback, VireoFileImagePreviewImage, VireoFileImagePreviewRoot, } from "./VireoFileImagePreview.styled.js";
+function useUtilityClasses(ownerState, classes) {
+    return composeClasses({
+        root: ["root"],
+        image: ["image"],
+        fallback: ["fallback", !ownerState.available && "unavailable"],
+    }, getVireoFileImagePreviewUtilityClass, classes);
+}
+/**
+ * Renders an opt-in, object-URL-backed preview for a browser image File.
+ */
+export const VireoFileImagePreview = React.forwardRef(function VireoFileImagePreview(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FILE_IMAGE_PREVIEW_NAME });
+    const { alt = "", className, classes: classesProp, file, objectFit = "contain", previewUnavailableText = "Preview unavailable", slotProps = {}, slots = {}, style, sx, ...other } = props;
+    const [decodeFailed, setDecodeFailed] = React.useState(false);
+    const previewable = file.type.toLowerCase().startsWith("image/");
+    const [preview, setPreview] = React.useState();
+    const objectUrl = preview?.file === file ? preview.url : undefined;
+    React.useEffect(() => {
+        setDecodeFailed(false);
+        setPreview(undefined);
+        if (!previewable)
+            return;
+        const url = URL.createObjectURL(file);
+        setPreview({ file, url });
+        return () => URL.revokeObjectURL(url);
+    }, [file, previewable]);
+    const ownerState = {
+        available: previewable && objectUrl !== undefined && !decodeFailed,
+        objectFit,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { className: rootSlotClassName, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef);
+    const resolvedImageSlotProps = resolveSlotProps(slotProps.image, ownerState);
+    const { className: imageSlotClassName, onError: imageSlotOnError, ...imageSlotOther } = resolvedImageSlotProps;
+    const resolvedFallbackSlotProps = resolveSlotProps(slotProps.fallback, ownerState);
+    const { className: fallbackSlotClassName, ...fallbackSlotOther } = resolvedFallbackSlotProps;
+    return (_jsx(VireoFileImagePreviewRoot, { ...other, ...rootSlotOther, as: slots.root ?? "div", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: ownerState.available && objectUrl ? (_jsx(VireoFileImagePreviewImage, { ...imageSlotOther, as: slots.image ?? "img", alt: alt, src: objectUrl, ownerState: ownerState, className: joinClassNames(classes.image, imageSlotClassName), onError: event => {
+                imageSlotOnError?.(event);
+                if (!event.defaultPrevented)
+                    setDecodeFailed(true);
+            } })) : (_jsx(VireoFileImagePreviewFallback, { ...fallbackSlotOther, as: slots.fallback, ownerState: ownerState, className: joinClassNames(classes.fallback, fallbackSlotClassName), children: previewUnavailableText })) }));
+});
+VireoFileImagePreview.displayName = VIREO_FILE_IMAGE_PREVIEW_NAME;

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.styled.d.ts

@@ -0,0 +1,8 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps, type TypographyProps } from "@mui/material";
+import { type VireoFileImagePreviewOwnerState } from "./VireoFileImagePreview.types.js";
+type VireoFileImagePreviewStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFileImagePreviewOwnerState>;
+export declare const VireoFileImagePreviewRoot: VireoFileImagePreviewStyledSlotComponent<BoxProps>;
+export declare const VireoFileImagePreviewImage: VireoFileImagePreviewStyledSlotComponent<React.ImgHTMLAttributes<HTMLImageElement>>;
+export declare const VireoFileImagePreviewFallback: VireoFileImagePreviewStyledSlotComponent<TypographyProps>;
+export {};

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.styled.js

@@ -0,0 +1,38 @@
+import { Box, Typography } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FILE_IMAGE_PREVIEW_NAME } from "./VireoFileImagePreview.identity.js";
+export const VireoFileImagePreviewRoot = styled(Box, {
+    name: VIREO_FILE_IMAGE_PREVIEW_NAME,
+    slot: "Root",
+    overridesResolver: (_props, styles) => styles.root,
+})(({ theme }) => ({
+    alignItems: "center",
+    backgroundColor: theme.palette.background.default,
+    border: `1px solid ${theme.palette.divider}`,
+    borderRadius: theme.shape.borderRadius,
+    display: "flex",
+    justifyContent: "center",
+    minHeight: 120,
+    overflow: "hidden",
+    width: "100%",
+}));
+export const VireoFileImagePreviewImage = styled("img", {
+    name: VIREO_FILE_IMAGE_PREVIEW_NAME,
+    slot: "Image",
+    overridesResolver: (_props, styles) => styles.image,
+})(({ ownerState }) => ({
+    display: "block",
+    maxHeight: 240,
+    maxWidth: "100%",
+    objectFit: ownerState.objectFit,
+    width: "100%",
+}));
+export const VireoFileImagePreviewFallback = styled(Typography, {
+    name: VIREO_FILE_IMAGE_PREVIEW_NAME,
+    slot: "Fallback",
+    overridesResolver: (_props, styles) => styles.fallback,
+})(({ theme }) => ({
+    color: theme.palette.text.secondary,
+    padding: theme.spacing(3),
+    textAlign: "center",
+}));

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.types.d.ts

@@ -0,0 +1,55 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { BoxProps, Typography } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFileImagePreviewClasses, type VireoFileImagePreviewClassKey } from "./VireoFileImagePreview.classes.js";
+import type { VIREO_FILE_IMAGE_PREVIEW_NAME, VireoFileImagePreviewSlotName } from "./VireoFileImagePreview.identity.js";
+export type VireoFileImagePreviewObjectFit = "contain" | "cover";
+export type VireoFileImagePreviewOwnerState = {
+    available: boolean;
+    objectFit: VireoFileImagePreviewObjectFit;
+};
+export interface VireoFileImagePreviewRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFileImagePreviewImageSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+export interface VireoFileImagePreviewFallbackSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoFileImagePreview}. */
+export type VireoFileImagePreviewSlots = {
+    [TSlotName in VireoFileImagePreviewSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoFileImagePreview}. */
+export type VireoFileImagePreviewSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFileImagePreviewSlots, {
+    /** @default 'div' */
+    root: SlotProps<"div", VireoFileImagePreviewRootSlotPropsOverrides, VireoFileImagePreviewOwnerState>;
+    /** @default 'img' */
+    image: SlotProps<"img", VireoFileImagePreviewImageSlotPropsOverrides, VireoFileImagePreviewOwnerState>;
+    /** @default Typography */
+    fallback: SlotProps<typeof Typography, VireoFileImagePreviewFallbackSlotPropsOverrides, VireoFileImagePreviewOwnerState>;
+}>;
+/** Props owned by {@link VireoFileImagePreview}. */
+export type VireoFileImagePreviewOwnProps = VireoFileImagePreviewSlotsAndSlotProps & {
+    /** Alternative text for a semantically meaningful preview. @default '' */
+    alt?: string;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoFileImagePreviewClasses>;
+    /** Image file to preview. */
+    file: File;
+    /** How the image fits inside the preview surface. @default 'contain' */
+    objectFit?: VireoFileImagePreviewObjectFit;
+    /** Content shown when the selected file cannot be previewed. @default 'Preview unavailable' */
+    previewUnavailableText?: React.ReactNode;
+};
+/** Props VireoFileImagePreview inherits from its default root after excluding component-owned props. */
+export type VireoFileImagePreviewInheritedProps = Omit<BoxProps<"div">, "children" | "component">;
+/** Props accepted by {@link VireoFileImagePreview}. */
+export type VireoFileImagePreviewProps = VireoFileImagePreviewOwnProps & VireoFileImagePreviewInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FILE_IMAGE_PREVIEW_NAME]?: VireoThemeComponent<VireoFileImagePreviewProps, VireoFileImagePreviewClassKey, VireoFileImagePreviewOwnerState, Theme>;
+    }
+}

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/VireoFileImagePreview.types.js

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

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/index.d.ts

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

package/dist/capabilities/forms/components/data-display/VireoFileImagePreview/index.js

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

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

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

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

@@ -0,0 +1,11 @@
+import { generateUtilityClass, generateUtilityClasses } from "@mui/material";
+import { VIREO_FORM_NAME, VIREO_FORM_SLOTS, VIREO_FORM_STATES, } from "./VireoForm.identity.js";
+/** Returns the generated utility class name for a VireoForm slot or state. */
+export function getVireoFormUtilityClass(slot) {
+    return generateUtilityClass(VIREO_FORM_NAME, slot);
+}
+/** Generated utility class names keyed by each public VireoForm class key. */
+export const vireoFormClasses = generateUtilityClasses(VIREO_FORM_NAME, [
+    ...VIREO_FORM_SLOTS,
+    ...VIREO_FORM_STATES,
+]);

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

@@ -0,0 +1,28 @@
+import { type AnyFormApi } from "@tanstack/react-form";
+import React from "react";
+import type { VireoMultiStepStore } from "../../../../../capabilities/forms/state/vireoMultiStepStore/vireoMultiStepStore.js";
+type VireoFormRuntimeApi = AnyFormApi & {
+    AppForm: React.ComponentType<React.PropsWithChildren>;
+};
+/**
+ * Provides the semantic form boundary, lifecycle wiring, and shared presentation policy used by `useVireoForm`.
+ *
+ * Consumers render this component through `form.Form`; the raw runtime is intentionally capability-bound.
+ */
+export declare const VireoForm: React.ForwardRefExoticComponent<import("./VireoForm.types.js").VireoFormSlotsAndSlotProps & {
+    children?: React.ReactNode;
+    classes?: Partial<import("./VireoForm.classes.js").VireoFormClasses>;
+    errorDisplay?: import("./VireoForm.types.js").VireoFormErrorDisplay;
+    formatError?: import("./VireoForm.types.js").VireoFormErrorFormatter;
+    focusInvalidFieldOnSubmit?: boolean;
+    layoutWidth?: import("./VireoForm.types.js").VireoFormLayoutWidth;
+    unsavedChangesGuard?: boolean;
+    unsavedChangesBusy?: boolean;
+    unsavedChangesScopeId?: string;
+} & Omit<Omit<React.DetailedHTMLProps<React.FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>, "ref">, "children" | "classes" | "errorDisplay" | "focusInvalidFieldOnSubmit" | "formatError" | "layoutWidth" | "ref" | "unsavedChangesBusy" | "unsavedChangesGuard" | "unsavedChangesScopeId" | keyof import("./VireoForm.types.js").VireoFormSlotsAndSlotProps> & {
+    sx?: import("@mui/system").SxProps<import("@mui/material").Theme>;
+} & {
+    form: VireoFormRuntimeApi;
+    multiStepController?: VireoMultiStepStore;
+} & React.RefAttributes<HTMLFormElement>>;
+export {};

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

@@ -0,0 +1,10 @@
+/** Stable component name shared by every VireoForm integration point. */
+export declare const VIREO_FORM_NAME = "VireoForm";
+/** Canonical public slots exposed by VireoForm, in rendered DOM order. */
+export declare const VIREO_FORM_SLOTS: readonly ["root"];
+/** Public slot names exposed by VireoForm. */
+export type VireoFormSlotName = (typeof VIREO_FORM_SLOTS)[number];
+/** Canonical state classes exposed by VireoForm. */
+export declare const VIREO_FORM_STATES: readonly ["dirty", "submitting", "validating", "invalid"];
+/** Public state names exposed by VireoForm. */
+export type VireoFormStateName = (typeof VIREO_FORM_STATES)[number];

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

@@ -0,0 +1,6 @@
+/** Stable component name shared by every VireoForm integration point. */
+export const VIREO_FORM_NAME = "VireoForm";
+/** Canonical public slots exposed by VireoForm, in rendered DOM order. */
+export const VIREO_FORM_SLOTS = ["root"];
+/** Canonical state classes exposed by VireoForm. */
+export const VIREO_FORM_STATES = ["dirty", "submitting", "validating", "invalid"];

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

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUnsavedChangesRegistration } from "../../../../../capabilities/unsaved-changes/public.js";
+import { joinClassNames, mergeSx, resolveSlotProps } from "../../../../../core/public.js";
+import { VireoFormContext } from "../../../../../capabilities/forms/contexts/VireoFormContext/VireoFormContext.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 { getVireoFormUtilityClass } from "./VireoForm.classes.js";
+import { VIREO_FORM_NAME } from "./VireoForm.identity.js";
+import { VireoFormRoot } from "./VireoForm.styled.js";
+function useUtilityClasses(ownerState, classes) {
+    return composeClasses({
+        root: [
+            "root",
+            ownerState.dirty && "dirty",
+            ownerState.submitting && "submitting",
+            ownerState.validating && "validating",
+            ownerState.invalid && "invalid",
+        ],
+    }, getVireoFormUtilityClass, classes);
+}
+function focusFirstInvalidField(root) {
+    const invalidRegion = root?.querySelector('[aria-invalid="true"]');
+    const candidate = invalidRegion?.querySelector('[data-vireo-field-focus-target="true"]:not([disabled])') ??
+        root?.querySelector('[aria-invalid="true"]:not([disabled]), [aria-invalid="true"] input:not([disabled]), [aria-invalid="true"] textarea:not([disabled]), [aria-invalid="true"] select:not([disabled]), [aria-invalid="true"] button:not([disabled])');
+    if (!candidate) {
+        const summary = root?.querySelector('[data-vireo-error-summary="true"]');
+        summary?.focus();
+        summary?.scrollIntoView?.({ block: "nearest" });
+        return;
+    }
+    candidate.focus();
+    candidate.scrollIntoView?.({ block: "nearest" });
+}
+/**
+ * Provides the semantic form boundary, lifecycle wiring, and shared presentation policy used by `useVireoForm`.
+ *
+ * Consumers render this component through `form.Form`; the raw runtime is intentionally capability-bound.
+ */
+export const VireoForm = React.forwardRef(function VireoForm(inProps, forwardedRef) {
+    const props = useThemeProps({ props: inProps, name: VIREO_FORM_NAME });
+    const { children, className, classes: classesProp, errorDisplay = "touched-or-submitted", focusInvalidFieldOnSubmit = true, form, formatError, layoutWidth = "standard", multiStepController, noValidate = true, onReset, onSubmit, slotProps = {}, slots = {}, style, sx, unsavedChangesBusy = false, unsavedChangesGuard = false, unsavedChangesScopeId, ...other } = props;
+    const rootElementRef = React.useRef(null);
+    const state = useStore(form.store, current => ({
+        dirty: current.isDirty,
+        invalid: !current.isValid,
+        submissionAttempts: current.submissionAttempts,
+        submitting: current.isSubmitting,
+        validating: current.isValidating,
+    }));
+    const ownerState = {
+        dirty: state.dirty,
+        invalid: state.invalid,
+        layoutWidth,
+        submitting: state.submitting,
+        validating: state.validating,
+    };
+    const classes = useUtilityClasses(ownerState, classesProp);
+    useUnsavedChangesRegistration({
+        busy: state.submitting || unsavedChangesBusy,
+        dirty: state.dirty,
+        enabled: unsavedChangesGuard,
+        scopeId: unsavedChangesScopeId,
+    });
+    const resolvedRootSlotProps = resolveSlotProps(slotProps.root, ownerState);
+    const { className: rootSlotClassName, onReset: rootSlotOnReset, onSubmit: rootSlotOnSubmit, ref: rootSlotRef, style: rootSlotStyle, sx: rootSlotSx, ...rootSlotOther } = resolvedRootSlotProps;
+    const rootRef = useForkRef(forwardedRef, rootSlotRef, rootElementRef);
+    const inheritedRootProps = { ...other, ...rootSlotOther };
+    const handleSubmit = (event) => {
+        const formEvent = event;
+        onSubmit?.(formEvent);
+        if (event.defaultPrevented)
+            return;
+        rootSlotOnSubmit?.(formEvent);
+        if (event.defaultPrevented)
+            return;
+        event.preventDefault();
+        if (multiStepController && !multiStepController.getSnapshot().isLastStep) {
+            void multiStepController.goToNextStep();
+            return;
+        }
+        void form.handleSubmit().then(() => {
+            if (form.state.isValid)
+                return;
+            if (multiStepController) {
+                void multiStepController.handleInvalidSubmit();
+                return;
+            }
+            if (focusInvalidFieldOnSubmit)
+                window.requestAnimationFrame(() => focusFirstInvalidField(rootElementRef.current));
+        });
+    };
+    const handleReset = (event) => {
+        const formEvent = event;
+        onReset?.(formEvent);
+        if (event.defaultPrevented)
+            return;
+        rootSlotOnReset?.(formEvent);
+        if (event.defaultPrevented)
+            return;
+        event.preventDefault();
+        form.reset();
+    };
+    return (_jsx(form.AppForm, { children: _jsx(VireoFormContext.Provider, { value: { errorDisplay, formatError, submissionAttempts: state.submissionAttempts }, children: _jsx(VireoFormRoot, { ...inheritedRootProps, as: slots.root ?? "form", ref: rootRef, ownerState: ownerState, className: joinClassNames(classes.root, className, rootSlotClassName), noValidate: noValidate, onReset: handleReset, onSubmit: handleSubmit, style: { ...style, ...rootSlotStyle }, sx: mergeSx(sx, rootSlotSx), children: children }) }) }));
+});
+VireoForm.displayName = VIREO_FORM_NAME;

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

@@ -0,0 +1,12 @@
+import { type StyledSlotComponent } from "../../../../../core/public.js";
+import { type BoxProps } from "@mui/material";
+import type React from "react";
+import { type VireoFormOwnerState } from "./VireoForm.types.js";
+type VireoFormStyledSlotComponent<TProps extends object> = StyledSlotComponent<TProps, VireoFormOwnerState>;
+type VireoFormRootProps = BoxProps & {
+    noValidate?: boolean;
+    onReset?: React.FormEventHandler<Element>;
+    onSubmit?: React.SubmitEventHandler<Element>;
+};
+export declare const VireoFormRoot: VireoFormStyledSlotComponent<VireoFormRootProps>;
+export {};

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

@@ -0,0 +1,24 @@
+import { Box } from "@mui/material";
+import { styled } from "@mui/material/styles";
+import { VIREO_FORM_NAME } from "./VireoForm.identity.js";
+export const VireoFormRoot = styled(Box, {
+    name: VIREO_FORM_NAME,
+    slot: "Root",
+    overridesResolver: ({ ownerState }, styles) => [
+        styles.root,
+        ownerState.dirty && styles.dirty,
+        ownerState.submitting && styles.submitting,
+        ownerState.validating && styles.validating,
+        ownerState.invalid && styles.invalid,
+    ],
+})(({ theme, ownerState }) => ({
+    display: "flex",
+    flexDirection: "column",
+    gap: theme.spacing(3),
+    marginInline: "auto",
+    minWidth: 0,
+    width: "100%",
+    ...(ownerState.layoutWidth === "standard" && { maxWidth: "48rem" }),
+    ...(ownerState.layoutWidth === "wide" && { maxWidth: "72rem" }),
+    ...(ownerState.layoutWidth === "full" && { maxWidth: "none" }),
+}));

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

@@ -0,0 +1,66 @@
+import type { VireoDataAttributeValue, VireoThemeComponent } from "../../../../../core/public.js";
+import type { SxProps, Theme } from "@mui/material";
+import type { CreateSlotsAndSlotProps, SlotProps } from "@mui/material/utils";
+import type React from "react";
+import { type VireoFormClasses, type VireoFormClassKey } from "./VireoForm.classes.js";
+import type { VIREO_FORM_NAME, VireoFormSlotName } from "./VireoForm.identity.js";
+export type VireoFormErrorDisplayPredicate = (context: {
+    submissionAttempts: number;
+    touched: boolean;
+}) => boolean;
+/** Controls when field errors are presented without changing validation timing. */
+export type VireoFormErrorDisplay = "always" | "never" | "touched-or-submitted" | VireoFormErrorDisplayPredicate;
+/** Converts a validation error into consumer-facing helper text. */
+export type VireoFormErrorFormatter = (error: unknown) => string | undefined;
+/** Standard content-width presets owned by {@link VireoForm}. */
+export type VireoFormLayoutWidth = "standard" | "wide" | "full";
+export type VireoFormOwnerState = {
+    dirty: boolean;
+    invalid: boolean;
+    layoutWidth: VireoFormLayoutWidth;
+    submitting: boolean;
+    validating: boolean;
+};
+export interface VireoFormRootSlotPropsOverrides {
+    [key: `data-${string}`]: VireoDataAttributeValue;
+}
+/** Replaceable semantic regions exposed by {@link VireoForm}. */
+export type VireoFormSlots = {
+    [TSlotName in VireoFormSlotName]: React.ElementType;
+};
+/** Slot props exposed by {@link VireoForm}. */
+export type VireoFormSlotsAndSlotProps = CreateSlotsAndSlotProps<VireoFormSlots, {
+    /** @default 'form' */
+    root: SlotProps<"form", VireoFormRootSlotPropsOverrides, VireoFormOwnerState>;
+}>;
+/** Props owned by {@link VireoForm}. */
+export type VireoFormOwnProps = VireoFormSlotsAndSlotProps & {
+    children?: React.ReactNode;
+    /** Override or extend the utility classes applied to each slot. */
+    classes?: Partial<VireoFormClasses>;
+    /** Controls when bound fields present validation errors. @default 'touched-or-submitted' */
+    errorDisplay?: VireoFormErrorDisplay;
+    /** Overrides Vireo's default validation-error formatter for bound fields. */
+    formatError?: VireoFormErrorFormatter;
+    /** Focuses the first focusable invalid field after a rejected submit. @default true */
+    focusInvalidFieldOnSubmit?: boolean;
+    /** Constrains and centers the form using Vireo's standard content-width presets. @default 'standard' */
+    layoutWidth?: VireoFormLayoutWidth;
+    /** Registers this form with the unsaved-changes capability while it is dirty. @default false */
+    unsavedChangesGuard?: boolean;
+    /** Adds non-form busy work to the unsaved-changes registration. @default false */
+    unsavedChangesBusy?: boolean;
+    /** Overrides the nearest unsaved-changes scope for this form. */
+    unsavedChangesScopeId?: string;
+};
+/** Props VireoForm inherits from its default root after excluding component-owned props. */
+export type VireoFormInheritedProps = Omit<React.ComponentPropsWithoutRef<"form">, keyof VireoFormOwnProps | "ref"> & {
+    sx?: SxProps<Theme>;
+};
+/** Props accepted by {@link VireoForm}. */
+export type VireoFormProps = VireoFormOwnProps & VireoFormInheritedProps;
+declare module "@mui/material/styles" {
+    interface Components<Theme = unknown> {
+        [VIREO_FORM_NAME]?: VireoThemeComponent<VireoFormProps, VireoFormClassKey, VireoFormOwnerState, Theme>;
+    }
+}

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

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

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

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

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

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

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

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

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

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