ObjectForm.tsx

/**
 * ObjectUI
 * Copyright (c) 2024-present ObjectStack Inc.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

/**
 * ObjectForm Component
 * 
 * A smart form component that generates forms from ObjectQL object schemas.
 * It automatically creates form fields based on object metadata.
 */

import React, { useEffect, useState, useCallback, useMemo } from 'react';
import type { ObjectFormSchema, FormField, FormSchema, DataSource } from '@object-ui/types';
import { SchemaRenderer, useSafeFieldLabel } from '@object-ui/react';
import { pickLocalized, useObjectTranslation, useLocalization } from '@object-ui/i18n';
import { useRecordInvalidation } from './recordInvalidation';
import { mapFieldTypeToFormType, buildValidationRules, formatFileSize, fieldHelpText } from '@object-ui/fields';
import { useIsMobile, toast } from '@object-ui/components';
import { resolveSuccessNavigate } from './successBehavior';
import { resolveSubmitRedirect, submitRedirectScope } from './submitRedirect';
import {
  useSubmitRedirectNavigation,
  type PendingSubmitRedirect,
} from './submitRedirectNavigation';
import { usePermissions } from '@object-ui/permissions';
import { sectionPredicateUnsupportedWarning } from './sectionPredicateDiagnostic';
import {
  warnUnresolvedTopLevelField,
  warnSectionMemberExcludedByFields,
  buildSectionFields,
  sectionEntryName,
  type SectionFieldsContext,
} from './sectionFields';
import { TabbedForm } from './TabbedForm';
import { WizardForm } from './WizardForm';
import { useFormChromeTranslation } from './formChrome';
import { MasterDetailForm } from './MasterDetailForm';
import {
  applyAutoLayout,
  filterAutoGeneratedFields,
  filterSystemFields,
  sectionedGridLayout,
} from './autoLayout';
import { deriveFieldGroupSections, projectSectionDivider, resolveSectionCollapse, type FormFieldWithGroup } from './fieldGroups';
import { mergeCustomFields } from './customFieldsMerge';
import { hasSectionGroupReference, resolveSectionGroupReferences } from './sectionGroups';
import {
  snapshotLoadedRecord,
  advanceLoadedRecord,
  type LoadedRecordSnapshot,
} from './sanitize';
import { formWritePayload } from './writePayload';
import { applyFieldPermissions, closedFormAffordance, fieldWriteGate, gateFormFields } from './fieldWriteGate';
import { RecordFieldAccessForForm } from './recordFieldAccess';
import { ClosedAffordanceNotice } from './closedAffordanceNotice';
import { resolveInitialRecord } from './initialRecord';
import { hasInlineFieldSource, isInlineFieldDef, noSubmitTargetError } from './submitTarget';
import { useUploadGate, UploadGateProvider, UploadInFlightNotice } from './uploadGate';
import {
  schemaDefaultValues,
  isCreateFormMode,
  isRequiredInForm,
} from './schemaDefaults';
import { useOccSave } from './occSave';
import {
  NO_LOAD_FAILURES,
  beginLoadRun,
  shownLoadFailure,
  type LoadFailures,
  type LoadRunSeq,
} from './loadFailure';

/**
 * Props of the `ObjectForm` React component.
 *
 * Renamed off the bare `ObjectFormProps` (objectui#4650): from 17.0.0
 * `@objectstack/spec/ui` owns that name, where it is the AUTHORED props
 * document of the `object-form` element — `z.input<typeof
 * ObjectFormPropsSchema>`, i.e. serialisable authoring keys only. This is the
 * RENDERER's props: a live `dataSource`, submit/cancel callbacks and imperative
 * handles, none of which can exist in authored metadata. Two layers under one
 * word, resolved the way this repo already resolved it for `PageHeaderProps` ->
 * `PageHeaderComponentProps` (app-shell) and the `Record*ComponentProps` family
 * in `@object-ui/types`.
 *
 * The barrel keeps `ObjectFormProps` as a deprecated alias of this type, so no
 * importer breaks. Tripwire: `__tests__/spec-symbol-4650.test.ts`.
 */
export interface ObjectFormComponentProps {
  /**
   * The schema configuration for the form
   */
  schema: ObjectFormSchema;
  
  /**
   * Data source (ObjectQL or ObjectStack adapter)
   * Optional when using inline field definitions (customFields or fields array with field objects)
   */
  dataSource?: DataSource;
  
  /**
   * Additional CSS class
   */
  className?: string;
}

/**
 * Fold the structured, spec-aligned `buttons`/`defaults` surface
 * (`@objectstack/spec` FormViewSchema; framework#1894 / objectstack-ai/objectstack#2998) down onto the
 * flat renderer props ObjectForm and its variants read
 * (`showSubmit`/`submitText`/`showCancel`/`cancelText`/`initialValues`). This is the objectui-side consumer of those spec keys — it
 * is what lets them flip `experimental → live` in the spec liveness ledger.
 *
 * Spec is the authored surface, but an explicitly-set flat key still wins so
 * existing metadata that authored the deprecated flat keys is unchanged.
 * Returns the input untouched when neither structured key is present (the
 * common case), so there is no allocation on the hot path.
 */
function foldFormButtons(schema: ObjectFormComponentProps['schema']): ObjectFormComponentProps['schema'] {
  const buttons = (schema as { buttons?: ObjectFormSchema['buttons'] }).buttons;
  const defaults = (schema as { defaults?: Record<string, any> }).defaults;
  if (!buttons && !defaults) return schema;
  const s = schema as Record<string, any>;
  const out: Record<string, any> = { ...s };
  if (buttons?.submit?.show !== undefined && s.showSubmit === undefined) out.showSubmit = buttons.submit.show;
  if (buttons?.submit?.label != null && s.submitText === undefined) out.submitText = buttons.submit.label;
  if (buttons?.cancel?.show !== undefined && s.showCancel === undefined) out.showCancel = buttons.cancel.show;
  if (buttons?.cancel?.label != null && s.cancelText === undefined) out.cancelText = buttons.cancel.label;
  if (defaults && s.initialValues === undefined) out.initialValues = defaults;
  return out as ObjectFormComponentProps['schema'];
}

/**
 * The seven members `ComponentPropsMap['object-form']` in `@objectstack/spec`
 * declares as `I18nLabel`: a plain string or an inline per-locale map such as
 * `{ en: 'Save order', 'zh-CN': '保存订单' }` (objectui#10993).
 */
const OBJECT_FORM_LABEL_KEYS = [
  'title',
  'description',
  'submitText',
  'cancelText',
  'nextText',
  'prevText',
  'successMessage',
] as const;
type ObjectFormLabelKey = (typeof OBJECT_FORM_LABEL_KEYS)[number];

/**
 * `ObjectFormSchema` as every presentation below reads it: the seven
 * `I18nLabel` members already resolved to a string. A homomorphic mapped type
 * rather than `Omit`, because `BaseSchema`'s index signature made `Omit`
 * collapse to that signature and drop every declared member (until
 * objectui#8347 removed it).
 */
type LocalizedObjectFormSchema = {
  [K in keyof ObjectFormSchema]: K extends ObjectFormLabelKey ? string : ObjectFormSchema[K];
};

/**
 * Resolve the seven `I18nLabel` members against the active UI language — the
 * source `ObjectMetricWidget` and `MasterDetailForm` resolve their own
 * `I18nLabel` members against — before any presentation reads them.
 *
 * Read raw, a map was a React child in every presentation that renders one
 * (`submitText` / `cancelText` on the form's buttons, `nextText` / `prevText`
 * on the wizard's, `title` / `description` as the drawer and modal headings)
 * and threw "Objects are not valid as a React child", taking the whole form
 * down; `successMessage` went into the success toast.
 *
 * Only the map arm is touched: a string, or any value that is not an object,
 * is handed on exactly as authored. A map with no usable entry resolves to
 * `undefined`, so each presentation's own default ('Create', 'Cancel', 'Next',
 * …) shows. Returns its input untouched when no member is a map, so there is
 * no allocation on the hot path.
 */
function localizeFormLabels(
  schema: ObjectFormComponentProps['schema'],
  language: string,
): LocalizedObjectFormSchema {
  let out: Record<string, unknown> | null = null;
  for (const key of OBJECT_FORM_LABEL_KEYS) {
    const value: unknown = schema[key];
    if (value === null || typeof value !== 'object') continue;
    out ??= { ...schema };
    out[key] = pickLocalized(value, language) || undefined;
  }
  return (out ?? schema) as LocalizedObjectFormSchema;
}

/**
 * ObjectForm Component
 *
 * Renders a form for an ObjectQL object with automatic schema integration.
 *
 * @example
 * ```tsx
 * <ObjectForm
 *   schema={{
 *     type: 'object-form',
 *     objectName: 'users',
 *     mode: 'create',
 *     fields: ['name', 'email', 'status']
 *   }}
 *   dataSource={dataSource}
 * />
 * ```
 */
/**
 * An `edit` form for a stored record answers its field locks from that record
 * (objectstack#26594) — see `recordFieldAccess.tsx`.
 */
export const ObjectForm: React.FC<ObjectFormComponentProps> = ({ schema, ...rest }) => (
  <RecordFieldAccessForForm schema={schema} dataSource={rest.dataSource}>
    {/* `schema=` by name, so the handler-key census follows the document into the body. */}
    <ObjectFormBody schema={schema} {...rest} />
  </RecordFieldAccessForForm>
);

/**
 * The schema every layout reads, prepared ONCE above the layout fork: the
 * structured `buttons` / `defaults` folded onto the flat keys, the seven
 * `I18nLabel` members resolved, legacy `groups` normalised to `sections`,
 * field-level permissions applied and `{ group }` sections resolved — plus the
 * section-label translator every section map uses.
 *
 * A hook of its own because two renderers prepare the same schema: this file's
 * `ObjectForm` (the `simple` / `tabbed` / `wizard` layouts) and
 * `ObjectFormContainer`, which supplies the drawer or modal container an
 * `object-form` block asks for with `formType` (ADR-0050 Decision 4 — the
 * container is the caller's, never the form's).
 */
export function usePreparedFormSchema(
  rawSchema: ObjectFormComponentProps['schema'],
  dataSource: ObjectFormComponentProps['dataSource'],
) {
  const perms = usePermissions();

  // ── `sections[].group` — the ADR-0085 §5 REFERENCE form (objectui#7051) ───
  //
  // A section may point `group` at one of the object's declared `fieldGroups`
  // instead of enumerating members (`@objectstack/spec` 17.3.0,
  // objectstack#13855). Resolving it needs the OBJECT definition, and this
  // preparation — unlike the layout bodies it feeds — has never loaded one.
  //
  // It is resolved HERE, above the routing, on purpose: every variant's
  // `sections` prop is rebuilt key by key in the maps below, so a `group` left
  // in place would be dropped before any container could see it, and each
  // container would need its own copy of the resolution. One site above the
  // fork is what makes "one assembler" true for all six layouts at once —
  // including `simple`, whose section loop read `section.fields.map(...)`
  // unguarded and threw `Cannot read properties of undefined (reading 'map')`
  // on a spec-legal `{ group }` section, blanking the WHOLE form (measured on
  // this file at `origin/main`; the other five silently dropped the section
  // instead, because `buildSectionFields` spells the same read `?? []`).
  //
  // The load is gated on an authored `group` being present, so a form that
  // does not use the reference form issues no request and takes no new path.
  const needsGroupLayout = hasSectionGroupReference((rawSchema as any)?.sections);
  const canResolveGroups = typeof (dataSource as any)?.getObjectSchema === 'function';
  const [groupObjectDef, setGroupObjectDef] = useState<any>(null);
  useEffect(() => {
    if (!needsGroupLayout || !canResolveGroups) return;
    let alive = true;
    Promise.resolve((dataSource as any).getObjectSchema(rawSchema.objectName))
      .then((def: any) => { if (alive) setGroupObjectDef(def ?? null); })
      // A failed load leaves the references unresolved (their sections render
      // empty). It is deliberately NOT reported as a dangling reference: the
      // body below owns the load error for the object, and claiming the group
      // does not exist would be a second, wrong diagnosis of one failure.
      .catch(() => { if (alive) setGroupObjectDef(null); });
    return () => { alive = false; };
  }, [needsGroupLayout, canResolveGroups, dataSource, rawSchema.objectName]);

  // The UI language the seven `I18nLabel` members resolve against — see
  // `localizeFormLabels` (objectui#10993).
  const { language } = useObjectTranslation();

  // Apply field-level permissions to the entire schema (sections + flat
  // fields) BEFORE dispatching to any variant. This way all variants
  // (Tabbed/Wizard/Simple here, Drawer/Modal through `ObjectFormContainer`)
  // transparently honour FLS.
  // Fail-open when no provider mounted (perms.isLoaded false).
  const schema = useMemo<LocalizedObjectFormSchema>(() => {
    // framework#1894 / objectstack-ai/objectstack#2998 (ADR-0078): the authored @objectstack/spec
    // FormViewSchema carries the structured `buttons.{submit,cancel}.
    // {show,label}` + `defaults` surface (`buttons.reset` retired, #27153), but this renderer historically read
    // only the flat `showSubmit`/`submitText`/…/`initialValues`. Fold the
    // structured shape down onto those flat props FIRST so every downstream
    // read (and every variant we dispatch `schema` into) sees it. An
    // explicitly-set flat key still wins (deprecated back-compat).
    //
    // objectui#10993: the seven `I18nLabel` members are resolved HERE, above the
    // `formType` fork, for the reason `sections[].group` is resolved above it:
    // every presentation reads them, so one site covers all of them. Folded
    // first, so a `buttons.*.label` lands on the flat key before it resolves.
    const folded = localizeFormLabels(foldFormButtons(rawSchema), language);
    // #2545: spec FormViewSchema defines `groups` as a legacy alias of
    // `sections`, and this renderer only ever consumes `sections` — normalize
    // so groups-only metadata actually renders (it used to be silently
    // ignored). Legacy shape maps `title`→`label`, `defaultCollapsed`→`collapsed`.
    const legacyGroups = (folded as any).groups;
    const base: LocalizedObjectFormSchema =
      !folded.sections?.length && Array.isArray(legacyGroups) && legacyGroups.length
        ? {
            ...folded,
            sections: legacyGroups.map((g: any) => ({
              label: g.title ?? g.label,
              description: g.description,
              collapsible: g.collapsible,
              collapsed: g.defaultCollapsed ?? g.collapsed,
              fields: g.fields ?? [],
            })),
          }
        : folded;
    /**
     * Resolve every `{ group }` section into the section that group declares.
     *
     * Returns its input UNCHANGED — same array reference — when no section
     * uses the reference form, so this memo cannot perturb any existing form.
     */
    const withGroups = (s: LocalizedObjectFormSchema) => {
      const resolved = resolveSectionGroupReferences(s.sections as any, {
        objectName: s.objectName,
        formType: s.formType,
        objectDef: groupObjectDef,
        resolvable: canResolveGroups,
      });
      return resolved === (s.sections as any) ? s : { ...s, sections: resolved as any };
    };
    if (!perms?.isLoaded) return withGroups(base);
    // ONE render gate, shared with `ModalForm` and `DrawerForm` — see
    // `fieldWriteGate.ts` for why the copy each container used to carry is the
    // defect rather than the style (`80c54122e`).
    const filterArr = (arr?: any[]) =>
      applyFieldPermissions(arr, { perms, objectName: base.objectName, mode: base.mode });
    return withGroups({
      ...base,
      fields: filterArr(base.fields as any[]),
      sections: base.sections?.map((s: any) => ({
        ...s,
        fields: filterArr(s.fields),
      })),
    } as LocalizedObjectFormSchema);
  }, [rawSchema, perms, groupObjectDef, canResolveGroups, language]);
  const { sectionLabel } = useSafeFieldLabel();
  const tSec = (s: any) =>
    s?.name ? sectionLabel(schema.objectName, s.name, s.label || s.name) : s?.label;
  return { schema, tSec };
}

const ObjectFormBody: React.FC<ObjectFormComponentProps> = ({
  schema: rawSchema,
  dataSource,
}) => {
  const { schema, tSec } = usePreparedFormSchema(rawSchema, dataSource);

  // Master-detail: when the schema declares inline child collections, render as
  // a master-detail form (parent fields + child grids, persisted atomically).
  // This lets a plain form view become master-detail by config — no bespoke
  // page. Skipped in view mode (read-only detail uses related lists instead).
  // A drawer or modal container never reaches here: `ObjectFormContainer`
  // hands it to DrawerForm/ModalForm, which host the master-detail form INSIDE
  // their envelope.
  const routesToMasterDetail = !!(schema as any).subforms?.length && schema.mode !== 'view';

  // ── objectui#6237 diagnostic, now scoped to the ONE arm still inert ────────
  // The interim diagnostic ruled on 2026-08-29 covered `tabbed` AND `wizard`,
  // the two routes that dropped an authored section `visibleWhen`. The tabbed
  // arm now HONOURS it (the map below copies the key, `TabbedForm` puts it on
  // the tab it synthesises, and the renderer evaluates it), so warning about it
  // would be a false alarm about a working feature — the same boundary the four
  // control rows of the diagnostic's pin defend. `wizard` stays inert by
  // DESIGN, not by omission: a step predicate is a different contract, not a
  // port (see `WizardStepConfig`), so its gap is still reported rather than
  // silently dropped.
  //
  // Deliberately NOT reported for the master-detail branch: that branch re-enters
  // `ObjectForm` through `MasterDetailForm`'s parent schema, which is where the
  // real layout is decided (a master-detail `wizard` parent renders `simple`,
  // which DOES honour the predicate). Reporting here as well would double-report
  // the tabbed parent and false-report the wizard one.
  const inertPredicateLayout = !routesToMasterDetail && schema.formType === 'wizard'
    ? schema.formType
    : null;
  // Joined to a string on purpose: the effect's deps must be primitives, or a
  // fresh array identity each render would re-report on every keystroke.
  const inertPredicateSections = (schema.sections ?? [])
    .filter((s: any) => s?.visibleWhen != null)
    .map((s: any) => s?.name || s?.label || '(unnamed)')
    .join(', ');
  useEffect(() => {
    if (!inertPredicateLayout || !inertPredicateSections) return;
    console.warn(sectionPredicateUnsupportedWarning(inertPredicateLayout, inertPredicateSections));
  }, [inertPredicateLayout, inertPredicateSections]);

  if (routesToMasterDetail) {
    return (
      <MasterDetailForm
        schema={{
          type: 'object-master-detail-form',
          objectName: schema.objectName,
          mode: schema.mode === 'edit' ? 'edit' : 'create',
          recordId: schema.recordId,
          // Forward prefilled header values so create-mode wizards (e.g. lead
          // conversion) seed the parent fields, not just plain forms.
          initialValues: (schema as any).initialValues,
          initialData: (schema as any).initialData,
          formType: schema.formType === 'tabbed' ? 'tabbed' : 'simple',
          // objectstack-ai/objectstack#26843 — the tabbed header's opening tab
          // and strip position, and the field layout, which this rebuild
          // dropped before the header form could read them.
          defaultTab: schema.defaultTab,
          tabPosition: schema.tabPosition,
          layout: schema.layout,
          sections: schema.sections as any,
          fields: schema.fields as any,
          title: schema.title,
          submitText: schema.submitText,
          cancelText: schema.cancelText,
          // Forward the host's submit-visibility so a non-persisting preview
          // can hide the master-detail Save bar (it owns the only Save here).
          showSubmit: (schema as any).showSubmit,
          details: (schema as any).subforms,
          onSuccess: schema.onSuccess,
          onError: schema.onError,
          // The master-detail action bar draws Cancel only when handed an
          // `onCancel`, so a hidden cancel button is no handler
          // (objectstack-ai/objectstack#26843).
          onCancel: schema.showCancel === false ? undefined : schema.onCancel,
          className: schema.className,
        }}
        dataSource={dataSource}
      />
    );
  }

  // Route to specialized form variant based on formType
  if (schema.formType === 'tabbed' && schema.sections?.length) {
    return (
      <TabbedForm
        schema={{
          ...schema,
          formType: 'tabbed',
          sections: schema.sections.map(s => ({
            name: s.name,
            label: tSec(s),
            description: s.description,
            columns: s.columns,
            // `?? []` because `ObjectFormSection.fields` is OPTIONAL since objectui#7051
            // — `group` is the other way a section declares its members. A `{ group }`
            // section has already been resolved into one carrying `fields` before this
            // map runs (and an unresolvable one into `fields: []`), so this default is
            // reached only by a programmatic caller sending a section with neither,
            // which the spec door refuses. These per-layout config types stay
            // `fields`-required on purpose: they are the programmatic React-mount
            // shapes, not the authorable surface, and the reference form is resolved
            // above them.
            fields: s.fields ?? [],
            // ADR-0089 section predicate (objectui#6237) — key-by-key rebuild,
            // so an uncopied key is silently dropped before TabbedForm ever
            // sees it, exactly as it was on this route until this card. The
            // drawer/modal maps (`ObjectFormContainer`) have carried it since
            // #6111; this is the tabbed arm joining them.
            //
            // Read WITHOUT an `as any` cast on purpose, unlike those two:
            // `ObjectFormSection.visibleWhen` is declared, so the compiler is
            // able to catch a rename here. Through a cast it would keep
            // compiling and silently copy `undefined` — the exact silent-drop
            // failure this line exists to fix.
            visibleWhen: s.visibleWhen,
            visibleWhenFault: s.visibleWhenFault,
            // ⛔ `className` / `gridClassName` are DELIBERATELY not copied here
            // or at any of the six sibling sites below — objectstack#13626,
            // maintainer ruling 2026-09-01 (director decision batch C):
            // "retire the reads".
            //
            // The two keys sit on the SDUI-only side of the authorable
            // boundary: `@objectstack/spec` deliberately does NOT declare them
            // on the form-view/section surface (see the "Deliberately NOT
            // declared" note in its `component.zod.ts`), and the
            // authorable-surface ledger carries no entry for them. They were
            // nevertheless reached off the parsed view through `as any` — the
            // boundary declared on one side and crossed on the other.
            //
            // Declaring them instead was weighed and NOT adopted: it would
            // formally invite free Tailwind strings into authored metadata,
            // the exact class the boundary exists to keep out — and per
            // ADR-0065 / ADR-0080 (rev. 2026-06-30) utility classNames in
            // runtime metadata are never scanned by the build-time Tailwind,
            // so they silently produce no CSS. If per-view styling becomes a
            // real product need it gets an explicit controlled token surface,
            // not two leaked keys.
            //
            // ⚠️ `ObjectFormSection` (this repo's own `@object-ui/types`) no
            // longer declares either key (objectui#7200), so an uncast
            // `className: s.className` fails to compile here. A CAST read —
            // the shape the seven retired sites had — still would, and JSON
            // metadata carries whatever an author wrote. The omission is
            // therefore pinned behaviourally, not by a source grep —
            // `__tests__/sectionStyleKeysRetired-13626.test.tsx`.
          })),
          defaultTab: schema.defaultTab,
          tabPosition: schema.tabPosition,
        }}
        dataSource={dataSource}
        className={schema.className}
      />
    );
  }

  if (schema.formType === 'wizard' && schema.sections?.length) {
    return (
      <WizardForm
        schema={{
          ...schema,
          formType: 'wizard',
          // Key-by-key rebuild into `WizardStepConfig`, the wizard's OWN step
          // shape: `visibleWhen` / `collapsible` / `collapsed` are deliberately
          // not copied — wizard steps carry no predicate slot and do not
          // collapse (objectui#6237 split; upgraded to a spec-door parse
          // refusal by objectstack#13622 D2, ruled 2026-08-31, so authored
          // metadata carrying them never reaches this map). The predicate drop
          // is additionally reported above for the callers the spec door
          // cannot see (programmatic SDUI, pre-tightening metadata).
          sections: schema.sections.map(s => ({
            name: s.name,
            label: tSec(s),
            description: s.description,
            columns: s.columns,
            // `?? []` — see the tabbed arm above (objectui#7051).
            fields: s.fields ?? [],
            // `className` / `gridClassName`: deliberately not copied — see the
            // tabbed arm above (objectstack#13626, ruled 2026-09-01).
          })),
          allowSkip: schema.allowSkip,
          showStepIndicator: schema.showStepIndicator,
          nextText: schema.nextText,
          prevText: schema.prevText,
          onStepChange: schema.onStepChange,
        }}
        dataSource={dataSource}
        className={schema.className}
      />
    );
  }

  // Default: simple form
  return <SimpleObjectForm schema={schema} dataSource={dataSource} />;
};

/**
 * SimpleObjectForm — default form variant with auto-generated fields from ObjectQL schema.
 */
/**
 * A simple form's opening values: the seeded defaults (empty on an edit),
 * overlaid with the record the form holds or the caller supplied. The form
 * renders these, and a create save judges a picked owner against them
 * (objectui#12359).
 */
function formOpeningValues(
  schemaDefaults: Record<string, unknown>,
  initialData: Record<string, unknown> | null | undefined,
): Record<string, unknown> {
  return { ...schemaDefaults, ...(initialData ?? {}) };
}

const SimpleObjectForm: React.FC<{ schema: LocalizedObjectFormSchema; dataSource?: DataSource }> = ({
  schema,
  dataSource,
}) => {
  const { fieldLabel, sectionLabel } = useSafeFieldLabel();
  // The form's own feedback chrome — the default success toast and
  // confirmation, the loading line, the load-failure heading and the default
  // submit label — in the session locale (objectui#11039). See `formChrome.ts`.
  const { t } = useFormChromeTranslation();
  const isMobile = useIsMobile();
  // Upload-in-flight gate (objectui#10166). Owns the aggregated "is any
  // file/image widget below me still uploading" answer, the Save label while it
  // is true, and the sentence that says why. See `uploadGate.tsx`.
  const uploadGate = useUploadGate();
  // Field-level permission gate. When the consumer hasn't mounted a
  // PermissionProvider / MePermissionsProvider, `usePermissions` returns
  // a permissive default (isLoaded:false, checkField always true) so we
  // remain backward-compatible.
  const perms = usePermissions();

  const [objectSchema, setObjectSchema] = useState<any>(null);
  // The hint under a field the caller may read but not write, in the session
  // locale (objectui#11071). A string rather than `t` in the dependency list
  // below: it changes when the language does and at no other time.
  const deniedDescription = t('form.deniedDescription');
  // The same reason for the file-size hint's sentence (objectui#12156): the
  // field builder below interpolates the size into it, and this string, not
  // `t`, is what its dependency list carries. It changes when the language, or
  // that language's late-arriving catalogue, does.
  const maxFileSizeSentence = t('form.maxFileSize', { size: '' });
  const [initialData, setInitialData] = useState<any>(null);
  // The persisted record, for `previous`-scoped field rules and the read-only
  // submit strip (objectui#3484). Edit mode only, and WITHOUT the schema
  // defaults folded in below: `previous` must be the row as the server last
  // stored it, not "the row plus what a blank column would default to". It is
  // also the from-state a `state_machine` select narrows by (#25933).
  const previousValues =
    schema.mode === 'edit' && schema.recordId && initialData && typeof initialData === 'object'
      ? (initialData as Record<string, any>)
      : undefined;
  // objectui#11000 — why `gateFields` locked every field, when the lock is the
  // form-wide one: the affordance for the mode is closed. Rendered above the
  // fields by `ClosedAffordanceNotice`.
  const closedAffordance = closedFormAffordance({
    perms,
    objectName: schema.objectName,
    mode: schema.mode,
    objectSchema,
  });
  const closedAffordanceNotice = (
    <ClosedAffordanceNotice
      affordance={closedAffordance}
      objectName={schema.objectName}
      objectSchema={objectSchema}
    />
  );
  const [formFields, setFormFields] = useState<FormField[]>([]);
  const [loading, setLoading] = useState(true);
  // objectui#10682 — the load error, kept per read (the object schema and the
  // record), each written only by the current run of its read and cleared when
  // a later run of that read commits: see `loadFailure.ts`. `error` is what
  // the error screen reports.
  const [loadFailures, setLoadFailures] = useState<LoadFailures>(NO_LOAD_FAILURES);
  const loadRunSeqRef = React.useRef<LoadRunSeq>({ schema: 0, record: 0 });
  const error = shownLoadFailure(loadFailures);
  // Terminal state for `submitBehavior: { kind: 'thank-you' | 'next-record' }`
  // — without it the form stayed mounted and fully filled after a successful
  // submit, with nothing disabling re-submission (a second click created a
  // second record).
  //
  // `refusal` carries the second fact a REFUSED `redirect` destination has to
  // report (objectui#4989): the write succeeded — hence the confirmation this
  // state already renders — but the authored destination is out of contract, so
  // nothing was navigated to and the author needs the reason. It rides on this
  // state rather than on `error` because `error` is the load/submit FAILURE
  // channel and a refused destination is not a failed submit; putting it there
  // would tell the submitter their record was lost.
  const [submitted, setSubmitted] = useState<
    { title?: string; message?: string; refusal?: string } | null
  >(null);

  // The accepted destination of a `submitBehavior: { kind: 'redirect' }` submit,
  // together with the delay declared for it, held from the moment the write
  // succeeds until the wait below elapses (objectui#5033).
  //
  // The wait used to be a bare `setTimeout` armed inside the submit handler:
  // nothing stored the handle and nothing cleared it, so for the whole of
  // `delayMs` a full-page navigation was pending that OUTLIVED this component. A
  // submitter who dismissed the modal/drawer variant, followed an in-app link, or
  // whose host re-keyed the subtree was pulled away from wherever they had gone.
  // Recording the destination here hands the wait to the effect below, which owns
  // it for exactly as long as this component is mounted.
  //
  // The delay travels WITH the destination rather than being re-read from
  // `schema.submitBehavior` at wait time: the value honoured is the one declared
  // when the write was accepted, so a host re-rendering with a different
  // `delayMs` mid-wait cannot restart the pause under the submitter.
  const [pendingRedirect, setPendingRedirect] = useState<PendingSubmitRedirect | null>(null);

  // The delayed leg of a `redirect` submit behaviour.
  //
  // `delayMs` semantics are unchanged: the pause is what makes the confirmation
  // readable, and an unset value still means "go now" (a zero timer, exactly as
  // the in-handler version scheduled it). The one thing that changed is who owns
  // the wait — unmounting cancels it instead of leaving it to fire into a page
  // the submitter has left.
  //
  // WHERE the wait lands is `submitRedirectNavigation.ts`'s question: the host's
  // injected navigate when one was supplied (so a mounted host's basename is
  // applied — objectui#4989 defect 4), else the `window.location.assign` this
  // arm has always done. The wizard consumes the same hook, so a wizard and a
  // flat form cannot travel to one authored destination differently.
  useSubmitRedirectNavigation(pendingRedirect);

  // OCC-guarded edit save + its conflict dialog (see occSave.tsx).
  const { saveWithOcc, conflictDialog } = useOccSave();

  // The record this form READ for the record it edits — the baseline an edit
  // save diffs against, so only the fields that changed are written
  // (objectui#10156). A ref, not state: only the save path reads it, and
  // nothing renders from it. Set by the `findOne` below and nowhere else, so a
  // caller-supplied record (inline fields, `initialData`) never becomes a
  // baseline and its save keeps sending every field. `initialData` itself is
  // left alone: it seeds the form and supplies the OCC token, and advancing it
  // after a save would reseed the one and move the other.
  const loadedRecordRef = React.useRef<LoadedRecordSnapshot | null>(null);

  // Check if using inline fields (fields defined as objects, not just names)
  const hasInlineFields = schema.customFields && schema.customFields.length > 0;
  // objectui#11615 — the members-only field source as the five other layouts
  // answer it (`hasInlineFieldSource`): `customFields` (limb a, which is
  // `hasInlineFields` above), or sections whose EVERY entry is self-describing
  // (limb b), which this arm now draws whatever its field pool holds. With no
  // adapter such a form has nothing to read: it opens on the caller's record,
  // and its `onSuccess` is the write (the carve-out in `handleSubmit`).
  const hasInlineSource = hasInlineFieldSource(schema);

  // Initialize with inline data if provided
  useEffect(() => {
    if (hasInlineFields) {
      setInitialData(resolveInitialRecord(schema));
      // objectui#9778: inline members no longer short-circuit the metadata
      // read — they MERGE over it — so the loading flag can only drop here
      // when nothing is going to be fetched. Dropping it unconditionally put
      // an empty `<form>` on screen for the duration of `getObjectSchema`.
      // The metadata branch's own tail (`willFetchData`) clears it otherwise.
      if (!(schema.objectName && dataSource)) {
        setLoading(false);
      }
    }
  }, [hasInlineFields, schema.initialData, schema.initialValues, schema.objectName, dataSource]);

  // Fetch object schema from ObjectQL/ObjectStack (inline members merge OVER it)
  useEffect(() => {
    // objectui#10712 — a read an `objectName` or data-source change has
    // superseded commits nothing: not the schema, and not the `loading` release
    // the current read owns. Otherwise it could land last and draw the current
    // object's record against the previous object's fields.
    let cancelled = false;
    // objectui#10682 — this run's writes to the schema read's failure; a newer
    // run of this effect makes them no-ops.
    const run = beginLoadRun(loadRunSeqRef, setLoadFailures, 'schema');
    // The field source when no object metadata is reachable: an object with no
    // fields, over which the authored members are the whole set.
    const inlineOnlySchema = {
      name: schema.objectName,
      fields: {} as Record<string, any>,
    };

    const fetchObjectSchema = async () => {
      try {
        if (!dataSource) {
          throw new Error('DataSource is required when using ObjectQL schema fetching (inline fields not provided)');
        }
        const schemaData = await dataSource.getObjectSchema(schema.objectName);
        if (cancelled) return;
        if (!schemaData) {
          throw new Error(`No schema found for object "${schema.objectName}"`);
        }
        setObjectSchema(schemaData);
        run.commit();
      } catch (err) {
        if (cancelled) return;
        // objectui#9778: for the inline path the metadata is an OVERLAY, not a
        // prerequisite. A form that renders its authored members today must not
        // become an error panel because the adapter cannot describe the object —
        // fall back to the members-only source the registration promises for the
        // no-data-source case.
        if (hasInlineFields) {
          setObjectSchema(inlineOnlySchema);
          run.commit();
          setLoading(false);
          return;
        }
        run.fail(err);
        setLoading(false);
      }
    };

    // objectui#9778: inline members are "merged over the set generated from
    // object metadata" (the registered description of `customFields`), so the
    // fetch is no longer skipped when they are present — without the generated
    // set there is nothing to merge over and the merge lookup further down
    // stays the dead code objectui#8071 measured. The members-only schema is
    // what the registration's second sentence describes ("with inline
    // definitions and no data source, this becomes the only field source"), so
    // it is now the FALLBACK rather than the inline path's fixed answer.
    //
    // objectui#11615: sections of self-describing entries are the other
    // members-only source (`hasInlineSource`), so they take the same fallback —
    // which is what lets the record effect below seed such a form.
    if (schema.objectName && dataSource) {
      fetchObjectSchema();
    } else if (hasInlineSource) {
      setObjectSchema(inlineOnlySchema);
      run.commit();
    } else {
      // No objectName or dataSource and no inline fields — cannot proceed
      setLoading(false);
    }
    return () => { cancelled = true; };
  }, [schema.objectName, dataSource, hasInlineFields, hasInlineSource]);

  // objectui#10572 — the data-invalidation bus (`notifyDataChanged` from
  // `@object-ui/react`), read for the record this form READS (edit/view mode,
  // no inline fields). The rule — which changes move it, the pristine gate, the
  // held re-read replayed on save or revert — is stated once in
  // `recordInvalidation.ts` and shared with the five other layouts
  // (objectui#10715). Dirtiness is read from the form renderer's existing
  // `onDirtyChange` channel; nothing new is declared on any schema.
  const readsRecord = !!schema.recordId && schema.mode !== 'create' && !hasInlineFields;
  const { refetch: recordRefetch, onDirtyChange: handleDirtyChange, saved: recordSaved } =
    useRecordInvalidation(schema.objectName, schema.recordId, readsRecord);
  // The `recordRefetch` value the fetch effect last ran for — a run that moved
  // it is a re-read IN PLACE and must not enter the loading branch.
  const appliedRecordRefetchRef = React.useRef(0);

  // Fetch initial data for edit/view modes (skip if using inline data)
  useEffect(() => {
    const inPlace = recordRefetch !== appliedRecordRefetchRef.current;
    appliedRecordRefetchRef.current = recordRefetch;
    // objectui#10712 — a read a newer run has superseded (another `recordId`,
    // say, while it was in flight) commits nothing: not the values, not the
    // baseline, and not the `loading` release the current run owns. Otherwise
    // the answer for the previous record could land last and be shown under
    // the new one. The shape the four other sectioned layouts already use
    // (recordSwapLoading.test.tsx).
    let cancelled = false;
    // objectui#10682 — this run's writes to the record read's failure; a newer
    // run of this effect makes them no-ops.
    const run = beginLoadRun(loadRunSeqRef, setLoadFailures, 'record');
    const fetchInitialData = async () => {
      if (!schema.recordId || schema.mode === 'create') {
        // Seeded from something other than a read: no baseline to diff against.
        loadedRecordRef.current = null;
        setInitialData(resolveInitialRecord(schema));
        // Not a read, so no earlier record read's failure describes the form.
        run.commit();
        setLoading(false);
        return;
      }

      // Skip fetching if using inline data
      if (hasInlineFields) {
        return;
      }

      if (!dataSource) {
        if (hasInlineSource) {
          // objectui#11615 — sections of self-describing entries with no
          // adapter: a self-contained collector with nothing to read, so it
          // opens on the caller's record, as the five other layouts open the
          // same form. Not a read, so no baseline.
          loadedRecordRef.current = null;
          setInitialData(resolveInitialRecord(schema));
          run.commit();
          setLoading(false);
          return;
        }
        run.fail(new Error('DataSource is required for fetching record data (inline data not provided)'));
        setLoading(false);
        return;
      }

      // A bus re-read keeps the form mounted (objectui#10572): the loading
      // branch would unmount it and drop the fields' own UI state.
      if (!inPlace) setLoading(true);
      try {
        const data = await dataSource.findOne(schema.objectName, schema.recordId);
        if (cancelled) return;
        // Tagged with the object and record it was read for, so a save that
        // runs against a different one finds no baseline and sends everything.
        loadedRecordRef.current = snapshotLoadedRecord(schema, data);
        setInitialData(data);
        // The record on screen is the one this run read, so an earlier record
        // read's failure no longer describes it. A schema failure stays: this
        // read says nothing about the object's fields.
        run.commit();
      } catch (err) {
        if (cancelled) return;
        console.error('Failed to fetch record:', err);
        // A failed background re-read (the bus above) is reported like any
        // other: the form has no silent mode, so the last good values stay in
        // state but are not drawn, and the next re-read that succeeds takes the
        // screen back.
        run.fail(err);
      } finally {
        if (!cancelled) setLoading(false);
      }
    };

    if (objectSchema && !hasInlineFields) {
      fetchInitialData();
    }
    return () => { cancelled = true; };
  }, [schema.objectName, schema.recordId, schema.mode, schema.initialValues, schema.initialData, dataSource, objectSchema, hasInlineFields, hasInlineSource, recordRefetch]);

  // FormField `visibleOn` (spec FormFieldSchema CEL expression) is consumed
  // directly by the form renderer via the canonical engine — it accepts both
  // the bare-string and `{ dialect, source }` wire shapes (#2212). Fields are
  // passed through verbatim; the previous normalization attached a
  // `visible(formData)` closure backed by the legacy `evaluateCondition`
  // matcher, which is not a CEL evaluator and was never called downstream.
  const normalizeVisibility = useCallback((f: any): any => f, []);

  // Generate form fields from object schema, with inline members merged over it
  //
  // objectui#9778 — `customFields` MERGES, it does not replace. The registered
  // description of the member ("Field definitions merged over the set generated
  // from object metadata. With inline definitions and no data source, this
  // becomes the only field source.") is the contract, and the per-member merge
  // (now `mergeCustomFields`, objectui#10073) was written for it — but a
  // non-empty `customFields` used to return from here with
  // `setFormFields(schema.customFields.map(normalizeVisibility))` BEFORE the
  // generated set existed, so that lookup only ever ran over an empty array.
  // The three directions the merge now takes, one case each in
  // `objectFormCustomFieldsMembers-8071.test.tsx`:
  //   override — a member naming a declared field replaces that field's
  //              generated definition, in the generated set's position;
  //   keep     — a declared field no member names still renders;
  //   append   — a member naming a field the metadata never declares is added
  //              after the generated set, in authored order.
  // With no data source the generated set is empty, so the members remain the
  // only field source (the registration's second sentence) — unchanged. The
  // drawer and modal arms resolve their members through the same helper, pinned
  // per arm by `drawerModalCustomFieldsMerge-10073.test.tsx`.
  useEffect(() => {
    if (!objectSchema) return;

    // ⛔ No managed-object lock here (ADR-0092 D4). This generator used to
    // stamp it on the fields it generates, so only this arm drew it — and an
    // inline member replacing a generated field escaped it. The lock now runs
    // in `gateFormFields`, the one step every layout draws its resolved fields
    // through, with field-level security (objectui#10612).

    // Determine which fields to include
    const fieldsToShow = schema.fields || Object.keys(objectSchema.fields || {});
    
    // Support object format for fields in schema (legacy/compat)
    const fieldNames = Array.isArray(fieldsToShow) 
        ? fieldsToShow 
        : Object.keys(fieldsToShow);

    const resolved: Array<{ name: string; entry: (typeof fieldNames)[number] }> = [];
    fieldNames.forEach((fieldName) => {
      // If fieldsToShow is an array of strings, fieldName is the string
      // If fieldsToShow is array of objects (unlikely but possible in some formats), we need to extract name
      const name = typeof fieldName === 'string' ? fieldName : (fieldName as any).name;
      if (!name) {
        // objectui#8738 route 1: a member that resolves to no name (most
        // commonly the spec `FormFieldSchema` object, identity key `field`,
        // that IS legal in `sections[].fields`) used to vanish here without a
        // word. Warn, don't accept — see `warnUnresolvedTopLevelField`.
        warnUnresolvedTopLevelField(fieldName, schema.objectName);
        return;
      }
      resolved.push({ name, entry: fieldName });
    });

    // The generated half of the merge: `undefined` for a name the object does
    // not declare, which `mergeCustomFields` then draws only if a member names
    // it. Field-level permissions are enforced downstream by `gateFields`
    // (the real per-caller gate via `perms.checkField`); the schema itself
    // carries no per-caller permission bits (objectstack#3661).
    const generateField = (name: string, index: number): FormField | undefined => {
      const fieldName = resolved[index].entry;
      const field = objectSchema.fields?.[name];
      if (field) {
        // Auto-generate field from schema
        const formField: FormFieldWithGroup = {
          name: name,
          label: fieldLabel(schema.objectName, name, field.label || fieldName),
          // (type, multiple) decides the widget, not the type alone: a `select`
          // declared `multiple: true` renders the multi-value chip picker, whose
          // label must be associated by IDREF — a fact declared per WIDGET, so
          // the widget id has to carry the arity (objectui#3986).
          type: mapFieldTypeToFormType(field.type, { multiple: field.multiple }),
          // Mode-aware: a CREATE form does not enforce `required` on a field
          // whose `defaultValue` is a runtime instruction the server resolves
          // at insert (#4069). The control is left empty on purpose so the
          // server resolves it — refusing the submit would leave the user with
          // nothing sensible to type.
          required: isRequiredInForm(field, isCreateFormMode(schema)),
          disabled: schema.readOnly || schema.mode === 'view' || field.readonly,
          placeholder: field.placeholder,
          // The help line under the control: the spec's `inlineHelpText`,
          // else `description`, through the one read `fromObjectSchema`
          // shares (`fieldHelpText`, objectui#12213). A file or image field's
          // size hint is appended to it below.
          description: fieldHelpText(field),
          validation: buildValidationRules(field),
          // Field-level CEL conditional rules (B2). Carried through verbatim so
          // the form renderer evaluates them reactively via the canonical
          // engine (same dialect the server enforces). Undefined when absent.
          visibleWhen: field.visibleWhen,
          readonlyWhen: field.readonlyWhen,
          requiredWhen: field.requiredWhen,
          // Field-group membership (Field.group → object.fieldGroups[].key).
          // Carried through so the form can auto-derive sections from the
          // object's declared field groups when no explicit sections are given.
          group: field.group,
          // Important: Pass the original field metadata so widgets can access properties like precision, currency, etc.
          field: field,
          // A per-field widget override. `form.tsx` resolves `widget || type`, so this makes the
          // auto-generated (no-form-view) form honor the override just like the
          // authored-section path already does (sectionFields.ts).
          widget: (field as any).widget,
        };

        // Add field-specific properties
        if (field.type === 'select' || field.type === 'lookup' || field.type === 'master_detail') {
          formField.options = field.options || [];
          formField.multiple = field.multiple;
        }

        if (field.type === 'number' || field.type === 'currency' || field.type === 'percent') {
          formField.inputType = 'number';
          formField.min = field.min;
          formField.max = field.max;
          // No `step` is written here (objectui#12130): the control that
          // draws this field derives it. The registered `number`, `currency`
          // and `percent` widgets always derived their own and dropped this
          // key. The form renderer's own number input (a field whose `widget`
          // is `input`) now derives it from the metadata carrier
          // (`formField.field`, the raw object field assigned above) by the
          // `number` widget's rule: an explicit numeric `step` wins, else
          // `10^-scale` (decimal places, never `precision`'s total digit
          // count, objectui#9574), else `'any'`. This line used to write that
          // step onto the entry, `'any'` included, which the spec's numeric
          // `FieldSchema.step` refuses; `FormField` now declares `step` by
          // reference to it. `objectFormNumericStep-9574.test.tsx` pins both
          // routes.
        }

        if (field.type === 'date') {
          formField.inputType = 'date';
        }

        if (field.type === 'datetime') {
          formField.inputType = 'datetime-local';
        }

        // ⛔ DO NOT ADD A TYPE TO THIS LIST TO GIVE IT A LENGTH CAP. Measured
        // on this branch's base (objectui#8438): on THIS path the assignment
        // below reaches nothing, for every one of the four types it names.
        //
        // `formField` is the FORM FIELD; the metadata carrier a registered
        // `field:*` widget reads is `formField.field` — a DIFFERENT object,
        // assigned from the raw object-schema `field` further down. So
        // `TextAreaField` resolves its cap from that carrier directly and
        // never consults the key written here. Ablation, both configurations,
        // with the two statements below replaced by a comment: the rendered
        // `maxlength` attribute and the character counter were byte-identical
        // to the unablated run (a `textarea` with a 111 cap kept
        // `maxlength="111"` and its `0/111` counter; `markdown`, `html` and
        // `richtext` rendered no `maxlength` either way). That was measured on
        // objectui#8438's base, when the cap was spelled `max_length`; the
        // carrier split it measured is unchanged.
        //
        // ⇒ objectui#8438 was filed as "`richtext` is missing from this list".
        // It is — and adding it would have changed nothing observable, which is
        // exactly the 假绿 objectui#4250 named and objectui#4831 warned about.
        // The cap was unread for ALL THREE of the rich-content registry keys,
        // and the fix is the widget reading it: see the `maxLength` docblock in
        // `packages/fields/src/widgets/RichTextField.tsx`.
        //
        // Left in place rather than deleted: `formField.maxLength` IS live for
        // the OTHER producer of form fields — `EmbeddableForm`'s
        // `applyDefaultMaxLengths` writes it onto `customFields`, where the
        // form field IS the carrier — and removing a dead assignment is a
        // different question from this card's, on a shared file.
        if (field.type === 'text' || field.type === 'textarea' || field.type === 'markdown' || field.type === 'html') {
          // The spec's `maxLength` / `minLength` (`FieldSchema`), the one
          // spelling read — as in `buildValidationRules`. The snake_case pair
          // this also read until objectui#11070 is retired: the spec refuses
          // it by name, and no objectui type declares it.
          formField.maxLength = field.maxLength;
          formField.minLength = field.minLength;
        }

        if (field.type === 'file' || field.type === 'image') {
          formField.inputType = 'file';
          formField.multiple = field.multiple;
          formField.accept = field.accept ? field.accept.join(',') : undefined;
          // The size-limit hint reads the spec's `maxSize` (`FieldSchema`),
          // the one spelling: the snake_case `max_size` this read until
          // objectui#12156 is refused by the spec and declared by no objectui
          // type. `field` is untyped here, so nothing but
          // `objectFormFileSizeHint-12156.test.tsx` catches a misspelt read.
          // The words are the session locale's pack value (`form.maxFileSize`);
          // the number and unit stay `formatFileSize`'s.
          if (field.maxSize) {
            const sizeHint = t('form.maxFileSize', {
              size: formatFileSize(field.maxSize),
              defaultValue: 'Max size: {{size}}',
            });
            formField.description = formField.description 
              ? `${formField.description} (${sizeHint})` 
              : sizeHint;
          }
        }

        if (field.type === 'email') {
          formField.inputType = 'email';
        }

        if (field.type === 'phone') {
          formField.inputType = 'tel';
        }

        if (field.type === 'url') {
          formField.inputType = 'url';
        }

        if (field.type === 'password') {
          formField.inputType = 'password';
        }

        if (field.type === 'time') {
          formField.inputType = 'time';
        }

        // Read-only fields for computed types
        if (field.type === 'formula' || field.type === 'summary' || field.type === 'auto_number') {
          formField.disabled = true;
        }

        // Conditional visibility is the spec's `visibleWhen`, carried above.
        // The snake_case `visible_on` this builder also read until
        // objectui#12242 is retired with no alias: `FieldSchema` refuses it by
        // name (suggesting `visibleWhen`) and `BaseFieldMetadata` refuses it.

        return formField;
      }
      return undefined;
    };

    // objectui#9778 — override / keep / append, spelled ONCE in
    // `customFieldsMerge.ts` and shared with the drawer and modal arms
    // (objectui#10073), so every `formType` merges the same way.
    setFormFields(
      mergeCustomFields(
        resolved.map((r) => r.name),
        schema.customFields,
        generateField,
        normalizeVisibility,
      ),
    );

    // Only set loading to false if we are not going to fetch data
    // This prevents a flash of empty form before data is loaded in edit mode
    const willFetchData = !hasInlineFields && (schema.recordId && schema.mode !== 'create' && dataSource);
    if (!willFetchData) {
      setLoading(false);
    }
  }, [objectSchema, schema.fields, schema.customFields, schema.readOnly, schema.mode, schema.objectName, hasInlineFields, schema.recordId, dataSource, maxFileSizeSentence]);

  // The object's declared field defaults, as this form's opening values.
  //
  // CREATE ONLY (#4047). This pass used to run in every mode — on an edit form
  // it folded a default under a persisted row, so a column the record leaves
  // unset showed the default and the next save wrote a value the user never
  // chose. `!recordId || mode === 'create'` is the same "no persisted record"
  // test the data-fetch effect above uses, so the two cannot drift.
  //
  // It also used to seed `defaultValue` VERBATIM, including the runtime
  // instructions the server resolves per insert (`NOW()`, `current_user`, CEL
  // envelopes) — which put the literal text `NOW()` into a datetime input and
  // then submitted it, suppressing the resolution the declaration asked for.
  // `schemaDefaultValues` seeds static literals only; see that module.
  // Same shared "no persisted record" test the field builder above uses for
  // the create-mode `required` suppression (#4069), so seeding and validation
  // cannot disagree about which mode this form is in.
  const isCreateForm = isCreateFormMode(schema);
  // ADR-0144 D8 rule 4 — the organization currency a record-currency code
  // field opens on in create mode.
  const { currency: homeCurrency } = useLocalization();
  // [#5683] `currentUserId` lets the one client-resolvable token
  // (`current_user`) pre-fill with the id the server would stamp anyway;
  // null/unloaded seeds nothing and keeps the omit-and-let-the-engine-resolve
  // contract above.
  const schemaDefaults = React.useMemo(
    () => (isCreateForm ? schemaDefaultValues(objectSchema, { currentUserId: perms.userId, homeCurrency }) : {}),
    [objectSchema, isCreateForm, perms.userId, homeCurrency],
  );

  // What the form OPENS with: the seeded defaults, overlaid with the caller's
  // record. A create save judges a picked owner against exactly this
  // (objectui#12359), so both readers spell it through `formOpeningValues`.
  const finalDefaultValues = formOpeningValues(schemaDefaults, initialData);

  // The ONE field-gate step every layout draws through (objectui#10612):
  // field-level security plus the ADR-0092 D4 managed-object lock, which this
  // arm's field generator used to stamp on its own — see `gateFormFields`.
  const gateFields = useCallback(
    (fields: FormField[]): FormField[] =>
      gateFormFields(fields, {
        perms,
        objectName: schema.objectName,
        mode: schema.mode,
        objectSchema,
        deniedDescription,
        previousValues,
        // What the form opens with stays offered on a create (#27763).
        openingValues: finalDefaultValues,
      }) as FormField[],
    [perms, schema.objectName, schema.mode, objectSchema, deniedDescription, previousValues, finalDefaultValues],
  );

  // Handle form submission
  const handleSubmit = useCallback(async (formData: any, e?: any) => {
    // An upload is still in flight (objectui#10166). A `file`/`image` value is
    // only its fileId once the presigned upload settles, so writing now stores
    // the record WITHOUT the attachment and reports success — the silent loss
    // this guard exists to stop. Refuse and say why: the Save button already
    // reads "Uploading…" and the notice beside it carries the same sentence,
    // and this arm is what covers a keyboard submit (the flat path's button is
    // rendered by the `form` node renderer and cannot be disabled from here).
    if (uploadGate.uploading) {
      toast.error(uploadGate.reason);
      return;
    }
    // If we receive an event as the first argument, it means the Form renderer passed the event instead of data
    // This happens when react-hook-form's handleSubmit is bypassed or configured incorrectly
    if (formData && (formData.nativeEvent || formData._reactName === 'onSubmit')) {
      console.warn('ObjectForm: Received Event instead of data in handleSubmit! This suggests a Form renderer issue.');
      // Proceed defensively - we can't do much if we don't have data, but let's try to not crash
      // If we are here, formData is actually the event
      if (e === undefined) {
         // The event arrived as the first arg; discard it and submit empty data
         // rather than the Event object. (`e` is unused beyond this guard.)
         formData = {}; // Reset to empty object or we try to submit the Event object
      }
    }

    // No submit TARGET: a declared `submitHandler` owns the write and needs no
    // adapter of its own (objectui#6176's seam), so only a form with NEITHER it
    // nor a `dataSource` is target-less. The one target-less form that is still
    // legitimate is the inline-fields collector, whose `onSuccess` IS the write.
    // This arm used to be `hasInlineFields && !dataSource` alone, checked BEFORE
    // the persistence chain: a declared `submitHandler` was never reached, so a
    // host that had said it owns the write got a success signal for a write it
    // was never asked to perform (objectui#6388). Same rule and same precedence
    // as the five variant renderers — see `submitTarget.ts` for the whole rule.
    //
    // The predicate is the shared `hasInlineFieldSource`, as on the five other
    // renderers (objectui#11615). Its limb (a) is this component's own
    // `hasInlineFields` (non-empty `customFields`); its limb (b) — sections
    // whose EVERY field is a self-describing inline `FormField` — is now one
    // this renderer draws, because a section here draws such an entry whatever
    // the parent field pool holds (`buildSectionFields`). So a sections-only
    // form with no adapter collects exactly the fields its sections declare,
    // and `onSuccess` is that collector's write, as it is everywhere else.
    // Until objectui#11615 this renderer kept `hasInlineFields` alone, and
    // rightly: a section only SELECTED pooled fields then, so the same form
    // resolved zero fields, and counting it inline would have confirmed an
    // empty submit. Limb (b) is all-or-nothing, so one name-only entry in any
    // section still refuses below: a form that needed metadata it could not
    // get never reaches the carve-out. The refusal is the shared one, verbatim.
    if (!dataSource && !schema.submitHandler && hasInlineFieldSource(schema)) {
      if (schema.onSuccess) {
        await schema.onSuccess(formData);
      }
      return formData;
    }

    // What this save writes — the ONE outbound sequence, shared with the
    // `tabbed` and `wizard` layouts (objectui#10563): strip what a form never
    // writes (server-owned, computed, read-only, unknown to the object, and
    // refused by the caller's field-level security through `fieldWriteGate`,
    // objectui#10108 / `80c54122e`), omit the producer-owned defaults on a
    // create (#4069), and on an EDIT keep only the fields that differ from the
    // record this form read (objectui#10156). `writePayload` goes to BOTH write
    // routes below: the host-owned seam, which is how a master-detail form's
    // parent operation is built, and the plain OCC-guarded update. See
    // `formWritePayload` for the whole rule, including the inline-members
    // case. The full `payload` stays the submit-redirect scope below: it is
    // the record as the form now holds it, whether or not a field was written.
    const { payload, writePayload } = formWritePayload(formData, schema, {
      objectSchema,
      canEdit: fieldWriteGate(perms, schema.objectName, schema.mode),
      snapshot: loadedRecordRef.current,
      // The values this create form opened with, so a picked owner is written
      // and a seeded one left alone is not (objectui#12359). Rebuilt from the
      // same two inputs `finalDefaultValues` reads, not from that object, so
      // this callback does not change identity on every render.
      createBaseline: formOpeningValues(schemaDefaults, initialData),
    });

    try {
      let result;

      if (schema.submitHandler) {
        // The host owns persistence (e.g. MasterDetailForm batching the parent
        // + children into one atomic transaction). The form just validates and
        // hands over the values; it does NOT create/update itself.
        result = await schema.submitHandler(writePayload);
      } else if (!dataSource) {
        // No route left: no host seam and no adapter. Refuse instead of
        // reporting success — the `catch` below hands this to `schema.onError`
        // and rethrows. Expressing it here rather than in a pre-`try` guard is
        // what lets the `submitHandler` branch above run first, and it is also
        // what narrows `dataSource` for the routes below with no assertion.
        throw noSubmitTargetError();
      } else if (schema.mode === 'create') {
        result = await dataSource.create(schema.objectName, payload);
      } else if (schema.mode === 'edit' && schema.recordId) {
        // OCC-guarded: sends `ifMatch` from the record we read; a 409 asks the
        // user to keep editing (skip the success path) or overwrite.
        const outcome = await saveWithOcc({
          dataSource,
          objectName: schema.objectName,
          recordId: schema.recordId,
          payload: writePayload,
          baseRecord: initialData,
        });
        if (outcome.status === 'cancelled') return;
        result = outcome.result;
      } else {
        throw new Error('Invalid form mode or missing record ID');
      }
      // The write landed: the next save from this still-mounted form diffs
      // against the record as it now stands, not as first read.
      loadedRecordRef.current = advanceLoadedRecord(loadedRecordRef.current, schema, writePayload);
      // objectui#10572 — the edit has landed, so what the form shows is what the
      // server holds: a change held while it was dirty (its own write's bus
      // echo included) is replayed now, and a later echo re-reads in place
      // instead of being held behind input that is no longer unsaved. The next
      // keystroke reports dirty again through `onDirtyChange`.
      recordSaved();

      // Call success callback if provided, else give default feedback. Skip the
      // default when a `submitHandler` owns persistence (e.g. MasterDetailForm
      // already toasts) so we never double-confirm.
      if (schema.onSuccess) {
        await schema.onSuccess(result);
      } else if (!schema.submitHandler && schema.submitBehavior) {
        const behavior = schema.submitBehavior;
        switch (behavior.kind) {
          case 'redirect': {
            // objectstack#7496 ruled this url a RELATIVE in-app path with
            // `{{record.field_name}}` interpolation, URL-escaped when the
            // redirect is built. `resolveSubmitRedirect` asks the spec's own
            // `FormViewSchema` for the shape verdict and performs the
            // substitution — see that module for why the verdict is not
            // restated here and what it deliberately does not fix.
            //
            // The old line asked `isSameOriginUrl`, which accepts a same-origin
            // ABSOLUTE url the contract refuses at the authoring door, and
            // dropped everything else in SILENCE: the write had already
            // succeeded, so the submitter was left facing a still-filled form
            // with no feedback, and the obvious next move — submit again — wrote
            // a second record (objectui#4989 defects 2, 3 and 5).
            const verdict = resolveSubmitRedirect(
              behavior.url,
              submitRedirectScope(payload, result),
            );
            if (!verdict.ok) {
              // The write SUCCEEDED and only the destination is out of contract.
              // So both facts are shown: the confirmation panel (which also
              // removes the form, so there is nothing left to resubmit) and the
              // spec's own prescription for the author. Following the value
              // instead would be the spelling the contract refuses; dropping it
              // is the silence the ruling rules out.
              toast.error(verdict.refusal);
              setSubmitted({
                message: schema.successMessage
                  || (schema.mode === 'create' ? t('form.created') : t('form.saved')),
                refusal: verdict.refusal,
              });
              break;
            }
            // Record the destination; the effect that owns the wait takes it
            // from here (objectui#5033). Nothing about the verdict flow above
            // changes — this arm still decides WHETHER to navigate, only no
            // longer WHEN, because a timer armed here answered to nobody.
            setPendingRedirect({ url: verdict.url, delayMs: behavior.delayMs ?? 0 });
            break;
          }
          case 'continue':
            // Reset is driven declaratively by `resetOnSubmit` below (mirrors
            // `resetOnSuccess`) — nothing imperative to do here.
            break;
          case 'next-record':
          case 'thank-you':
          default: {
            const message = behavior.kind === 'thank-you' && behavior.message
              ? behavior.message
              : schema.successMessage || (schema.mode === 'create' ? t('form.created') : t('form.saved'));
            toast.success(message);
            // Replace the (still fully filled) form with a confirmation panel
            // so there's nothing left to resubmit.
            setSubmitted({ title: behavior.kind === 'thank-you' ? behavior.title : undefined, message });
            break;
          }
        }
      } else if (!schema.submitHandler) {
        const nav = resolveSuccessNavigate(schema.navigateOnSuccess, result);
        if (nav) {
          // An ACCEPTED `navigateOnSuccess` destination goes to the host —
          // objectui#5034, points 1 and 3.
          //
          // A rooted path such as `/apps/x/o/record/r1` handed to
          // `window.location.assign` resolves against the ORIGIN root, so under a
          // host mounted at a sub-path (the framework CLI configures one for
          // every embedded deployment; the console runs at basename `/_console`)
          // an authored in-app destination left the application. Only the host
          // knows its mount, and the seam that landed with PR #5111 is already
          // wired into this component — the state below and the effect that owns
          // it are 440 lines up. `delayMs: 0` reuses that one mechanism rather
          // than minting a second: this key declares no delay, and an unset delay
          // was already a zero timer, i.e. "go now". Reuse also hands this arm the
          // property objectui#5033 bought for the other one — unmounting cancels
          // the wait, so a navigation cannot fire into a form the submitter has
          // left.
          //
          // Handed over UNCONDITIONALLY, which is point 3's consequence rather
          // than a relaxation. `resolveSuccessNavigate` now admits relative
          // references only (maintainer ruling 2026-08-17: this key runs under the
          // objectstack#7496 semantics, so a same-origin ABSOLUTE is refused at
          // the door like any other out-of-contract value). `HostNavigationValue`
          // declares `to` to be "an already-resolved, application-relative path,
          // never an absolute URL … It is the CALLER's job to have judged the
          // destination" — and the caller has now judged it, once, at the
          // admission door instead of twice.
          //
          // The `window.location.assign(nav)` arm that used to stand here was
          // deleted as unreachable, not as unwanted: nothing can reach it once
          // every accepted value is relative. That is proved rather than reasoned
          // — `navigateOnSuccess.urlContract.test.tsx` pins, over a corpus,
          // that every value this helper accepts satisfies the predicate the arm
          // branched on. The absent-seam fallback is unchanged and still
          // `window.location.assign`; it lives in `useSubmitRedirectNavigation`.
          setPendingRedirect({ url: nav, delayMs: 0 });
          return result;
        }
        if (schema.navigateOnSuccess) {
          // Declared, and refused (objectui#5034 point 2). This is NOT the total
          // silence objectui#4989 defect 2 described — the submitter does get a
          // success toast, so they are not left facing a still-filled form and are
          // not invited to resubmit. The injury is narrower and real: that toast
          // was indistinguishable from the one a form with no `navigateOnSuccess`
          // produces, so the declared navigation failed with nobody told. The
          // write genuinely succeeded, so the fix is a note on the success — not
          // an error, not a blocking panel. The template goes to the console for
          // the author, where naming it cannot mislead the submitter.
          console.warn(
            '[ObjectForm] `navigateOnSuccess` was declared but produced no destination:',
            schema.navigateOnSuccess,
          );
          toast.success(
            schema.successMessage || (schema.mode === 'create' ? t('form.created') : t('form.saved')),
            { description: t('form.navigateRefused') },
          );
        } else {
          toast.success(schema.successMessage || (schema.mode === 'create' ? t('form.created') : t('form.saved')));
        }
      }

      return result;
    } catch (err) {
      console.error('Failed to submit form:', err);
      
      // Call error callback if provided
      if (schema.onError) {
        schema.onError(err as Error);
      }
      
      throw err;
    }
  }, [schema, dataSource, perms, objectSchema, saveWithOcc, initialData, schemaDefaults, uploadGate.uploading, uploadGate.reason, recordSaved, t]);

  // Handle form cancellation
  const handleCancel = useCallback(() => {
    if (schema.onCancel) {
      schema.onCancel();
    }
  }, [schema]);


  // Auto-layout parity with the flat path (which runs these inside
  // applyAutoLayout): drop platform-managed system fields — and, in create
  // mode, server-computed fields — BEFORE deriving field-group sections, so a
  // grouped form hides exactly the fields the flat form hides instead of
  // leaking created_at / formula columns into the trailing ungrouped bucket.
  const groupableFields = React.useMemo(() => {
    let fs = filterSystemFields(formFields, objectSchema);
    if (schema.mode === 'create') fs = filterAutoGeneratedFields(fs, objectSchema);
    return fs;
  }, [formFields, objectSchema, schema.mode]);

  // Auto-derive sections from the object's declared `fieldGroups` when the
  // consumer hasn't supplied explicit sections. This makes field groups laid
  // out in the object designer render as sections on the actual form — not just
  // in the designer preview. Falls back to a flat form (null) when the object
  // declares no groups or no field opts into one.
  const fieldGroupSections = React.useMemo(
    () =>
      schema.sections?.length
        ? null
        : deriveFieldGroupSections(groupableFields, objectSchema?.fieldGroups),
    [schema.sections, groupableFields, objectSchema],
  );
  const effectiveSections = schema.sections?.length ? schema.sections : fieldGroupSections;

  // Per-section collapse state for the simple grouped form. Keyed by section
  // name/label; an unseeded key falls back to the section's declared `collapsed`
  // (so a group declared `collapsed: true` starts closed without pre-seeding).
  const [collapsedSections, setCollapsedSections] = useState<Record<string, boolean>>({});

  // Render error state
  if (error) {
    return (
      <div className="p-3 sm:p-4 border border-red-300 bg-red-50 rounded-md">
        <h3 className="text-red-800 font-semibold">{t('form.errorLoading')}</h3>
        <p className="text-red-600 text-sm mt-1">{error.message}</p>
      </div>
    );
  }

  // Render loading state
  if (loading) {
    return (
      <div className="p-4 sm:p-8 text-center">
        <div className="inline-block animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900"></div>
        <p className="mt-2 text-sm text-gray-600">{t('publicForm.loading')}</p>
      </div>
    );
  }

  if (submitted) {
    const confirmation = (
      <div className="rounded-md border bg-card p-6 sm:p-8 text-center">
        <h3 className="text-lg font-semibold">{submitted.title ?? t('publicForm.thankYouTitle')}</h3>
        {submitted.message && (
          <p className="mt-2 text-sm text-muted-foreground">{submitted.message}</p>
        )}
      </div>
    );
    // A refused `redirect` destination (objectui#4989) keeps the confirmation —
    // the record WAS written — and adds the reason nothing was navigated to.
    // `role="alert"` because this appears after the submit the user just made,
    // so it has to reach a screen reader without a focus move.
    if (!submitted.refusal) return confirmation;
    return (
      <div className="space-y-4">
        {confirmation}
        <div
          role="alert"
          className="rounded-md border border-destructive/40 bg-destructive/10 p-4 text-sm text-destructive"
        >
          {submitted.refusal}
        </div>
      </div>
    );
  }

  // Convert to FormSchema. `layout` is `vertical | horizontal` on both faces
  // since objectui#11168 slice 3 (objectui#7759 group C); the fold that mapped
  // the retired `inline` / `grid` to `vertical` here is retired with them.
  const formLayout = schema.layout ?? 'vertical';

  // Clear after a save ("save and add another"): `submitBehavior: { kind:
  // 'continue' }`, or the legacy `resetOnSuccess` on a create form when no
  // `submitBehavior` is declared. ONE rule, read by both the sectioned and the
  // flat `form` node below — the sectioned node used to carry none, so a
  // grouped form kept the saved record's values while the flat one cleared
  // (objectstack#27602).
  const resetOnSubmit = schema.submitBehavior?.kind === 'continue'
    || (!schema.submitBehavior && schema.resetOnSuccess && schema.mode === 'create');

  // If sections are provided (explicitly, or derived from the object's
  // `fieldGroups`) for the simple form, render them as full-width, optionally
  // collapsible groups.
  //
  // All sections share ONE SchemaRenderer / react-hook-form instance: a virtual
  // `section-divider` field renders each group's header, and the group's own
  // fields follow inline. This is the same single-form pattern DrawerForm uses,
  // and it matters for correctness — N separate per-section <form> elements
  // would each own isolated form state, so a submit (which only fired the last
  // section) silently dropped every other group's edits. One form also lets
  // collapse simply hide a group's fields (`hidden: true`) while react-hook-form
  // retains their values, and lets cross-section conditions resolve via watch().
  if (effectiveSections?.length && (!schema.formType || schema.formType === 'simple')) {
    // Derived (fieldGroup) sections were computed from the filtered field list;
    // explicit sections keep the authored field selection as-is.
    const sourceFields = fieldGroupSections ? groupableFields : formFields;
    // objectstack-ai/objectstack#2578: honour per-section `columns`. The form renders as ONE grid (one
    // react-hook-form instance); each section lays its OWN fields out at its
    // declared density within that grid. The one sectioned-form rule
    // (objectui#12548) is handed the AUTHORED counts and resolves the rest: grid
    // width = explicit form `columns`, else the widest section, a section that
    // declares nothing — a fieldGroup-derived one included — drawing two per
    // row from `@md`, as the dialog does (objectui#12592). 12 tracks wide when
    // the counts do not all fit.
    const sectionGrid = sectionedGridLayout(
      schema.columns,
      effectiveSections.map(s => (s as any).columns),
    );
    const formColumns = sectionGrid.columns;
    const groupedFields: FormField[] = [];
    // The section builder every other arm uses (objectui#10475), handed this
    // arm's parent field POOL: a section's members come out in the section's
    // AUTHORED order with each entry's full override set applied (`label`,
    // `required`, `readonly`, `helpText`, `visibleWhen`, …), onto the POOLED
    // field as the base. The pool still decides membership (objectui#9884's
    // intersection, warned below) and the per-field facts only this arm's
    // generator knows — see `SectionFieldsContext.pool`.
    const sectionCtx: SectionFieldsContext = {
      objectSchema,
      objectName: schema.objectName,
      readOnly: schema.readOnly,
      mode: schema.mode,
      recordId: schema.recordId,
      fieldLabel,
      customFields: schema.customFields,
      pool: sourceFields,
    };
    effectiveSections.forEach((section, index) => {
      // ⚠️ `?? []`, not a bare `.map` — the second containment layer for
      // objectui#7051. The group-reference resolution above this component
      // means a `{ group }` section never arrives here carrying no `fields`,
      // but this loop runs in `SimpleObjectForm`'s own body, ABOVE the JSX it
      // returns: a throw here is outside every per-section subtree, so no
      // error boundary that a section could own would contain it. That is
      // exactly how a spec-legal section blanked the entire form — the
      // well-formed siblings with it — before objectui#7051. `buildSectionFields`
      // spells the same read `section.fields ?? []` for the members below.
      // NAME-ONLY entries only: a self-describing inline entry is drawn
      // whatever the pool holds (objectui#11615, `isInlineFieldDef`), so it is
      // never one the intersection below drops, and naming it there would
      // report a loss that did not happen.
      const sectionFieldNames = (section.fields ?? [])
        .filter(entry => !isInlineFieldDef(entry))
        .map(sectionEntryName);

      // objectui#9884 — make the INTERSECTION audible.
      //
      // The builder below resolves a section's members against the parent field
      // POOL, and that pool was built from `schema.fields` (`fieldsToShow`
      // above). So top-level `fields` and `sections` intersect: a member this
      // section names, that the object really declares, is dropped for the one
      // reason that `fields` does not list it — and when it was the section's
      // last surviving member, `sectionFields.length === 0` below drops the
      // section whole, heading included.
      //
      // ⛔ The intersection itself is NOT the defect and is deliberately left
      // standing: `fields` is the parent field pool that bounds what this form
      // DRAWS and edits, so resolving these members here would change what a
      // landed schema draws and lets a user edit. It does not bound the write
      // itself: a value seeded through `initialValues` is written whether or
      // not it is drawn (objectui#11114). What WAS
      // the defect is that the loss was silent, plus this block's registration
      // claiming `fields` is "Ignored when `sections` is given" — a claim its
      // three sibling `fields` registrations never made and the one shared
      // renderer never honoured. objectui#9884 corrected the sentence and
      // added this warning; see `warnSectionMemberExcludedByFields`.
      //
      // Measured BEFORE `gateFields`, on purpose: a field the pool holds
      // and per-caller permissions then remove is not an authoring mistake and
      // must not be reported as one.
      if (schema.fields != null && schema.sections?.length) {
        const pooled = new Set(sourceFields.map(f => f.name));
        sectionFieldNames.forEach(memberName => {
          if (typeof memberName !== 'string' || pooled.has(memberName)) return;
          // Only when the member WOULD have resolved without the `fields`
          // narrowing. A member naming nothing the form could ever draw is the
          // sibling silence pinned by row 2 of both `sections` member pins, and
          // it has a different remedy.
          const declared =
            objectSchema?.fields?.[memberName] != null ||
            (schema.customFields ?? []).some((f: any) => f?.name === memberName);
          if (!declared) return;
          warnSectionMemberExcludedByFields(
            memberName,
            schema.objectName,
            section.name || section.label,
          );
        });
      }

      // Field-level permissions gate the BUILT members, after the entry
      // overrides — the order the drawer and modal arms apply them in — so no
      // override can re-open a field the caller may not edit.
      const sectionFields = gateFields(buildSectionFields(section, sectionCtx));
      if (sectionFields.length === 0) return;

      const sectionKey = section.name || section.label || String(index);
      // Untitled trailing bucket (ungrouped fields): no divider row. The
      // renderer still draws it as its own block, split off where the previous
      // heading's membership claim ends (objectui#11777).
      const label = section.name
        ? sectionLabel(schema.objectName, section.name, section.label || section.name)
        : section.label;
      // `collapsed` IMPLIES `collapsible` (objectui#9780), read from the
      // DECLARATION — through `resolveSectionCollapse`, the ONE resolution
      // every arm calls (objectui#9849). The control lives on the divider row
      // (director ruling letter E, item 3), so a member yielding neither a
      // heading nor a blurb is never collapsible, never loses its fields, and
      // is reported if it declared the pair.
      const collapse = resolveSectionCollapse(section, {
        live: collapsedSections[sectionKey],
        title: label,
        description: section.description,
        where: `ObjectForm section '${sectionKey}' of object '${schema.objectName}'`,
        setCollapsed: next => setCollapsedSections(prev => ({ ...prev, [sectionKey]: next })),
      });

      // The ONE path from a section configuration to its divider row, and the
      // ONE row rule (objectui#9849, director ruling letter E): the ADR-0089
      // predicate and the objectui#6236 membership claim ride the group on
      // every arm whether or not it yields a heading, and the visible row
      // exists iff `title || description`. See `projectSectionDivider`.
      groupedFields.push(
        ...projectSectionDivider({
          key: sectionKey,
          title: label,
          description: section.description,
          visibleWhen: (section as any).visibleWhen,
          visibleWhenFault: section.visibleWhenFault,
          // RESOLVED rather than authored on purpose: the authored
          // `section.fields` entries can be spec field-defs, and a
          // perms-filtered field is not in the form at all.
          members: sectionFields.map(f => f.name),
          collapse,
        }),
      );

      // objectstack-ai/objectstack#2578: lay THIS section's fields out at its declared column density
      // within the shared form grid (span-aware; wide fields still full-row).
      const laid = sectionGrid.layOut(sectionFields, (section as any).columns);

      // Collapsed groups keep their fields registered (values preserved) but
      // hidden from the DOM. A section with no row is never collapsible, so it
      // is never collapsed either — `resolveSectionCollapse` answers both.
      if (collapse.collapsed) {
        groupedFields.push(...laid.map(f => ({ ...f, hidden: true })));
      } else {
        groupedFields.push(...laid);
      }
    });

    // Per-section colSpan was applied in the loop above — each section at its
    // own density within the shared `formColumns` grid. The field grid uses
    // container-query classes (with the @container wrapper below), so it tracks
    // the form's own width: a grouped form in a wide dialog goes multi-column
    // while a narrow drawer stays stacked. Section dividers span the full row.
    const laidOutFields = groupedFields;
    const fieldContainerClass = sectionGrid.fieldContainerClass;

    return (
      <UploadGateProvider gate={uploadGate}>
        <div className="w-full @container">
          {closedAffordanceNotice}
          <SchemaRenderer
            schema={{
              type: 'form',
              objectName: schema.objectName,
              fields: laidOutFields,
              layout: formLayout,
              columns: formColumns,
              ...(fieldContainerClass ? { fieldContainerClass } : {}),
              defaultValues: finalDefaultValues,
              previousValues,
              showSubmit: schema.showSubmit !== false && schema.mode !== 'view',
              showCancel: schema.showCancel !== false,
              // The declared Reset button (objectstack#27247); see the flat path.
              showReset: schema.showReset === true && schema.mode !== 'view',
              resetOnSubmit,
              // While an upload is in flight the Save button says so, the same
              // answer ActionParamDialog gives its Confirm button. The notice
              // below carries the reason in a sentence (objectui#10166).
              submitLabel: uploadGate.uploading
                ? uploadGate.busyLabel
                : schema.submitText || (schema.mode === 'create' ? t('form.create') : t('form.update')),
              cancelLabel: schema.cancelText,
              onSubmit: handleSubmit,
              onCancel: handleCancel,
              onDirtyChange: handleDirtyChange,
            } as FormSchema}
          />
          <UploadInFlightNotice gate={uploadGate} />
          {conflictDialog}
        </div>
      </UploadGateProvider>
    );
  }

  // Apply auto-layout: infer columns and colSpan when not explicitly configured
  const hasSections = schema.sections?.length;
  const gatedFormFields = gateFields(formFields);
  const autoLayoutResult = !hasSections
    ? applyAutoLayout(gatedFormFields, objectSchema, schema.columns, schema.mode)
    : { fields: gatedFormFields, columns: schema.columns };

  // ----- Mobile UX (round 3) -----
  // 1) Propagate fullscreen-textarea opt-in to each textarea field so the
  //    field widget can render its expand affordance + dialog.
  //
  //    `mobile_fullscreen` is a PROJECTION of this form-level setting onto the
  //    field metadata — this component is its one and only producer, and the
  //    flag has one and only one legal carrier: the object the form renderer
  //    forwards to the widget as `field`. That object is `f.field || f`
  //    (`renderFieldComponent` in `@object-ui/components`): the stashed
  //    object-field metadata when there is one, else the FormField itself.
  //
  //    Stamping it on `f` unconditionally was the objectui#3245 break. For an
  //    AUTO-GENERATED field `.field` exists, so the widget was handed the raw
  //    metadata (flag-free) while the FormField-level copy was dropped by
  //    `stripRegisteredFieldProps` — every generated form silently lost the
  //    feature, and only the hand-authored `customFields` path (no `.field`)
  //    ever worked. Resolving the carrier the same way the renderer does keeps
  //    both paths on ONE key in ONE place (objectui#3232 / #3233): no widget
  //    reads a second spelling, so a flag written anywhere else stays dead
  //    instead of being quietly caught by a fallback.
  //
  //    Every type below has a READER, which is what makes the stamp mean
  //    something (objectui#3301): `textarea` is the form renderer's built-in
  //    branch, `field:textarea` is `TextAreaField`, and `field:markdown` /
  //    `field:html` / `field:richtext` ALL resolve to `RichTextField` — which
  //    reads the flag since #3301, so `ObjectFormSchema.mobile`'s documented
  //    "textarea/rich-text get an expand button" is true of rich text as well.
  //
  //    `field:richtext` was missing from this list until objectui#4831, and it
  //    is the ONE spelling `@objectstack/spec` itself uses: `FieldType` spells
  //    the type `richtext` (`markdown` / `html` are the other two), the alias
  //    table maps `richtext → field:richtext` (`field-type-alias.ts`), and the
  //    widget map resolves `richtext` to `RichTextField` right beside the other
  //    two (`fields/src/index.tsx`). So the reader had been there all along and
  //    two of that widget's THREE registry keys were stamped — a field authored
  //    exactly as the spec prescribes was the only one that got nothing. Same
  //    shape as objectui#4250, which found the same hole in the twin set below
  //    (`WIDE_FIELD_TYPES` in `./autoLayout`) and closed it the same way.
  //
  //    Why this stays a hand-written list rather than becoming "whatever
  //    resolves to a long-text widget" (measured for #4831, both candidates):
  //    `fieldWidgetMap` is module-private and its entries are distinct arrow
  //    closures over distinct `import()`s, so widget IDENTITY is observable
  //    only by awaiting a dynamic import — this stamp is a synchronous `.map()`
  //    during render, so deriving from it means eagerly loading every widget
  //    module, the exact cost the lazy registry exists to avoid.
  //    `mapFieldTypeToFormType` records no "these three are one widget" fact
  //    either: it maps each spelling to its own value. And NEITHER source can
  //    account for `'textarea'`, which is not a registry key at all but the
  //    form renderer's built-in branch (`BUILTIN_FIELD_TYPES`). There is no
  //    single source to derive from; inventing one would put a second
  //    definition of "long text" in the repo, so the list stays explicit and
  //    the behavioural pin in `__tests__/ObjectForm.mobileFullscreen.test.tsx`
  //    is what keeps it honest (never an assertion that a literal is present —
  //    that is the fake-green shape objectui#4250 named).
  //
  //    A sixth type, `'string-multiline'`, was stamped here until #3301 and is
  //    gone: `grep -rn "string-multiline"` across BOTH this repo and
  //    `objectstack` (excluding node_modules/dist) returned exactly one hit —
  //    this line. No producer emitted it, no registry key matched it, and no
  //    widget read it, so the branch could only ever be false. Stamping types
  //    nobody produces is how a flag comes to look supported while doing
  //    nothing; a type belongs here once something can actually render it.
  const mobileOpts = schema.mobile;
  const fieldsWithMobile = mobileOpts?.fullscreenLongText
    ? autoLayoutResult.fields.map((f) => {
        const t = f.type as string | undefined;
        const isTextarea = t === 'textarea' || t === 'field:textarea' ||
          t === 'field:markdown' || t === 'field:html' ||
          t === 'field:richtext';
        if (!isTextarea) return f;
        return f.field
          ? { ...f, field: { ...f.field, mobile_fullscreen: true } }
          : { ...f, mobile_fullscreen: true };
      })
    : autoLayoutResult.fields;

  // 2) Auto-stepper: when explicitly enabled, OR when set to 'auto' on a
  //    long form on a small viewport, route the flat field list through
  //    WizardForm with one (or a few) fields per step.
  const stepperMode = mobileOpts?.stepper;
  const stepperMin = mobileOpts?.stepperMinFields ?? 8;
  const fieldsPerStep = Math.max(1, mobileOpts?.stepperFieldsPerStep ?? 1);
  const wantsStepper =
    !schema.formType &&
    !hasSections &&
    fieldsWithMobile.length >= 2 &&
    (
      stepperMode === true ||
      (stepperMode === 'auto' && isMobile && fieldsWithMobile.length >= stepperMin)
    );

  if (wantsStepper) {
    const visibleFields = fieldsWithMobile;
    const syntheticSections = [] as Array<{ name: string; label?: string; fields: FormField[] }>;
    for (let i = 0; i < visibleFields.length; i += fieldsPerStep) {
      const chunk = visibleFields.slice(i, i + fieldsPerStep);
      syntheticSections.push({
        name: `step-${Math.floor(i / fieldsPerStep) + 1}`,
        label: chunk[0]?.label || chunk[0]?.name || `Step ${Math.floor(i / fieldsPerStep) + 1}`,
        fields: chunk,
      });
    }
    return (
      <WizardForm
        schema={{
          ...schema,
          formType: 'wizard',
          sections: syntheticSections,
          showStepIndicator: true,
        } as any}
        dataSource={dataSource}
        className={schema.className}
      />
    );
  }

  // Default flat form (no sections)
  const formSchema: FormSchema = {
    type: 'form',
    objectName: schema.objectName,
    fields: fieldsWithMobile,
    layout: formLayout,
    columns: autoLayoutResult.columns,
    // See the sections path above: the label is the affordance's own
    // explanation while an upload is in flight (objectui#10166).
    submitLabel: uploadGate.uploading
      ? uploadGate.busyLabel
      : schema.submitText || (schema.mode === 'create' ? t('form.create') : t('form.update')),
    cancelLabel: schema.cancelText,
    showSubmit: schema.showSubmit !== false && schema.mode !== 'view',
    showCancel: schema.showCancel !== false,
    // `showReset` is the declared Reset button — "Show the reset button" in
    // the spec's block contract — drawn by the form's action bar and
    // restoring the opening values without a save. It is NOT a clear after
    // submit: it used to be OR-ed into `resetOnSubmit` below, so `true` drew
    // no button and emptied the form after every save (objectstack#27247).
    showReset: schema.showReset === true && schema.mode !== 'view',
    resetOnSubmit,
    defaultValues: finalDefaultValues,
    previousValues,
    onSubmit: handleSubmit,
    onCancel: handleCancel,
    onDirtyChange: handleDirtyChange,
    className: schema.className,
    mobileStickyActions: Boolean(mobileOpts?.stickyActions),
  };

  return (
    <UploadGateProvider gate={uploadGate}>
      <div
        className={mobileOpts?.stickyActions ? 'w-full pb-20 md:pb-0' : 'w-full'}
        data-mobile-form={mobileOpts ? 'true' : undefined}
      >
        {closedAffordanceNotice}
        <SchemaRenderer schema={formSchema} />
        <UploadInFlightNotice gate={uploadGate} />
        {conflictDialog}
      </div>
    </UploadGateProvider>
  );
};