@objectstack/spec 6.9.0 → 7.0.0

package/src/ui/action.zod.ts

@@ -118,6 +118,37 @@ const TARGET_REQUIRED_TYPES: ReadonlySet<string> = new Set(
  * Note: The action name is the configuration ID. JavaScript function names can use camelCase,
  * but the metadata ID must be lowercase snake_case.
  */
+/**
+ * Action Location — where an action is allowed to surface in the UI.
+ *
+ * Canonical list (single source of truth for the whole platform). Renderers,
+ * the ActionEngine, the Studio designer dropdowns, and `objectui` consumers
+ * MUST import from this constant rather than re-declaring their own enum —
+ * adding a new location should require touching this one file only.
+ *
+ * Semantics:
+ * - `list_toolbar`    — header/toolbar of a list view (bulk actions, "New", export).
+ * - `list_item`       — per-row action on a list/grid row (Salesforce row-level menu).
+ * - `record_header`   — primary actions in the record-detail title bar.
+ * - `record_more`     — overflow menu under the "More" / ⋯ button on a record.
+ * - `record_related`  — actions on a related list section inside a record.
+ * - `record_section`  — actions surfaced inside a body section/tab of a record
+ *                       (e.g. a Security tab grouping change-password, 2FA, etc.).
+ * - `global_nav`      — global navigation/command-palette level actions.
+ */
+export const ACTION_LOCATIONS = [
+  'list_toolbar',
+  'list_item',
+  'record_header',
+  'record_more',
+  'record_related',
+  'record_section',
+  'global_nav',
+] as const;
+
+export const ActionLocationSchema = z.enum(ACTION_LOCATIONS);
+export type ActionLocation = z.infer<typeof ActionLocationSchema>;
+
 export const ActionSchema = lazySchema(() => z.object({
   /** Machine name of the action */
   name: SnakeCaseIdentifierSchema.describe('Machine name (lowercase snake_case)'),
@@ -132,11 +163,7 @@ export const ActionSchema = lazySchema(() => z.object({
   icon: z.string().optional().describe('Icon name'),
 
   /** Where does this action appear? */
-  locations: z.array(z.enum([
-    'list_toolbar', 'list_item', 
-    'record_header', 'record_more', 'record_related',
-    'global_nav'
-  ])).optional().describe('Locations where this action is visible'),
+  locations: z.array(ActionLocationSchema).optional().describe('Locations where this action is visible'),
 
   /** 
    * Visual Component Type
@@ -158,8 +185,19 @@ export const ActionSchema = lazySchema(() => z.object({
    * Required for url, flow, modal, and api types.
    * For `script` type: prefer `body` over `target`. `target` is kept only for
    * legacy bundle.functions[name] references.
+   *
+   * **Interpolation** (renderer responsibility, all action types):
+   * `target` MAY contain `${param.X}` and `${ctx.X}` tokens. Renderers
+   * resolve them just before invocation:
+   * - `${param.X}` — value collected from the action's params dialog.
+   * - `${ctx.X}` — values from the action context: `ctx.origin`
+   *   (window.origin), `ctx.recordId`, `ctx.user.id`, `ctx.org.id`, etc.
+   * Used by redirect-style actions like `link_social`, where the target is
+   * e.g. `/api/v1/auth/sign-in/social?provider=${param.provider}&callbackURL=${ctx.origin}/_account/linked-accounts`.
+   * Renderers MUST `encodeURIComponent` interpolated values before
+   * substituting them into URL query positions.
    */
-  target: z.string().optional().describe('URL, Script Name, Flow ID, or API Endpoint'),
+  target: z.string().optional().describe('URL, Script Name, Flow ID, or API Endpoint. Supports ${param.X} and ${ctx.X} interpolation.'),
 
   /**
    * Action Body (L1 expression or L2 sandboxed JS).
@@ -191,6 +229,54 @@ export const ActionSchema = lazySchema(() => z.object({
   confirmText: I18nLabelSchema.optional().describe('Confirmation message before execution'),
   successMessage: I18nLabelSchema.optional().describe('Success message to show after execution'),
   refreshAfter: z.boolean().default(false).describe('Refresh view after execution'),
+
+  /**
+   * Result Dialog — describe how to render the API response on success.
+   *
+   * When set and the action returns successfully, the renderer SHOULD open a
+   * dialog showing the selected fields from `result.data` instead of the
+   * `successMessage` toast. The dialog has an acknowledge button only — the
+   * user must explicitly close it. Used for **one-shot reveals** of values
+   * the user must copy now because they cannot be retrieved later:
+   *
+   * - TOTP enrollment URI + secret (`enable_two_factor`)
+   * - Backup recovery codes (`regenerate_backup_codes`)
+   * - Freshly minted OAuth `client_secret` (`rotate_client_secret`,
+   *   `create_oauth_application`)
+   *
+   * `fields` selects what to render and how. Each entry's `path` is a dot
+   * path into `result.data` (e.g. `'totpURI'`, `'backupCodes'`,
+   * `'client.client_secret'`). When `fields` is omitted, the renderer falls
+   * back to JSON-printing the whole response under a single block.
+   *
+   * `format` (dialog-level) is a default for fields that don't carry their
+   * own `format`; the per-field `format` always wins.
+   *
+   * Renderer contract (objectui):
+   * - `qrcode` — render the value as a QR code; also render the raw string
+   *   underneath with a copy button (so the user can paste into apps that
+   *   don't scan).
+   * - `code-list` — value must be an array of strings; render each in a
+   *   monospace row with per-row copy and a "Copy all" affordance.
+   * - `secret` — render a single string masked by default with a reveal
+   *   toggle and copy button.
+   * - `text` — plain text with copy.
+   * - `json` — pretty-printed JSON in a monospace block.
+   *
+   * The dialog SHOULD set `refreshAfter` to true on close (separate from
+   * the existing `refreshAfter` flag, which fires immediately on success).
+   */
+  resultDialog: z.object({
+    title: I18nLabelSchema.optional(),
+    description: I18nLabelSchema.optional(),
+    acknowledge: I18nLabelSchema.optional().describe('Acknowledge button label, e.g. "I have saved this"'),
+    format: z.enum(['qrcode', 'code-list', 'secret', 'text', 'json']).optional().describe('Default format for fields without their own format. Defaults to json when omitted.'),
+    fields: z.array(z.object({
+      path: z.string().describe('Dot path into result.data (e.g. "totpURI", "client.client_secret").'),
+      label: I18nLabelSchema.optional(),
+      format: z.enum(['qrcode', 'code-list', 'secret', 'text', 'json']).optional().describe('Per-field format override.'),
+    })).optional().describe('Which fields from result.data to render. Omit to dump full JSON.'),
+  }).optional().describe('Render API response in a one-shot reveal dialog (suppresses successMessage when set).'),
   
   /** Access */
   visible: ExpressionInputSchema.optional().describe('Visibility predicate (CEL).'),

package/src/ui/app.zod.ts

@@ -77,12 +77,53 @@ const BaseNavItemSchema = z.object({
 
 /**
  * 1. Object Navigation Item
- * Navigates to an object's list view.
+ *
+ * Navigates to an object's list view by default. When `recordId` is set,
+ * navigates directly to that record's detail page instead — useful for
+ * "My Profile", "My Settings", or any other always-one-row entry where
+ * dropping the user on a list view first would be wrong UX.
+ *
+ * `recordId` supports a small set of template variables resolved at render
+ * time by the shell (see Console's `AppSidebar` / `AppContent`):
+ *   - `{current_user_id}` — the signed-in user's id
+ *   - `{current_org_id}`  — the active organization id
+ * These mirror the variables already understood by the view-layer
+ * filter resolver (see e.g. `sys_user.me` listView), so authors only
+ * have to learn one vocabulary.
+ *
+ * @example List view (existing behaviour)
+ * ```ts
+ * { id: 'nav_users', type: 'object', label: 'Users',
+ *   objectName: 'sys_user', viewName: 'all_users' }
+ * ```
+ *
+ * @example Direct-to-record (new)
+ * ```ts
+ * { id: 'nav_profile', type: 'object', label: 'My Profile',
+ *   objectName: 'sys_user', recordId: '{current_user_id}' }
+ * ```
  */
 export const ObjectNavItemSchema = lazySchema(() => BaseNavItemSchema.extend({
   type: z.literal('object'),
   objectName: z.string().describe('Target object name'),
-  viewName: z.string().optional().describe('Default list view to open. Defaults to "all"'),
+  viewName: z.string().optional().describe('Default list view to open. Defaults to "all". Ignored when `recordId` is set.'),
+  /**
+   * When set, navigate straight to the detail page of this specific
+   * record instead of the object's list view. Supports template
+   * variables `{current_user_id}` and `{current_org_id}` resolved by
+   * the shell at render time. Mutually exclusive with `viewName`
+   * (viewName is ignored if both are set).
+   */
+  recordId: z.string().optional().describe(
+    'Navigate directly to this record id instead of the list view. Supports template vars: {current_user_id}, {current_org_id}.',
+  ),
+  /**
+   * Open the record in view (default) or edit mode. Only meaningful
+   * when `recordId` is set.
+   */
+  recordMode: z.enum(['view', 'edit']).optional().describe(
+    'Open the record in view (default) or edit mode. Only meaningful when `recordId` is set.',
+  ),
 }));
 
 /**
@@ -321,6 +362,22 @@ export const AppSchema = lazySchema(() => z.object({
 
   /** Is this the default app for new users? */
   isDefault: z.boolean().optional().default(false).describe('Is default app'),
+
+  /**
+   * Hide this app from the top-level App Switcher.
+   *
+   * Hidden apps stay fully routable and permission-checked — they just
+   * don't appear in the apps dropdown. The shell is expected to surface
+   * them through the avatar / user dropdown instead, so this is the
+   * right knob for personal-settings-style apps ("Account") that would
+   * feel out of place next to business apps (CRM, HR, Setup).
+   *
+   * Mirrors GitHub Settings / Google account chip / Salesforce
+   * "Personal Settings" — visible to every user, but reached from the
+   * avatar rather than the app launcher.
+   */
+  hidden: z.boolean().optional()
+    .describe('Hide from the App Switcher; the shell surfaces hidden apps via the avatar menu instead'),
   
   /** 
    * Full Navigation Tree — supports unlimited nesting depth.

package/src/ui/page.zod.ts

@@ -33,7 +33,7 @@ export const PageComponentType = z.enum([
   // Structure
   'page:header', 'page:footer', 'page:sidebar', 'page:tabs', 'page:accordion', 'page:card', 'page:section',
   // Record Context
-  'record:details', 'record:highlights', 'record:related_list', 'record:activity', 'record:chatter', 'record:path',
+  'record:details', 'record:highlights', 'record:related_list', 'record:activity', 'record:chatter', 'record:path', 'record:alert', 'record:quick_actions', 'record:reference_rail', 'record:history',
   // Navigation
   'app:launcher', 'nav:menu', 'nav:breadcrumb',
   // Utility
@@ -324,10 +324,10 @@ export const PageSchema = lazySchema(() => z.object({
    * Each slot accepts a single PageComponent or an array. Slots not
    * provided fall through to the synthesized default.
    *
-   * Slot menu (v1): header | actions | highlights | details | tabs |
-   * discussion. Each slot is a full replacement at the slot boundary —
-   * no deep merge, no patch operations. To compose default + custom,
-   * call the corresponding `buildDefault*` sub-builder from the
+   * Slot menu (v1): header | actions | alerts | highlights | details |
+   * tabs | discussion. Each slot is a full replacement at the slot
+   * boundary — no deep merge, no patch operations. To compose default +
+   * custom, call the corresponding `buildDefault*` sub-builder from the
    * renderer runtime (e.g. @object-ui/plugin-detail).
    *
    * Only honored when `kind === 'slotted'`.
@@ -335,6 +335,7 @@ export const PageSchema = lazySchema(() => z.object({
   slots: z.object({
     header: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),
     actions: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),
+    alerts: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),
     highlights: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),
     details: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),
     tabs: z.union([PageComponentSchema, z.array(PageComponentSchema)]).optional(),

package/src/ui/view.zod.ts

@@ -595,6 +595,13 @@ export const FormFieldSchema: z.ZodType<any> = lazySchema(() => z.object({
  * Form Layout Section
  */
 export const FormSectionSchema = lazySchema(() => z.object({
+  /**
+   * Stable identifier for translation lookup. snake_case convention.
+   * When provided, translation bundles can target this section's `label`
+   * and `description` via `metadataForms.<type>.sections.<name>`.
+   * Optional for backward-compat with sections that only have a `label`.
+   */
+  name: z.string().optional().describe('Stable section identifier for i18n lookup (snake_case)'),
   label: I18nLabelSchema.optional(),
   description: z.string().optional().describe('Optional description rendered under the section header.'),
   collapsible: z.boolean().default(false),

package/json-schema/data/TenantDatabaseLifecycle.json

@@ -1,96 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "onTenantCreate": {
-      "type": "object",
-      "properties": {
-        "autoCreate": {
-          "default": true,
-          "description": "Auto-create database on tenant registration",
-          "type": "boolean"
-        },
-        "group": {
-          "description": "Turso group for the new database",
-          "type": "string"
-        },
-        "applyGroupSchema": {
-          "default": true,
-          "description": "Apply shared schema from group",
-          "type": "boolean"
-        },
-        "seedData": {
-          "default": false,
-          "description": "Populate seed data on creation",
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "autoCreate",
-        "applyGroupSchema",
-        "seedData"
-      ],
-      "additionalProperties": false,
-      "description": "Tenant creation hook"
-    },
-    "onTenantDelete": {
-      "type": "object",
-      "properties": {
-        "immediate": {
-          "default": false,
-          "description": "Destroy database immediately",
-          "type": "boolean"
-        },
-        "gracePeriodHours": {
-          "default": 72,
-          "description": "Grace period before permanent deletion",
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 9007199254740991
-        },
-        "createBackup": {
-          "default": true,
-          "description": "Create backup before deletion",
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "immediate",
-        "gracePeriodHours",
-        "createBackup"
-      ],
-      "additionalProperties": false,
-      "description": "Tenant deletion hook"
-    },
-    "onTenantSuspend": {
-      "type": "object",
-      "properties": {
-        "revokeTokens": {
-          "default": true,
-          "description": "Revoke auth tokens on suspension",
-          "type": "boolean"
-        },
-        "readOnly": {
-          "default": true,
-          "description": "Set database to read-only on suspension",
-          "type": "boolean"
-        }
-      },
-      "required": [
-        "revokeTokens",
-        "readOnly"
-      ],
-      "additionalProperties": false,
-      "description": "Tenant suspension hook"
-    }
-  },
-  "required": [
-    "onTenantCreate",
-    "onTenantDelete",
-    "onTenantSuspend"
-  ],
-  "additionalProperties": false,
-  "description": "Tenant database lifecycle hooks",
-  "$id": "https://schema.objectstack.io/v6.9.0/data/TenantDatabaseLifecycle.json",
-  "x-spec-version": "6.9.0"
-}

package/json-schema/data/TenantResolverStrategy.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "string",
-  "enum": [
-    "header",
-    "subdomain",
-    "path",
-    "token",
-    "lookup"
-  ],
-  "description": "Strategy for resolving tenant identity from request context",
-  "$id": "https://schema.objectstack.io/v6.9.0/data/TenantResolverStrategy.json",
-  "x-spec-version": "6.9.0"
-}

package/json-schema/data/TursoGroup.json

@@ -1,38 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Turso database group name"
-    },
-    "primaryLocation": {
-      "type": "string",
-      "minLength": 2,
-      "description": "Primary Turso region code (e.g., iad, lhr, nrt)"
-    },
-    "replicaLocations": {
-      "default": [],
-      "description": "Additional replica region codes",
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 2
-      }
-    },
-    "schemaDatabase": {
-      "description": "Schema database name for multi-db schemas",
-      "type": "string"
-    }
-  },
-  "required": [
-    "name",
-    "primaryLocation",
-    "replicaLocations"
-  ],
-  "additionalProperties": false,
-  "description": "Turso database group configuration",
-  "$id": "https://schema.objectstack.io/v6.9.0/data/TursoGroup.json",
-  "x-spec-version": "6.9.0"
-}

package/json-schema/data/TursoMultiTenantConfig.json

@@ -1,187 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "organizationSlug": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Turso organization slug"
-    },
-    "urlTemplate": {
-      "type": "string",
-      "minLength": 1,
-      "description": "URL template with {tenant_id} placeholder"
-    },
-    "groupAuthToken": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Group-level auth token for platform operations"
-    },
-    "tenantResolverStrategy": {
-      "default": "token",
-      "type": "string",
-      "enum": [
-        "header",
-        "subdomain",
-        "path",
-        "token",
-        "lookup"
-      ],
-      "description": "Strategy for resolving tenant identity from request context"
-    },
-    "group": {
-      "description": "Database group configuration",
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Turso database group name"
-        },
-        "primaryLocation": {
-          "type": "string",
-          "minLength": 2,
-          "description": "Primary Turso region code (e.g., iad, lhr, nrt)"
-        },
-        "replicaLocations": {
-          "default": [],
-          "description": "Additional replica region codes",
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 2
-          }
-        },
-        "schemaDatabase": {
-          "description": "Schema database name for multi-db schemas",
-          "type": "string"
-        }
-      },
-      "required": [
-        "name",
-        "primaryLocation",
-        "replicaLocations"
-      ],
-      "additionalProperties": false
-    },
-    "lifecycle": {
-      "description": "Lifecycle hooks",
-      "type": "object",
-      "properties": {
-        "onTenantCreate": {
-          "type": "object",
-          "properties": {
-            "autoCreate": {
-              "default": true,
-              "description": "Auto-create database on tenant registration",
-              "type": "boolean"
-            },
-            "group": {
-              "description": "Turso group for the new database",
-              "type": "string"
-            },
-            "applyGroupSchema": {
-              "default": true,
-              "description": "Apply shared schema from group",
-              "type": "boolean"
-            },
-            "seedData": {
-              "default": false,
-              "description": "Populate seed data on creation",
-              "type": "boolean"
-            }
-          },
-          "required": [
-            "autoCreate",
-            "applyGroupSchema",
-            "seedData"
-          ],
-          "additionalProperties": false,
-          "description": "Tenant creation hook"
-        },
-        "onTenantDelete": {
-          "type": "object",
-          "properties": {
-            "immediate": {
-              "default": false,
-              "description": "Destroy database immediately",
-              "type": "boolean"
-            },
-            "gracePeriodHours": {
-              "default": 72,
-              "description": "Grace period before permanent deletion",
-              "type": "integer",
-              "minimum": 0,
-              "maximum": 9007199254740991
-            },
-            "createBackup": {
-              "default": true,
-              "description": "Create backup before deletion",
-              "type": "boolean"
-            }
-          },
-          "required": [
-            "immediate",
-            "gracePeriodHours",
-            "createBackup"
-          ],
-          "additionalProperties": false,
-          "description": "Tenant deletion hook"
-        },
-        "onTenantSuspend": {
-          "type": "object",
-          "properties": {
-            "revokeTokens": {
-              "default": true,
-              "description": "Revoke auth tokens on suspension",
-              "type": "boolean"
-            },
-            "readOnly": {
-              "default": true,
-              "description": "Set database to read-only on suspension",
-              "type": "boolean"
-            }
-          },
-          "required": [
-            "revokeTokens",
-            "readOnly"
-          ],
-          "additionalProperties": false,
-          "description": "Tenant suspension hook"
-        }
-      },
-      "required": [
-        "onTenantCreate",
-        "onTenantDelete",
-        "onTenantSuspend"
-      ],
-      "additionalProperties": false
-    },
-    "maxCachedConnections": {
-      "default": 100,
-      "description": "Max cached tenant connections (LRU)",
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 9007199254740991
-    },
-    "connectionCacheTTL": {
-      "default": 300,
-      "description": "Connection cache TTL in seconds",
-      "type": "integer",
-      "minimum": 0,
-      "maximum": 9007199254740991
-    }
-  },
-  "required": [
-    "organizationSlug",
-    "urlTemplate",
-    "groupAuthToken",
-    "tenantResolverStrategy",
-    "maxCachedConnections",
-    "connectionCacheTTL"
-  ],
-  "additionalProperties": false,
-  "description": "Turso multi-tenant router configuration",
-  "$id": "https://schema.objectstack.io/v6.9.0/data/TursoMultiTenantConfig.json",
-  "x-spec-version": "6.9.0"
-}