@object-ui/types 0.5.0 → 3.0.0

package/src/ui-action.ts

@@ -9,7 +9,7 @@
 /**
  * @object-ui/types - UI Action Schema
  * 
- * ObjectStack Spec v0.7.1 compliant action schema with enhanced capabilities:
+ * ObjectStack Spec v2.0.1 compliant action schema with enhanced capabilities:
  * - Location-based action placement
  * - Parameter collection
  * - Conditional visibility and enablement
@@ -19,30 +19,13 @@
  * @packageDocumentation
  */
 
-/**
- * Field type for action parameters
- * Simplified type definition for parameter inputs
- */
-export type ActionParamFieldType =
-  | 'text'
-  | 'textarea'
-  | 'number'
-  | 'boolean'
-  | 'date'
-  | 'datetime'
-  | 'time'
-  | 'select'
-  | 'email'
-  | 'phone'
-  | 'url'
-  | 'password'
-  | 'file'
-  | 'color'
-  | 'slider'
-  | 'rating';
+// ============================================================================
+// Spec-Canonical Action Sub-types — imported from @objectstack/spec/ui
+// ============================================================================
 
 /**
- * Action placement locations (ObjectStack Spec v0.7.1)
+ * Action placement locations
+ * Canonical definition from @objectstack/spec/ui ActionSchema.locations.
  */
 export type ActionLocation = 
   | 'list_toolbar'       // Top toolbar in list views
@@ -53,7 +36,8 @@ export type ActionLocation =
   | 'global_nav';        // Global navigation bar
 
 /**
- * Visual component type for actions (ObjectStack Spec v0.7.1)
+ * Visual component type for actions
+ * Canonical definition from @objectstack/spec/ui ActionSchema.component.
  */
 export type ActionComponent = 
   | 'action:button'      // Standard button
@@ -62,7 +46,8 @@ export type ActionComponent =
   | 'action:group';      // Action group/dropdown
 
 /**
- * Action execution type (ObjectStack Spec v0.7.1)
+ * Action execution type
+ * Canonical definition from @objectstack/spec/ui ActionSchema.type.
  */
 export type ActionType = 
   | 'script'             // Execute JavaScript/expression
@@ -72,7 +57,30 @@ export type ActionType =
   | 'api';               // Call API endpoint
 
 /**
- * Action parameter definition (ObjectStack Spec v0.7.1)
+ * Field type for action parameters
+ * Subset of field types commonly used in action parameter collection UIs.
+ * Aligned with the field types available in @objectstack/spec ActionParamSchema.
+ */
+export type ActionParamFieldType =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'time'
+  | 'select'
+  | 'email'
+  | 'phone'
+  | 'url'
+  | 'password'
+  | 'file'
+  | 'color'
+  | 'slider'
+  | 'rating';
+
+/**
+ * Action parameter definition (ObjectStack Spec v2.0.1)
  */
 export interface ActionParam {
   /** Parameter name (snake_case) */
@@ -104,7 +112,7 @@ export interface ActionParam {
 }
 
 /**
- * Enhanced Action Schema (ObjectStack Spec v0.7.1)
+ * Enhanced Action Schema (ObjectStack Spec v2.0.1)
  * 
  * This is the primary action schema that should be used for all new implementations.
  * The legacy ActionSchema in crud.ts is maintained for backward compatibility.
@@ -274,3 +282,134 @@ export type ActionExecutor = (
   context: ActionContext,
   params?: Record<string, any>
 ) => Promise<ActionResult>;
+
+// ============================================================================
+// Batch Operations (Q2 2026 - Spec v2.0.1 Enhancement)
+// ============================================================================
+
+/** Batch operation configuration */
+export interface BatchOperationConfig {
+  /** Operation name */
+  name: string;
+  /** Display label */
+  label: string;
+  /** Target action to execute on each record */
+  action: string;
+  /** Whether to run in parallel */
+  parallel?: boolean;
+  /** Maximum concurrent operations */
+  concurrency?: number;
+  /** Whether to continue on error */
+  continueOnError?: boolean;
+  /** Progress callback expression */
+  onProgress?: string;
+  /** Completion callback expression */
+  onComplete?: string;
+}
+
+/** Batch operation result */
+export interface BatchOperationResult {
+  /** Total items processed */
+  total: number;
+  /** Successfully processed count */
+  succeeded: number;
+  /** Failed count */
+  failed: number;
+  /** Individual results */
+  results: Array<{
+    recordId: string;
+    success: boolean;
+    error?: string;
+  }>;
+}
+
+// ============================================================================
+// Transaction Support (Q2 2026 - Spec v2.0.1 Enhancement)
+// ============================================================================
+
+/** Transaction isolation level */
+export type TransactionIsolationLevel = 'read-uncommitted' | 'read-committed' | 'repeatable-read' | 'serializable';
+
+/** Transaction configuration */
+export interface TransactionConfig {
+  /** Transaction name for identification */
+  name?: string;
+  /** Isolation level */
+  isolation?: TransactionIsolationLevel;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Actions to execute within the transaction */
+  actions: ActionSchema[];
+  /** Rollback action on failure */
+  rollbackAction?: string;
+  /** Whether to auto-retry on conflict */
+  retryOnConflict?: boolean;
+  /** Maximum retry attempts */
+  maxRetries?: number;
+}
+
+/** Transaction result */
+export interface TransactionResult {
+  /** Whether all actions succeeded */
+  success: boolean;
+  /** Transaction ID */
+  transactionId: string;
+  /** Individual action results */
+  actionResults: ActionResult[];
+  /** Error if transaction failed */
+  error?: string;
+  /** Whether the transaction was rolled back */
+  rolledBack?: boolean;
+}
+
+// ============================================================================
+// Undo/Redo Support (Q2 2026 - Spec v2.0.1 Enhancement)
+// ============================================================================
+
+/** Undo/redo operation entry */
+export interface UndoRedoEntry {
+  /** Entry identifier */
+  id: string;
+  /** Action that was performed */
+  action: string;
+  /** Description of the action */
+  description: string;
+  /** Timestamp */
+  timestamp: string;
+  /** Data before the action (for undo) */
+  previousState: Record<string, unknown>;
+  /** Data after the action (for redo) */
+  nextState: Record<string, unknown>;
+  /** Target object */
+  object?: string;
+  /** Target record ID */
+  recordId?: string;
+}
+
+/** Undo/redo configuration */
+export interface UndoRedoConfig {
+  /** Enable undo/redo */
+  enabled: boolean;
+  /** Maximum history size */
+  maxHistorySize?: number;
+  /** Actions that support undo */
+  undoableActions?: string[];
+  /** Whether to group rapid changes */
+  groupChanges?: boolean;
+  /** Group timeout in milliseconds */
+  groupTimeout?: number;
+}
+
+/** Undo/redo state */
+export interface UndoRedoState {
+  /** Whether undo is available */
+  canUndo: boolean;
+  /** Whether redo is available */
+  canRedo: boolean;
+  /** Undo stack */
+  undoStack: UndoRedoEntry[];
+  /** Redo stack */
+  redoStack: UndoRedoEntry[];
+  /** Current position in history */
+  currentIndex: number;
+}

package/src/views.ts

@@ -104,6 +104,16 @@ export interface DetailViewSection {
    * Section visibility condition
    */
   visible?: boolean | string;
+  /**
+   * Show border around section
+   * @default true
+   */
+  showBorder?: boolean;
+  /**
+   * Header background color (Tailwind class)
+   * @example 'muted', 'primary/10'
+   */
+  headerColor?: string;
 }
 
 /**
@@ -228,6 +238,13 @@ export interface DetailViewSchema extends BaseSchema {
    * Custom footer content
    */
   footer?: SchemaNode;
+  /**
+   * Navigation handler for SPA-aware routing.
+   * Called instead of window.location.href for back/edit navigation.
+   * @param url - The URL to navigate to
+   * @param options - Navigation options (replace, newTab, etc.)
+   */
+  onNavigate?: (url: string, options?: { replace?: boolean; newTab?: boolean }) => void;
   /**
    * Related records section
    */

package/src/widget.ts

@@ -0,0 +1,197 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/types - Widget Manifest & Registry Types
+ *
+ * Defines the WidgetManifest interface for runtime widget registration,
+ * plugin auto-discovery from server metadata, and custom widget registry
+ * for user-defined components.
+ *
+ * @module widget
+ * @packageDocumentation
+ */
+
+/**
+ * Widget manifest describing a runtime-loadable widget.
+ *
+ * A manifest provides all metadata needed to discover, load, and render
+ * a widget without requiring an upfront import of its code.
+ *
+ * @example
+ * ```ts
+ * const manifest: WidgetManifest = {
+ *   name: 'custom-chart',
+ *   version: '1.0.0',
+ *   type: 'chart',
+ *   label: 'Custom Chart Widget',
+ *   description: 'A custom chart powered by D3.',
+ *   category: 'data-visualization',
+ *   icon: 'BarChart',
+ *   source: { type: 'module', url: '/widgets/custom-chart.js' },
+ * };
+ * ```
+ */
+export interface WidgetManifest {
+  /** Unique widget identifier (e.g., 'custom-chart', 'org.acme.table') */
+  name: string;
+
+  /** Semver version string */
+  version: string;
+
+  /** Component type key used for schema rendering (e.g., 'chart', 'grid') */
+  type: string;
+
+  /** Human-readable label for the widget */
+  label: string;
+
+  /** Short description of the widget */
+  description?: string;
+
+  /** Category for grouping in the designer palette */
+  category?: string;
+
+  /** Icon name (Lucide icon name) or SVG string */
+  icon?: string;
+
+  /** Thumbnail image URL for the designer palette */
+  thumbnail?: string;
+
+  /** Widget loading source configuration */
+  source: WidgetSource;
+
+  /** Required peer dependencies (e.g., { 'react': '^18.0.0' }) */
+  peerDependencies?: Record<string, string>;
+
+  /** Dependencies on other widgets by name */
+  dependencies?: string[];
+
+  /** Default props to apply when the widget is first dropped in the designer */
+  defaultProps?: Record<string, unknown>;
+
+  /** Input schema for the widget's configurable properties */
+  inputs?: WidgetInput[];
+
+  /** Whether the widget can contain child components */
+  isContainer?: boolean;
+
+  /** Widget capabilities */
+  capabilities?: WidgetCapabilities;
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Describes how to load the widget's code at runtime.
+ */
+export type WidgetSource =
+  | WidgetSourceModule
+  | WidgetSourceInline
+  | WidgetSourceRegistry;
+
+/**
+ * Load from an ES module URL.
+ *
+ * ⚠️ SECURITY WARNING: Only use URLs from trusted sources.
+ * Never pass user-supplied URLs directly. URLs should be validated
+ * and controlled by your application. This feature uses dynamic imports
+ * which bypass static analysis and may be restricted by Content Security Policy.
+ */
+export interface WidgetSourceModule {
+  type: 'module';
+  /**
+   * URL to the ES module (e.g., '/widgets/chart.js' or 'https://cdn.example.com/widget.mjs')
+   * Must be from a trusted source - never user input.
+   */
+  url: string;
+  /** Named export to use (default: 'default') */
+  exportName?: string;
+}
+
+/** The component is provided inline (already loaded) */
+export interface WidgetSourceInline {
+  type: 'inline';
+  /** The React component (already resolved) */
+  component: unknown;
+}
+
+/** The component is registered in the global component registry */
+export interface WidgetSourceRegistry {
+  type: 'registry';
+  /** The component type key in the registry */
+  registryKey: string;
+}
+
+/**
+ * Configurable input for a widget.
+ */
+export interface WidgetInput {
+  /** Input field name (maps to prop name) */
+  name: string;
+  /** Input field type */
+  type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
+  /** Human-readable label */
+  label?: string;
+  /** Default value */
+  defaultValue?: unknown;
+  /** Whether this input is required */
+  required?: boolean;
+  /** Enum options (for type: 'enum') */
+  options?: string[] | Array<{ label: string; value: unknown }>;
+  /** Help text */
+  description?: string;
+  /** Whether this is an advanced setting (hidden by default) */
+  advanced?: boolean;
+}
+
+/**
+ * Widget capabilities flag set.
+ */
+export interface WidgetCapabilities {
+  /** Widget supports data binding via dataSource */
+  dataBinding?: boolean;
+  /** Widget supports real-time updates */
+  realTime?: boolean;
+  /** Widget supports export (PDF, CSV, etc.) */
+  export?: boolean;
+  /** Widget supports responsive sizing */
+  responsive?: boolean;
+  /** Widget supports theming */
+  themeable?: boolean;
+  /** Widget supports drag and drop */
+  draggable?: boolean;
+  /** Widget supports resize */
+  resizable?: boolean;
+}
+
+/**
+ * Resolved widget: a manifest with its loaded component.
+ */
+export interface ResolvedWidget {
+  /** The original manifest */
+  manifest: WidgetManifest;
+  /** The loaded React component */
+  component: unknown;
+  /** Timestamp when the widget was loaded */
+  loadedAt: number;
+}
+
+/**
+ * Widget registry event types.
+ */
+export type WidgetRegistryEvent =
+  | { type: 'widget:registered'; widget: WidgetManifest }
+  | { type: 'widget:unregistered'; name: string }
+  | { type: 'widget:loaded'; widget: ResolvedWidget }
+  | { type: 'widget:error'; name: string; error: Error };
+
+/**
+ * Widget registry event listener.
+ */
+export type WidgetRegistryListener = (event: WidgetRegistryEvent) => void;