@wildo-ai/saas-frontend-lib 1.0.1

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

@@ -0,0 +1,771 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * FormField Component
+ *
+ * Smart form field that auto-detects schema type and renders
+ * the appropriate input component.
+ *
+ * Priority for component selection:
+ * 1. Explicit `as` prop
+ * 2. Schema decorator (FormComponent)
+ * 3. Auto-detection from schema type
+ *
+ * ## Validation Trigger Logic
+ *
+ * FormField controls when validation is triggered based on `validationMode`:
+ * - `onBlur`: Validates when field loses focus (default for text fields)
+ * - `onChange`: Validates on every change, debounced for text fields (300ms)
+ * - `onSubmit`: No field-level validation, only on form submit
+ *
+ * The RHF form-level mode sets the baseline, but FormField can override
+ * with per-field `validationMode` prop or via `{primitive}UI({ edit: { validationMode } })`.
+ *
+ * Touch state: Errors are only shown after a field is touched (blur) or
+ * after form submit attempt. This prevents showing errors on initial render.
+ */
+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 { AutomatedLayoutFrontendUtils } from '../../../core/automated-layout/automated-layout.frontend.utils.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 { 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 { Input } from '../../../components/form/controls/input.js';
+import { FormFieldDate } from '../fields/form-field-date.js';
+import { FormFieldDateTime } from '../fields/form-field-datetime.js';
+import { FormFieldTime } from '../fields/form-field-time.js';
+import { FormFieldRangeNumber } from '../fields/form-field-range-number.js';
+import { FormFieldRangeDate } from '../fields/form-field-range-date.js';
+import { FormFieldRangeDateTime } from '../fields/form-field-range-datetime.js';
+import { FormFieldRangeTime } from '../fields/form-field-range-time.js';
+// Field, FieldLabel, FieldDescription no longer used here — chrome is handled by FormFieldChrome
+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 { 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)
+import { FormFieldBoolean } from '../fields/form-field-boolean.js';
+import { FormFieldString } from '../fields/form-field-string.js';
+import { FormFieldNumber } from '../fields/form-field-number.js';
+import { FormFieldEnum } from '../fields/form-field-enum.js';
+import { FormFieldMoney } from '../fields/form-field-money.js';
+import { FormFieldDuration } from '../fields/form-field-duration.js';
+import { FormFieldPhone } from '../fields/form-field-phone.js';
+import { FormFieldBigDecimal } from '../fields/form-field-bigdecimal.js';
+import { FormFieldCode } from '../fields/form-field-code.js';
+import { FormFieldRangeBigDecimal } from '../fields/form-field-range-bigdecimal.js';
+import { FormFieldRangeMoney } from '../fields/form-field-range-money.js';
+// Import FK edit field component
+// 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';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+import { getFieldError, FILE_VALIDATION_ERROR_TYPE } from '../validation-errors/getFieldError.js';
+// =============================================================================
+// VALIDATION TRIGGER HOOKS
+// =============================================================================
+/**
+ * Default debounce delay for onChange validation on text fields.
+ * This prevents excessive validation during typing.
+ * Renamed for clarity.
+ */
+const DEBOUNCE_DELAY_MS = 300;
+/**
+ * Hook to create debounced validation trigger.
+ * Used for onChange validation mode on text fields to avoid
+ * validating on every keystroke.
+ *
+ * @param trigger - RHF trigger function
+ * @param fieldName - Field name to trigger validation for
+ * @param debounceMs - Debounce delay in milliseconds
+ * @returns Debounced trigger function
+ */
+function useDebouncedTrigger(trigger, fieldName, debounceMs = DEBOUNCE_DELAY_MS) {
+    const timeoutRef = useRef(null);
+    // Clear timeout on unmount
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    const cancelDebounce = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+    }, []);
+    const debouncedTrigger = useCallback(() => {
+        // Clear any existing timeout
+        cancelDebounce();
+        // Schedule new validation trigger
+        timeoutRef.current = setTimeout(() => {
+            trigger(fieldName);
+        }, debounceMs);
+    }, [trigger, fieldName, debounceMs, cancelDebounce]);
+    return { debouncedTrigger, cancelDebounce };
+}
+function hasActionableFileEndpoints(endpoints) {
+    return !!(endpoints?.upload || endpoints?.override);
+}
+/**
+ * Hook to create field validation handlers with proper trigger logic.
+ *
+ * Wraps RHF's field handlers to add validation triggering based on
+ * the configured validation mode:
+ * - onBlur: Triggers validation when field loses focus
+ * - onChange: Triggers validation on value change (debounced for text)
+ * - onSubmit: No field-level trigger (form-level only)
+ *
+ * Also handles autosave triggering based on field decorator or context config.
+ *
+ * @param formContext - RHF form context
+ * @param fieldName - Field name for validation
+ * @param validationMode - When to trigger validation
+ * @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) {
+    const { debouncedTrigger, cancelDebounce } = useDebouncedTrigger(formContext.trigger, fieldName, DEBOUNCE_DELAY_MS);
+    // Get autosave context (may be null if not within AutosaveProvider)
+    const autosaveContext = useOptionalAutosave();
+    const fieldEditConfig = schema ? getFieldUIEditConfig(schema) : undefined;
+    const autosaveConfig = fieldEditConfig?.autosave;
+    // Resolve autosave trigger mode
+    const autosaveTrigger = resolveAutosaveTrigger(autosaveConfig, autosaveContext?.config.defaultTrigger, isTextField);
+    // Get autosave field state info for UI indicator
+    const autosaveStateInfo = autosaveContext?.getFieldStateInfo(fieldName);
+    const autosaveFieldState = autosaveStateInfo?.state ?? AutosaveFieldState.IDLE;
+    const autosaveError = autosaveStateInfo?.lastError;
+    const handleRetrySave = useCallback(() => {
+        autosaveContext?.retryFieldSave?.(fieldName);
+    }, [autosaveContext, fieldName]);
+    // Uniqueness pre-validation on blur (only active when validateFieldUrl is in form context
+    // and the field has the isUnique() decorator)
+    const { validateUniqueness } = useFieldUniquenessValidation({ fieldName, fieldSchema: schema });
+    /**
+     * Wrap onBlur to trigger validation in onBlur mode.
+     * This ensures validation runs when user leaves the field.
+     *
+     * EDGE CASE: For onChange mode with text fields, we cancel any pending
+     * debounced trigger and validate immediately on blur for responsive UX.
+     *
+     * Also triggers autosave for 'blur' trigger mode.
+     * Also triggers uniqueness pre-validation for fields with isUnique() decorator.
+     */
+    const createBlurHandler = useCallback((fieldOnBlur) => () => {
+        // Always call RHF's onBlur to mark field as touched
+        fieldOnBlur();
+        // Cancel any pending debounced validation to avoid double trigger
+        cancelDebounce();
+        // Trigger validation based on mode
+        if (validationMode === 'onBlur' || validationMode === 'onTouched') {
+            formContext.trigger(fieldName);
+        }
+        else if (validationMode === 'onChange' && isTextField) {
+            // onChange mode with text field: validate immediately on blur
+            // (user left field, so give immediate feedback instead of waiting)
+            formContext.trigger(fieldName);
+        }
+        // onSubmit mode: no field-level trigger
+        // Trigger autosave on blur if configured
+        if (autosaveContext && autosaveTrigger === AutosaveTrigger.BLUR) {
+            const fieldValue = formContext.getValues(fieldName);
+            autosaveContext.triggerSave(fieldName, fieldValue, AutosaveTrigger.BLUR);
+        }
+        // Trigger uniqueness pre-validation on blur (fire-and-forget async)
+        // The hook internally guards against no-op cases (no decorator, no URL, empty value)
+        validateUniqueness();
+    }, [formContext, fieldName, validationMode, isTextField, cancelDebounce, autosaveContext, autosaveTrigger, validateUniqueness]);
+    /**
+     * Wrap onChange to trigger validation in onChange mode.
+     * Uses debounce for text fields to avoid excessive validation.
+     *
+     * Also triggers re-validation in onBlur mode when the field already has an
+     * error — this clears the error as soon as the user corrects the value,
+     * without waiting for the next blur event (better UX).
+     *
+     * Also triggers autosave for 'debounce' trigger mode.
+     */
+    const createChangeHandler = useCallback(
+    // Note: <T,> syntax (trailing comma) is required in TSX to distinguish from JSX
+    (fieldOnChange) => (value) => {
+        // Always call RHF's onChange to update value
+        fieldOnChange(value);
+        const fieldState = formContext.getFieldState(fieldName);
+        const shouldTrigger = validationMode === 'onChange' ||
+            // onTouched: validate on change once the field has been touched (blurred at least once)
+            (validationMode === 'onTouched' && fieldState.isTouched) ||
+            // onBlur: re-validate on change only when the field already has an error
+            (validationMode === 'onBlur' && !!fieldState.error);
+        if (shouldTrigger) {
+            if (isTextField) {
+                // Use debounced trigger for text fields
+                debouncedTrigger();
+            }
+            else {
+                // Immediate trigger for non-text fields (select, checkbox, etc.)
+                formContext.trigger(fieldName);
+            }
+        }
+        // Trigger autosave on change if configured for debounce mode
+        // The AutosaveContext handles debouncing internally
+        if (autosaveContext && autosaveTrigger === AutosaveTrigger.DEBOUNCE) {
+            autosaveContext.triggerSave(fieldName, value, AutosaveTrigger.DEBOUNCE);
+        }
+    }, [formContext, fieldName, validationMode, isTextField, debouncedTrigger, autosaveContext, autosaveTrigger]);
+    return {
+        createBlurHandler,
+        createChangeHandler,
+        autosaveFieldState,
+        autosaveError,
+        handleRetrySave,
+    };
+}
+/**
+ * Resolve autosave trigger mode from field schema or context default.
+ *
+ * @param autosaveConfig - Autosave config from decorator (true = default, object = custom, undefined = inherit)
+ * @param contextDefaultTrigger - Default trigger from AutosaveContext
+ * @param isTextField - Whether this is a text field (affects default behavior)
+ * @returns The resolved trigger mode
+ */
+function resolveAutosaveTrigger(autosaveConfig, contextDefaultTrigger = AutosaveTrigger.DEBOUNCE, isTextField = false) {
+    // No autosave config on field - use context default
+    if (autosaveConfig === undefined) {
+        return contextDefaultTrigger;
+    }
+    // True = default (use context default or debounce for text, blur for others)
+    if (autosaveConfig === true) {
+        return isTextField ? AutosaveTrigger.DEBOUNCE : AutosaveTrigger.BLUR;
+    }
+    // Object config
+    if (typeof autosaveConfig === 'object') {
+        // Check if explicitly disabled via enabled: false
+        if (autosaveConfig.enabled === false) {
+            return AutosaveTrigger.NONE;
+        }
+        // Use explicit trigger or trigger: 'none' to disable
+        if (autosaveConfig.trigger) {
+            return autosaveConfig.trigger;
+        }
+        // Default based on field type
+        return isTextField ? AutosaveTrigger.DEBOUNCE : AutosaveTrigger.BLUR;
+    }
+    return contextDefaultTrigger;
+}
+function hasUnavailableFileAttachmentValue(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    if (typeof candidate.fileId === 'string' && candidate.fileId.trim() !== '') {
+        return true;
+    }
+    return Array.isArray(candidate.fileIds)
+        && candidate.fileIds.some(fileId => typeof fileId === 'string' && fileId.trim() !== '');
+}
+function getUnavailableFileFieldDisplayValue(value, t) {
+    if (!hasUnavailableFileAttachmentValue(value)) {
+        return '';
+    }
+    const candidate = value;
+    const fileCount = Array.isArray(candidate.fileIds)
+        ? candidate.fileIds.filter(fileId => typeof fileId === 'string' && fileId.trim() !== '').length
+        : 0;
+    return fileCount > 1
+        ? (t(`${fileCount} files attached`, { count: fileCount }) ?? `${fileCount} files attached`)
+        : (t('File attached') ?? 'File attached');
+}
+/**
+ * Resolve validation mode using hierarchy.
+ *
+ * Hierarchy (highest priority first):
+ * 1. {primitive}UI.edit.validationMode (field-level via decorator)
+ * 2. Field prop: <FormField validationMode="onBlur" />
+ * 3. Form-level config: <Form validationMode="onBlur"> (from FormSchemaContext)
+ * 4. Type default: based on field type (text→onBlur, select→onChange, etc.)
+ *
+ * @param schema - Zod schema to check for UI decorator
+ * @param fieldProp - validationMode prop passed to FormField
+ * @param formLevelMode - validationMode from FormSchemaContext
+ * @param schemaType - Field schema type for type-based default
+ * @returns Resolved ValidationMode
+ */
+function resolveValidationMode(schema, fieldProp, formLevelMode, schemaType) {
+    // 1. Check {primitive}UI.edit.validationMode (highest priority)
+    const decoratorMode = getFieldUIEditConfig(schema)?.validationMode;
+    if (decoratorMode) {
+        return decoratorMode;
+    }
+    // 2. Check field prop
+    if (fieldProp) {
+        return fieldProp;
+    }
+    // 3. Form-level config from FormSchemaContext
+    if (formLevelMode) {
+        return formLevelMode;
+    }
+    // 4. Type-based default
+    return AutomatedLayoutFrontendUtils.getDefaultValidationMode(schemaType);
+}
+/**
+ * Detect if a string schema should render as a textarea (long text)
+ * Internal helper - not exported for Fast Refresh compatibility
+ */
+function isLongText(schema) {
+    const schemaType = getSchemaType(schema);
+    if (schemaType !== FieldSchemaType.STRING)
+        return false;
+    // Formatted strings (email, url, etc.) are never long text
+    const format = getStringFormat(schema);
+    if (format)
+        return false;
+    const constraints = getStringConstraints(schema);
+    // Only consider it long text if maxLength is explicitly > 100
+    // If no constraint, assume short text for better UX
+    return constraints.maxLength !== undefined && constraints.maxLength > 100;
+}
+function fieldMatchesTemplateRule(fieldName, rules) {
+    return rules.some((rule) => (fieldName === rule ||
+        fieldName.startsWith(`${rule}.`) ||
+        fieldName.startsWith(`${rule}[`)));
+}
+function scopeShowWhenParams(params, parentPathPrefix) {
+    if (!parentPathPrefix) {
+        return params;
+    }
+    const conditions = Array.isArray(params.conditions)
+        ? params.conditions
+        : [params.conditions];
+    return {
+        ...params,
+        conditions: conditions.map((condition) => ({
+            ...condition,
+            field: condition.field.includes('.') || condition.field.includes('[')
+                ? condition.field
+                : `${parentPathPrefix}.${condition.field}`,
+        })),
+    };
+}
+/**
+ * Resolve a field's schema by walking the root form schema along a dotted path.
+ * Used by the name-only FormField mode (schema resolved from FormTemplateContext).
+ */
+function resolveFieldSchema(rootSchema, path) {
+    return AutomatedLayoutFrontendUtils.resolveFieldSchemaPath(rootSchema, path);
+}
+/**
+ * Smart FormField component
+ *
+ * Auto-detects schema type and renders appropriate component.
+ * 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, }) {
+    const formContext = useFormContext();
+    const schemaContext = useFormSchemaContext();
+    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);
+    // 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);
+    const label = labelProp ?? ctx?.fieldLabels?.[resolvedName] ?? name;
+    const description = descriptionProp ?? ctx?.fieldDescriptions?.[resolvedName];
+    const tooltip = tooltipProp ?? ctx?.fieldTooltips?.[resolvedName];
+    const enumLabels = enumLabelsProp ?? ctx?.enumLabels?.[resolvedName];
+    const disabled = disabledProp ?? ctx?.disabled;
+    const fileUploadContext = fileUploadContextProp ?? ctx?.fileUploadContext;
+    const overrideElement = ctx?.generatedFieldOverrides?.[resolvedName];
+    const upstreamHiddenRuleNames = [
+        ...Object.keys(ctx?.contextFieldValues ?? {}),
+        ...(ctx?.hiddenFieldNames ?? []),
+        ...Object.keys(ctx?.generatedFieldOverrides ?? {}),
+    ];
+    const isHiddenByUpstreamShaping = overrideElement == null &&
+        fieldMatchesTemplateRule(resolvedName, upstreamHiddenRuleNames);
+    const rawShowWhenParams = schema ? getShowWhenParams(schema) : undefined;
+    const showWhenParams = rawShowWhenParams
+        ? scopeShowWhenParams(rawShowWhenParams, pathPrefix)
+        : undefined;
+    const showWhenWatchFields = showWhenParams
+        ? AutomatedLayoutFrontendUtils.getShowWhenWatchFields(showWhenParams)
+        : [];
+    const showWhenWatchedValues = useWatch({ name: showWhenWatchFields.length > 0 ? showWhenWatchFields : [] });
+    const showWhenWatchValuesArray = Array.isArray(showWhenWatchedValues)
+        ? showWhenWatchedValues
+        : (showWhenWatchFields.length > 0 ? [showWhenWatchedValues] : []);
+    const discriminatorWatchNames = ctx?.inheritanceConfig?.discriminatorField
+        ? [ctx.inheritanceConfig.discriminatorField]
+        : [];
+    const discriminatorWatchValues = useWatch({ name: discriminatorWatchNames });
+    const activeDiscriminatorValue = Array.isArray(discriminatorWatchValues)
+        ? discriminatorWatchValues[0]
+        : discriminatorWatchValues;
+    const rootFieldName = resolvedName.match(/^[^.[\]]+/)?.[0] ?? resolvedName;
+    const isVisibleByShowWhen = useMemo(() => {
+        if (!showWhenParams) {
+            return true;
+        }
+        const showWhenData = Object.fromEntries(showWhenWatchFields.map((fieldName, index) => [fieldName, showWhenWatchValuesArray[index]]));
+        return AutomatedLayoutFrontendUtils.evaluateShowWhen(showWhenParams, showWhenData);
+    }, [showWhenParams, showWhenWatchFields, showWhenWatchValuesArray]);
+    const isVisibleByDiscriminator = useMemo(() => {
+        if (!ctx?.inheritanceConfig?.discriminatorField) {
+            return true;
+        }
+        return AutomatedLayoutFrontendUtils.computeFieldVisibility(ctx.schema, rootFieldName, {
+            [ctx.inheritanceConfig.discriminatorField]: activeDiscriminatorValue,
+        }, ctx.inheritanceConfig);
+    }, [activeDiscriminatorValue, ctx?.inheritanceConfig, ctx?.schema, rootFieldName]);
+    // Get schema type (guard for missing schema — all hooks must be called before early return)
+    const schemaType = schema ? getSchemaType(schema) : FieldSchemaType.STRING;
+    const fieldEditConfig = schema ? getFieldUIEditConfig(schema) : undefined;
+    const relationshipObjectFieldSemantics = useMemo(() => {
+        if (!schema ||
+            !schemaContext.resourceType ||
+            (schemaType !== FieldSchemaType.OBJECT && schemaType !== FieldSchemaType.ARRAY)) {
+            return undefined;
+        }
+        return resolveRelationshipWriteSurface({
+            resourceType: schemaContext.resourceType,
+            fieldName: resolvedName,
+            operationType: schemaContext.operationType,
+            registry,
+        });
+    }, [schema, schemaContext.operationType, schemaContext.resourceType, resolvedName, registry, schemaType]);
+    // Determine if this is a text field (needs debounced onChange validation)
+    // Include numeric types that render as text inputs
+    const isTextField = schemaType === FieldSchemaType.STRING ||
+        schemaType === FieldSchemaType.CODE ||
+        schemaType === FieldSchemaType.NUMBER ||
+        schemaType === FieldSchemaType.BIGINT ||
+        schemaType === FieldSchemaType.MONEY ||
+        schemaType === FieldSchemaType.BIGDECIMAL;
+    // Resolve validation mode using hierarchy (decorator → prop → form → default)
+    const resolvedValidationMode = schema
+        ? resolveValidationMode(schema, validationMode, schemaContext.validationMode, schemaType)
+        : (validationMode ?? schemaContext.validationMode ?? ValidationMode.ON_BLUR);
+    // Resolve readOnly: prop > context > schema decorator (operation-aware)
+    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.
+    const isInsideAutomatedForm = !!ctx;
+    const resolvedAutoFocus = isInsideAutomatedForm
+        ? undefined
+        : (autoFocusProp ?? fieldEditConfig?.autoFocus);
+    // Required state: use schema optionality directly.
+    // Visibility is enforced before render, so mounted fields reflect their
+    // true required state from the schema.
+    const effectivelyRequired = useMemo(() => {
+        if (!schema)
+            return false;
+        return !isOptional(schema);
+    }, [schema]);
+    // Handler for file component internal validation errors
+    // Syncs file-specific validation (MIME type, size) with RHF's error state
+    // This ensures formState.isValid correctly reflects file validation state
+    const handleFileValidationError = useCallback((fileError) => {
+        if (fileError) {
+            formContext.setError(resolvedName, {
+                type: FILE_VALIDATION_ERROR_TYPE,
+                message: fileError
+            });
+        }
+        else {
+            const currentError = formContext.getFieldState(resolvedName, formContext.formState).error;
+            if (currentError?.type === FILE_VALIDATION_ERROR_TYPE) {
+                formContext.clearErrors(resolvedName);
+            }
+        }
+    }, [formContext, resolvedName]);
+    // =========================================================================
+    // CHROME & BASE FIELD PROPS — must be defined before any early returns
+    // =========================================================================
+    // Shared field state for error display
+    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 2 (viewport-based) happens inside FormFieldChrome
+    const { formChromeMode, sectionChromeMode } = useFormChromeContext();
+    const resolvedChromeMode = fieldEditConfig?.chromeMode ?? sectionChromeMode ?? formChromeMode;
+    // 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
+    // and let the schema determine what's actually shown.
+    if (!schema) {
+        return null;
+    }
+    if (isHiddenByUpstreamShaping || !isVisibleByShowWhen || !isVisibleByDiscriminator) {
+        return null;
+    }
+    if (overrideElement != null) {
+        return _jsx(_Fragment, { children: overrideElement });
+    }
+    // Chrome props — consumed exclusively by FormFieldChrome wrapper
+    // forceHide: in the non-responsive case, it's a plain ForceHideConfig object.
+    // Per-breakpoint resolution (ResponsiveAware) is handled downstream by FormFieldChrome.
+    const forceHide = fieldEditConfig?.forceHide;
+    const chromeProps = {
+        mode: resolvedChromeMode,
+        label,
+        description,
+        tooltip,
+        error,
+        required: effectivelyRequired,
+        hideLabel: forceHide?.label,
+        hideDescription: forceHide?.description,
+        hideError: forceHide?.error,
+        saveState: autosaveFieldState,
+        saveErrorMessage: autosaveError,
+        onRetrySave: handleRetrySave,
+        fieldName: resolvedName,
+        disabled,
+        className,
+    };
+    // Control props — passed to preset components (NO chrome data)
+    const baseFieldProps = {
+        schema,
+        name: resolvedName,
+        disabled,
+        readOnly: resolvedReadOnly,
+        validationMode: resolvedValidationMode,
+        required: effectivelyRequired,
+        autoFocus: resolvedAutoFocus || undefined, // Only pass true, not false (avoid unnecessary re-renders)
+    };
+    const shouldHideRelationshipObjectField = Boolean(relationshipObjectFieldSemantics &&
+        (relationshipObjectFieldSemantics.semantics.nature !== RelationshipNature.COMPOSITION ||
+            !relationshipObjectFieldSemantics.nestedMutationConfig));
+    // Handle RANGE types (z_range schemas) - BEFORE object check
+    // Range schemas are z.object({from, to}) but with SCHEMA_METADATA.rangeConfig
+    // Check for all range schema types including specialized ones
+    const isRangeSchemaType = schemaType === FieldSchemaType.RANGE_NUMBER ||
+        schemaType === FieldSchemaType.RANGE_DATE ||
+        schemaType === FieldSchemaType.RANGE_DATETIME ||
+        schemaType === FieldSchemaType.RANGE_TIME ||
+        schemaType === FieldSchemaType.RANGE_BIGDECIMAL ||
+        schemaType === FieldSchemaType.RANGE_MONEY;
+    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 }) => {
+                const wrappedOnBlur = createBlurHandler(field.onBlur);
+                const wrappedOnChange = createChangeHandler(field.onChange);
+                const commonProps = {
+                    ...baseFieldProps,
+                    value: field.value,
+                    onBlur: wrappedOnBlur,
+                };
+                // Lookup map for component → element factory (avoids repetitive switch/if)
+                const rangeElement = (() => {
+                    // RHF field.ref is Ref<unknown>; cast for range components with varying ref types (Ref is invariant)
+                    const ref = field.ref;
+                    switch (componentType) {
+                        case FormFieldComponent.RANGE_SLIDER:
+                            return _jsx(RangeSlider, { ...commonProps, onValueChange: wrappedOnChange, ref: ref });
+                        case FormFieldComponent.DATE_RANGE:
+                            return _jsx(FormFieldRangeDate, { ...commonProps, onChange: wrappedOnChange, ref: ref });
+                        case FormFieldComponent.DATETIME_RANGE:
+                            return _jsx(FormFieldRangeDateTime, { ...commonProps, onChange: wrappedOnChange, ref: ref });
+                        case FormFieldComponent.TIME_RANGE:
+                            return _jsx(FormFieldRangeTime, { ...commonProps, onChange: wrappedOnChange, ref: ref });
+                        case FormFieldComponent.BIGDECIMAL_RANGE:
+                            return _jsx(FormFieldRangeBigDecimal, { ...commonProps, onChange: wrappedOnChange, ref: ref });
+                        case FormFieldComponent.MONEY_RANGE:
+                            return _jsx(FormFieldRangeMoney, { ...commonProps, onChange: wrappedOnChange, ref: ref });
+                        default: {
+                            // Fallback based on schema type
+                            const fallbackMap = {
+                                [FieldSchemaType.RANGE_BIGDECIMAL]: _jsx(FormFieldRangeBigDecimal, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                                [FieldSchemaType.RANGE_MONEY]: _jsx(FormFieldRangeMoney, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                                [FieldSchemaType.RANGE_DATE]: _jsx(FormFieldRangeDate, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                                [FieldSchemaType.RANGE_DATETIME]: _jsx(FormFieldRangeDateTime, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                                [FieldSchemaType.RANGE_TIME]: _jsx(FormFieldRangeTime, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                                [FieldSchemaType.RANGE_NUMBER]: _jsx(FormFieldRangeNumber, { ...commonProps, onChange: wrappedOnChange, ref: ref }),
+                            };
+                            return fallbackMap[schemaType] ?? _jsx(RangeSlider, { ...commonProps, onValueChange: wrappedOnChange, ref: ref });
+                        }
+                    }
+                })();
+                return _jsx(FormFieldChrome, { ...chromeProps, children: rangeElement });
+            } }));
+    }
+    // Handle composite object types (static keys)
+    if (schemaType === FieldSchemaType.OBJECT) {
+        if (shouldHideRelationshipObjectField) {
+            return null;
+        }
+        return (_jsx(FormFieldComposite, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, renderField: renderField, excludedChildKeys: excludedChildKeys }));
+    }
+    // Handle record types (dynamic string keys)
+    if (schemaType === FieldSchemaType.RECORD) {
+        const valueSchema = getRecordValueSchema(schema);
+        if (!valueSchema)
+            return null;
+        return (_jsx(FormFieldRecord, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, valueSchema: valueSchema, keySchema: null }));
+    }
+    // Handle map types (typed keys + typed values)
+    if (schemaType === FieldSchemaType.MAP) {
+        const mapSchemas = getMapSchemas(schema);
+        if (!mapSchemas)
+            return null;
+        return (_jsx(FormFieldRecord, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, valueSchema: mapSchemas.valueSchema, keySchema: mapSchemas.keySchema }));
+    }
+    // Handle array types
+    if (schemaType === FieldSchemaType.ARRAY) {
+        if (shouldHideRelationshipObjectField) {
+            return null;
+        }
+        return (_jsx(FormFieldArray, { name: resolvedName, schema: schema, label: label, description: description, disabled: disabled, className: className, renderField: renderField }));
+    }
+    // =========================================================================
+    // FIELD RENDERING - Dispatch by schema type
+    // =========================================================================
+    /**
+     * Helper to reduce Controller boilerplate.
+     * Wraps a field component in RHF Controller with standard change/blur handlers
+     * and the centralized FormFieldChrome wrapper for label/description/error.
+     * 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,
+                    onChange: createChangeHandler(field.onChange),
+                    onBlur: createBlurHandler(field.onBlur),
+                    ref: field.ref,
+                }) })) }));
+    }
+    // =========================================================================
+    // COMPONENT OVERRIDE — from `{primitive}UI.edit.component` or `as` prop.
+    // When set, overrides the default component dispatch for this field's schema type.
+    // =========================================================================
+    const resolvedAs = as;
+    if (resolvedAs && !isRangeSchemaType) {
+        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 })));
+            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:
+            case FormFieldComponent.SWITCH:
+                return renderControlled(field => (_jsx(FormFieldBoolean, { ...baseFieldProps, checked: field.value, onCheckedChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+            case FormFieldComponent.SELECT:
+            case FormFieldComponent.RADIO_GROUP:
+            case FormFieldComponent.CHECKBOX_GROUP: {
+                const enumOptions = enumLabels ? buildOptions(schema, enumLabels) : undefined;
+                return renderControlled(field => (_jsx(FormFieldEnum, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, options: enumOptions })));
+            }
+            case FormFieldComponent.DATE:
+                return renderControlled(field => (_jsx(FormFieldDate, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+            case FormFieldComponent.DATETIME:
+                return renderControlled(field => (_jsx(FormFieldDateTime, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+            case FormFieldComponent.TIME:
+                return renderControlled(field => (_jsx(FormFieldTime, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+            default:
+                // Unrecognized override — fall through to schema-type dispatch
+                break;
+        }
+    }
+    // --- Specialized types ---
+    if (schemaType === FieldSchemaType.MONEY) {
+        return renderControlled(field => (_jsx(FormFieldMoney, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+    }
+    if (schemaType === FieldSchemaType.DURATION) {
+        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 })));
+    }
+    if (schemaType === FieldSchemaType.BIGDECIMAL) {
+        return renderControlled(field => (_jsx(FormFieldBigDecimal, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+    }
+    if (schemaType === FieldSchemaType.CODE) {
+        return renderControlled(field => (_jsx(FormFieldCode, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder })));
+    }
+    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 })));
+        }
+        // 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 })));
+    }
+    // --- Foreign key (check before primitives — FK decorated strings) ---
+    if (isForeignKey(schema)) {
+        return renderControlled(field => (_jsx(ResourceFieldEdit_ResourceReference, { ...baseFieldProps, quickCreateSourceFieldName: quickCreateSourceFieldName, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, placeholder: placeholder })));
+    }
+    // --- Primitive types ---
+    if (schemaType === FieldSchemaType.BOOLEAN) {
+        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 })));
+    }
+    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 })));
+    }
+    if (schemaType === FieldSchemaType.ENUM) {
+        const enumOptions = enumLabels ? buildOptions(schema, enumLabels) : undefined;
+        return renderControlled(field => (_jsx(FormFieldEnum, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref, options: enumOptions })));
+    }
+    if (schemaType === FieldSchemaType.DATE) {
+        return renderControlled(field => (_jsx(FormFieldDate, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+    }
+    if (schemaType === FieldSchemaType.DATETIME) {
+        return renderControlled(field => (_jsx(FormFieldDateTime, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+    }
+    if (schemaType === FieldSchemaType.TIME) {
+        return renderControlled(field => (_jsx(FormFieldTime, { ...baseFieldProps, value: field.value, onChange: field.onChange, onBlur: field.onBlur, ref: field.ref })));
+    }
+    // --- Unsupported type — display error indicator ---
+    return (_jsx(FormFieldChrome, { ...chromeProps, children: _jsxs("div", { className: "flex items-center gap-element px-card-sm py-card-sm rounded-md border border-destructive bg-destructive/10 text-destructive text-sm", children: [_jsx("span", { className: "font-medium", children: "Unsupported field type:" }), _jsx("code", { className: "bg-destructive/20 px-item-xs rounded", children: schemaType }), _jsxs("span", { className: "text-muted-foreground", children: ["(", name, ")"] })] }) }));
+}
+FormFieldImpl.displayName = 'FormField';
+export const FormField = FormFieldImpl;
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Build options for enum fields
+ */
+function buildOptions(schema, enumLabels) {
+    const values = getEnumValues(schema);
+    return values.map((value) => ({
+        value,
+        label: enumLabels?.[value] ?? value,
+    }));
+}
+//# sourceMappingURL=FormField.js.map