docs: add record-edit-modes guide and changelogs

Copilot · hotlong · web-flow · commit 17cb41704921 · 2026-05-08T01:29:45.000Z
Agent-Logs-Url: https://github.com/objectstack-ai/objectui/sessions/9bbb4b9a-dc45-41ea-b03e-55d3172b7dde Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Page-mode record forms (`editMode: 'page'`).** New per-object
+  metadata flag that opts a record's create/edit form into a dedicated
+  full-screen route instead of the default modal dialog. Routes are
+  scoped under the active app:
+  - `GET /apps/:appName/:objectName/new` — create page
+  - `GET /apps/:appName/:objectName/record/:recordId/edit` — edit page
+
+  These URLs are deep-linkable, refresh-safe, and integrate with the
+  browser back button — making them suitable for long forms,
+  multi-tab/wizard layouts, and copy-paste-share workflows. The same
+  `<ObjectForm>` pipeline drives both modes, so every existing field /
+  section / `formType` configuration carries over unchanged.
+
+  Two new declarative actions, `navigate_create` and `navigate_edit`,
+  let JSON `<action:button>` schemas open the page routes directly
+  without any host-app code changes. Default behavior (modal) is
+  preserved for any object that does not set `editMode`.
+
+  Implemented in `@object-ui/app-shell` (new `RecordFormPage` view +
+  routes in `AppContent`). Type added to `@object-ui/types`
+  (`ObjectSchemaMetadata.editMode`). New guide at
+  `content/docs/guide/record-edit-modes.md`.
+
 ### Fixed
 
 - **`@object-ui/plugin-list` & `@object-ui/plugin-detail`: shared `ComponentRegistry` singleton broken when consumed via published dist.** Both packages' `vite.config.ts` only listed `react`, `react-dom`, `react/jsx-runtime` in `rollupOptions.external`. As a result Rolldown inlined `@object-ui/core` (and a large chunk of lucide-react) into each plugin's bundle, giving every plugin its **own private `ComponentRegistry` instance**. Downstream apps that loaded the published plugins from npm saw `registry.get('object-grid')` from one plugin return `undefined` for components registered by another plugin — only workspace `alias` overrides pointing back to `packages/*/src` masked the issue. The `external` config now uses a regex covering all `@object-ui/*` workspace packages, the `@object-ui/*` deps have been moved from `dependencies` to `peerDependencies` (versioned `workspace:^` for publish-time rewrite, mirrored in `devDependencies` for local builds), and a regression test (`packages/core/src/registry/__tests__/cross-plugin-singleton.test.ts`) imports the built dist of `@object-ui/plugin-grid` and `@object-ui/plugin-list` and asserts cross-plugin lookup works against the same `ComponentRegistry` singleton. Downstream consumers (e.g. framework `apps/dashboard`) can now drop any `OBJECTUI_ROOT` / `packages/*/src` aliases.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -17,6 +17,7 @@
 > - 🛑 **Spec v4 native opt-ins** for the platform layer (CLI v4 plugin options, multi-tenant v4 resolver) — engine-level work, no immediate end-user impact.
 
 > **Recently Completed (queued in `.changeset/` for next release):**
+> - 🪟 Page-mode record forms — `editMode: 'page'` opens create/edit on a deep-linkable, refresh-safe full-screen route alongside the existing modal flow
 > - 📱 Mobile UX rounds 1 & 2 — Kanban readability, Calendar mobile default, Timeline dot clipping, list/sidebar/record-detail polish
 > - 🪟 `plugin-view` Manage Views dialog (replaces inline tab drag)
 > - 🧭 App-shell view-tab strip for single-view objects + DropdownMenu propagation fix
diff --git a/content/docs/guide/meta.json b/content/docs/guide/meta.json
@@ -16,6 +16,7 @@
     "plugins",
     "plugin-development",
     "building-crud-app",
+    "record-edit-modes",
     "console",
     "console-architecture",
     "objectos-integration",
diff --git a/content/docs/guide/record-edit-modes.md b/content/docs/guide/record-edit-modes.md
@@ -0,0 +1,132 @@
+---
+title: Record Edit Modes
+description: Choose between modal and full-page record forms with the editMode metadata flag.
+---
+
+# Record Edit Modes
+
+ObjectUI's default console shell (`@object-ui/app-shell`) supports two ways
+to render the create/edit form for a record:
+
+- **Modal** (default) — the form opens in an overlay dialog above the
+  current view. Best for short forms, quick edits, and contextual data
+  entry.
+- **Page** — the form takes over a full route. Best for long forms,
+  multi-tab or wizard layouts, or anywhere you need a deep-linkable URL
+  that survives a refresh and integrates with the browser back button.
+
+Both modes use the same `<ObjectForm>` pipeline under the hood, so all
+field types, sections, validations, and visibility expressions work
+identically in either mode.
+
+## Choosing a mode
+
+Set `editMode` on the object metadata:
+
+```jsonc
+// metadata/objects/account.json
+{
+  "name": "account",
+  "label": "Account",
+  "editMode": "page",       // "modal" (default) | "page"
+  "fields": {
+    "name":     { "type": "text",     "label": "Name", "required": true },
+    "industry": { "type": "picklist", "label": "Industry" },
+    "owner":    { "type": "lookup",   "label": "Owner", "reference_to": "user" }
+  }
+}
+```
+
+Omitting `editMode` (or setting it to `"modal"`) keeps the existing
+behavior — clicking **Create** or **Edit** opens the global `ModalForm`
+overlay.
+
+## URL patterns
+
+When `editMode: "page"` is set, the console renders the form on a
+dedicated route under the active app:
+
+| Action | URL |
+|--------|-----|
+| Create | `/apps/:appName/:objectName/new` |
+| Edit   | `/apps/:appName/:objectName/record/:recordId/edit` |
+
+Examples (for an app `sales` and an object `account`):
+
+- Create: `https://your-console.example/apps/sales/account/new`
+- Edit:   `https://your-console.example/apps/sales/account/record/0015e000abcd/edit`
+
+These URLs are stable. Users can bookmark them, share them in chat, or
+refresh the page mid-edit (the form rehydrates from the URL `:recordId`).
+
+## Triggering the routes from JSON
+
+In addition to the implicit "click create/edit on a list" entry point,
+two declarative actions let you open the page-mode routes from any
+`<action:button>` in metadata:
+
+```jsonc
+{
+  "type": "action:button",
+  "label": "New Account",
+  "icon":  "plus",
+  "action": {
+    "action": "navigate_create",
+    "params": { "objectName": "account" }
+  }
+}
+```
+
+```jsonc
+{
+  "type": "action:button",
+  "label": "Edit",
+  "icon":  "pencil",
+  "action": {
+    "action": "navigate_edit",
+    "params": {
+      "objectName": "account",
+      "recordId":   "${record.id}"
+    }
+  }
+}
+```
+
+When invoked from inside an `ObjectView`, the action context already
+carries the active `objectName`, so `objectName` may be omitted from the
+`params`:
+
+```jsonc
+{
+  "type": "action:button",
+  "label": "New",
+  "action": { "action": "navigate_create" }
+}
+```
+
+## Behavior summary
+
+| Aspect | Modal | Page |
+|--------|-------|------|
+| Default | ✅ | — |
+| Deep-linkable URL | ❌ | ✅ |
+| Survives refresh | ❌ | ✅ |
+| Back button closes form | n/a | ✅ |
+| Best for | quick edits | long / multi-section forms |
+
+## Migrating an existing object
+
+The change is additive — existing apps continue to work unchanged. To
+migrate a single object to page mode:
+
+1. Add `"editMode": "page"` to the object metadata.
+2. (Optional) Adjust the form layout — page mode pairs well with
+   `formType: "tabbed"` or `formType: "wizard"` for long forms.
+3. Reload the console. Existing **Create** / **Edit** entry points
+   automatically route to the new pages; no UI code changes required.
+
+## See also
+
+- [`@object-ui/app-shell` README](https://www.objectui.org/docs/layout/app-shell)
+- [`ObjectForm` API](../plugins/plugin-form.md)
+- [Schema rendering](./schema-rendering.md)
diff --git a/packages/app-shell/CHANGELOG.md b/packages/app-shell/CHANGELOG.md
@@ -1,5 +1,39 @@
 # @object-ui/app-shell — Changelog
 
+## Unreleased
+
+### Added
+
+- **Page-mode record forms.** Objects can now opt into a route-driven
+  full-screen create/edit experience by setting `editMode: 'page'` on the
+  object metadata (default remains `'modal'`). When opted in, the
+  console mounts two new routes under `/apps/:appName/`:
+  - `:objectName/new` for create
+  - `:objectName/record/:recordId/edit` for edit
+
+  URLs are deep-linkable, refresh-safe, and respect the browser back
+  button. The new `RecordFormPage` view renders inside the existing
+  `ConsoleLayout` chrome and reuses the same `<ObjectForm>` pipeline as
+  the modal flow, so every existing form configuration (sections,
+  visibility expressions, validations, `formType: 'tabbed' | 'wizard'`,
+  …) works without changes.
+
+  Two declarative actions expose the routes for `<action:button>` JSON:
+  - `{ "action": "navigate_create", "params": { "objectName": "..." } }`
+  - `{ "action": "navigate_edit", "params": { "objectName": "...", "recordId": "..." } }`
+
+  When called from inside an `ObjectView` the `objectName` falls back to
+  the action context, so it can be omitted from the params.
+
+  See `content/docs/guide/record-edit-modes.md` for a walkthrough.
+
+  - New view: `packages/app-shell/src/views/RecordFormPage.tsx`
+  - New helpers: `resolveRecordFormTarget`, `resolveNavigateCreateUrl`,
+    `resolveNavigateEditUrl` in
+    `packages/app-shell/src/utils/recordFormNavigation.ts`
+  - Tests: `RecordFormPage.test.tsx` (6) and
+    `recordFormNavigation.test.ts` (22), all passing.
+
 ## 4.0.1
 
 ### Patch Changes
diff --git a/packages/app-shell/README.md b/packages/app-shell/README.md
@@ -175,6 +175,60 @@ See `examples/byo-backend-console` for a complete working example that demonstra
 - Cherry-picking only needed components
 - Building a console in ~100 lines of code
 
+## Record create/edit modes
+
+The default `<DefaultAppContent>` shell mounts a global `<ModalForm>` for
+record create/edit interactions. Each object can opt in to a route-driven
+full-screen experience instead by setting `editMode` on its metadata:
+
+```jsonc
+// objects/account.json
+{
+  "name": "account",
+  "label": "Account",
+  "editMode": "page",        // ← opt-in. Default is "modal".
+  "fields": { /* ... */ }
+}
+```
+
+When `editMode: 'page'` is set, clicking **Create** or **Edit** for an
+`account` record navigates to a dedicated route instead of opening the
+dialog:
+
+| Action | URL |
+|--------|-----|
+| Create | `/apps/:appName/account/new` |
+| Edit   | `/apps/:appName/account/record/:recordId/edit` |
+
+These routes are deep-linkable (refresh-safe), respect the browser back
+button, and render the same `<ObjectForm>` pipeline as the modal — so
+`tabbed`, `wizard`, and section configurations work in both modes.
+
+JSON `<action:button>` schemas can also trigger the page routes directly
+via the action runner, regardless of the object's `editMode`:
+
+```json
+{
+  "type": "action:button",
+  "label": "New Account",
+  "action": { "action": "navigate_create", "params": { "objectName": "account" } }
+}
+```
+
+```json
+{
+  "type": "action:button",
+  "label": "Edit",
+  "action": {
+    "action": "navigate_edit",
+    "params": { "objectName": "account", "recordId": "${record.id}" }
+  }
+}
+```
+
+See [`content/docs/guide/record-edit-modes.md`](../../content/docs/guide/record-edit-modes.md)
+for a longer walkthrough.
+
 <!-- release-metadata:v3.3.0 -->
 
 ## Compatibility
diff --git a/packages/types/CHANGELOG.md b/packages/types/CHANGELOG.md
@@ -1,5 +1,17 @@
 # @object-ui/types
 
+## Unreleased
+
+### Added
+
+- **`ObjectSchemaMetadata.editMode`.** Optional `'modal' | 'page'` flag
+  declaring whether record create/edit should open the global
+  `<ModalForm>` (default) or navigate to the dedicated full-screen route
+  mounted by `@object-ui/app-shell` (`/apps/:appName/:objectName/new` and
+  `/apps/:appName/:objectName/record/:recordId/edit`). Default remains
+  `'modal'` so existing schemas are unaffected. See the new guide at
+  `content/docs/guide/record-edit-modes.md` for details.
+
 ## 4.0.1
 
 ## 4.0.0
