Skip to content

app.mdx

Latest commit

 

History

History
394 lines (286 loc) · 14.6 KB

app.mdx

File metadata and controls

394 lines (286 loc) · 14.6 KB
Raw
title App
description App protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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, DashboardNavItem, GroupNavItem, NavigationArea, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui';
import type { ActionNavItem, App, AppBranding, DashboardNavItem, GroupNavItem, NavigationArea, 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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
actionDef Object ✅ 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 Object optional App-specific branding
active boolean ✅ Whether the app is enabled
isDefault boolean ✅ Is default app
navigation [__schema0](./__schema0)[] optional Full navigation tree for the app sidebar
areas Object[] optional Navigation areas for partitioning navigation by business domain
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 Object optional Public sharing configuration
embed Object optional Iframe embedding configuration
mobileNavigation Object optional Mobile-specific navigation configuration
aria Object optional ARIA accessibility attributes for the application

AppBranding

Properties

Property Type Required Description
primaryColor string optional Primary theme color hex code
logo string optional Custom logo URL for this app
favicon string optional Custom favicon URL for this app

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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
expanded boolean ✅ 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 optional Visibility formula condition for this area
requiredPermissions string[] optional Permissions required to access this area
navigation [__schema0](./__schema0)[] ✅ Navigation items within this area

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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
objectName string ✅ Target object name
viewName string optional Default list view to open. Defaults to "all"
children [#](./#)[] 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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
url string ✅ Target external URL
target Enum<'_self' | '_blank'> ✅ 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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
actionDef Object ✅ Action definition to execute when clicked

Option 7

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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
expanded boolean ✅ Default expansion state in sidebar
children [#](./#)[] ✅ 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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
objectName string ✅ Target object name
viewName string optional Default list view to open. Defaults to "all"

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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
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
visible string optional Visibility formula condition
requiredPermissions string[] optional Permissions required to access this item
type string ✅
url string ✅ Target external URL
target Enum<'_self' | '_blank'> ✅ Link target window