feat(app-shell): add page-mode record form route

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>

Author: Copilot

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,47 @@ 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.
+    runner.registerHandler('navigate_create', async (action: any) => {
+      const ctx = (runner as any).context ?? {};
+      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 as any).context ?? {};
+      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 +254,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 +348,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 />} />

packages/app-shell/src/index.ts

@@ -88,12 +88,14 @@ export {
 export {
   ObjectView,
   RecordDetailView,
+  RecordFormPage,
   DashboardView,
   PageView,
   ReportView,
   SearchResultsPage,
   ViewConfigPanel,
 } from './views';
+export type { RecordFormPageProps } from './views';
 
 // Hooks
 export {

packages/app-shell/src/utils/__tests__/recordFormNavigation.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Tests for resolveRecordFormTarget — the modal-vs-page decision used by
+ * `AppContent.handleEdit` when the user clicks "Create" or "Edit" on a
+ * record. Covers:
+ *   - default (no editMode) → modal
+ *   - editMode: 'modal' → modal (explicit opt-out)
+ *   - editMode: 'page' + null/undefined record → create URL
+ *   - editMode: 'page' + record with id → edit URL
+ *   - editMode: 'page' + record with _id (Mongo-style) → edit URL
+ *   - URL encoding of record ids that contain reserved characters
+ *   - missing objectDef → modal (defensive fallback)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  resolveRecordFormTarget,
+  resolveNavigateCreateUrl,
+  resolveNavigateEditUrl,
+} from '../recordFormNavigation';
+
+describe('resolveRecordFormTarget', () => {
+  const baseUrl = '/apps/sales';
+
+  it('returns modal when editMode is unset (default)', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account' },
+        baseUrl,
+        record: null,
+      }),
+    ).toEqual({ kind: 'modal' });
+  });
+
+  it('returns modal when editMode is explicitly "modal"', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'modal' },
+        baseUrl,
+        record: { id: 'r1' },
+      }),
+    ).toEqual({ kind: 'modal' });
+  });
+
+  it('returns the create URL when editMode is "page" and no record is provided', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: null,
+      }),
+    ).toEqual({ kind: 'page', url: '/apps/sales/account/new' });
+  });
+
+  it('returns the edit URL when editMode is "page" and record has id', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: { id: 'r1' },
+      }),
+    ).toEqual({ kind: 'page', url: '/apps/sales/account/record/r1/edit' });
+  });
+
+  it('falls back to record._id (Mongo-style) when id is missing', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: { _id: 'mongo-7' },
+      }),
+    ).toEqual({ kind: 'page', url: '/apps/sales/account/record/mongo-7/edit' });
+  });
+
+  it('URL-encodes record ids with reserved characters', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: { id: 'a/b c' },
+      }),
+    ).toEqual({
+      kind: 'page',
+      url: '/apps/sales/account/record/a%2Fb%20c/edit',
+    });
+  });
+
+  it('treats an empty-string id as create-mode', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: { id: '' },
+      }),
+    ).toEqual({ kind: 'page', url: '/apps/sales/account/new' });
+  });
+
+  it('treats numeric ids correctly', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: 'account', editMode: 'page' },
+        baseUrl,
+        record: { id: 42 },
+      }),
+    ).toEqual({ kind: 'page', url: '/apps/sales/account/record/42/edit' });
+  });
+
+  it('returns modal when objectDef is missing (defensive fallback)', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: null,
+        baseUrl,
+        record: { id: 'r1' },
+      }),
+    ).toEqual({ kind: 'modal' });
+  });
+
+  it('returns modal when objectDef has no name', () => {
+    expect(
+      resolveRecordFormTarget({
+        objectDef: { name: '', editMode: 'page' },
+        baseUrl,
+        record: { id: 'r1' },
+      }),
+    ).toEqual({ kind: 'modal' });
+  });
+});
+
+describe('resolveNavigateCreateUrl', () => {
+  const defaultBaseUrl = '/apps/sales';
+
+  it('uses params.objectName as primary source', () => {
+    expect(
+      resolveNavigateCreateUrl({
+        action: { params: { objectName: 'lead' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/new' });
+  });
+
+  it('falls back to action.objectName when params.objectName is missing', () => {
+    expect(
+      resolveNavigateCreateUrl({
+        action: { objectName: 'lead' },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/new' });
+  });
+
+  it('falls back to context.objectName as last resort', () => {
+    expect(
+      resolveNavigateCreateUrl({
+        action: {},
+        context: { objectName: 'lead' },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/new' });
+  });
+
+  it('prefers context.baseUrl over defaultBaseUrl', () => {
+    expect(
+      resolveNavigateCreateUrl({
+        action: { params: { objectName: 'lead' } },
+        context: { baseUrl: '/apps/marketing' },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/marketing/lead/new' });
+  });
+
+  it('errors when objectName cannot be resolved', () => {
+    expect(
+      resolveNavigateCreateUrl({
+        action: {},
+        defaultBaseUrl,
+      }),
+    ).toEqual({
+      success: false,
+      error: 'navigate_create: objectName is required',
+    });
+  });
+});
+
+describe('resolveNavigateEditUrl', () => {
+  const defaultBaseUrl = '/apps/sales';
+
+  it('builds the edit URL from params', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { objectName: 'lead', recordId: 'L-7' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/record/L-7/edit' });
+  });
+
+  it('falls back to action.objectName + action.recordId', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { objectName: 'lead', recordId: 'L-7' },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/record/L-7/edit' });
+  });
+
+  it('uses context.objectName but never context.recordId', () => {
+    // recordId must always come from the action — every record click
+    // should provide its own id.
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { recordId: 'L-7' } },
+        context: { objectName: 'lead' },
+        defaultBaseUrl,
+      }),
+    ).toEqual({ success: true, url: '/apps/sales/lead/record/L-7/edit' });
+  });
+
+  it('URL-encodes record ids', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { objectName: 'lead', recordId: 'a/b c' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({
+      success: true,
+      url: '/apps/sales/lead/record/a%2Fb%20c/edit',
+    });
+  });
+
+  it('errors when objectName is missing', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { recordId: 'L-7' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({
+      success: false,
+      error: 'navigate_edit: objectName and recordId are required',
+    });
+  });
+
+  it('errors when recordId is missing', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { objectName: 'lead' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({
+      success: false,
+      error: 'navigate_edit: objectName and recordId are required',
+    });
+  });
+
+  it('errors when recordId is empty string', () => {
+    expect(
+      resolveNavigateEditUrl({
+        action: { params: { objectName: 'lead', recordId: '' } },
+        defaultBaseUrl,
+      }),
+    ).toEqual({
+      success: false,
+      error: 'navigate_edit: objectName and recordId are required',
+    });
+  });
+});

packages/app-shell/src/utils/index.ts

@@ -2,6 +2,14 @@
  * Utility functions for ObjectStack Console
  */
 
+export {
+  resolveRecordFormTarget,
+} from './recordFormNavigation';
+export type {
+  ObjectDefinitionForNavigation,
+  RecordFormTarget,
+} from './recordFormNavigation';
+
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.