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

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

@@ -26,19 +26,20 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useCallback, useRef, useEffect, useMemo } from 'react';
 import { useFormContext, Controller, useWatch } from 'react-hook-form';
 import { RelationshipNature, } from '@wildo-ai/saas-models';
-import { FormFieldComponent, FieldSchemaType, RangeSchemaType, getDefaultRangeComponent, getSchemaType, getEnumValues, getRangeType, getStringConstraints, getStringFormat, isForeignKey, getFieldUIEditConfig, isOptional, isNotEditableForOperation, getRecordValueSchema, getMapSchemas, getShowWhenParams, AutosaveTrigger } from '@wildo-ai/zod-decorators';
+import { EditChromeMode, FormFieldComponent, FieldSchemaType, RangeSchemaType, getDefaultRangeComponent, getSchemaType, getEnumValues, getRangeType, getStringConstraints, getStringFormat, isForeignKey, isTemplatableFileField, getFieldUIEditConfig, isOptional, isNotEditableForOperation, getRecordValueSchema, getMapSchemas, getShowWhenParams, normalizeClearedRequestDtoValue, normalizeClearedMainSchemaValue, requestDtoFieldIsClearable, mainSchemaFieldIsClearable, AutosaveTrigger } from '@wildo-ai/zod-decorators';
 import { AutomatedLayoutFrontendUtils } from '../../../core/automated-layout/automated-layout.frontend.utils.js';
+import { useSurfacePolicy } from '../../../core/ui/SurfacePolicyContext.js';
 import { AutosaveFieldState } from '../../../components/form/automated/AutosaveContext.js';
 import { useOptionalAutosave } from './AutosaveContext.js';
 import { useOptionalFormTemplateContext } from './FormTemplateContext.js';
-import { useFieldScope, useResolvedFieldName } from '../../resources/skeleton/FieldScopeContext.js';
+import { useResolvedFieldName } from '../../resources/skeleton/FieldScopeContext.js';
 import { useWizardFieldRegistration } from '../../resources/skeleton/WizardStepFieldsContext.js';
 import { useSectionFieldRegistration } from '../../resources/skeleton/SectionFieldsContext.js';
 import { useFieldUniquenessValidation } from '../validation-errors/useFieldUniquenessValidation.js';
 import { FormFieldChrome } from '../chromes/FormFieldChrome.js';
 import { useFormChromeContext } from '../chromes/FormChromeContext.js';
 import { RangeSlider } from '../controls/number/slider.js';
-import { ValidationMode } from '../form-field-types.js';
+import { FormSchemaKind, ValidationMode } from '../form-field-types.js';
 import { Input } from '../../../components/form/controls/input.js';
 import { FormFieldDate } from '../fields/form-field-date.js';
 import { FormFieldDateTime } from '../fields/form-field-datetime.js';
@@ -52,7 +53,7 @@ import { useI18n } from '../../../core/i18n/useI18n.js';
 import { useFormSchemaContext } from '../../../components/form/useFormSchemaContext.js';
 import { FormFieldComposite } from './FormFieldComposite.js';
 import { FormFieldRecord } from './FormFieldRecord.js';
-import { FormFieldArray } from './FormFieldArray.js';
+import { AutomatedArrayField } from './AutomatedArrayField.js';
 import { useResourceRegistry } from '../../../core/resources/useResourceRegistry.js';
 import { resolveRelationshipWriteSurface } from '../../../core/resources/relationship-surface-runtime.frontend.utils.js';
 // Import specialized form field components (dispatchers based on zod decorator editMode)
@@ -71,10 +72,45 @@ import { FormFieldRangeMoney } from '../fields/form-field-range-money.js';
 // Import FormFieldFile for resource-integrated file uploads
 import { FormFieldFile } from '../fields/form-field-file.js';
 import { ResourceFieldEdit_ResourceReference } from '../../../components/resources-fields/resource-reference/ResourceFieldEdit_ResourceReference.js';
+import { buildFormFieldAutoCompleteValue } from './form-field-autocomplete.frontend.utils.js';
+import { ControlSize } from '@wildo-ai/presets-components-models';
 // =============================================================================
 // CONSTANTS
 // =============================================================================
 import { getFieldError, FILE_VALIDATION_ERROR_TYPE } from '../validation-errors/getFieldError.js';
+export function resolveSurfaceFormChromeMode(value) {
+    switch (value) {
+        case 'stacked':
+            return EditChromeMode.STACKED;
+        case 'inline':
+            return EditChromeMode.INLINE;
+        case 'compact':
+            return EditChromeMode.COMPACT;
+        default:
+            return undefined;
+    }
+}
+export function resolveSurfaceAutoLabelPlacement(value) {
+    switch (value) {
+        case 'top':
+        case 'start':
+        case 'inline':
+        case 'hidden':
+            return value;
+        default:
+            return undefined;
+    }
+}
+export function resolveSurfaceAutoFieldDensity(value) {
+    switch (value) {
+        case 'sm':
+            return ControlSize.SM;
+        case 'md':
+            return ControlSize.MD;
+        default:
+            return undefined;
+    }
+}
 // =============================================================================
 // VALIDATION TRIGGER HOOKS
 // =============================================================================
@@ -123,6 +159,26 @@ function useDebouncedTrigger(trigger, fieldName, debounceMs = DEBOUNCE_DELAY_MS)
 function hasActionableFileEndpoints(endpoints) {
     return !!(endpoints?.upload || endpoints?.override);
 }
+/**
+ * The INBOUND half of the field-clearing contract: what a control should receive when form state
+ * holds the framework's cleared representation.
+ *
+ * A cleared field is `null` in form state (see `normalizeClearedRequestDtoValue`), but no edit control
+ * accepts `null` as a renderable value — `null` reaching a text input is what produces React's
+ * uncontrolled-input warning, and a date picker cannot render it at all. Every control already
+ * defines its OWN empty representation through its `controlledValue ?? internalValue` fallback
+ * (`''` for the string and enum families, the initial value elsewhere), so handing it `undefined`
+ * lets each control answer that question for itself rather than duplicating a per-type map here
+ * that would drift from the controls it describes.
+ *
+ * This mirrors the platform in the other direction: assigning `null` to an `input`'s value is
+ * coerced to `''` by the DOM, and Angular's default value accessor writes `''` for `null` for the
+ * same reason. Only the framework's own cleared sentinel is translated; every other value, `0` and
+ * `false` included, passes through untouched.
+ */
+function toRenderableFieldValue(value) {
+    return value ?? undefined;
+}
 /**
  * Hook to create field validation handlers with proper trigger logic.
  *
@@ -140,7 +196,10 @@ function hasActionableFileEndpoints(endpoints) {
  * @param isTextField - Whether this is a text input (needs debounce)
  * @param schema - Field schema for autosave config detection
  */
-function useFieldValidation(formContext, fieldName, validationMode = ValidationMode.ON_BLUR, isTextField = false, schema) {
+function useFieldValidation(formContext, fieldName, validationMode = ValidationMode.ON_BLUR, isTextField = false, schema, 
+// The clearing normalisation matching the KIND of schema this form validates. Passed in rather
+// than chosen here, because only the form knows which kind it holds.
+normalizeClearedValue = normalizeClearedRequestDtoValue) {
     const { debouncedTrigger, cancelDebounce } = useDebouncedTrigger(formContext.trigger, fieldName, DEBOUNCE_DELAY_MS);
     // Get autosave context (may be null if not within AutosaveProvider)
     const autosaveContext = useOptionalAutosave();
@@ -204,7 +263,17 @@ function useFieldValidation(formContext, fieldName, validationMode = ValidationM
      */
     const createChangeHandler = useCallback(
     // Note: <T,> syntax (trailing comma) is required in TSX to distinguish from JSX
-    (fieldOnChange) => (value) => {
+    (fieldOnChange) => (rawValue) => {
+        // FIELD-CLEARING CONTRACT — the single point where a control's "the user emptied me" gesture
+        // becomes the framework's one CLEARED representation (`null`).
+        //
+        // It belongs HERE, and nowhere else, because this is the only place a control's value reaches
+        // BOTH consumers below: react-hook-form's state (which validation, submit and section-save all
+        // read) and the autosave queue. Normalising in each control would repeat the rule per control;
+        // normalising at submit would run after validation has already rejected the empty string, and
+        // would miss autosave entirely; normalising only inside the validation schema is the shape of
+        // a long-standing Formik defect, where the schema validates a value the server never receives.
+        const value = (schema ? normalizeClearedValue(schema, rawValue) : rawValue);
         // Always call RHF's onChange to update value
         fieldOnChange(value);
         const fieldState = formContext.getFieldState(fieldName);
@@ -228,7 +297,7 @@ function useFieldValidation(formContext, fieldName, validationMode = ValidationM
         if (autosaveContext && autosaveTrigger === AutosaveTrigger.DEBOUNCE) {
             autosaveContext.triggerSave(fieldName, value, AutosaveTrigger.DEBOUNCE);
         }
-    }, [formContext, fieldName, validationMode, isTextField, debouncedTrigger, autosaveContext, autosaveTrigger]);
+    }, [formContext, fieldName, validationMode, isTextField, debouncedTrigger, autosaveContext, autosaveTrigger, schema, normalizeClearedValue]);
     return {
         createBlurHandler,
         createChangeHandler,
@@ -377,20 +446,60 @@ function resolveFieldSchema(rootSchema, path) {
  * Handles composite (object) and array schemas by delegating to
  * specialized components.
  */
-function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description: descriptionProp, tooltip: tooltipProp, enumLabels: enumLabelsProp, as, validationMode, disabled: disabledProp, readOnly: readOnlyProp, className, placeholder, type, autoComplete, renderField, fileUploadContext: fileUploadContextProp, autoFocus: autoFocusProp, excludedChildKeys, quickCreateSourceFieldName, }) {
+function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description: descriptionProp, tooltip: tooltipProp, labelPlacement, hideLabel, hideDescription, controlSize, respectSurfaceErrorPlacement, enumLabels: enumLabelsProp, as, validationMode, disabled: disabledProp, readOnly: readOnlyProp, className, placeholder, type, renderField, sectionAppearance, objectItemLayout, fileUploadContext: fileUploadContextProp, autoFocus: autoFocusProp, excludedChildKeys, quickCreateSourceFieldName, }) {
     const formContext = useFormContext();
     const schemaContext = useFormSchemaContext();
+    const surfacePolicy = useSurfacePolicy();
     const { registry } = useResourceRegistry();
     const { t, tErrorValidation, isReady } = useI18n({ keys: ['errors_validation'] });
     const ctx = useOptionalFormTemplateContext();
-    const { pathPrefix } = useFieldScope();
     const resolvedName = useResolvedFieldName(name);
     useWizardFieldRegistration(resolvedName);
     useSectionFieldRegistration(resolvedName);
+    // Fields INSIDE a field-array item must NOT use `shouldUnregister` (RHF array paths carry a
+    // numeric index segment, e.g. `checklist.0.label` or `tags.0`). `useFieldArray` + per-field
+    // `shouldUnregister:true` is a documented RHF antipattern: when a freshly-appended item's
+    // Controllers mount→unmount→mount (React StrictMode, dev), the unmount UNREGISTERS and DROPS
+    // the just-appended nested value — it isn't in the form's `defaultValues` the way
+    // pre-existing items are — so quick-add/append items silently lose their data before the
+    // whole-array autosave reads `getValues`. Top-level and nested-object fields keep
+    // `shouldUnregister:true` for variant/showWhen filtering. See array-element-authoring Step 4.
+    //
+    // Conditional exclusion for array-item sub-fields does NOT rely on this unmount path (it can't —
+    // see above). It is handled deterministically by the visibility-driven clear effect below
+    // (`isFieldHidden` → clear value), so a `showWhen`/discriminator-gated field INSIDE an array item
+    // is correctly dropped from the payload when hidden.
+    const shouldUnregisterField = !/\.\d+(\.|$)/.test(resolvedName);
     // Resolve props from FormTemplateContext when not explicitly provided.
     // Uses `resolvedName` (full path including ObjectScope prefix) for context lookups
     // because label/description dictionaries are keyed by full schema path.
     const schema = schemaProp ?? resolveFieldSchema(ctx?.schema, resolvedName);
+    // RESIDUAL "name → label" FLASH (progressive-form-skeleton-rendering plan).
+    // The `?? name` tail is a humanized field-name fallback. While the resource
+    // label bundle (`useResourceLabels`, keyed `resources.<type>.fields.*`) is
+    // still loading, `ctx.fieldLabels[resolvedName]` is absent, so the field shows
+    // e.g. "email" for a beat and then swaps to "Email address" — a small text +
+    // minor-width change (no big reflow).
+    //
+    // Likely INVISIBLE in production: there the resource bundle and the form's
+    // other bundles micro-batch together (16ms), so labels are usually resolved by
+    // the time `AutomatedForm` drops its loading skeleton and this renders. The DEV
+    // immediate-flush (one fetch per request) exaggerates it — so judge visibility
+    // from a prod-like build, not dev.
+    //
+    // We deliberately do NOT gate the whole form on the resource bundle: that was
+    // tried and reverted (broke AutomatedForm.integration; risks a never-resolving
+    // skeleton if a resource bundle never loads — a worse failure than a brief
+    // flash). See `AutomatedForm`'s skeleton gate.
+    //
+    // CLEAN FIX IF IT PROVES VISIBLE — verify first, then do it at THIS leaf (a
+    // single label briefly in skeleton degrades gracefully; a whole form does not):
+    //   1. `useResourceLabels` already returns `isReady` (exported for this).
+    //   2. Thread it as `labelsReady` onto `FormTemplateContextValue` (set in
+    //      `AutomatedForm`'s `formTemplateContextValue`).
+    //   3. Here, compute `labelLoading = !labelProp && ctx != null && !ctx.labelsReady`
+    //      and render the label via `<SkeletonText loading={labelLoading} …>` in
+    //      `FormFieldChrome` instead of the raw `name` fallback.
     const label = labelProp ?? ctx?.fieldLabels?.[resolvedName] ?? name;
     const description = descriptionProp ?? ctx?.fieldDescriptions?.[resolvedName];
     const tooltip = tooltipProp ?? ctx?.fieldTooltips?.[resolvedName];
@@ -406,8 +515,22 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     const isHiddenByUpstreamShaping = overrideElement == null &&
         fieldMatchesTemplateRule(resolvedName, upstreamHiddenRuleNames);
     const rawShowWhenParams = schema ? getShowWhenParams(schema) : undefined;
+    // Sibling scoping for showWhen conditions derives from the RESOLVED path's
+    // parent segment, NOT from the FieldScope pathPrefix alone. The two agree for
+    // skeleton scopes (ObjectScope 'address' + name 'city' → parent 'address'),
+    // but the automated renderers (FormFieldComposite, AutomatedArrayField) mount
+    // children with ABSOLUTE dotted names under an EMPTY scope — with
+    // pathPrefix-based scoping, `reminder.leadTimeMinutes` showWhen({field:'enabled'})
+    // watched root-level `enabled` (always undefined) and the field never appeared.
+    // Deriving the parent from `resolvedName` keeps the decorator's documented
+    // sibling semantics on every render path, including nested-object depths the
+    // prefix cannot see (name 'geo.lat' under scope 'address' → sibling scope
+    // 'address.geo', not 'address').
+    const showWhenSiblingScope = resolvedName.includes('.')
+        ? resolvedName.slice(0, resolvedName.lastIndexOf('.'))
+        : '';
     const showWhenParams = rawShowWhenParams
-        ? scopeShowWhenParams(rawShowWhenParams, pathPrefix)
+        ? scopeShowWhenParams(rawShowWhenParams, showWhenSiblingScope)
         : undefined;
     const showWhenWatchFields = showWhenParams
         ? AutomatedLayoutFrontendUtils.getShowWhenWatchFields(showWhenParams)
@@ -471,14 +594,31 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     const resolvedReadOnly = readOnlyProp ?? ctx?.readOnly ?? (schema ? isNotEditableForOperation(schema, schemaContext.operationType) : false);
     // Create validation trigger handlers and autosave handlers
     // These wrap RHF's field handlers to add validation triggering and autosave
-    const { createBlurHandler, createChangeHandler, autosaveFieldState, autosaveError, handleRetrySave } = useFieldValidation(formContext, resolvedName, resolvedValidationMode, isTextField, schema);
-    // Resolve autoFocus: when inside AutomatedForm (FormTemplateContext present),
-    // autoFocus will be handled by FormLayout imperatively (TODO: F-10).
-    // When standalone, the prop/decorator flows through to the native attribute.
+    // FIELD-CLEARING CONTRACT — resolve, ONCE and here, which question "may this be cleared?" is.
+    // Only this component knows which KIND of schema the surrounding form validates, and the two
+    // kinds cannot be told apart by shape (see `FormSchemaKind`). Resolving it here and handing the
+    // controls a plain boolean is what stops three separate controls re-asking the request-DTO
+    // question of a schema that may be a MAIN schema — which silently made refined optional fields
+    // unclearable on inline-edit surfaces while plain optional strings kept working by accident.
+    const isMainSchemaForm = schemaContext?.schemaKind === FormSchemaKind.MAIN_SCHEMA;
+    const normalizeClearedValue = isMainSchemaForm
+        ? normalizeClearedMainSchemaValue
+        : normalizeClearedRequestDtoValue;
+    const fieldIsClearable = schema
+        ? (isMainSchemaForm ? mainSchemaFieldIsClearable(schema) : requestDtoFieldIsClearable(schema))
+        : false;
+    const { createBlurHandler, createChangeHandler, autosaveFieldState, autosaveError, handleRetrySave } = useFieldValidation(formContext, resolvedName, resolvedValidationMode, isTextField, schema, normalizeClearedValue);
+    // Resolve autoFocus: explicit props keep working even inside AutomatedForm so
+    // hand-authored templates can preserve intentional focus behavior. Only
+    // decorator-driven autoFocus stays suppressed there until FormLayout owns the
+    // broader "first focusable field" imperative strategy.
     const isInsideAutomatedForm = !!ctx;
-    const resolvedAutoFocus = isInsideAutomatedForm
-        ? undefined
-        : (autoFocusProp ?? fieldEditConfig?.autoFocus);
+    const resolvedAutoFocus = autoFocusProp ?? (isInsideAutomatedForm ? undefined : fieldEditConfig?.autoFocus);
+    const autoCompleteConfig = fieldEditConfig;
+    const resolvedAutoComplete = buildFormFieldAutoCompleteValue({
+        identifier: autoCompleteConfig?.autoComplete,
+        modifier: autoCompleteConfig?.autoCompleteModifier,
+    });
     // Required state: use schema optionality directly.
     // Visibility is enforced before render, so mounted fields reflect their
     // true required state from the schema.
@@ -511,10 +651,46 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     const fieldState = formContext.getFieldState(resolvedName, formContext.formState);
     const error = getFieldError(fieldState, formContext.formState.isSubmitted, resolvedValidationMode, tErrorValidation);
     // ── Chrome mode resolution cascade ──
-    // Phase 1: field {primitive}UI.edit.chromeMode → section default → form default → STACKED
+    // Phase 1: field {primitive}UI.edit.chromeMode → section default → form default → surface policy → STACKED
     // Phase 2 (viewport-based) happens inside FormFieldChrome
     const { formChromeMode, sectionChromeMode } = useFormChromeContext();
-    const resolvedChromeMode = fieldEditConfig?.chromeMode ?? sectionChromeMode ?? formChromeMode;
+    const surfaceChromeMode = resolveSurfaceFormChromeMode(surfacePolicy.autoRender?.autoFieldChrome);
+    const explicitChromeMode = fieldEditConfig?.chromeMode ?? sectionChromeMode ?? formChromeMode;
+    const resolvedChromeMode = explicitChromeMode ?? surfaceChromeMode;
+    const resolvedLabelPlacement = labelPlacement ?? resolveSurfaceAutoLabelPlacement(surfacePolicy.autoRender?.autoLabelPlacement);
+    const resolvedControlSize = controlSize ?? resolveSurfaceAutoFieldDensity(surfacePolicy.autoRender?.autoFieldDensity);
+    const hideInlineErrorForPolicy = respectSurfaceErrorPlacement !== false
+        && surfacePolicy.autoRender?.autoErrorPlacement === 'summary-at-surface-top';
+    // Whether this field is hidden by conditional visibility (upstream display shaping, `showWhen`,
+    // or a discriminated-union variant switch). Hoisted so the deterministic-exclusion effect below
+    // and the render early-return share ONE source of truth.
+    const isFieldHidden = !!schema
+        && (isHiddenByUpstreamShaping || !isVisibleByShowWhen || !isVisibleByDiscriminator);
+    // DETERMINISTIC conditional-field exclusion — driven by VISIBILITY, not the unmount lifecycle.
+    //
+    // When a field is hidden by its condition, its value must be excluded from the resource. Top-level
+    // fields get that for free: they unmount (early-return below) and `shouldUnregister:true` drops
+    // the value. But array-item sub-fields deliberately DON'T unregister (that would drop a
+    // freshly-appended item's value under React StrictMode — see `shouldUnregisterField` above), so
+    // for them the unmount path can't be the exclusion mechanism. Instead we clear the value the
+    // moment the field becomes hidden, so exclusion is driven by the condition itself. This makes a
+    // conditional field INSIDE an array item a first-class citizen — e.g. `checklist[i].advancedNote`
+    // shown only when `checklist[i].kind === 'advanced'`: flip `kind` back to a value that hides it,
+    // and its value is dropped from the whole-array autosave payload, exactly like a top-level field.
+    // (Guarded to array-item paths so top-level fields keep their existing unmount-based exclusion —
+    // a `setValue` on a field already unregistered by its unmount would spuriously re-register it.)
+    useEffect(() => {
+        if (isFieldHidden
+            && !shouldUnregisterField
+            && resolvedName
+            && formContext.getValues(resolvedName) !== undefined) {
+            // field-clearing: N/A — `undefined` is correct HERE and must not become the cleared
+            // sentinel. This excludes a hidden sub-field from an array ITEM, and the array is submitted
+            // WHOLESALE: an absent key on the item object is already exclusion. Writing `null` would
+            // instead persist an explicit "no value" into the item.
+            formContext.setValue(resolvedName, undefined, { shouldDirty: false, shouldValidate: false });
+        }
+    }, [isFieldHidden, shouldUnregisterField, resolvedName, formContext]);
     // Schema guard — if schema could not be resolved, the field is absent from the
     // current form schema (e.g., a conditionally omitted field like organizationName).
     // Return null so templates can render <FormField name="x" /> unconditionally
@@ -522,7 +698,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     if (!schema) {
         return null;
     }
-    if (isHiddenByUpstreamShaping || !isVisibleByShowWhen || !isVisibleByDiscriminator) {
+    if (isFieldHidden) {
         return null;
     }
     if (overrideElement != null) {
@@ -537,11 +713,12 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         label,
         description,
         tooltip,
+        labelPlacement: resolvedLabelPlacement,
         error,
         required: effectivelyRequired,
-        hideLabel: forceHide?.label,
-        hideDescription: forceHide?.description,
-        hideError: forceHide?.error,
+        hideLabel: hideLabel ?? forceHide?.label,
+        hideDescription: hideDescription ?? forceHide?.description,
+        hideError: forceHide?.error || hideInlineErrorForPolicy,
         saveState: autosaveFieldState,
         saveErrorMessage: autosaveError,
         onRetrySave: handleRetrySave,
@@ -552,12 +729,15 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     // Control props — passed to preset components (NO chrome data)
     const baseFieldProps = {
         schema,
+        // Resolved by the form, never re-derived by the control — see the resolution above.
+        clearable: fieldIsClearable,
         name: resolvedName,
         disabled,
         readOnly: resolvedReadOnly,
         validationMode: resolvedValidationMode,
         required: effectivelyRequired,
         autoFocus: resolvedAutoFocus || undefined, // Only pass true, not false (avoid unnecessary re-renders)
+        controlSize: resolvedControlSize,
     };
     const shouldHideRelationshipObjectField = Boolean(relationshipObjectFieldSemantics &&
         (relationshipObjectFieldSemantics.semantics.nature !== RelationshipNature.COMPOSITION ||
@@ -574,12 +754,15 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     if (isRangeSchemaType) {
         const rangeType = getRangeType(schema);
         const componentType = as ?? fieldEditConfig?.component ?? getDefaultRangeComponent(rangeType ?? RangeSchemaType.NUMBER);
-        return (_jsx(Controller, { name: resolvedName, control: formContext.control, shouldUnregister: true, render: ({ field }) => {
+        return (_jsx(Controller, { name: resolvedName, control: formContext.control, shouldUnregister: shouldUnregisterField, render: ({ field }) => {
                 const wrappedOnBlur = createBlurHandler(field.onBlur);
                 const wrappedOnChange = createChangeHandler(field.onChange);
                 const commonProps = {
                     ...baseFieldProps,
-                    value: field.value,
+                    // Range controls take the same inbound treatment as every other control — this branch
+                    // owns its own `Controller` rather than going through `renderControlled`, so the guard
+                    // has to be applied here too or a cleared range renders `null`.
+                    value: toRenderableFieldValue(field.value),
                     onBlur: wrappedOnBlur,
                 };
                 // Lookup map for component → element factory (avoids repetitive switch/if)
@@ -621,7 +804,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         if (shouldHideRelationshipObjectField) {
             return null;
         }
-        return (_jsx(FormFieldComposite, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, renderField: renderField, excludedChildKeys: excludedChildKeys }));
+        return (_jsx(FormFieldComposite, { name: resolvedName, schema: schema, label: label, hideLabel: hideLabel, description: description, disabled: disabled, className: className, renderField: renderField, excludedChildKeys: excludedChildKeys }));
     }
     // Handle record types (dynamic string keys)
     if (schemaType === FieldSchemaType.RECORD) {
@@ -642,7 +825,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         if (shouldHideRelationshipObjectField) {
             return null;
         }
-        return (_jsx(FormFieldArray, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, renderField: renderField }));
+        return (_jsx(AutomatedArrayField, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, renderField: renderField, sectionAppearance: sectionAppearance, objectItemLayout: objectItemLayout }));
     }
     // =========================================================================
     // FIELD RENDERING - Dispatch by schema type
@@ -654,9 +837,13 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
      * Passes field.ref so RHF focus features (setFocus, scroll to first error) work.
      * Note: ref is cast to satisfy each form field's specific ref type (input/button/div).
      */
-    function renderControlled(render) {
-        return (_jsx(Controller, { name: resolvedName, control: formContext.control, shouldUnregister: true, render: ({ field }) => (_jsx(FormFieldChrome, { ...chromeProps, children: render({
-                    value: field.value,
+    function renderControlled(render, 
+    // Per-field chrome overrides (e.g. force STACKED for intrinsically-wide controls
+    // like the file uploader — see the FILE branch). Spread AFTER chromeProps so the
+    // override wins.
+    chromeOverrides) {
+        return (_jsx(Controller, { name: resolvedName, control: formContext.control, shouldUnregister: shouldUnregisterField, render: ({ field }) => (_jsx(FormFieldChrome, { ...chromeProps, ...chromeOverrides, children: render({
+                    value: toRenderableFieldValue(field.value),
                     onChange: createChangeHandler(field.onChange),
                     onBlur: createBlurHandler(field.onBlur),
                     ref: field.ref,
@@ -671,7 +858,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         switch (resolvedAs) {
             case FormFieldComponent.INPUT:
             case FormFieldComponent.TEXTAREA:
-                return renderControlled(field => (_jsx(FormFieldString, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder, autoComplete: autoComplete })));
+                return renderControlled(field => (_jsx(FormFieldString, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder, autoComplete: resolvedAutoComplete, type: type })));
             case FormFieldComponent.SLIDER:
                 return renderControlled(field => (_jsx(FormFieldNumber, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder })));
             case FormFieldComponent.CHECKBOX:
@@ -702,7 +889,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         return renderControlled(field => (_jsx(FormFieldDuration, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
     }
     if (schemaType === FieldSchemaType.PHONE) {
-        return renderControlled(field => (_jsx(FormFieldPhone, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder })));
+        return renderControlled(field => (_jsx(FormFieldPhone, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder, autoComplete: resolvedAutoComplete })));
     }
     if (schemaType === FieldSchemaType.BIGDECIMAL) {
         return renderControlled(field => (_jsx(FormFieldBigDecimal, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
@@ -713,15 +900,29 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
     if (schemaType === FieldSchemaType.FILE) {
         const fileContextKey = AutomatedLayoutFrontendUtils.normalizeSchemaFieldPath(resolvedName);
         const fileEndpoints = fileUploadContext?.[fileContextKey];
-        if (hasActionableFileEndpoints(fileEndpoints)) {
-            return renderControlled(field => (_jsx(FormFieldFile, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, endpoints: fileEndpoints, onValidationError: handleFileValidationError })));
+        const isGeneratedPdfFileField = isTemplatableFileField(schema);
+        if (!isGeneratedPdfFileField && hasActionableFileEndpoints(fileEndpoints)) {
+            // File uploaders are intrinsically wide/tall (drop zone, filename row, image
+            // preview) and do not fit the narrow SETTINGS_ROW right column (w-72).
+            // `wideControl` keeps the field a real settings-list row (inset, rhythm,
+            // divider, flush stacking) with the uploader spanning the full row width
+            // beneath the label; in STACKED contexts it is inert. (Previously this
+            // forced `mode: STACKED`, which dropped the row shell entirely — the field
+            // lost the list's `px-card` label inset and broke the flush divided list.)
+            return renderControlled(field => (_jsx(FormFieldFile, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, endpoints: fileEndpoints, onValidationError: handleFileValidationError })), { wideControl: true });
         }
         // Fail closed when upload endpoints are unavailable. File fields should not
         // degrade into manual file-id entry because that bypasses the secure upload
         // contract and encourages invalid metadata writes. Keep the UI truthful when
         // the form already holds a linked file value instead of rendering a fake
         // empty field that still submits hidden attachment state.
-        return renderControlled(field => (_jsx(Input, { ...baseFieldProps, value: getUnavailableFileFieldDisplayValue(field.value, t), onChange: () => undefined, onBlur: field.onBlur, ref: field.ref, placeholder: t('File uploads unavailable') ?? 'File uploads unavailable', type: "text", readOnly: true, disabled: true })));
+        const unavailableFilePlaceholder = isGeneratedPdfFileField
+            ? t('Generated PDF fields are read-only') ?? 'Generated PDF fields are read-only'
+            : t('File uploads unavailable') ?? 'File uploads unavailable';
+        if (isGeneratedPdfFileField) {
+            return (_jsx(FormFieldChrome, { ...chromeProps, children: _jsx(Input, { ...baseFieldProps, value: getUnavailableFileFieldDisplayValue(formContext.getValues(resolvedName), t), onChange: () => undefined, placeholder: unavailableFilePlaceholder, type: "text", readOnly: true, disabled: true }) }));
+        }
+        return renderControlled(field => (_jsx(FormFieldChrome, { ...chromeProps, children: _jsx(Input, { ...baseFieldProps, value: getUnavailableFileFieldDisplayValue(field.value, t), onChange: () => undefined, onBlur: field.onBlur, ref: field.ref, placeholder: unavailableFilePlaceholder, type: "text", readOnly: true, disabled: true }) })));
     }
     // --- Foreign key (check before primitives — FK decorated strings) ---
     if (isForeignKey(schema)) {
@@ -732,7 +933,7 @@ function FormFieldImpl({ name, schema: schemaProp, label: labelProp, description
         return renderControlled(field => (_jsx(FormFieldBoolean, { ...baseFieldProps, checked: field.value, onCheckedChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
     }
     if (schemaType === FieldSchemaType.STRING) {
-        return renderControlled(field => (_jsx(FormFieldString, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder, autoComplete: autoComplete })));
+        return renderControlled(field => (_jsx(FormFieldString, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder, autoComplete: resolvedAutoComplete, type: type })));
     }
     if (schemaType === FieldSchemaType.NUMBER || schemaType === FieldSchemaType.BIGINT) {
         return renderControlled(field => (_jsx(FormFieldNumber, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder })));
@@ -768,4 +969,4 @@ function buildOptions(schema, enumLabels) {
         label: enumLabels?.[value] ?? value,
     }));
 }
-//# sourceMappingURL=FormField.js.map
+//# sourceMappingURL=FormField.js.map