feat(spec): declare editMode?: 'modal' | 'page' on the object document (#11408) (#12208)

Maintainer ruling 2026-08-24 (declare — #10144 declare-or-rule-out family):
objectui's shipped runtime reads objectDef.editMode for record-edit routing
while the spec's strict parse rejected the key with unrecognized_keys. The
object document now declares it beside the other display hints; values
outside the enum fail as a located value error at editMode. Accept-set
widening; consumer-side retirement of ObjectSchemaClientExtensions.editMode
is a release-gated objectui follow-up per the recorded ruling.


Claude-Session: https://claude.ai/code/session_01NDGG54XF5gbTLdQzCtnaVV

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/object-editmode-declared.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare `editMode?: 'modal' | 'page'` on the object document (#11408)
+
+Accept-set **widening** — no existing document changes meaning and nothing is
+removed. Maintainer ruling 2026-08-24 (declare, the #10144 declare-or-rule-out
+family): objectui's shipped runtime reads `objectDef.editMode` (record-edit
+routing: modal form vs a dedicated `/record/:id/edit` route) and its CHANGELOG
+announces the key to authors, while the spec's strict parse rejected it with
+`unrecognized_keys` — so an author following objectui's documentation was
+refused by every spec-validating path and the key only worked through data
+sources that skip validation.
+
+The object document now declares it beside the other display hints
+(`nameField`, `highlightFields`, `stageField`): an optional cross-renderer
+edit-interaction intent — `'modal'` opens the edit form as a dialog over the
+current view, `'page'` navigates to a dedicated full-page edit route, absent
+lets the renderer pick its own default (objectui defaults to modal). Values
+outside the enum are rejected as a located value error at `editMode`.
+
+Consumer-side follow-up (not in this change): objectui retires its
+`ObjectSchemaClientExtensions.editMode` client-extension member and lets the
+spec derivation carry the key — its pinned rejection tests flip by design.
+That retirement is **release-gated** on the `@objectstack/spec` release
+containing this change (per the recorded ruling), not merely on this merge.

content/docs/references/data/object.mdx

@@ -136,6 +136,7 @@ const result = ApiMethod.parse(data);
 | **titleFormat** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | [DEPRECATED → nameField (ADR-0079)] Render-only title template; the server cannot return or query it, and an explicit nameField now takes precedence. Migrate a single-field title to nameField, a composite to a formula field designated as nameField. |
 | **highlightFields** | `string[]` | optional | [ADR-0085] Ordered most-important fields; first entry wins where only one fits. Drives default columns, cards, previews, detail highlight strip. Renamed from compactLayout. |
 | **stageField** | `string \| false` | optional | [ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed. |
+| **editMode** | `Enum<'modal' \| 'page'>` | optional | Edit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (#11408, #10144 family). |
 | **listViews** | `Record<string, { name?: string; label?: string \| Record<string, string>; type?: Enum<'grid' \| 'kanban' \| 'gallery' \| 'calendar' \| 'timeline' \| 'gantt' \| 'map' \| 'chart' \| 'tree'>; data?: object \| … +3 more; … }>` | optional | Built-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047) |
 | **searchableFields** | `string[]` | optional | Fields the `$search` query matches against (ADR-0061). Canonical default for the record picker, list quick-search and global search; views may narrow it. When unset, search auto-defaults to the name/title field plus short-text fields. Entries must name a STORED column: a virtual `formula` field is computed on read and materializes no column, so searching it can never match and it is refused (#6674) — mirror the value onto a stored text field and declare that. |
 | **enable** | `{ trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' \| 'list' \| 'create' \| 'update' \| 'delete' \| 'bulk'>[]; … }` | optional | Enabled system features modules |

packages/spec/authorable-surface/data.json

@@ -623,6 +623,7 @@
     "data/Object:datasource",
     "data/Object:description",
     "data/Object:displayNameField",
+    "data/Object:editMode",
     "data/Object:enable",
     "data/Object:external",
     "data/Object:externalSharingModel",

packages/spec/liveness/object.json

@@ -45,6 +45,10 @@
       "proof": "packages/qa/dogfood/test/semantic-roles.dogfood.test.ts#semantic-roles-served",
       "note": "ADR-0085 semantic role: objectui plugin-detail detectStatusField drives the record:path stepper; string names the lifecycle field, false suppresses heuristic stage detection."
     },
+    "editMode": {
+      "status": "live",
+      "note": "objectui record-edit routing: app-shell recordFormNavigation branches on editMode !== 'page' and AppContent handleEdit routes modal form vs dedicated /record/:id/edit route. Declared by the #11408 ruling (#10144 declare-or-rule-out family)."
+    },
     "fieldGroups": {
       "status": "live",
       "proof": "packages/qa/dogfood/test/semantic-roles.dogfood.test.ts#semantic-roles-served",

packages/spec/liveness/state-counts.md

@@ -27,7 +27,7 @@ for both corollaries.
 
 | Type | live | exp | dead | planned | classified |
 |---|---|---|---|---|---|
-| `object` | 50 | 0 | 0 | 1 | 51 |
+| `object` | 51 | 0 | 0 | 1 | 52 |
 | `field` | 89 | 0 | 0 | 2 | 91 |
 | `flow` | 34 | 0 | 6 | 0 | 40 |
 | `action` | 42 | 0 | 2 | 2 | 46 |
@@ -58,4 +58,4 @@ for both corollaries.
 | `capability` | 12 | 0 | 0 | 0 | 12 |
 | `qa` | 4 | 0 | 5 | 0 | 9 |
 | `manifest` | 22 | 0 | 21 | 0 | 43 |
-| **total** | **822** | **5** | **76** | **10** | **913** |
+| **total** | **823** | **5** | **76** | **10** | **914** |

packages/spec/src/data/object.test.ts

@@ -1632,6 +1632,43 @@ describe('ObjectSchema semantic roles (ADR-0085)', () => {
   });
 });
 
+describe('ObjectSchema editMode (#11408 — declared by maintainer ruling, #10144 family)', () => {
+  it('accepts both enum values through the strict parse and carries them on the output', () => {
+    // Full parse green (not merely "no unrecognized_keys"): the ruling adopts
+    // the key as authored surface, so a legal document must parse end to end.
+    const modal = ObjectSchema.parse({ name: 'task', fields: {}, editMode: 'modal' });
+    expect(modal.editMode).toBe('modal');
+    const page = ObjectSchema.parse({ name: 'task', fields: {}, editMode: 'page' });
+    expect(page.editMode).toBe('page');
+  });
+
+  it('stays optional: an object without editMode parses and the output carries no value', () => {
+    const parsed = ObjectSchema.parse({ name: 'task', fields: {} });
+    expect(parsed.editMode).toBeUndefined();
+  });
+
+  it('rejects a value outside the enum, as a VALUE error located at editMode — not unrecognized_keys', () => {
+    // Before #11408 the failure mode was `unrecognized_keys` at the top level
+    // (the key itself was unknown). Declaring the key moves the judgment to
+    // the VALUE: a bad spelling must now fail as an enum error at the
+    // `editMode` path, proving the key is recognised and its value contract
+    // is enforced.
+    for (const bad of ['drawer', 'inline', true, 3] as const) {
+      const result = ObjectSchema.safeParse({ name: 'task', fields: {}, editMode: bad });
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error.issues[0].code).not.toBe('unrecognized_keys');
+        expect(result.error.issues[0].path).toEqual(['editMode']);
+      }
+    }
+  });
+
+  it('is accepted by the authoring path (create()) as well as parse()', () => {
+    const created = ObjectSchema.create({ name: 'task', fields: {}, editMode: 'page' });
+    expect(created.editMode).toBe('page');
+  });
+});
+
 describe('ObjectSchema.fieldGroups', () => {
   it('should accept an object without fieldGroups (fully optional)', () => {
     const result = ObjectSchema.safeParse({

packages/spec/src/data/object.zod.ts

@@ -2073,6 +2073,24 @@ const ObjectSchemaBase = strictObject(
    */
   stageField: z.union([z.string(), z.literal(false)]).optional().describe('[ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed.'),
 
+  /**
+   * Cross-renderer EDIT-INTERACTION intent: whether a record of this object is
+   * edited in a modal dialog over the current view (`'modal'`) or on a
+   * dedicated full-page edit route (`'page'`). Like the other hints in this
+   * block it is an intent about the record, not pixel styling — any renderer
+   * can honour it. Absent = the renderer chooses its own default (objectui's
+   * shipped runtime treats anything but `'page'` as modal:
+   * `recordFormNavigation.ts` branches on `editMode !== 'page'`, and
+   * `AppContent`'s `handleEdit` dispatcher routes on it).
+   *
+   * Declared here by the #11408 maintainer ruling (the measured residue of the
+   * #10144 declare-or-rule-out census): objectui had published the key to
+   * authors (CHANGELOG + live runtime read) while this strict parse rejected
+   * it. objectui's `ObjectSchemaClientExtensions.editMode` mirror retires in a
+   * release-gated follow-up and the spec derivation carries it from then on.
+   */
+  editMode: z.enum(['modal', 'page']).optional().describe("Edit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (#11408, #10144 family)."),
+
   /**
    * Built-in List Views
    *