Merge pull request #1296 from objectstack-ai/copilot/add-fullscreen-edit-route

Author: hotlong

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.

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

content/docs/guide/meta.json

@@ -16,6 +16,7 @@
     "plugins",
     "plugin-development",
     "building-crud-app",
+    "record-edit-modes",
     "console",
     "console-architecture",
     "objectos-integration",

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)

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

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

packages/app-shell/src/console/AppContent.tsx

@@ -21,6 +21,7 @@ import { useMetadata } from '../providers/MetadataProvider';
 import { useAdapter } from '../providers/AdapterProvider';
 import { ExpressionProvider, evaluateVisibility } from '../providers/ExpressionProvider';
 import { useRecentItems } from '../hooks/useRecentItems';
+import { resolveRecordFormTarget, resolveNavigateCreateUrl, resolveNavigateEditUrl } from '../utils/recordFormNavigation';
 import { ExpressionEvaluator } from '@object-ui/core';
 
 // Components (eagerly loaded — always needed)
@@ -39,6 +40,7 @@ const DashboardView = lazy(() => import('../views/DashboardView').then(m => ({ d
 const PageView = lazy(() => import('../views/PageView').then(m => ({ default: m.PageView })));
 const ReportView = lazy(() => import('../views/ReportView').then(m => ({ default: m.ReportView })));
 const SearchResultsPage = lazy(() => import('../views/SearchResultsPage').then(m => ({ default: m.SearchResultsPage })));
+const RecordFormPage = lazy(() => import('../views/RecordFormPage').then(m => ({ default: m.RecordFormPage })));
 
 // Designer pages — sourced from @object-ui/plugin-designer so third-party hosts
 // can opt out by not registering these routes.
@@ -133,13 +135,54 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
       return { success: true };
     });
 
+    // Page-mode navigation handlers — declarative counterparts to the
+    // imperative `handleEdit` callback. These let JSON schemas open the
+    // full-screen create/edit pages directly via `<action:button>` without
+    // any custom code:
+    //   { "action": "navigate_create", "params": { "objectName": "..." } }
+    //   { "action": "navigate_edit",
+    //     "params": { "objectName": "...", "recordId": "..." } }
+    // The `objectName` param falls back to the action context's
+    // `objectName` (set per view) so action buttons mounted inside an
+    // ObjectView can omit it.
+    // NOTE on duplication below: each handler reads `runner.getContext()`
+    // INSIDE its closure (at action-invocation time) rather than once at
+    // registration. Hoisting the call outside the registrations would
+    // freeze the context to whatever it was when the effect last ran,
+    // breaking dynamic per-view `runner.updateContext({ objectName, ... })`
+    // calls (used by ObjectView / RecordDetailView). Keep the call where
+    // it is.
+    runner.registerHandler('navigate_create', async (action: any) => {
+      const ctx = runner.getContext?.() ?? {};
+      const result = resolveNavigateCreateUrl({
+        action,
+        context: ctx,
+        defaultBaseUrl: `/apps/${appName ?? ''}`,
+      });
+      if (!result.success) return result;
+      navigate(result.url);
+      return { success: true };
+    });
+
+    runner.registerHandler('navigate_edit', async (action: any) => {
+      const ctx = runner.getContext?.() ?? {};
+      const result = resolveNavigateEditUrl({
+        action,
+        context: ctx,
+        defaultBaseUrl: `/apps/${appName ?? ''}`,
+      });
+      if (!result.success) return result;
+      navigate(result.url);
+      return { success: true };
+    });
+
     // NOTE: `flow` actions are handled at the per-view ActionProvider level
     // (RecordDetailView / ObjectView) so they share the same ActionRunner that
     // <action:button> renderers consume via useAction(). Do NOT register a
     // `flow` handler on this top-level useActionRunner — it lives on a
     // different ActionRunner instance and would never be invoked from the
     // record/list action buttons.
-  }, [runner]);
+  }, [runner, navigate, appName]);
 
   useEffect(() => {
     if (!dataSource) return;
@@ -218,6 +261,19 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
   }, [location.pathname, addRecentItem]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const handleEdit = (record: any) => {
+    // Page-mode opt-in: when the object metadata declares
+    // `editMode: 'page'`, route to the full-screen create/edit page instead
+    // of opening the global ModalForm. Default behavior (modal) is
+    // preserved for any object without the flag.
+    const target = resolveRecordFormTarget({
+      objectDef: currentObjectDef as any,
+      baseUrl: activeApp?.name ? `/apps/${activeApp.name}` : '',
+      record,
+    });
+    if (target.kind === 'page') {
+      navigate(target.url);
+      return;
+    }
     setEditingRecord(record);
     setIsDialogOpen(true);
   };
@@ -299,12 +355,18 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
                 <Route path=":objectName" element={
                   <ObjectView dataSource={dataSource} objects={allObjects} onEdit={handleEdit} />
                 } />
+                <Route path=":objectName/new" element={
+                  <RecordFormPage mode="create" />
+                } />
                 <Route path=":objectName/view/:viewId" element={
                   <ObjectView dataSource={dataSource} objects={allObjects} onEdit={handleEdit} />
                 } />
                 <Route path=":objectName/record/:recordId" element={
                   <RecordDetailView key={refreshKey} dataSource={dataSource} objects={allObjects} onEdit={handleEdit} />
                 } />
+                <Route path=":objectName/record/:recordId/edit" element={
+                  <RecordFormPage mode="edit" />
+                } />
                 <Route path="dashboard/:dashboardName" element={<DashboardView dataSource={dataSource} />} />
                 <Route path="report/:reportName" element={<ReportView dataSource={dataSource} />} />
                 <Route path="page/:pageName" element={<PageView />} />