@object-ui/plugin-form 11.2.0 → 11.4.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # @object-ui/plugin-form
 
+## 11.4.0
+
+### Minor Changes
+
+- 8bf6295: feat: adaptive record surface + semantic field span + responsive columns (framework#2578)
+
+  Field-heavy objects (all metadata is AI-authored) now present themselves without
+  any authored presentation config:
+
+  - **Adaptive surface** — a record's create/edit/detail opens as a full page when
+    the object is field-heavy, or a drawer when it is light. Derived from field
+    count (`deriveRecordSurface`), not authored; mobile always pages. Wired into the
+    app-shell ObjectView detail navigation (an authored view/object `navigation`
+    still wins).
+  - **Semantic field span** — `FormField.span` (`auto`/`full`) is a width primitive
+    decoupled from the (per-surface derived) column count; legacy `colSpan` is
+    clamped so it never overflows. `ObjectForm` now honours per-section `columns`
+    and carries `span`/`colSpan` from section defs — fixes the bug where
+    `type:'simple'` ignored `section.columns` and grouped fields rendered single
+    column.
+  - **Responsive columns** — `inferColumns` scales the column CAP with field count
+    (≤3→1, ≤8→2, ≤15→3, 16+→4); the ACTUAL column count follows the form's real
+    width via CSS container queries, so the same form goes 1→2→3→4 columns as a
+    drawer widens or becomes a page.
+  - **Runtime overlay width** — `NavigationConfig.size` bucket is resolved to a
+    viewport-clamped width at runtime (`overlayWidthFor`); a pixel width is never
+    authored (the author cannot know the client viewport).
+
+- 144ab55: Consume the ADR-0085 object semantic roles from `@objectstack/spec@11.7.0`, retiring the per-surface hint dialects:
+
+  - **Single-source fieldGroups derivation**: `plugin-form`'s `deriveFieldGroupSections` and `plugin-detail`'s `deriveFieldGroupDetailSections` are now thin adapters over the spec's `deriveFieldGroupLayout` (ADR-0085 §5) — forms, modals and detail pages render the SAME grouping from one implementation. The canonical `collapse: 'none' | 'expanded' | 'collapsed'` enum is honoured everywhere (deprecated `collapsible`/`collapsed` and `defaultExpanded` spellings still read for pre-11.7 metadata).
+  - **`stageField` semantic role**: the detail stepper reads the top-level `stageField`; `stageField: false` now actually suppresses stage detection (previously the `false` handling was wired to the removed `detail.stageField` key, so spec-authored `false` fell through to the name heuristic).
+  - **`highlightFields` rename**: default grid columns, card compact views, the detail highlight strip, child-record preview fields and interface-page default columns read the object's `highlightFields` (deprecated `compactLayout` spelling read as fallback for pre-11.7 metadata).
+  - **Removed dead reads**: the never-spec-writable `objectDef.views.*` UI hints and the ADR-0085-removed `detail.*` block (`sections`, `sectionGroups`, `highlightFields`, `stageField`, `useFieldGroups`, `showReferenceRail`, `hideReferenceRail`, `hideRelatedTab`, `relatedLayout`) are no longer consulted. Per-page customization goes through an assigned Page schema (`record:reference_rail` remains available there as a renderer capability). `detail.renderViaSchema` survives only as the legacy-renderer kill-switch and is removed together with that path.
+
+### Patch Changes
+
+- c38d107: Fix view-level `FormField.visibleOn` (CEL) never taking effect (#2212).
+
+  The spec ships `visibleOn` as an Expression object `{ dialect: 'cel', source }`
+  (what the `P` template emits) or a bare string, but the whole chain dropped it:
+
+  - `sectionFields.ts` / `ObjectForm.tsx` only accepted the bare-string shape and
+    attached a dead `visible()` closure no renderer ever called — the Expression
+    object shape was silently discarded.
+  - The form renderer destructured `visibleOn` out of the field config and never
+    evaluated it.
+  - `RecordFormPage` dropped a `simple` form view's `sections` entirely, so
+    page-mode create/edit fell back to the raw schema (every field, no authored
+    selection/grouping) while the modal path honored the same view.
+  - `ObjectForm`'s grouped-sections path matched section fields by name only,
+    dropping per-field `visibleOn` overrides.
+
+  `visibleOn` now flows through normalization verbatim (both wire shapes) and is
+  evaluated reactively by the form renderer with the canonical expression engine
+  (`evalFieldPredicate` — same engine, record scope, and fail-open semantics as
+  field-level `visibleWhen`; both predicates must allow a field for it to show).
+  Sectioned/flat normalization also copies field-level `visibleWhen` /
+  `readonlyWhen` / `requiredWhen` rules it previously lost.
+
+- 1e9145d: Hydrate widget types on hand-authored master-detail subform columns. A view can
+  list a child grid's columns as bare `{ field, label }` (the common authoring
+  form); previously such untyped columns were passed straight to the grid, so a
+  `select` / `lookup` / `date` / `number` field silently rendered as a plain text
+  cell. `MasterDetailForm` (and `deriveDetail`) now resolve each untyped column's
+  `type` (plus `options` / `reference` / computed `expr`) from the child object's
+  schema via the new `hydrateColumns` helper — a picklist becomes a dropdown, a
+  lookup a record picker, a date a date input — while preserving the author's
+  exact column set, order and labels. Columns that already declare a `type` are
+  left untouched (the author's explicit choice still wins).
+- Updated dependencies [8bf6295]
+- Updated dependencies [1948c5b]
+- Updated dependencies [bce581a]
+- Updated dependencies [9cd9be1]
+- Updated dependencies [5160832]
+- Updated dependencies [69d6b94]
+- Updated dependencies [c38d107]
+- Updated dependencies [243a9ba]
+- Updated dependencies [289be5b]
+- Updated dependencies [7782698]
+- Updated dependencies [19f2533]
+- Updated dependencies [790558b]
+- Updated dependencies [09e1b26]
+- Updated dependencies [e84d64d]
+  - @object-ui/types@11.4.0
+  - @object-ui/components@11.4.0
+  - @object-ui/fields@11.4.0
+  - @object-ui/i18n@11.4.0
+  - @object-ui/core@11.4.0
+  - @object-ui/permissions@11.4.0
+  - @object-ui/react@11.4.0
+
+## 11.3.0
+
+### Patch Changes
+
+- Updated dependencies [d88c8ec]
+- Updated dependencies [b7237bb]
+- Updated dependencies [d23d6eb]
+  - @object-ui/components@11.3.0
+  - @object-ui/i18n@11.3.0
+  - @object-ui/core@11.3.0
+  - @object-ui/fields@11.3.0
+  - @object-ui/react@11.3.0
+  - @object-ui/types@11.3.0
+  - @object-ui/permissions@11.3.0
+
 ## 11.2.0
 
 ### Patch Changes

package/dist/autoLayout.d.ts

@@ -8,21 +8,49 @@ export declare function isWideFieldType(type: string): boolean;
  */
 export declare function isAutoGeneratedFieldType(type: string): boolean;
 /**
- * Infer optimal number of columns based on the number of visible fields
- * and whether any wide fields are present.
+ * Infer the MAX column count from the field count (#2578). This is an UPPER
+ * BOUND — the actual column count at render time is decided by the CSS
+ * container queries in {@link CONTAINER_GRID_COLS} against the form's REAL
+ * width, so a narrow drawer stays 1–2 columns while the SAME form on a wide
+ * page spreads out to this cap. The cap scales with field count so a light
+ * form is never thinned across too many columns, while a field-heavy record
+ * can use the full width.
  *
- * Rules:
- * - 0-3 fields → 1 column
- * - 4+ fields → 2 columns
+ * Rules (upper bound; container queries clamp to the actual width):
+ * - 0–3 fields  → 1 column
+ * - 4–8 fields  → 2 columns
+ * - 9–15 fields → 3 columns
+ * - 16+ fields  → 4 columns
  */
 export declare function inferColumns(fieldCount: number): number;
 /**
- * Apply colSpan to wide fields so they span the full row.
- * Only sets colSpan if the field does not already have one explicitly set.
+ * Resolve the effective colSpan (grid cells) a field occupies, given the form's
+ * grid width and the section's desired column count (#2578).
  *
+ * The column count is derived per surface (mobile 1 / modal 2 / page 3-4), so
+ * the robust field-width primitive is the relative `span`, NOT an absolute
+ * colSpan. Precedence:
+ *   1. `span: 'full'`     → whole row (grid cells).
+ *   2. legacy `colSpan`   → honoured but CLAMPED to the grid (never overflows).
+ *   3. wide widget type   → whole row (textarea/markdown/… — the `span:'auto'` default).
+ *   4. section density    → grid / sectionColumns, so `sectionColumns` fields fill a row.
+ *
+ * `sectionColumns` defaults to the grid width, i.e. one field per cell (the flat
+ * form's historical behaviour) when there is no narrower section.
+ */
+export declare function resolveColSpan(field: FormField, gridColumns: number, sectionColumns?: number): number;
+/**
+ * Apply the resolved colSpan to each field so the form's CSS grid lays them out
+ * at the intended density. Span-aware and clamping (#2578); wide fields still
+ * span the full row (the `span: 'auto'` default). `section-divider` rows are
+ * left untouched (they carry their own full-row span).
+ *
+ * @param gridColumns    The form's grid column count (1-4).
+ * @param sectionColumns The desired columns for THIS group of fields (defaults
+ *                       to the grid width = one field per cell).
  * @returns A new array of fields with colSpan applied where needed.
  */
-export declare function applyAutoColSpan(fields: FormField[], columns: number): FormField[];
+export declare function applyAutoColSpan(fields: FormField[], gridColumns: number, sectionColumns?: number): FormField[];
 /**
  * Filter out auto-managed system fields (id, audit timestamps, tenant/owner ids).
  * Applied in BOTH create and edit modes, because these fields are always
@@ -54,6 +82,37 @@ export declare function filterCreateModeFields(fields: FormField[], objectSchema
  * their current computed values rendered as readonly.
  */
 export declare function filterAutoGeneratedFields(fields: FormField[], objectSchema?: any): FormField[];
+/**
+ * Container-query-based grid classes for laying out form FIELDS inside a
+ * section. Uses `@container` / `@md:` / `@2xl:` / `@4xl:` variants so the grid
+ * responds to the form's actual width (modal / drawer / split panel) instead of
+ * the viewport — a narrow modal stays single-column regardless of viewport size.
+ *
+ * `1` maps to `undefined` so the caller falls back to the form renderer's
+ * default single-column stack (`space-y-4`).
+ */
+export declare const CONTAINER_GRID_COLS: Record<number, string | undefined>;
+/** Clamp an arbitrary column count into the 1–4 keys of {@link CONTAINER_GRID_COLS}. */
+export declare function containerGridColsFor(columns: number | undefined): string | undefined;
+/**
+ * Build the layout-related props for a *section's* inner form (`SchemaRenderer`).
+ *
+ * A section groups its fields and lays them out in `columns` columns. That grid
+ * must be applied to the FIELD container INSIDE the form — not wrapped around
+ * the whole form element. Wrapping the single `<form>` in a multi-column grid
+ * (as the section variants used to) puts the entire form in the first grid cell
+ * and leaves every other column permanently empty. Here we instead thread
+ * `columns` + `fieldContainerClass` into the form so its own field container
+ * becomes the multi-column grid — mirroring the flat-fields layout path.
+ *
+ * @param fields  Already-built (and permission-filtered) section fields.
+ * @param columns Section column count (1–4).
+ */
+export declare function sectionFormLayout(fields: FormField[], columns: number | undefined): {
+    fields: FormField[];
+    columns: number;
+    fieldContainerClass?: string;
+};
 /**
  * Infer an appropriate modal size based on the number of layout columns.
  * Used to auto-upgrade the modal width when auto-layout detects multi-column forms.

package/dist/deriveMasterDetail.d.ts

@@ -34,6 +34,18 @@ export declare function deriveColumns(childSchema: ObjectSchemaLike | undefined,
     exclude?: string[];
     maxColumns?: number;
 }): GridColumn[];
+/**
+ * Fill in missing widget metadata on author-supplied grid columns from the
+ * child object's field definitions. A view often lists columns as bare
+ * `{ field, label }` (the common, ergonomic authoring form) — without a `type`
+ * those cells fall back to a plain text `<Input>`, so a lookup, date, number or
+ * picklist field silently renders as free text. This resolves each such
+ * column's `type` (plus `options` / `reference` / computed `expr`) from the
+ * schema, exactly as {@link deriveColumns} would, while preserving the author's
+ * column set, order and labels. A column that already declares a `type` is left
+ * untouched — the author's explicit choice always wins.
+ */
+export declare function hydrateColumns(columns: GridColumn[] | undefined, childSchema: ObjectSchemaLike | undefined): GridColumn[];
 /**
  * Field names for a child's full "row form" (the per-row expand editor) — every
  * editable business field, skipping system/audit fields, the back-reference FK,

package/dist/fieldGroups.d.ts

@@ -1,27 +1,21 @@
 import { FormField, ObjectFormSection } from '@object-ui/types';
-/** A declared field group on the object metadata. */
-export interface DeclaredFieldGroup {
-    key: string;
-    label?: string;
-    /** Render the group's section header with a collapse toggle. */
-    collapsible?: boolean;
-    /** Start the (collapsible) group collapsed. */
-    collapsed?: boolean;
-}
-/** Read an object's `fieldGroups` into a normalized, well-typed list. */
-export declare function readObjectFieldGroups(input: unknown): DeclaredFieldGroup[];
 /**
  * Derive form sections from an object's declared `fieldGroups` and each
  * rendered field's `group`.
  *
  * Returns `null` when grouping does not apply — no declared groups, or no
  * rendered field opts into a declared group — so callers fall back to a flat
- * form. Sections come back in declared order; fields without a declared group
- * collect into a trailing untitled section (no `name`/`label`) so they render
- * as a plain block rather than a card.
+ * form.
  *
- * Section `fields` are returned as field *names* (strings) so the result plugs
- * straight into ObjectForm's existing section-render path, which resolves names
- * back to generated `FormField`s and applies field-level permissions.
+ * The derivation runs against the RENDERED field list (post permission /
+ * visibility filtering), not the raw object def, so a section never names a
+ * field the form isn't showing. Any rendered field the shared derivation
+ * excludes from its default buckets (audit/system fields) is re-appended to
+ * the trailing bucket: the form was already told to render it, and a layout
+ * helper silently dropping a rendered input is exactly the failure mode
+ * ADR-0085 exists to kill.
+ *
+ * Section `fields` are field *names* (strings) so the result plugs straight
+ * into ObjectForm's existing section-render path.
  */
 export declare function deriveFieldGroupSections(fields: FormField[], fieldGroups: unknown): ObjectFormSection[] | null;