@object-ui/types 3.0.3 → 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

@@ -482,6 +482,8 @@ export interface DashboardWidgetLayout {
 export interface DashboardWidgetSchema {
   id?: string;
   title?: string;
+  /** Widget description */
+  description?: string;
   /** Component schema (legacy format) */
   component?: SchemaNode;
   layout?: DashboardWidgetLayout;
@@ -489,6 +491,68 @@ export interface DashboardWidgetSchema {
   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;
+  };
 }
 
 /**
@@ -496,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;
+  };
 }
 
 /**

package/src/data-display.ts

@@ -341,6 +341,13 @@ export interface DataTableSchema extends BaseSchema {
    * @default false
    */
   selectable?: boolean | 'single' | 'multiple';
+  /**
+   * Selection checkbox display style
+   * - 'always': Checkboxes are always visible
+   * - 'hover': Checkboxes only appear on row hover
+   * @default 'always'
+   */
+  selectionStyle?: 'always' | 'hover';
   /**
    * Enable column sorting
    * @default true
@@ -388,6 +395,12 @@ export interface DataTableSchema extends BaseSchema {
    * @default false
    */
   editable?: boolean;
+  /**
+   * Enable single-click editing mode
+   * When true with editable, clicking a cell enters edit mode (instead of double-click)
+   * @default false
+   */
+  singleClickEdit?: boolean;
   /**
    * Cell value change handler
    * Called when a cell value is edited
@@ -413,6 +426,41 @@ export interface DataTableSchema extends BaseSchema {
    * Function that returns a CSS class string for each row
    */
   rowClassName?: (row: any, index: number) => string | undefined;
+  /**
+   * Dynamic row inline style
+   * Function that returns CSSProperties for each row (e.g., from conditionalFormatting).
+   */
+  rowStyle?: (row: any, index: number) => React.CSSProperties | undefined;
+  /**
+   * Number of columns to freeze (left-pin)
+   * When set, the first N columns remain fixed while the rest scroll horizontally.
+   * @default 0
+   */
+  frozenColumns?: number;
+  /**
+   * Show row numbers in the first column (Airtable-style)
+   * @default false
+   */
+  showRowNumbers?: boolean;
+  /**
+   * Show "+ Add record" row at the bottom of the table (Airtable-style)
+   * @default false
+   */
+  showAddRow?: boolean;
+  /**
+   * Callback when the "+ Add record" row is clicked
+   */
+  onAddRecord?: () => void;
+  /**
+   * Column resize handler
+   * Called when a column is resized
+   */
+  onColumnResize?: (columnKey: string, width: number) => void;
+  /**
+   * Column reorder handler (new order of accessorKeys)
+   * Called when columns are reordered via drag-and-drop
+   */
+  onColumnReorder?: (newOrder: string[]) => void;
 }
 
 /**
@@ -593,6 +641,64 @@ export interface ChartSchema extends BaseSchema {
   config?: Record<string, any>;
 }
 
+/**
+ * Aggregation function for pivot table values
+ */
+export type PivotAggregation = 'sum' | 'count' | 'avg' | 'min' | 'max';
+
+/**
+ * Pivot table (cross-tabulation) component
+ *
+ * Renders a matrix where rows correspond to one field,
+ * columns to another, and cells show an aggregated value.
+ */
+export interface PivotTableSchema extends BaseSchema {
+  type: 'pivot';
+  /**
+   * Pivot table title
+   */
+  title?: string;
+  /**
+   * Field used for row headers
+   */
+  rowField: string;
+  /**
+   * Field used for column headers
+   */
+  columnField: string;
+  /**
+   * Field whose values are aggregated in cells
+   */
+  valueField: string;
+  /**
+   * Aggregation function applied to valueField
+   * @default 'sum'
+   */
+  aggregation?: PivotAggregation;
+  /**
+   * Source data rows
+   */
+  data: Record<string, unknown>[];
+  /**
+   * Show a totals column on the right
+   * @default false
+   */
+  showRowTotals?: boolean;
+  /**
+   * Show a totals row at the bottom
+   * @default false
+   */
+  showColumnTotals?: boolean;
+  /**
+   * Numeric format string (e.g. "$,.2f") — applied via simple prefix/suffix/decimals
+   */
+  format?: string;
+  /**
+   * Mapping of column header values to Tailwind text-color classes
+   */
+  columnColors?: Record<string, string>;
+}
+
 /**
  * Timeline event
  */
@@ -706,6 +812,7 @@ export type DataDisplaySchema =
   | MarkdownSchema
   | TreeViewSchema
   | ChartSchema
+  | PivotTableSchema
   | TimelineSchema
   | HtmlSchema
   | StatisticSchema