@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/components/form/automated/AutomatedArrayField.js

@@ -0,0 +1,458 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * AutomatedArrayField Component
+ *
+ * Handles array schema types using react-hook-form's useFieldArray.
+ * Renders a list of items with add/remove controls and optional
+ * drag-and-drop reordering via @dnd-kit.
+ */
+import { useRef, useEffect, useState, useCallback, useMemo } from 'react';
+import { useFieldArray, useFormContext, useWatch, Controller } from 'react-hook-form';
+import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors, } from '@dnd-kit/core';
+import { SortableContext, useSortable, sortableKeyboardCoordinates, verticalListSortingStrategy, } from '@dnd-kit/sortable';
+import { FormFieldChrome } from '../chromes/FormFieldChrome.js';
+import { useFormChromeContext } from '../chromes/FormChromeContext.js';
+import { FormFieldCheckboxGroup } from '../controls/form-field-checkbox-group.js';
+import { useUI } from '../../../core/ui/useUI.js';
+import { useIconRegistry } from '../../../core/icons/useIconRegistry.js';
+import { IconSize, StandardIconReference } from '../../../core/icons/icon-registry.frontend.schemas.js';
+import { Button, ButtonVariants_Variant } from '../../../components/actions/button.js';
+import { FieldDescription as ContentSectionDescription } from '../../../components/form/chromes/field.js';
+import { ContentSection, ContentSectionLegend, ContentSectionGroup, } from '../../../components/sections/content-section.js';
+import { cn } from '../../../core/ui/cn.js';
+import { FormField, resolveSurfaceAutoFieldDensity, resolveSurfaceAutoLabelPlacement, resolveSurfaceFormChromeMode } from './FormField.js';
+import { useOptionalFormTemplateContext } from './FormTemplateContext.js';
+import { ComboboxMultiple } from '../../../components/form/combobox.js';
+import { InputRoot } from '../controls/input.js';
+import { getFieldError } from '../validation-errors/getFieldError.js';
+import { getArrayConstraints, getArrayItemSchema, getSchemaType, getArrayUI, getObjectShape, getObjectKeys, ArrayAddMode, ArrayObjectItemLayout, FormFieldComponent, FieldSchemaType, AutosaveTrigger, ValidationMode, getFieldUIEditConfig, getEnumUI, getEnumValues, EnumEditMode, SectionMode } from '@wildo-ai/zod-decorators';
+import { AutomatedLayoutFrontendUtils } from '../../../core/automated-layout/automated-layout.frontend.utils.js';
+import { FrontendComponentType, UIBehavior, TypographyVariant, ButtonSize } from '@wildo-ai/presets-components-models';
+import { useI18n } from '../../../core/i18n/useI18n.js';
+import { useOptionalAutosave } from './AutosaveContext.js';
+import { AutosaveFieldState } from '../form-field-types.js';
+import { AutosaveIndicator } from './autosave-indicator.js';
+import { useSurfacePolicy } from '../../../core/ui/SurfacePolicyContext.js';
+// ============================================================================
+// SORTABLE ITEM WRAPPERS
+// ============================================================================
+/**
+ * Converts a dnd-kit Transform to a CSS translate3d string.
+ * Inlined to avoid the @dnd-kit/utilities dependency.
+ */
+function transformToString(transform) {
+    if (!transform)
+        return undefined;
+    return `translate3d(${Math.round(transform.x)}px, ${Math.round(transform.y)}px, 0)`;
+}
+// DnD sensor configuration — module-level constants to avoid recreation on each render
+const POINTER_SENSOR_OPTIONS = { activationConstraint: { distance: 8 } };
+const KEYBOARD_SENSOR_OPTIONS = { coordinateGetter: sortableKeyboardCoordinates };
+/**
+ * Drag handle button rendered on sortable items.
+ */
+function DragHandle({ listeners, attributes, disabled, ariaLabel, renderIcon }) {
+    return (_jsx("button", { type: "button", className: cn("shrink-0 cursor-grab touch-none rounded p-0.5 text-muted-foreground/60", "hover:text-muted-foreground hover:bg-accent/50", "focus-ring-offset", "active:cursor-grabbing", disabled && "pointer-events-none opacity-0"), "aria-label": ariaLabel, tabIndex: disabled ? -1 : 0, ...attributes, ...listeners, children: renderIcon(StandardIconReference.GRIP_VERTICAL, { size: IconSize.SM }) }));
+}
+/**
+ * Sortable wrapper for primitive array items (string, number, etc.).
+ */
+function SortablePrimitiveItem({ id, fieldName, fieldLabel, itemSchema, disabled, canRemove, isValidating, reorderable, showUpDownIcons, isFirst, isLast, dragHandleAriaLabel, moveUpAriaLabel, moveDownAriaLabel, removeAriaLabel, renderField, onRemove, onMoveUp, onMoveDown, index, renderIcon, }) {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging, } = useSortable({ id, disabled: !reorderable || disabled });
+    const style = {
+        transform: transformToString(transform),
+        transition,
+        opacity: isDragging ? 0.5 : undefined,
+        zIndex: isDragging ? 10 : undefined,
+        position: 'relative',
+    };
+    return (_jsxs("div", { ref: setNodeRef, style: style, className: "flex items-end gap-element", children: [reorderable && (_jsx(DragHandle, { listeners: listeners, attributes: attributes, disabled: disabled, ariaLabel: dragHandleAriaLabel, renderIcon: renderIcon })), showUpDownIcons && (_jsxs("div", { className: "flex shrink-0 flex-col gap-0.5 mb-element", children: [_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveUp(index), disabled: disabled || isValidating || isFirst, className: "h-5 w-5", "aria-label": moveUpAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_UP, { size: IconSize.XS }) }), _jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveDown(index), disabled: disabled || isValidating || isLast, className: "h-5 w-5", "aria-label": moveDownAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_DOWN, { size: IconSize.XS }) })] })), _jsx("div", { className: "flex-1", children: renderField ? (renderField(fieldName, itemSchema)) : (_jsx(FormField, { name: fieldName, schema: itemSchema, label: fieldLabel, disabled: disabled })) }), canRemove && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onRemove(index), disabled: disabled || isValidating, className: "shrink-0 mb-element", "aria-label": removeAriaLabel, children: renderIcon(StandardIconReference.DELETE, { size: IconSize.SM }) }))] }));
+}
+/**
+ * Fixed width of the ROW-layout leading gutter cell (holds the item's boolean
+ * toggle — the checklist "☐"). Shared by the item rows AND the quick-add row's
+ * spacer so every primary input aligns to the same column regardless of the
+ * toggle control's intrinsic width.
+ */
+const ROW_GUTTER_WIDTH_CLASS = 'w-12';
+/**
+ * Leading-gutter width for a ROW array that supplies a custom per-item TEMPLATE
+ * (`renderField`). Templates typically lead with a compact CHECKBOX rather than
+ * the wider default Switch, so the gutter is tighter. Exported so the app's item
+ * template can reserve the SAME leading cell for its control — keeping the
+ * template rows AND the framework "add item" quick-add input aligned to one
+ * column. Wrap the template's leading control in
+ * `<div className={ARRAY_ROW_TEMPLATE_GUTTER_CLASS + ' shrink-0 flex items-center'}>`.
+ */
+export const ARRAY_ROW_TEMPLATE_GUTTER_CLASS = 'w-7';
+/** Reveal-on-row-hover classes for the ROW drag handle + remove button (kept
+ * visible for keyboard focus and coarse pointers, which have no hover). */
+const ROW_HOVER_REVEAL_CLASS = 'opacity-0 transition-opacity duration-[var(--motion-duration-fast)] group-hover/array-row:opacity-100 group-focus-within/array-row:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100';
+/**
+ * Compact inline renderer for an OBJECT-array item's sub-fields — the body of a
+ * {@link ArrayObjectItemLayout.ROW} item. Mirrors {@link FormFieldComposite}'s
+ * per-field `FormField` dispatch AND its context label-resolution chain, but
+ * lays the fields out horizontally with sr-only labels
+ * (`labelPlacement="hidden"` — keeps the accessible name, unlike `hideLabel`
+ * which drops it entirely). BOOLEAN sub-fields render FIRST as leading compact
+ * toggles (the "☐" of a checklist); the item's primary field fills the row.
+ */
+function ObjectItemRowFields({ fieldName, itemSchema, primaryFieldName, disabled, only, }) {
+    const ctx = useOptionalFormTemplateContext();
+    const shape = getObjectShape(itemSchema);
+    const keys = getObjectKeys(itemSchema);
+    if (!shape || keys.length === 0)
+        return null;
+    const booleanKeys = keys.filter((k) => getSchemaType(shape[k]) === FieldSchemaType.BOOLEAN);
+    const bodyKeys = keys.filter((k) => getSchemaType(shape[k]) !== FieldSchemaType.BOOLEAN);
+    const renderKeys = only === 'boolean' ? booleanKeys : only === 'body' ? bodyKeys : [...booleanKeys, ...bodyKeys];
+    return (_jsx(_Fragment, { children: renderKeys.map((key) => {
+            const subName = `${fieldName}.${key}`;
+            // Same label chain as FormFieldComposite: context dotted-path label →
+            // humanized leaf fallback (array-index paths are absent from the map).
+            const subLabel = ctx?.fieldLabels?.[subName]
+                ?? AutomatedLayoutFrontendUtils.formatFieldLabelFallback(key);
+            return (_jsx(FormField, { name: subName, schema: shape[key], label: subLabel, labelPlacement: "hidden", disabled: disabled, 
+                // Field-chrome roots are `w-full` (see field-chrome context map,
+                // Gotcha 9) — a row cell MUST override that to `w-auto`, else the
+                // first cell (e.g. the `done` toggle) eats the row and the primary
+                // field collapses to zero width.
+                className: cn('w-auto', key === primaryFieldName ? 'min-w-0 flex-1' : 'shrink-0') }, key));
+        }) }));
+}
+/**
+ * Sortable wrapper for object array items.
+ */
+function SortableObjectItem({ id, fieldName, fieldLabel, layout, primaryFieldName, itemSchema, disabled, canRemove, isValidating, reorderable, showUpDownIcons, isFirst, isLast, dragHandleAriaLabel, moveUpAriaLabel, moveDownAriaLabel, removeAriaLabel, renderField, onRemove, onMoveUp, onMoveDown, index, renderIcon, }) {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging, } = useSortable({ id, disabled: !reorderable || disabled });
+    const style = {
+        transform: transformToString(transform),
+        transition,
+        opacity: isDragging ? 0.5 : undefined,
+        zIndex: isDragging ? 10 : undefined,
+        position: 'relative',
+    };
+    // Live primary-field value as the item summary header (e.g. the checklist `label`),
+    // falling back to fieldLabel ("Item N") when blank or non-text. useWatch scopes the
+    // subscription to THIS item's primary path so editing only re-renders this badge.
+    const primaryValue = useWatch({ name: primaryFieldName ? `${fieldName}.${primaryFieldName}` : fieldName });
+    const summaryHeader = typeof primaryValue === 'string' && primaryValue.trim() !== ''
+        ? primaryValue.trim()
+        : typeof primaryValue === 'number'
+            ? String(primaryValue)
+            : fieldLabel;
+    // ROW layout: a compact single-row item — no card frame, no floating chip.
+    // A fixed-width leading GUTTER holds the boolean toggle(s) (the checklist
+    // "☐"); the primary field fills the body. The reorder handle lives in the
+    // LEFT MARGIN (absolute, hover-revealed) so it adds NO permanent gutter —
+    // the item content therefore aligns with the quick-add row (which reserves
+    // the same gutter). Remove button hover-reveals at the end. This is the
+    // checklist / tag-list / key-value look.
+    if (layout === ArrayObjectItemLayout.ROW) {
+        return (_jsxs("div", { ref: setNodeRef, style: style, className: "group/array-row relative flex items-center gap-element", children: [reorderable && !showUpDownIcons && (_jsx("div", { className: cn('absolute -left-5 top-1/2 -translate-y-1/2', ROW_HOVER_REVEAL_CLASS), children: _jsx(DragHandle, { listeners: listeners, attributes: attributes, disabled: disabled, ariaLabel: dragHandleAriaLabel, renderIcon: renderIcon }) })), showUpDownIcons && (_jsxs("div", { className: "flex shrink-0 flex-col gap-0.5", children: [_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveUp(index), disabled: disabled || isValidating || isFirst, className: "h-5 w-5", "aria-label": moveUpAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_UP, { size: IconSize.XS }) }), _jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveDown(index), disabled: disabled || isValidating || isLast, className: "h-5 w-5", "aria-label": moveDownAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_DOWN, { size: IconSize.XS }) })] })), !renderField && (_jsx("div", { className: cn('flex shrink-0 items-center', ROW_GUTTER_WIDTH_CLASS), children: _jsx(ObjectItemRowFields, { fieldName: fieldName, itemSchema: itemSchema, primaryFieldName: primaryFieldName, disabled: disabled, only: "boolean" }) })), _jsx("div", { className: "flex min-w-0 flex-1 items-center gap-element", children: renderField ? (renderField(fieldName, itemSchema)) : (_jsx(ObjectItemRowFields, { fieldName: fieldName, itemSchema: itemSchema, primaryFieldName: primaryFieldName, disabled: disabled, only: "body" })) }), canRemove && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onRemove(index), disabled: disabled || isValidating, className: cn('shrink-0', ROW_HOVER_REVEAL_CLASS), "aria-label": removeAriaLabel, children: renderIcon(StandardIconReference.DELETE, { size: IconSize.SM }) }))] }));
+    }
+    return (_jsxs("div", { ref: setNodeRef, style: style, 
+        // `mt-3` reserves the exact headroom the floating `-top-3` header chip
+        // protrudes into — WITHOUT it the first item's chip overlaps whatever sits
+        // above the list (the array section legend), because `space-y-*` on the
+        // list container only spaces BETWEEN items. Keeping the reservation on the
+        // item itself makes the floating-chip design container-agnostic.
+        className: "relative mt-3 rounded-lg border border-border p-card", children: [_jsxs("div", { className: "absolute -top-3 start-card-sm z-10 flex max-w-[calc(100%-4.5rem)] items-center gap-1 overflow-hidden bg-background px-card-sm text-sm font-medium text-muted-foreground", children: [reorderable && (_jsx(DragHandle, { listeners: listeners, attributes: attributes, disabled: disabled, ariaLabel: dragHandleAriaLabel, renderIcon: renderIcon })), showUpDownIcons && (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveUp(index), disabled: disabled || isValidating || isFirst, className: "h-5 w-5", "aria-label": moveUpAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_UP, { size: IconSize.XS }) }), _jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onMoveDown(index), disabled: disabled || isValidating || isLast, className: "h-5 w-5", "aria-label": moveDownAriaLabel, children: renderIcon(StandardIconReference.CHEVRON_DOWN, { size: IconSize.XS }) })] })), _jsx("span", { className: "truncate", children: summaryHeader })] }), canRemove && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.ICON, onClick: () => onRemove(index), disabled: disabled || isValidating, className: "absolute -top-3 end-3 z-10 h-6 w-6 bg-background", "aria-label": removeAriaLabel, children: renderIcon(StandardIconReference.CLOSE, { size: IconSize.SM }) })), _jsx("div", { className: "pt-item", children: renderField ? (renderField(fieldName, itemSchema)) : (
+                // The card badge above IS the item header — render the object's fields
+                // WITHOUT the composite's own legend so "Item N" isn't shown twice.
+                _jsx(FormField, { name: fieldName, schema: itemSchema, label: fieldLabel, hideLabel: true, disabled: disabled })) })] }));
+}
+function ArrayQuickAddRow({ primaryField, itemSchema, onAdd, disabled, addLabel, placeholder, leadingGutterClassName, }) {
+    const { renderIcon } = useIconRegistry();
+    const isNumeric = getSchemaType(primaryField.schema) === FieldSchemaType.NUMBER;
+    const [rawValue, setRawValue] = useState('');
+    const trimmed = rawValue.trim();
+    // Validate-before-add: non-empty AND schema-valid, else the commit is a no-op.
+    const stagedPrimary = isNumeric ? Number(trimmed) : trimmed;
+    const canCommit = !disabled && trimmed !== '' && primaryField.schema.safeParse(stagedPrimary).success;
+    const commit = useCallback(() => {
+        if (disabled)
+            return;
+        const value = rawValue.trim();
+        if (value === '')
+            return;
+        const committedPrimary = isNumeric ? Number(value) : value;
+        if (!primaryField.schema.safeParse(committedPrimary).success)
+            return;
+        const item = primaryField.name === null
+            ? committedPrimary
+            : {
+                ...AutomatedLayoutFrontendUtils.getDefaultValueForSchema(itemSchema),
+                [primaryField.name]: committedPrimary,
+            };
+        onAdd(item);
+        setRawValue('');
+    }, [disabled, rawValue, isNumeric, primaryField, itemSchema, onAdd]);
+    return (_jsxs("div", { className: "flex items-center gap-element", "data-testid": "array-quick-add-row", onKeyDown: (e) => {
+            if (e.key === 'Enter') {
+                e.preventDefault();
+                commit();
+            }
+        }, children: [leadingGutterClassName && _jsx("span", { "aria-hidden": "true", className: cn('shrink-0', leadingGutterClassName) }), _jsx(InputRoot, { type: isNumeric ? 'number' : 'text', value: rawValue, onChange: (e) => setRawValue(e.target.value), placeholder: placeholder ?? addLabel, disabled: disabled, wrapperClassName: "flex-1", "aria-label": addLabel }), _jsx(Button, { type: "button", variant: ButtonVariants_Variant.OUTLINE, onClick: commit, disabled: !canCommit, "aria-label": addLabel, children: renderIcon(StandardIconReference.PLUS, { size: IconSize.SM }) })] }));
+}
+function AutomatedArrayFieldComponent({ name, schema, label, description, disabled, className, renderField, addLabel: addLabelProp, itemLabel: itemLabelProp, reorderable: reorderableProp = true, sectionAppearance, objectItemLayout: objectItemLayoutOverride, }) {
+    const { control, getFieldState, getValues, formState, trigger } = useFormContext();
+    const { renderIcon } = useIconRegistry();
+    const { tComponent, tErrorValidation, isReady } = useI18n({
+        component: FrontendComponentType.LOW_LEVEL_FORM_MESSAGE,
+        keys: ['errors_validation'],
+    });
+    const { getRecipe } = useUI();
+    const descriptionRecipe = getRecipe(UIBehavior.TYPOGRAPHY, TypographyVariant.DESCRIPTION);
+    const { formChromeMode, sectionChromeMode } = useFormChromeContext();
+    const surfacePolicy = useSurfacePolicy();
+    const fieldEditConfig = getFieldUIEditConfig(schema);
+    const resolvedChromeMode = fieldEditConfig?.chromeMode ?? sectionChromeMode ?? formChromeMode ?? resolveSurfaceFormChromeMode(surfacePolicy.autoRender?.autoFieldChrome);
+    const resolvedLabelPlacement = resolveSurfaceAutoLabelPlacement(surfacePolicy.autoRender?.autoLabelPlacement);
+    const resolvedControlSize = resolveSurfaceAutoFieldDensity(surfacePolicy.autoRender?.autoFieldDensity);
+    const hideInlineErrorForPolicy = surfacePolicy.autoRender?.autoErrorPlacement === 'summary-at-surface-top';
+    // Autosave context (null if not within AutosaveProvider)
+    const autosaveContext = useOptionalAutosave();
+    // Resolve labels from i18n with prop overrides
+    const addLabel = addLabelProp ?? tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayAddItem');
+    const itemLabel = itemLabelProp ?? tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayItemLabel');
+    const emptyMessage = tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayEmptyMessage');
+    // Track mounted state to prevent validation trigger after unmount
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        // Set true on EVERY (re)mount — do NOT rely solely on the `useRef(true)` initializer.
+        // Under React StrictMode (dev) the mount→unmount→remount double-invoke runs this
+        // effect's cleanup (→ false) and then re-runs the effect; without re-setting true here
+        // the ref is left FALSE for a still-mounted component, which makes `afterArrayMutation`
+        // bail before `triggerSave` and SILENTLY SWALLOW every array autosave (add/edit/remove/
+        // reorder). Surfaced by the read-inline checklist editor — see array-element-authoring
+        // Step 4; the same latent bug affects array autosave inside the full resource form.
+        mountedRef.current = true;
+        return () => { mountedRef.current = false; };
+    }, []);
+    // Track validation state to prevent rapid clicks during async operations
+    const [isValidating, setIsValidating] = useState(false);
+    const { fields, append, remove, move } = useFieldArray({
+        control,
+        name,
+    });
+    // Get array item schema and constraints
+    const itemSchema = getArrayItemSchema(schema);
+    const constraints = getArrayConstraints(schema);
+    const itemSchemaType = itemSchema ? getSchemaType(itemSchema) : 'unknown';
+    // Check if this array should be rendered as a checkbox group
+    // This applies when:
+    // 1. The array has the explicit CHECKBOX_GROUP decorator, OR
+    // 2. The array contains enum items with no explicit form component override
+    //    (enum arrays are best displayed as checkbox groups by default)
+    const formComponent = fieldEditConfig?.component;
+    const isEnumArray = itemSchema && getSchemaType(itemSchema) === FieldSchemaType.ENUM;
+    const isCheckboxGroup = isEnumArray
+        && (formComponent === FormFieldComponent.CHECKBOX_GROUP || !formComponent);
+    // Read sortable config from arrayUI.edit
+    const arrayEditUI = getArrayUI(schema)?.edit;
+    // Object-array item framing (card vs compact row). Governs both this edit
+    // pipeline and the read-only display path (DisplayValueDispatcher).
+    // Per-placement prop wins over the schema's arrayUI default (Decision 2 —
+    // presentation is a placement choice, not a field truth).
+    const objectItemLayout = objectItemLayoutOverride ?? getArrayUI(schema)?.objectItemLayout ?? ArrayObjectItemLayout.CARD;
+    const isSortable = arrayEditUI?.isSortable;
+    const dndEnabled = isSortable != null ? (!!isSortable && arrayEditUI?.dnd !== false) : true;
+    const showUpDownIcons = isSortable ? (arrayEditUI?.upDownIcons ?? false) : false;
+    // Reordering requires at least 2 items and non-disabled state
+    const reorderable = reorderableProp && dndEnabled && !disabled && fields.length > 1;
+    // DnD sensors: PointerSensor with small activation distance to prevent accidental drags,
+    // and KeyboardSensor with sortable-aware coordinate getter for a11y
+    const sensors = useSensors(useSensor(PointerSensor, POINTER_SENSOR_OPTIONS), useSensor(KeyboardSensor, KEYBOARD_SENSOR_OPTIONS));
+    // Stable list of sortable item IDs for SortableContext
+    const sortableIds = useMemo(() => fields.map(f => f.id), [fields]);
+    // Check if we can add more items
+    const canAdd = constraints.maxLength === undefined || fields.length < constraints.maxLength;
+    // Check if we can remove items
+    const canRemove = constraints.minLength === undefined || fields.length > constraints.minLength;
+    /**
+     * Shared post-mutation handler for all array operations (add, remove, move).
+     *
+     * 1. Re-validates the array field so constraint errors (min/max length) and
+     *    item-level error indices are refreshed.
+     * 2. Triggers autosave (debounced) when the form is within an AutosaveProvider,
+     *    sending the full array value as a single PATCH field.
+     *
+     * Uses setTimeout(0) to allow RHF to flush its internal state update before
+     * we read the new array value and trigger validation.
+     *
+     * NOTE: these handlers (and `canAdd`/`canRemove`) are declared via `useCallback`
+     * BEFORE every early return below. Rules of Hooks require an unconditional,
+     * stable hook order — the `!isReady` / combobox / checkbox-group early returns
+     * skip later hooks on some renders, so callbacks placed after them produced
+     * "Rendered more hooks than during the previous render" the moment `isReady`
+     * flipped false→true with an array field mounted. Keep ALL hooks above the returns.
+     */
+    const afterArrayMutation = useCallback(() => {
+        setIsValidating(true);
+        setTimeout(async () => {
+            if (!mountedRef.current)
+                return;
+            // Re-validate array (min/max length, item schemas, error index mapping)
+            await trigger(name);
+            if (!mountedRef.current)
+                return;
+            setIsValidating(false);
+            // Trigger autosave with the full array value
+            if (autosaveContext) {
+                const arrayValue = getValues(name);
+                autosaveContext.triggerSave(name, arrayValue, AutosaveTrigger.DEBOUNCE);
+            }
+        }, 0);
+    }, [trigger, name, autosaveContext, getValues]);
+    // Handle add item with validation debounce
+    const handleAdd = useCallback(() => {
+        if (!canAdd || disabled || isValidating)
+            return;
+        // Create default value based on item schema type
+        const defaultValue = AutomatedLayoutFrontendUtils.getDefaultValueForSchema(itemSchema);
+        append(defaultValue);
+        afterArrayMutation();
+    }, [canAdd, disabled, isValidating, itemSchema, append, afterArrayMutation]);
+    // Quick-add (validate-before-add): appends a PRE-BUILT, already-validated item
+    // staged by ArrayQuickAddRow — unlike handleAdd, which appends a blank card. Same
+    // post-mutation revalidation + whole-array autosave applies.
+    const handleQuickAdd = useCallback((item) => {
+        if (!canAdd || disabled || isValidating)
+            return;
+        append(item);
+        afterArrayMutation();
+    }, [canAdd, disabled, isValidating, append, afterArrayMutation]);
+    // Handle remove item with validation debounce
+    const handleRemove = useCallback((index) => {
+        if (!canRemove || disabled || isValidating)
+            return;
+        remove(index);
+        afterArrayMutation();
+    }, [canRemove, disabled, isValidating, remove, afterArrayMutation]);
+    // Handle up/down icon reordering
+    const handleMoveUp = useCallback((index) => {
+        if (index > 0 && !disabled && !isValidating) {
+            move(index, index - 1);
+            afterArrayMutation();
+        }
+    }, [move, disabled, isValidating, afterArrayMutation]);
+    const handleMoveDown = useCallback((index) => {
+        if (index < fields.length - 1 && !disabled && !isValidating) {
+            move(index, index + 1);
+            afterArrayMutation();
+        }
+    }, [fields.length, move, disabled, isValidating, afterArrayMutation]);
+    // Handle drag-and-drop reorder
+    const handleDragEnd = useCallback((event) => {
+        const { active, over } = event;
+        if (over && active.id !== over.id) {
+            const oldIndex = fields.findIndex(f => f.id === active.id);
+            const newIndex = fields.findIndex(f => f.id === over.id);
+            if (oldIndex !== -1 && newIndex !== -1) {
+                move(oldIndex, newIndex);
+                afterArrayMutation();
+            }
+        }
+    }, [fields, move, afterArrayMutation]);
+    if (!itemSchema) {
+        return null;
+    }
+    if (!isReady)
+        return null;
+    // Render a COMPACT multi-select combobox for enum arrays that opt into COMBOBOX
+    // editMode — `z.array(z.enum(X).enumUI({ edit: { editMode: EnumEditMode.COMBOBOX } }))`.
+    // A settings row has no room for a full inline checkbox column (every option
+    // listed); this renders selected values as chips inside a searchable popover
+    // (the same `ComboboxMultiple` control `FormFieldEnum` uses for COMBOBOX + array
+    // value). Purely opt-in: enum arrays WITHOUT this editMode keep the checkbox-group
+    // path below, so no existing field changes. Options are the raw enum values, the
+    // same projection the checkbox group uses.
+    const itemEnumUI = isEnumArray && itemSchema ? getEnumUI(itemSchema) : undefined;
+    const isComboboxMultiSelect = isEnumArray && itemEnumUI?.edit?.editMode === EnumEditMode.COMBOBOX;
+    // field-clearing: N/A — this control produces an ARRAY, and an empty array is a VALUE rather
+    // than an absence, so it needs no cleared sentinel. It writes RHF state through its own
+    // `Controller` rather than `FormField`'s change handler for the same reason.
+    if (isComboboxMultiSelect && itemSchema) {
+        const comboValidationMode = fieldEditConfig?.validationMode ?? ValidationMode.ON_BLUR;
+        const comboOptions = (getEnumValues(itemSchema) ?? []).map((v) => ({ value: v, label: v }));
+        return (_jsx(Controller, { name: name, control: control, shouldUnregister: true, render: ({ field, fieldState }) => (_jsx(FormFieldChrome, { mode: resolvedChromeMode, label: label, description: description, error: getFieldError(fieldState, formState.isSubmitted, comboValidationMode, tErrorValidation), labelPlacement: resolvedLabelPlacement, hideError: hideInlineErrorForPolicy, saveState: autosaveContext?.getFieldState(name), saveErrorMessage: autosaveContext?.getFieldStateInfo(name).lastError, onRetrySave: autosaveContext ? () => autosaveContext.retryFieldSave(name) : undefined, fieldName: name, disabled: disabled, className: className, children: _jsx(ComboboxMultiple, { schema: schema, name: name, options: comboOptions, value: Array.isArray(field.value) ? field.value : [], onChange: field.onChange, onBlur: field.onBlur, disabled: disabled, showSelectAll: true }) })) }));
+    }
+    // Render as checkbox group for arrays of enums with CHECKBOX_GROUP component
+    // field-clearing: N/A — array-valued, as above.
+    if (isCheckboxGroup) {
+        const checkboxValidationMode = fieldEditConfig?.validationMode ?? ValidationMode.ON_BLUR;
+        return (_jsx(Controller, { name: name, control: control, shouldUnregister: true, render: ({ field, fieldState }) => (_jsx(FormFieldChrome, { mode: resolvedChromeMode, label: label, description: description, error: getFieldError(fieldState, formState.isSubmitted, checkboxValidationMode, tErrorValidation), labelPlacement: resolvedLabelPlacement, hideError: hideInlineErrorForPolicy, saveState: autosaveContext?.getFieldState(name), saveErrorMessage: autosaveContext?.getFieldStateInfo(name).lastError, onRetrySave: autosaveContext ? () => autosaveContext.retryFieldSave(name) : undefined, fieldName: name, disabled: disabled, className: className, children: _jsx(FormFieldCheckboxGroup, { schema: schema, name: name, disabled: disabled, value: field.value ?? [], onChange: field.onChange, onBlur: field.onBlur, controlSize: resolvedControlSize }) })) }));
+    }
+    // ── Whole-array autosave state (audit B1-render) ──
+    // `afterArrayMutation` autosaves the WHOLE array under this field's key
+    // (`triggerSave(name, arrayValue, DEBOUNCE)`), and `AutosaveContext.executeSave`
+    // records SAVING/SAVED/ERROR under the same key — but this component renders a
+    // `ContentSection`, not the scalar `FormFieldChrome` that owns the autosave
+    // indicator. Without a renderer here, a FAILED array autosave (network loss,
+    // conflict, resource deleted) was completely invisible: the optimistic rows
+    // kept rendering "saved" state while nothing persisted. Surface the same
+    // `AutosaveIndicator` (spinner / check / error + Retry) beside the section
+    // legend, wired to `retryFieldSave` so the error state carries its retry
+    // affordance exactly like scalar fields. Not hooks — safe below the early
+    // returns (the two Controller variants above thread the same state through
+    // their `FormFieldChrome` saveState props instead).
+    const arrayAutosaveInfo = autosaveContext?.getFieldStateInfo(name);
+    const arrayAutosaveIndicator = autosaveContext && arrayAutosaveInfo && arrayAutosaveInfo.state !== AutosaveFieldState.IDLE
+        ? (_jsx(AutosaveIndicator, { state: arrayAutosaveInfo.state, errorMessage: arrayAutosaveInfo.lastError, onRetry: () => autosaveContext.retryFieldSave(name), position: "inline", size: "sm", className: "ms-element align-middle" }))
+        : null;
+    // P4-T02: Get array-level error (not item-specific errors). Non-hook derived
+    // values may stay below the early returns; the handlers + canAdd/canRemove were
+    // hoisted above them (see the Rules-of-Hooks note).
+    const fieldState = getFieldState(name, formState);
+    const arrayError = fieldState.error?.root?.message || fieldState.error?.message;
+    const shouldShowArrayError = Boolean(arrayError && !hideInlineErrorForPolicy);
+    // Resolve the add affordance: QUICK_ADD renders an inline validate-before-add row
+    // (the item's primary field), every other mode keeps the append-a-blank "+ Add"
+    // button. Default-by-shape lives in resolveArrayAddMode (primitive / single-prominent
+    // -field object → quick-add). Non-hook; safe below the early returns.
+    const addMode = AutomatedLayoutFrontendUtils.resolveArrayAddMode(schema, itemSchema);
+    // The item's primary field drives BOTH the quick-add staging input (when QUICK_ADD)
+    // and the per-item summary header — the card badge shows the live primary value
+    // (e.g. the checklist `label`) instead of a generic "Item N".
+    const itemPrimaryField = AutomatedLayoutFrontendUtils.getArrayItemPrimaryField(itemSchema);
+    const quickAddPrimaryField = addMode === ArrayAddMode.QUICK_ADD ? itemPrimaryField : null;
+    // Render item list content (shared between DnD-wrapped and plain modes)
+    const isPrimitive = itemSchemaType !== 'object' && itemSchemaType !== 'array';
+    const renderItems = () => fields.map((field, index) => {
+        const fieldName = `${name}.${index}`;
+        const fieldLabel = `${itemLabel} ${index + 1}`;
+        const dragAriaLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayDragHandle', { label: fieldLabel });
+        const moveUpLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayMoveUp', { label: fieldLabel });
+        const moveDownLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayMoveDown', { label: fieldLabel });
+        const removeLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_MESSAGE, 'arrayRemoveItem', { label: fieldLabel });
+        if (isPrimitive) {
+            return (_jsx(SortablePrimitiveItem, { id: field.id, fieldName: fieldName, fieldLabel: fieldLabel, itemSchema: itemSchema, disabled: disabled, canRemove: canRemove, isValidating: isValidating, reorderable: reorderable, showUpDownIcons: showUpDownIcons, isFirst: index === 0, isLast: index === fields.length - 1, dragHandleAriaLabel: dragAriaLabel, moveUpAriaLabel: moveUpLabel, moveDownAriaLabel: moveDownLabel, removeAriaLabel: removeLabel, renderField: renderField, onRemove: handleRemove, onMoveUp: handleMoveUp, onMoveDown: handleMoveDown, index: index, renderIcon: renderIcon }, field.id));
+        }
+        // Object or nested array items
+        return (_jsx(SortableObjectItem, { id: field.id, fieldName: fieldName, fieldLabel: fieldLabel, layout: objectItemLayout, primaryFieldName: itemPrimaryField.name, itemSchema: itemSchema, disabled: disabled, canRemove: canRemove, isValidating: isValidating, reorderable: reorderable, showUpDownIcons: showUpDownIcons, isFirst: index === 0, isLast: index === fields.length - 1, dragHandleAriaLabel: dragAriaLabel, moveUpAriaLabel: moveUpLabel, moveDownAriaLabel: moveDownLabel, removeAriaLabel: removeLabel, renderField: renderField, onRemove: handleRemove, onMoveUp: handleMoveUp, onMoveDown: handleMoveDown, index: index, renderIcon: renderIcon }, field.id));
+    });
+    return (_jsxs(ContentSection
+    // Arrays default to a QUIET, frameless GHOST section (legend + list, no
+    // card border) — the framework baseline for "an array is just a labelled
+    // list here". Callers opt into CARD / COLLAPSIBLE to containerize. Applied
+    // at this consumer so EVERY array (wrapper-authored or a direct
+    // FormField/DisplayField) shares the default, not only the wrappers.
+    , { 
+        // Arrays default to a QUIET, frameless GHOST section (legend + list, no
+        // card border) — the framework baseline for "an array is just a labelled
+        // list here". Callers opt into CARD / COLLAPSIBLE to containerize. Applied
+        // at this consumer so EVERY array (wrapper-authored or a direct
+        // FormField/DisplayField) shares the default, not only the wrappers.
+        appearance: sectionAppearance ?? SectionMode.GHOST, disabled: disabled, className: cn(className, arrayError && 'border-destructive'), "data-field": name, "data-testid": `field-array-${name}`, "aria-invalid": !!arrayError, "aria-describedby": shouldShowArrayError ? `${name}-error` : undefined, children: [_jsxs(ContentSectionLegend, { children: [label, arrayAutosaveIndicator] }), description && _jsx(ContentSectionDescription, { children: description }), shouldShowArrayError && (_jsx("p", { id: `${name}-error`, className: "text-sm text-destructive mt-item-xs", role: "alert", children: arrayError })), _jsxs(ContentSectionGroup, { className: cn(objectItemLayout === ArrayObjectItemLayout.ROW ? undefined : 'space-y-field'), style: objectItemLayout === ArrayObjectItemLayout.ROW ? { rowGap: 'var(--spacing-element)' } : undefined, children: [_jsx(DndContext, { sensors: sensors, collisionDetection: closestCenter, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: sortableIds, strategy: verticalListSortingStrategy, children: renderItems() }) }), canAdd && quickAddPrimaryField ? (_jsx(ArrayQuickAddRow, { primaryField: quickAddPrimaryField, itemSchema: itemSchema, onAdd: handleQuickAdd, disabled: disabled || isValidating, addLabel: addLabel, 
+                        // ROW object arrays: reserve the same leading gutter the item rows
+                        // use for their leading control, so the staging input aligns to one
+                        // column. A custom item template leads with a tighter (checkbox)
+                        // gutter than the default Switch gutter.
+                        leadingGutterClassName: objectItemLayout === ArrayObjectItemLayout.ROW && !isPrimitive
+                            ? (renderField ? ARRAY_ROW_TEMPLATE_GUTTER_CLASS : ROW_GUTTER_WIDTH_CLASS)
+                            : undefined })) : canAdd ? (_jsxs(Button, { type: "button", variant: ButtonVariants_Variant.OUTLINE, onClick: handleAdd, disabled: disabled || isValidating, className: "w-full", children: [renderIcon(StandardIconReference.PLUS, { size: IconSize.SM, className: "me-element" }), addLabel] })) : null, fields.length === 0 && (_jsx("p", { className: cn(descriptionRecipe.base, "text-center py-card"), children: emptyMessage }))] })] }));
+}
+AutomatedArrayFieldComponent.displayName = 'AutomatedArrayField';
+export const AutomatedArrayField = AutomatedArrayFieldComponent;
+//# sourceMappingURL=AutomatedArrayField.js.map