Skip to content

app.mdx

Latest commit

 

History

History
549 lines (415 loc) · 33.5 KB

app.mdx

File metadata and controls

549 lines (415 loc) · 33.5 KB
Raw
title App
description App protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Base Navigation Item Schema

Shared properties for all navigation types.

NAMING CONVENTION:

Navigation item IDs are used in URLs and configuration and must be lowercase snake_case.

@example Good IDs

  • 'menu_accounts'

  • 'page_dashboard'

  • 'nav_settings'

@example Bad IDs (will be rejected)

  • 'MenuAccounts' (PascalCase)

  • 'Page Dashboard' (spaces)

**Source:** `packages/spec/src/ui/app.zod.ts`

TypeScript Usage

import { ActionNavItem, App, AppBranding, AppContextSelector, ComponentNavItem, DashboardNavItem, GroupNavItem, NavigationArea, NavigationContribution, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui';
import type { ActionNavItem, App, AppBranding, AppContextSelector, ComponentNavItem, DashboardNavItem, GroupNavItem, NavigationArea, NavigationContribution, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui';

// Validate data
const result = ActionNavItem.parse(data);

ActionNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'action' ✅
actionDef { actionName: string; params?: Record<string, any> } ✅ Action definition to execute when clicked

App

Properties

Property Type Required Description
name string ✅ App unique machine name (lowercase snake_case)
label string ✅ App display label
version string optional App version
description string optional App description
icon string optional App icon used in the App Launcher
branding { primaryColor?: string; accentColor?: string; logo?: string; favicon?: string } optional App-specific branding
active boolean optional Whether the app is enabled
isDefault boolean optional Is default app
hidden boolean optional Hide from the App Switcher; the shell surfaces hidden apps via the avatar menu instead
navigation { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | { id: string; label: string; icon?: string; order?: number; … }[] optional Full navigation tree for the app sidebar
areas { id: string; label: string; icon?: string; order?: number; … }[] optional Navigation areas for partitioning navigation by business domain
contextSelectors { id: string; label: string; icon?: string; optionsSource: object; … }[] optional App-level scope dropdowns whose value is injected into nav items as {<id>} template vars
homePageId string optional ID of the navigation item to serve as landing page
requiredPermissions string[] optional Permissions required to access this app
objects any[] optional Objects belonging to this app
apis any[] optional Custom APIs belonging to this app
sharing { enabled?: boolean; publicLink?: string; password?: string; allowedDomains?: string[]; … } optional Public sharing configuration
embed { enabled?: boolean; allowedOrigins?: string[]; width?: string; height?: string; … } optional Iframe embedding configuration
mobileNavigation { mode?: Enum<'drawer' | 'bottom_nav' | 'hamburger'>; bottomNavItems?: string[] } optional Mobile-specific navigation configuration
defaultAgent string optional Platform agent bound to this app's ambient chat ('ask' is the implicit default; 'build' for authoring surfaces) — ADR-0063 §1
aria { ariaLabel?: string; ariaDescribedBy?: string; role?: string } optional ARIA accessibility attributes for the application
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } optional Package author protection block — lock policy for this app.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional documentation link surfaced next to _lockReason.

AppBranding

Properties

Property Type Required Description
primaryColor string optional Primary theme color hex code
accentColor string optional Accent color hex code (highlights, active states). Declared to match the objectui ConsoleLayout read of branding.accentColor (inverse-drift fix, liveness audit #1878/#1891/#1894).
logo string optional Custom logo URL for this app
favicon string optional Custom favicon URL for this app

AppContextSelector

Properties

Property Type Required Description
id string ✅ Selector id; selected value is exposed as the nav template var {<id>}
label string ✅ Dropdown label
icon string optional Icon name
optionsSource { endpoint: string; valueKey: string; labelKey: string; filter?: { key: string; op: Enum<'eq' | 'ne' | 'in' | 'nin'>; value: string | string[] }[] } ✅ Option data source
includeAll boolean ✅ Prepend an "All" option that clears the scope
allValue string ✅ Template value when "All" is selected (empty = no filter)
persist Enum<'query' | 'session' | 'none'> ✅ Persist selection via URL query, sessionStorage, or not at all
placement Enum<'sidebar_header' | 'topbar'> ✅ Render location in the app chrome

ComponentNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'component' ✅
componentRef string ✅ Component registry key (e.g. "metadata:directory")
params Record<string, any> optional Props passed to the component

DashboardNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'dashboard' ✅
dashboardName string ✅ Target dashboard name

GroupNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'group' ✅
expanded boolean optional Default expansion state in sidebar

NavigationArea

Properties

Property Type Required Description
id string ✅ Unique area identifier (lowercase snake_case)
label string ✅ Area display label
icon string optional Area icon name
order number optional Sort order among areas (lower = first)
description string optional Area description
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL) for this area.
requiredPermissions string[] optional Permissions required to access this area
navigation { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | { id: string; label: string; icon?: string; order?: number; … }[] ✅ Navigation items within this area

NavigationContribution

A navigation contribution: a package injecting nav items into an app it does not own (ADR-0029 D7)

Properties

Property Type Required Description
app string ✅ Target app name to contribute navigation into (e.g. "setup")
group string optional Target group nav-item id to append into (e.g. "group_integrations"); omit to append at the app top level
priority integer optional Merge priority within the target group — lower applied first (matches object extender priority)
items { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { id: string; label: string; icon?: string; order?: number; … } | { type: 'separator'; id?: string; order?: number } | { id: string; label: string; icon?: string; order?: number; … }[] ✅ Navigation items contributed into the target app/group

NavigationItem

Union Options

This schema accepts one of the following structures:

Option 1

Type: object

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'object' ✅
objectName string ✅ Target object name
viewName string optional Default list view to open. Defaults to "all". Ignored when recordId is set.
recordId string optional Navigate directly to this record id instead of the list view. Supports template vars: {current_user_id}, {current_org_id}.
recordMode Enum<'view' | 'edit'> optional Open the record in view (default) or edit mode. Only meaningful when recordId is set.
filters Record<string, string> optional URL filter conditions — targets the /:objectName/data bare surface via filter[<field>]=<value> params instead of a saved view. Values support template vars {current_user_id}, {current_org_id}. Mutually exclusive with recordId/viewName.
children [NavigationItem](#navigationitem)[] optional Child navigation items (e.g. specific views)

Option 2

Type: dashboard

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'dashboard' ✅
dashboardName string ✅ Target dashboard name

Option 3

Type: page

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'page' ✅
pageName string ✅ Target custom page component name
params Record<string, any> optional Parameters passed to the page context

Option 4

Type: url

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'url' ✅
url string ✅ Target external URL
target Enum<'_self' | '_blank'> optional Link target window

Option 5

Type: report

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'report' ✅
reportName string ✅ Target report name

Option 6

Type: action

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'action' ✅
actionDef { actionName: string; params?: Record<string, any> } ✅ Action definition to execute when clicked

Option 7

Type: component

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'component' ✅
componentRef string ✅ Component registry key (e.g. "metadata:directory")
params Record<string, any> optional Props passed to the component

Option 8

Type: separator

Properties

Property Type Required Description
type 'separator' ✅
id string optional Optional id for the separator
order number optional Sort order within the same level (lower = first)

Option 9

Type: group

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'group' ✅
expanded boolean optional Default expansion state in sidebar
children [NavigationItem](#navigationitem)[] ✅ Child navigation items

ObjectNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'object' ✅
objectName string ✅ Target object name
viewName string optional Default list view to open. Defaults to "all". Ignored when recordId is set.
recordId string optional Navigate directly to this record id instead of the list view. Supports template vars: {current_user_id}, {current_org_id}.
recordMode Enum<'view' | 'edit'> optional Open the record in view (default) or edit mode. Only meaningful when recordId is set.
filters Record<string, string> optional URL filter conditions — targets the /:objectName/data bare surface via filter[<field>]=<value> params instead of a saved view. Values support template vars {current_user_id}, {current_org_id}. Mutually exclusive with recordId/viewName.

PageNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'page' ✅
pageName string ✅ Target custom page component name
params Record<string, any> optional Parameters passed to the page context

ReportNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'report' ✅
reportName string ✅ Target report name

UrlNavItem

Properties

Property Type Required Description
id string ✅ Unique identifier for this navigation item (lowercase snake_case)
label string ✅ Display proper label
icon string optional Icon name
order number optional Sort order within the same level (lower = first)
badge string | number optional Badge text or count displayed on the item
badgeVariant Enum<'default' | 'secondary' | 'destructive' | 'outline'> optional Visual variant of the nav badge. Declared to match the objectui NavigationRenderer read (inverse-drift fix, liveness audit #1878/#1891/#1894).
visible string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Visibility predicate (CEL). e.g. P'org_admin' in current_user.positions
requiredPermissions string[] optional Permissions required to access this item
requiresObject string optional Hide/disable this entry unless the named object is registered in the runtime
requiresService string optional Hide/disable this entry unless the named kernel service is registered
type 'url' ✅
url string ✅ Target external URL
target Enum<'_self' | '_blank'> optional Link target window