@object-ui/types 3.0.2 → 3.1.0

package/src/workflow.ts

@@ -407,3 +407,229 @@ export interface WorkflowInstanceSchema extends BaseSchema {
    */
   data?: Record<string, any>;
 }
+
+// ============================================================================
+// Flow Designer — spec v3.0.9 enhanced flow editor
+// ============================================================================
+
+/**
+ * Flow node types — includes v3.0.9 gateway/boundary additions
+ */
+export type FlowNodeType =
+  | 'start'
+  | 'end'
+  | 'task'
+  | 'user_task'
+  | 'service_task'
+  | 'script_task'
+  | 'approval'
+  | 'condition'
+  | 'parallel_gateway'
+  | 'join_gateway'
+  | 'boundary_event'
+  | 'delay'
+  | 'notification'
+  | 'webhook';
+
+/**
+ * Wait event type for boundary/delay nodes (spec v3.0.9 WaitEventType)
+ */
+export type FlowWaitEventType = 'condition' | 'manual' | 'webhook' | 'timer' | 'signal';
+
+/**
+ * Execution status for a flow node
+ */
+export type FlowNodeExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+/**
+ * Node executor descriptor (spec v3.0.9 NodeExecutorDescriptor)
+ */
+export interface FlowNodeExecutorDescriptor {
+  /** Executor type identifier */
+  type: string;
+  /** Human-readable label */
+  label?: string;
+  /** Input schema (JSON Schema) */
+  inputSchema?: Record<string, unknown>;
+  /** Output schema (JSON Schema) */
+  outputSchema?: Record<string, unknown>;
+  /** Wait event configuration for wait/timer executors */
+  waitEventConfig?: {
+    eventType: FlowWaitEventType;
+    /** Timer duration expression (ISO 8601 or expression) */
+    timer?: string;
+    /** Condition expression */
+    condition?: string;
+    /** Webhook URL */
+    webhookUrl?: string;
+    /** Signal name */
+    signalName?: string;
+  };
+  /** Timeout behavior */
+  timeoutMs?: number;
+  /** Retry configuration (spec v3.0.9 enhanced retry) */
+  retry?: {
+    maxAttempts?: number;
+    delayMs?: number;
+    backoffMultiplier?: number;
+    maxRetryDelayMs?: number;
+    jitter?: boolean;
+  };
+}
+
+/**
+ * Boundary configuration for boundary event nodes (spec v3.0.9)
+ */
+export interface FlowBoundaryConfig {
+  /** The host node this boundary event is attached to */
+  attachedToNodeId: string;
+  /** Boundary event sub-type */
+  eventType: 'error' | 'timer' | 'message' | 'signal' | 'compensation';
+  /** Whether the boundary event is interrupting */
+  cancelActivity?: boolean;
+  /** Timer expression (ISO 8601) for timer boundary events */
+  timer?: string;
+  /** Error code pattern for error boundary events */
+  errorCode?: string;
+}
+
+/**
+ * A node in the flow graph
+ */
+export interface FlowNode {
+  /** Unique node identifier */
+  id: string;
+  /** Node type */
+  type: FlowNodeType;
+  /** Display label */
+  label: string;
+  /** Node description */
+  description?: string;
+  /** Canvas position */
+  position: { x: number; y: number };
+  /** Node executor configuration (spec v3.0.9) */
+  executor?: FlowNodeExecutorDescriptor;
+  /** Boundary event configuration (spec v3.0.9, only for boundary_event nodes) */
+  boundaryConfig?: FlowBoundaryConfig;
+  /** Runtime execution status (used in monitoring view) */
+  executionStatus?: FlowNodeExecutionStatus;
+  /** Node-specific properties */
+  properties?: Record<string, unknown>;
+}
+
+/**
+ * Flow edge types — includes v3.0.9 conditional edges
+ */
+export type FlowEdgeType = 'default' | 'conditional' | 'timeout';
+
+/**
+ * An edge connecting two flow nodes
+ */
+export interface FlowEdge {
+  /** Unique edge identifier */
+  id: string;
+  /** Source node identifier */
+  source: string;
+  /** Target node identifier */
+  target: string;
+  /** Edge type */
+  type?: FlowEdgeType;
+  /** Display label */
+  label?: string;
+  /** Condition expression (for conditional edges) */
+  condition?: string;
+  /** Whether this is the default/fallthrough edge (spec v3.0.9 isDefault flag) */
+  isDefault?: boolean;
+}
+
+/**
+ * Flow version entry (spec v3.0.9 FlowVersionHistory)
+ */
+export interface FlowVersionEntry {
+  /** Version number */
+  version: number;
+  /** ISO 8601 timestamp */
+  createdAt: string;
+  /** Author identifier */
+  author?: string;
+  /** Change description */
+  changeNote?: string;
+  /** Whether this version is currently active */
+  isCurrent?: boolean;
+}
+
+/**
+ * Concurrency policy (spec v3.0.9 ConcurrencyPolicy)
+ */
+export type FlowConcurrencyPolicy = 'allow' | 'forbid' | 'replace' | 'queue';
+
+/**
+ * BPMN interop result (spec v3.0.9 BpmnInteropResult)
+ */
+export interface FlowBpmnInteropResult {
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Number of nodes mapped */
+  nodeCount?: number;
+  /** Number of edges mapped */
+  edgeCount?: number;
+  /** Warnings produced during mapping */
+  warnings?: string[];
+  /** Errors produced during mapping */
+  errors?: string[];
+  /** Raw BPMN XML string (for export) */
+  bpmnXml?: string;
+}
+
+/**
+ * Execution log step (spec v3.0.9 ExecutionStepLog)
+ */
+export interface FlowExecutionStep {
+  /** Node identifier */
+  nodeId: string;
+  /** Step status */
+  status: FlowNodeExecutionStatus;
+  /** ISO 8601 start timestamp */
+  startedAt?: string;
+  /** ISO 8601 end timestamp */
+  completedAt?: string;
+  /** Error message (if failed) */
+  error?: string;
+  /** Step output data */
+  output?: Record<string, unknown>;
+}
+
+/**
+ * Flow Designer Schema — canvas-based flow editor component
+ */
+export interface FlowDesignerSchema extends BaseSchema {
+  type: 'flow-designer';
+  /** Flow nodes */
+  nodes?: FlowNode[];
+  /** Flow edges */
+  edges?: FlowEdge[];
+  /** Flow title */
+  title?: string;
+  /** Flow description */
+  description?: string;
+  /** Flow lifecycle status */
+  status?: WorkflowStatus;
+  /** Concurrency policy (spec v3.0.9) */
+  concurrencyPolicy?: FlowConcurrencyPolicy;
+  /** Version history */
+  versionHistory?: FlowVersionEntry[];
+  /** Execution steps (for monitoring overlay) */
+  executionSteps?: FlowExecutionStep[];
+  /** Whether the designer is read-only */
+  readOnly?: boolean;
+  /** Show minimap */
+  showMinimap?: boolean;
+  /** Show toolbar */
+  showToolbar?: boolean;
+  /** Show version history panel */
+  showVersionHistory?: boolean;
+  /** Show execution monitoring overlay */
+  showExecutionOverlay?: boolean;
+  /** Callback action name for save */
+  onSave?: string;
+}

package/src/zod/app.zod.ts

@@ -19,8 +19,69 @@
 import { z } from 'zod';
 import { BaseSchema } from './base.zod.js';
 
+// ============================================================================
+// Unified NavigationItem Schema
+// ============================================================================
+
+/**
+ * Navigation Item Type enum
+ */
+export const NavigationItemTypeSchema = z.enum([
+  'object', 'dashboard', 'page', 'report', 'url', 'group', 'separator', 'action',
+]);
+
+/**
+ * Navigation Item Schema — unified model aligned with @objectstack/spec.
+ */
+export const NavigationItemSchema: z.ZodType<any> = z.lazy(() => z.object({
+  id: z.string().describe('Unique identifier'),
+  type: NavigationItemTypeSchema.describe('Navigation item type'),
+  label: z.string().describe('Display label'),
+  icon: z.string().optional().describe('Icon name (Lucide)'),
+
+  // Type-specific target fields
+  objectName: z.string().optional().describe('Target object name (type: object)'),
+  viewName: z.string().optional().describe('Target view name (type: object) — named list view e.g. calendar, pipeline'),
+  dashboardName: z.string().optional().describe('Target dashboard name (type: dashboard)'),
+  pageName: z.string().optional().describe('Target page name (type: page)'),
+  reportName: z.string().optional().describe('Target report name (type: report)'),
+  url: z.string().optional().describe('Target URL (type: url)'),
+  target: z.enum(['_blank', '_self']).optional().describe('Link target (type: url)'),
+
+  // Grouping
+  children: z.array(z.lazy(() => NavigationItemSchema)).optional().describe('Child items (type: group)'),
+
+  // Visibility & Permissions
+  visible: z.union([z.boolean(), z.string()]).optional().describe('Visibility expression'),
+  requiredPermissions: z.array(z.string()).optional().describe('Required permissions'),
+
+  // UX Enhancements
+  badge: z.union([z.string(), z.number()]).optional().describe('Badge text or count'),
+  badgeVariant: z.enum(['default', 'destructive', 'outline']).optional().describe('Badge variant'),
+  defaultOpen: z.boolean().optional().describe('Group default expanded state'),
+  pinned: z.boolean().optional().describe('Pinned item'),
+  order: z.number().optional().describe('Sort order weight'),
+}));
+
+/**
+ * Navigation Area Schema — business-domain partition of navigation.
+ */
+export const NavigationAreaSchema = z.object({
+  id: z.string().describe('Unique identifier'),
+  label: z.string().describe('Display label'),
+  icon: z.string().optional().describe('Icon name (Lucide)'),
+  navigation: z.array(NavigationItemSchema).describe('Navigation items within area'),
+  visible: z.union([z.boolean(), z.string()]).optional().describe('Visibility expression'),
+  requiredPermissions: z.array(z.string()).optional().describe('Required permissions'),
+});
+
+// ============================================================================
+// Legacy MenuItem Schema (backward compat)
+// ============================================================================
+
 /**
  * Menu Item Schema - Navigation menu item
+ * @deprecated Use NavigationItemSchema instead.
  */
 export const MenuItemSchema: z.ZodType<any> = z.lazy(() => z.object({
   type: z.enum(['item', 'group', 'separator']).optional().describe('Item type'),
@@ -33,6 +94,10 @@ export const MenuItemSchema: z.ZodType<any> = z.lazy(() => z.object({
   hidden: z.union([z.boolean(), z.string()]).optional().describe('Visibility condition'),
 }));
 
+// ============================================================================
+// App Action Schema
+// ============================================================================
+
 /**
  * App Action Schema - Application header/toolbar action
  */
@@ -49,6 +114,10 @@ export const AppActionSchema = z.object({
   size: z.enum(['default', 'sm', 'lg', 'icon']).optional().describe('Button size'),
 });
 
+// ============================================================================
+// App Schema
+// ============================================================================
+
 /**
  * App Schema - Top-level application configuration
  */
@@ -60,13 +129,17 @@ export const AppSchema = BaseSchema.extend({
   logo: z.string().optional().describe('Logo URL or icon name'),
   favicon: z.string().optional().describe('Favicon URL'),
   layout: z.enum(['sidebar', 'header', 'empty']).optional().default('sidebar').describe('Global layout strategy'),
-  menu: z.array(MenuItemSchema).optional().describe('Global navigation menu'),
+  menu: z.array(MenuItemSchema).optional().describe('Legacy navigation menu (deprecated, use navigation)'),
+  navigation: z.array(NavigationItemSchema).optional().describe('Unified navigation tree'),
+  areas: z.array(NavigationAreaSchema).optional().describe('Navigation areas (business-domain partitions)'),
   actions: z.array(AppActionSchema).optional().describe('Global actions (user profile, settings, etc.)'),
 });
 
 /**
  * Export type inference helpers
  */
+export type NavigationItemSchemaType = z.infer<typeof NavigationItemSchema>;
+export type NavigationAreaSchemaType = z.infer<typeof NavigationAreaSchema>;
 export type MenuItemSchemaType = z.infer<typeof MenuItemSchema>;
 export type AppActionSchemaType = z.infer<typeof AppActionSchema>;
 export type AppSchemaType = z.infer<typeof AppSchema>;

package/src/zod/complex.zod.ts

@@ -18,6 +18,7 @@
 
 import { z } from 'zod';
 import { BaseSchema, SchemaNodeSchema } from './base.zod.js';
+import { DASHBOARD_COLOR_VARIANTS, DASHBOARD_WIDGET_TYPES } from '../designer.js';
 
 /**
  * Kanban Card Schema
@@ -227,12 +228,18 @@ export const DashboardWidgetLayoutSchema = z.object({
 
 /**
  * Dashboard Widget Schema
+ *
+ * Supports two formats:
+ * 1. Component format (legacy): `{ id, component: { type, ... }, layout }`
+ * 2. Shorthand format (@objectstack/spec): `{ type: 'metric'|'bar'|…, options: {…}, layout }`
  */
 export const DashboardWidgetSchema = z.object({
-  id: z.string().describe('Widget ID'),
+  id: z.string().optional().describe('Widget ID'),
   title: z.string().optional().describe('Widget Title'),
-  component: SchemaNodeSchema.describe('Widget Component'),
+  component: SchemaNodeSchema.optional().describe('Widget Component (legacy format)'),
   layout: DashboardWidgetLayoutSchema.optional().describe('Widget Layout'),
+  type: z.string().optional().describe('Widget visualization type (spec shorthand)'),
+  options: z.unknown().optional().describe('Widget specific configuration (spec shorthand)'),
 });
 
 /**
@@ -245,6 +252,64 @@ export const DashboardSchema = BaseSchema.extend({
   widgets: z.array(DashboardWidgetSchema).describe('Dashboard widgets'),
 });
 
+/**
+ * Dashboard Widget Config Schema (for DashboardConfigPanel)
+ */
+export const DashboardWidgetConfigSchema = z.object({
+  id: z.string().describe('Widget ID'),
+  title: z.string().optional().describe('Widget title'),
+  description: z.string().optional().describe('Widget description'),
+  type: z.enum(DASHBOARD_WIDGET_TYPES).optional().describe('Widget visualization type'),
+  object: z.string().optional().describe('Data source object name'),
+  filter: z.array(z.any()).optional().describe('Widget filter conditions'),
+  categoryField: z.string().optional().describe('Category/x-axis field'),
+  valueField: z.string().optional().describe('Value/y-axis field'),
+  aggregate: z.string().optional().describe('Aggregation function'),
+  chartConfig: z.any().optional().describe('Chart configuration'),
+  colorVariant: z.enum(DASHBOARD_COLOR_VARIANTS).optional().describe('Color variant'),
+  layout: DashboardWidgetLayoutSchema.optional().describe('Widget grid layout'),
+  actionUrl: z.string().optional().describe('Clickable action URL'),
+});
+
+/**
+ * Dashboard Config Schema — Zod validator for DashboardConfigPanel data model.
+ *
+ * Validates the unified dashboard configuration used by create/edit workflows.
+ */
+export const DashboardConfigSchema = z.object({
+  id: z.string().optional().describe('Dashboard identifier'),
+  title: z.string().optional().describe('Dashboard title'),
+  description: z.string().optional().describe('Dashboard description'),
+  columns: z.number().min(1).max(24).optional().describe('Grid columns (1-24)'),
+  gap: z.number().min(0).optional().describe('Grid gap in pixels'),
+  refreshInterval: z.number().min(0).optional().describe('Auto-refresh interval in seconds'),
+  widgets: z.array(DashboardWidgetConfigSchema).optional().describe('Dashboard widgets'),
+  globalFilters: z.array(z.any()).optional().describe('Global filter conditions'),
+  dateRange: z.object({
+    enabled: z.boolean().optional(),
+    field: z.string().optional(),
+    presets: z.array(z.string()).optional(),
+  }).optional().describe('Date range filter'),
+  userFilters: z.array(z.object({
+    field: z.string(),
+    label: z.string().optional(),
+    type: z.string().optional(),
+  })).optional().describe('User-selectable filters'),
+  showHeader: z.boolean().optional().describe('Show dashboard header'),
+  showFilters: z.boolean().optional().describe('Show global filter bar'),
+  showDateRange: z.boolean().optional().describe('Show date range picker'),
+  headerActions: z.array(z.object({
+    label: z.string(),
+    action: z.string().optional(),
+    icon: z.string().optional(),
+    variant: z.string().optional(),
+  })).optional().describe('Header action buttons'),
+  aria: z.object({
+    label: z.string().optional(),
+    description: z.string().optional(),
+  }).optional().describe('ARIA accessibility attributes'),
+});
+
 /**
  * Complex Schema Union - All complex component schemas
  */

package/src/zod/data-display.zod.ts

@@ -147,6 +147,8 @@ export const DataTableSchema = BaseSchema.extend({
   onRowDelete: z.function().optional().describe('Row delete handler'),
   onSelectionChange: z.function().optional().describe('Selection change handler'),
   onColumnsReorder: z.function().optional().describe('Column reorder handler'),
+  frozenColumns: z.number().optional().describe('Number of frozen columns'),
+  showRowNumbers: z.boolean().optional().describe('Show row numbers'),
 });
 
 /**

package/src/zod/index.zod.ts

@@ -40,6 +40,9 @@
 export {
   AppSchema,
   AppActionSchema,
+  NavigationItemSchema,
+  NavigationItemTypeSchema,
+  NavigationAreaSchema,
   MenuItemSchema as AppMenuItemSchema,
 } from './app.zod.js';
 
@@ -227,6 +230,8 @@ export {
   DashboardWidgetLayoutSchema,
   DashboardWidgetSchema,
   DashboardSchema,
+  DashboardWidgetConfigSchema,
+  DashboardConfigSchema,
   ComplexSchema,
 } from './complex.zod.js';
 

package/src/zod/navigation.zod.ts

@@ -34,6 +34,20 @@ export const NavLinkSchema: z.ZodType<any> = z.lazy(() =>
   })
 );
 
+/**
+ * Breadcrumb Item Schema
+ */
+export const BreadcrumbItemSchema = z.object({
+  label: z.string().describe('Breadcrumb label'),
+  href: z.string().optional().describe('Link URL'),
+  icon: z.string().optional().describe('Breadcrumb icon'),
+  onClick: z.function().optional().describe('Click handler'),
+  siblings: z.array(z.object({
+    label: z.string().describe('Sibling label'),
+    href: z.string().describe('Sibling URL'),
+  })).optional().describe('Sibling items for dropdown navigation'),
+});
+
 /**
  * Header Bar Schema - Header/navigation bar component
  */
@@ -42,6 +56,14 @@ export const HeaderBarSchema = BaseSchema.extend({
   title: z.string().optional().describe('Header title'),
   logo: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Logo content'),
   nav: z.array(NavLinkSchema).optional().describe('Navigation links'),
+  crumbs: z.array(BreadcrumbItemSchema).optional().describe('Breadcrumb items'),
+  search: z.object({
+    enabled: z.boolean().describe('Whether search is enabled'),
+    placeholder: z.string().optional().describe('Search placeholder text'),
+    shortcut: z.string().optional().describe('Keyboard shortcut (e.g., "⌘K")'),
+  }).optional().describe('Search configuration'),
+  actions: z.array(SchemaNodeSchema).optional().describe('Right-side action slots'),
+  rightContent: SchemaNodeSchema.optional().describe('Custom right content area'),
   left: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Left content'),
   center: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Center content'),
   right: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional().describe('Right content'),
@@ -69,16 +91,6 @@ export const SidebarSchema = BaseSchema.extend({
   variant: z.enum(['default', 'bordered', 'floating']).optional().describe('Sidebar variant'),
 });
 
-/**
- * Breadcrumb Item Schema
- */
-export const BreadcrumbItemSchema = z.object({
-  label: z.string().describe('Breadcrumb label'),
-  href: z.string().optional().describe('Link URL'),
-  icon: z.string().optional().describe('Breadcrumb icon'),
-  onClick: z.function().optional().describe('Click handler'),
-});
-
 /**
  * Breadcrumb Schema - Breadcrumb navigation
  */