@object-ui/types 3.0.2 → 3.1.0

package/src/app.ts

@@ -11,10 +11,144 @@
  * 
  * Defines the metadata structure for a complete application, including
  * global layout, navigation menus, and routing configuration.
+ * 
+ * ## Navigation Model
+ * 
+ * ObjectUI uses a unified `NavigationItem` model aligned with @objectstack/spec.
+ * The legacy `MenuItem` type is retained for backward compatibility but new
+ * configurations should use `NavigationItem` and the `navigation` / `areas` fields.
  */
 
 import type { BaseSchema } from './base';
 
+// ============================================================================
+// Unified Navigation Model (aligned with @objectstack/spec)
+// ============================================================================
+
+/**
+ * Navigation item type — determines the target and required fields.
+ */
+export type NavigationItemType =
+  | 'object'
+  | 'dashboard'
+  | 'page'
+  | 'report'
+  | 'url'
+  | 'group'
+  | 'separator'
+  | 'action';
+
+/**
+ * Unified Navigation Item
+ * 
+ * The single navigation primitive used across ObjectUI and @objectstack/spec.
+ * Replaces the legacy `MenuItem` for application navigation trees.
+ * 
+ * Supports typed navigation targets (object, dashboard, page, report, url),
+ * nested groups, visibility expressions, RBAC permissions, and UX enhancements
+ * like badges, pinning, and sort ordering.
+ */
+export interface NavigationItem {
+  /** Unique identifier */
+  id: string;
+
+  /** Navigation item type */
+  type: NavigationItemType;
+
+  /** Display label (plain string or I18nLabel object for internationalization) */
+  label: string | { key: string; defaultValue?: string; params?: Record<string, any> };
+
+  /** Icon name (Lucide) */
+  icon?: string;
+
+  // -- Type-specific target fields --
+
+  /** Target object name (for type: 'object') */
+  objectName?: string;
+
+  /** Target view name (for type: 'object') — opens a specific named list view e.g. 'calendar', 'pipeline' */
+  viewName?: string;
+
+  /** Target dashboard name (for type: 'dashboard') */
+  dashboardName?: string;
+
+  /** Target page name (for type: 'page') */
+  pageName?: string;
+
+  /** Target report name (for type: 'report') */
+  reportName?: string;
+
+  /** Target URL (for type: 'url') */
+  url?: string;
+
+  /** Link target (for type: 'url') */
+  target?: '_blank' | '_self';
+
+  // -- Grouping --
+
+  /** Child navigation items (for type: 'group') */
+  children?: NavigationItem[];
+
+  // -- Visibility & Permissions --
+
+  /** Visibility expression — boolean or expression string e.g. "${user.role === 'admin'}" */
+  visible?: boolean | string;
+
+  /** Required permissions to see/access this item */
+  requiredPermissions?: string[];
+
+  // -- UX Enhancements --
+
+  /** Badge text or count */
+  badge?: string | number;
+
+  /** Badge visual variant */
+  badgeVariant?: 'default' | 'destructive' | 'outline';
+
+  /** Whether group is expanded by default (for type: 'group') */
+  defaultOpen?: boolean;
+
+  /** Whether this item is pinned */
+  pinned?: boolean;
+
+  /** Sort order weight (lower = higher) */
+  order?: number;
+}
+
+/**
+ * Navigation Area — a business-domain partition of navigation items.
+ * 
+ * Inspired by Salesforce Lightning App → Area → Tab model and
+ * Microsoft Power Apps Area → Group → Subarea pattern.
+ * 
+ * Each area contains an independent navigation tree, allowing large
+ * enterprise applications to organise navigation by domain (e.g.
+ * Sales, Service, Marketing).
+ */
+export interface NavigationArea {
+  /** Unique identifier */
+  id: string;
+
+  /** Display label (plain string or I18nLabel object for internationalization) */
+  label: string | { key: string; defaultValue?: string; params?: Record<string, any> };
+
+  /** Icon name (Lucide) */
+  icon?: string;
+
+  /** Navigation items within this area */
+  navigation: NavigationItem[];
+
+  /** Visibility expression */
+  visible?: boolean | string;
+
+  /** Required permissions to see this area */
+  requiredPermissions?: string[];
+}
+
+// ============================================================================
+// Application Schema
+// ============================================================================
+
 /**
  * Top-level Application Configuration (app.json)
  */
@@ -31,11 +165,21 @@ export interface AppSchema extends BaseSchema {
    */
   title?: string;
 
+  /**
+   * Display Label (used in navigation and app switcher)
+   */
+  label?: string;
+
   /**
    * Application Description
    */
   description?: string;
 
+  /**
+   * Icon name (Lucide) for app switcher and navigation
+   */
+  icon?: string;
+
   /**
    * Logo URL or Icon name
    */
@@ -46,6 +190,17 @@ export interface AppSchema extends BaseSchema {
    */
   favicon?: string;
 
+  /**
+   * Branding configuration
+   */
+  branding?: BrandingConfig;
+
+  /**
+   * Whether the application is active (visible in app switcher)
+   * @default true
+   */
+  active?: boolean;
+
   /**
    * Global Layout Strategy
    * - sidebar: Standard admin layout with left sidebar
@@ -57,9 +212,23 @@ export interface AppSchema extends BaseSchema {
 
   /**
    * Global Navigation Menu
+   * @deprecated Use `navigation` instead. Retained for backward compatibility.
    */
   menu?: MenuItem[];
 
+  /**
+   * Unified navigation tree (aligned with @objectstack/spec NavigationItem model).
+   * Takes precedence over `menu` when both are present.
+   */
+  navigation?: NavigationItem[];
+
+  /**
+   * Navigation areas / business-domain partitions.
+   * When provided, the sidebar displays an area switcher and renders
+   * the selected area's navigation tree.
+   */
+  areas?: NavigationArea[];
+
   /**
    * Global Actions (User Profile, Settings, etc)
    */
@@ -78,8 +247,13 @@ export interface AppSchema extends BaseSchema {
   requiredPermissions?: string[];
 }
 
+// ============================================================================
+// Legacy MenuItem (backward compat — prefer NavigationItem)
+// ============================================================================
+
 /**
  * Navigation Menu Item
+ * @deprecated Use `NavigationItem` instead.
  */
 export interface MenuItem {
   /**
@@ -123,6 +297,209 @@ export interface MenuItem {
   hidden?: boolean | string;
 }
 
+// ============================================================================
+// MenuItem → NavigationItem Transform
+// ============================================================================
+
+/**
+ * Convert a legacy `MenuItem` to a `NavigationItem`.
+ * 
+ * Mapping rules:
+ * - `type: 'item'` → inferred from `href` (url) or `path` (page)
+ * - `type: 'group'` → `type: 'group'`
+ * - `type: 'separator'` → `type: 'separator'`
+ * - `hidden` → `visible` (inverted)
+ * - `path` → `pageName` (last segment) or kept as-is for url
+ * - `href` → `url` with `target: '_blank'`
+ */
+export function menuItemToNavigationItem(
+  item: MenuItem,
+  index: number = 0,
+): NavigationItem {
+  const id = `migrated_${index}`;
+
+  if (item.type === 'separator') {
+    return {
+      id,
+      type: 'separator',
+      label: item.label || '',
+    };
+  }
+
+  if (item.type === 'group') {
+    return {
+      id,
+      type: 'group',
+      label: item.label || '',
+      icon: item.icon,
+      children: (item.children || []).map((child, i) =>
+        menuItemToNavigationItem(child, index * 100 + i),
+      ),
+      visible: item.hidden !== undefined ? !item.hidden : undefined,
+      badge: item.badge,
+      defaultOpen: true,
+    };
+  }
+
+  // Default: 'item' type — infer target from href / path
+  if (item.href) {
+    return {
+      id,
+      type: 'url',
+      label: item.label || '',
+      icon: item.icon,
+      url: item.href,
+      target: '_blank',
+      visible: item.hidden !== undefined ? !item.hidden : undefined,
+      badge: item.badge,
+    };
+  }
+
+  // Path-based item → treat as page navigation
+  return {
+    id,
+    type: 'page',
+    label: item.label || '',
+    icon: item.icon,
+    pageName: item.path || '',
+    visible: item.hidden !== undefined ? !item.hidden : undefined,
+    badge: item.badge,
+  };
+}
+
+// ============================================================================
+// App Creation Wizard Types
+// ============================================================================
+
+/**
+ * Wizard step identifier for app creation flow.
+ */
+export type AppWizardStepId = 'basic' | 'objects' | 'navigation' | 'branding';
+
+/**
+ * App wizard step definition.
+ */
+export interface AppWizardStep {
+  /** Step identifier */
+  id: AppWizardStepId;
+
+  /** Display label */
+  label: string;
+
+  /** Step description */
+  description?: string;
+
+  /** Icon name (Lucide) */
+  icon?: string;
+
+  /** Whether the step is optional */
+  optional?: boolean;
+}
+
+/**
+ * Branding configuration for an application.
+ */
+export interface BrandingConfig {
+  /** Logo URL or base64 data URI */
+  logo?: string;
+
+  /** Primary brand color (hex) */
+  primaryColor?: string;
+
+  /** Favicon URL */
+  favicon?: string;
+
+  /** Font family override */
+  fontFamily?: string;
+}
+
+/**
+ * Object selection entry for the wizard.
+ */
+export interface ObjectSelection {
+  /** Object name (snake_case) */
+  name: string;
+
+  /** Display label */
+  label: string;
+
+  /** Icon name (Lucide) */
+  icon?: string;
+
+  /** Whether this object is selected */
+  selected: boolean;
+}
+
+/**
+ * App creation wizard draft state — represents the in-progress
+ * application configuration before it is finalized into an AppSchema.
+ */
+export interface AppWizardDraft {
+  /** App name (snake_case, validated) */
+  name: string;
+
+  /** Display title */
+  title: string;
+
+  /** Description */
+  description?: string;
+
+  /** App icon name (Lucide) */
+  icon?: string;
+
+  /** Template to start from */
+  template?: string;
+
+  /** Layout strategy */
+  layout: 'sidebar' | 'header' | 'empty';
+
+  /** Selected business objects */
+  objects: ObjectSelection[];
+
+  /** Navigation tree being built */
+  navigation: NavigationItem[];
+
+  /** Branding configuration */
+  branding: BrandingConfig;
+}
+
+/**
+ * Editor mode for the app designer.
+ */
+export type EditorMode = 'edit' | 'preview' | 'code';
+
+/**
+ * Validate an app name is snake_case.
+ * Pattern: starts with lowercase letter, followed by lowercase letters/digits,
+ * with optional underscore-separated segments (no trailing/leading/double underscores).
+ */
+export function isValidAppName(name: string): boolean {
+  return /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/.test(name);
+}
+
+/**
+ * Convert an AppWizardDraft to an AppSchema.
+ */
+export function wizardDraftToAppSchema(draft: AppWizardDraft): AppSchema {
+  return {
+    type: 'app',
+    name: draft.name,
+    title: draft.title,
+    label: draft.title,
+    description: draft.description,
+    icon: draft.icon,
+    logo: draft.branding.logo,
+    favicon: draft.branding.favicon,
+    branding: draft.branding,
+    layout: draft.layout,
+    navigation: draft.navigation,
+  };
+}
+
+// ============================================================================
+// Application Actions
+// ============================================================================
+
 /**
  * Application Header/Toolbar Action
  */

package/src/complex.ts

@@ -17,35 +17,6 @@
 
 import type { BaseSchema, SchemaNode } from './base';
 
-/**
- * Dashboard Component Schema
- * (Report / BI View)
- */
-export interface DashboardSchema extends BaseSchema {
-  type: 'dashboard';
-  /**
-   * Layout Grid Configuration (e.g. 12 column grid)
-   */
-  columns?: number;
-  /**
-   * Widget gap
-   */
-  gap?: number;
-  /**
-   * Dashboard Widgets
-   */
-  widgets: Array<{
-    /** Unique Widget ID */
-    id: string;
-    /** Widget Title */
-    title?: string;
-    /** Widget Component (Chart, Statistic, List, etc) */
-    component: SchemaNode;
-    /** Grid Position: x, y, w, h */
-    layout?: { x: number; y: number; w: number; h: number };
-  }>;
-}
-
 /**
  * Kanban column
  */
@@ -503,12 +474,85 @@ export interface DashboardWidgetLayout {
 
 /**
  * Dashboard Widget
+ *
+ * Supports two formats:
+ * 1. **Component format** (legacy): `{ id, component: { type, ... }, layout }`
+ * 2. **Shorthand format** (@objectstack/spec): `{ type: 'metric'|'bar'|…, options: {…}, layout }`
  */
 export interface DashboardWidgetSchema {
-  id: string;
+  id?: string;
   title?: string;
-  component: SchemaNode;
+  /** Widget description */
+  description?: string;
+  /** Component schema (legacy format) */
+  component?: SchemaNode;
   layout?: DashboardWidgetLayout;
+  /** Widget visualization type (spec shorthand format) */
+  type?: string;
+  /** Widget-specific configuration (spec shorthand format) */
+  options?: unknown;
+  /** Chart configuration for chart-type widgets */
+  chartConfig?: any;
+  /**
+   * Widget color variant.
+   * Aligned with @objectstack/spec WidgetColorVariantSchema.
+   */
+  colorVariant?: 'default' | 'blue' | 'teal' | 'orange' | 'purple' | 'success' | 'warning' | 'danger';
+  /** Action URL for clickable widgets */
+  actionUrl?: string;
+  /** Action type for widget interactions */
+  actionType?: string;
+  /** Action icon name */
+  actionIcon?: string;
+  /**
+   * Data binding: Object name for data source.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.object.
+   */
+  object?: string;
+  /**
+   * Data binding: Filter conditions.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.filter.
+   */
+  filter?: any;
+  /**
+   * Data binding: Category field for grouping.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.categoryField.
+   */
+  categoryField?: string;
+  /**
+   * Data binding: Value field for aggregation.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.valueField.
+   */
+  valueField?: string;
+  /**
+   * Aggregation function.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.aggregate.
+   */
+  aggregate?: string;
+  /**
+   * Multiple measures for pivot/matrix display.
+   * Aligned with @objectstack/spec WidgetMeasureSchema.
+   */
+  measures?: Array<{
+    valueField: string;
+    aggregate: string;
+    label?: string;
+    format?: string;
+  }>;
+  /**
+   * Responsive configuration per breakpoint.
+   * Aligned with @objectstack/spec DashboardWidgetSchema.responsive.
+   */
+  responsive?: any;
+  /**
+   * ARIA accessibility attributes.
+   * Aligned with @objectstack/spec AriaPropsSchema.
+   */
+  aria?: {
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+    role?: string;
+  };
 }
 
 /**
@@ -516,11 +560,67 @@ export interface DashboardWidgetSchema {
  */
 export interface DashboardSchema extends BaseSchema {
   type: 'dashboard';
+  /** Dashboard title displayed in the header */
+  title?: string;
   columns?: number;
   gap?: number;
   widgets: DashboardWidgetSchema[];
   /** Auto-refresh interval in seconds. When set, the dashboard will periodically trigger onRefresh. */
   refreshInterval?: number;
+  /**
+   * Dashboard header configuration.
+   * Aligned with @objectstack/spec DashboardHeaderSchema.
+   */
+  header?: {
+    showTitle?: boolean;
+    showDescription?: boolean;
+    actions?: Array<{
+      label: string;
+      actionUrl?: string;
+      actionType?: string;
+      icon?: string;
+    }>;
+  };
+  /**
+   * Global filter configurations.
+   * Applied across all dashboard widgets.
+   * Aligned with @objectstack/spec GlobalFilterSchema.
+   */
+  globalFilters?: Array<{
+    field: string;
+    label?: string;
+    type?: 'text' | 'select' | 'date' | 'number' | 'lookup';
+    options?: string[];
+    optionsFrom?: {
+      object: string;
+      valueField: string;
+      labelField?: string;
+      filter?: any;
+    };
+    defaultValue?: any;
+    scope?: string;
+    targetWidgets?: string[];
+  }>;
+  /**
+   * Date range filter configuration.
+   * Aligned with @objectstack/spec DashboardSchema.dateRange.
+   */
+  dateRange?: {
+    field?: string;
+    defaultRange?: 'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month'
+      | 'this_quarter' | 'last_quarter' | 'this_year' | 'last_year'
+      | 'last_7_days' | 'last_30_days' | 'last_90_days' | 'custom';
+    allowCustomRange?: boolean;
+  };
+  /**
+   * ARIA accessibility attributes.
+   * Aligned with @objectstack/spec AriaPropsSchema.
+   */
+  aria?: {
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+    role?: string;
+  };
 }
 
 /**