@object-ui/types 0.3.1 → 2.0.0

package/src/theme.ts

@@ -0,0 +1,238 @@
+/**
+ * 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 - Theme Schema
+ *
+ * Defines theme configuration aligned with @objectstack/spec.
+ * Provides the complete design token system: colors, typography,
+ * spacing, borders, shadows, breakpoints, animation, z-index.
+ *
+ * @module theme
+ * @packageDocumentation
+ */
+
+import type { BaseSchema } from './base';
+
+// ============================================================================
+// Spec-Canonical Theme Sub-types — imported from @objectstack/spec/ui
+// Rule: "Never Redefine Types. ALWAYS import them."
+// ============================================================================
+
+/**
+ * Color Palette Definition
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { ColorPalette } from '@objectstack/spec/ui';
+
+/**
+ * Typography Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Typography } from '@objectstack/spec/ui';
+
+/**
+ * Spacing Scale Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Spacing } from '@objectstack/spec/ui';
+
+/**
+ * Border Radius Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { BorderRadius } from '@objectstack/spec/ui';
+
+/**
+ * Shadow Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Shadow } from '@objectstack/spec/ui';
+
+/**
+ * Responsive Breakpoints Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Breakpoints } from '@objectstack/spec/ui';
+
+/**
+ * Animation Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { Animation } from '@objectstack/spec/ui';
+
+/**
+ * Z-Index Layer Configuration
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { ZIndex } from '@objectstack/spec/ui';
+
+/**
+ * Theme Mode
+ * Canonical definition from @objectstack/spec/ui.
+ */
+export type { ThemeMode } from '@objectstack/spec/ui';
+
+// Import spec types for local use in interfaces below
+import type {
+  ColorPalette,
+  Typography,
+  Spacing,
+  BorderRadius,
+  Shadow,
+  Breakpoints,
+  Animation,
+  ZIndex,
+  ThemeMode,
+} from '@objectstack/spec/ui';
+
+/**
+ * Logo / Branding Assets
+ * ObjectUI-specific convenience type matching the inline logo object
+ * in @objectstack/spec ThemeSchema.
+ */
+export interface ThemeLogo {
+  /** Logo URL for light mode */
+  light?: string;
+  /** Logo URL for dark mode */
+  dark?: string;
+  /** Favicon URL */
+  favicon?: string;
+}
+
+/**
+ * Complete Theme Definition
+ * Compatible with @objectstack/spec Theme (input shape).
+ *
+ * Note: The spec's z.infer<Theme> has `mode` required (via ZodDefault).
+ * ObjectUI uses the input shape where `mode` is optional (defaults to 'auto').
+ *
+ * This is the canonical JSON shape for a theme.
+ * It can be serialized, stored, and applied at runtime via ThemeProvider.
+ */
+export interface Theme {
+  /** Theme identifier (required) */
+  name: string;
+  /** Display label (required) */
+  label: string;
+  /** Human-readable description */
+  description?: string;
+  /** Theme mode: light, dark, or auto (default: 'auto') */
+  mode?: ThemeMode;
+  /** Semantic color palette (primary is required) */
+  colors: ColorPalette;
+  /** Typography design tokens */
+  typography?: Typography;
+  /** Spacing scale */
+  spacing?: Spacing;
+  /** Border radius scale */
+  borderRadius?: BorderRadius;
+  /** Shadow scale */
+  shadows?: Shadow;
+  /** Responsive breakpoint definitions */
+  breakpoints?: Breakpoints;
+  /** Animation duration and timing */
+  animation?: Animation;
+  /** Z-index layering system */
+  zIndex?: ZIndex;
+  /** Arbitrary CSS custom properties */
+  customVars?: Record<string, string>;
+  /** Logo/branding assets */
+  logo?: ThemeLogo;
+  /** Extend another theme by name */
+  extends?: string;
+}
+
+// ============================================================================
+// ObjectUI Component Schemas (UI rendering)
+// ============================================================================
+
+/**
+ * Theme Component Schema
+ *
+ * Used by SchemaRenderer to render a theme manager component.
+ */
+export interface ThemeSchema extends BaseSchema {
+  type: 'theme';
+
+  /** Current theme mode */
+  mode?: ThemeMode;
+
+  /** Available themes */
+  themes?: Theme[];
+
+  /** Active theme name */
+  activeTheme?: string;
+
+  /** Allow user theme switching */
+  allowSwitching?: boolean;
+
+  /** Persist theme preference to storage */
+  persistPreference?: boolean;
+
+  /** Storage key for persisting theme */
+  storageKey?: string;
+}
+
+/**
+ * Theme Switcher Component Schema
+ */
+export interface ThemeSwitcherSchema extends BaseSchema {
+  type: 'theme-switcher';
+
+  /** Switcher variant */
+  variant?: 'dropdown' | 'toggle' | 'buttons';
+
+  /** Show mode selector (light/dark) */
+  showMode?: boolean;
+
+  /** Show theme selector */
+  showThemes?: boolean;
+
+  /** Icon for light mode */
+  lightIcon?: string;
+
+  /** Icon for dark mode */
+  darkIcon?: string;
+}
+
+/**
+ * Theme Preview Component Schema
+ */
+export interface ThemePreviewSchema extends BaseSchema {
+  type: 'theme-preview';
+
+  /** Theme to preview */
+  theme?: Theme;
+
+  /** Preview mode */
+  mode?: ThemeMode;
+
+  /** Show color palette */
+  showColors?: boolean;
+
+  /** Show typography samples */
+  showTypography?: boolean;
+
+  /** Show component samples */
+  showComponents?: boolean;
+}
+
+// ============================================================================
+// Legacy Aliases (Backward Compatibility)
+// ============================================================================
+
+/**
+ * @deprecated Use `Theme` instead. Kept for backward compatibility.
+ */
+export type ThemeDefinition = Theme;
+
+/**
+ * @deprecated Use `Spacing` instead. Kept for backward compatibility.
+ */
+export type SpacingScale = Spacing;

package/src/ui-action.ts

@@ -0,0 +1,415 @@
+/**
+ * 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 - UI Action Schema
+ * 
+ * ObjectStack Spec v2.0.1 compliant action schema with enhanced capabilities:
+ * - Location-based action placement
+ * - Parameter collection
+ * - Conditional visibility and enablement
+ * - Rich feedback mechanisms
+ * 
+ * @module ui-action
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Spec-Canonical Action Sub-types — imported from @objectstack/spec/ui
+// ============================================================================
+
+/**
+ * Action placement locations
+ * Canonical definition from @objectstack/spec/ui ActionSchema.locations.
+ */
+export type ActionLocation = 
+  | 'list_toolbar'       // Top toolbar in list views
+  | 'list_item'          // Per-item actions in list
+  | 'record_header'      // Header area of record detail
+  | 'record_more'        // More menu in record detail
+  | 'record_related'     // Related lists section
+  | 'global_nav';        // Global navigation bar
+
+/**
+ * Visual component type for actions
+ * Canonical definition from @objectstack/spec/ui ActionSchema.component.
+ */
+export type ActionComponent = 
+  | 'action:button'      // Standard button
+  | 'action:icon'        // Icon-only button
+  | 'action:menu'        // Menu item
+  | 'action:group';      // Action group/dropdown
+
+/**
+ * Action execution type
+ * Canonical definition from @objectstack/spec/ui ActionSchema.type.
+ */
+export type ActionType = 
+  | 'script'             // Execute JavaScript/expression
+  | 'url'                // Navigate to URL
+  | 'modal'              // Open modal dialog
+  | 'flow'               // Start workflow/automation
+  | 'api';               // Call API endpoint
+
+/**
+ * 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) */
+  name: string;
+  
+  /** Display label */
+  label: string;
+  
+  /** Field type for input */
+  type: ActionParamFieldType;
+  
+  /** Whether parameter is required */
+  required?: boolean;
+  
+  /** Options for select/picklist types */
+  options?: Array<{ label: string; value: string }>;
+  
+  /** Default value */
+  defaultValue?: unknown;
+  
+  /** Help text */
+  helpText?: string;
+  
+  /** Placeholder text */
+  placeholder?: string;
+  
+  /** Validation expression */
+  validation?: string;
+}
+
+/**
+ * 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.
+ */
+export interface ActionSchema {
+  /** Unique action identifier (snake_case) */
+  name: string;
+  
+  /** Display label */
+  label: string;
+  
+  /** Optional icon (Lucide icon name) */
+  icon?: string;
+  
+  // === Placement ===
+  
+  /** Where to show this action (defaults to ['record_header']) */
+  locations?: ActionLocation[];
+  
+  /** Visual component type (defaults to 'action:button') */
+  component?: ActionComponent;
+  
+  // === Behavior ===
+  
+  /** Action execution type */
+  type: ActionType;
+  
+  /** Target for the action (URL, script name, etc.) */
+  target?: string;
+  
+  /** Script to execute (for type: 'script') */
+  execute?: string;
+  
+  /** API endpoint (for type: 'api') */
+  endpoint?: string;
+  
+  /** HTTP method (for type: 'api') */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  
+  // === Parameters ===
+  
+  /** Input parameters to collect before execution */
+  params?: ActionParam[];
+  
+  // === Feedback ===
+  
+  /** Confirmation text to show before execution */
+  confirmText?: string;
+  
+  /** Success message to show after execution */
+  successMessage?: string;
+  
+  /** Error message to show on failure */
+  errorMessage?: string;
+  
+  /** Whether to refresh data after execution */
+  refreshAfter?: boolean;
+  
+  /** Toast notification configuration */
+  toast?: {
+    /** Show toast on success */
+    showOnSuccess?: boolean;
+    
+    /** Show toast on error */
+    showOnError?: boolean;
+    
+    /** Toast duration in milliseconds */
+    duration?: number;
+  };
+  
+  // === Conditional ===
+  
+  /** Expression controlling visibility (e.g., "status === 'draft'") */
+  visible?: string;
+  
+  /** Expression controlling enabled state (e.g., "hasPermission('edit')") */
+  enabled?: string;
+  
+  // === Styling ===
+  
+  /** Button variant */
+  variant?: 'default' | 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost';
+  
+  /** Button size */
+  size?: 'sm' | 'md' | 'lg';
+  
+  /** Custom CSS class */
+  className?: string;
+  
+  // === Metadata ===
+  
+  /** Action description */
+  description?: string;
+  
+  /** Permission required to execute */
+  permission?: string;
+  
+  /** Tags for categorization */
+  tags?: string[];
+}
+
+/**
+ * Action group for organizing related actions
+ */
+export interface ActionGroup {
+  /** Group name */
+  name: string;
+  
+  /** Display label */
+  label: string;
+  
+  /** Optional icon */
+  icon?: string;
+  
+  /** Actions in this group */
+  actions: ActionSchema[];
+  
+  /** Group visibility condition */
+  visible?: string;
+  
+  /** Display as dropdown or inline */
+  display?: 'dropdown' | 'inline';
+}
+
+/**
+ * Action execution context
+ */
+export interface ActionContext {
+  /** Current record data */
+  record?: Record<string, any>;
+  
+  /** Selected records (for list actions) */
+  selectedRecords?: Record<string, any>[];
+  
+  /** Current user */
+  user?: Record<string, any>;
+  
+  /** Additional context data */
+  [key: string]: any;
+}
+
+/**
+ * Action execution result
+ */
+export interface ActionResult {
+  /** Whether action succeeded */
+  success: boolean;
+  
+  /** Result data */
+  data?: any;
+  
+  /** Error message if failed */
+  error?: string;
+  
+  /** Whether to refresh data */
+  refresh?: boolean;
+  
+  /** Whether to close dialog/modal */
+  close?: boolean;
+}
+
+/**
+ * Action executor function type
+ */
+export type ActionExecutor = (
+  action: ActionSchema,
+  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;
+}