@object-ui/types 0.3.0 → 0.5.0

package/src/theme.ts

@@ -0,0 +1,351 @@
+/**
+ * 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 for dynamic theme switching and customization.
+ */
+
+import type { BaseSchema } from './base';
+
+/**
+ * Color Palette Definition
+ */
+export interface ColorPalette {
+  /**
+   * Primary brand color
+   */
+  primary?: string;
+
+  /**
+   * Secondary color
+   */
+  secondary?: string;
+
+  /**
+   * Accent color
+   */
+  accent?: string;
+
+  /**
+   * Background color
+   */
+  background?: string;
+
+  /**
+   * Foreground/text color
+   */
+  foreground?: string;
+
+  /**
+   * Muted color (for less prominent elements)
+   */
+  muted?: string;
+
+  /**
+   * Muted foreground color
+   */
+  mutedForeground?: string;
+
+  /**
+   * Border color
+   */
+  border?: string;
+
+  /**
+   * Input border color
+   */
+  input?: string;
+
+  /**
+   * Ring/focus color
+   */
+  ring?: string;
+
+  /**
+   * Success color
+   */
+  success?: string;
+
+  /**
+   * Warning color
+   */
+  warning?: string;
+
+  /**
+   * Error/destructive color
+   */
+  destructive?: string;
+
+  /**
+   * Info color
+   */
+  info?: string;
+
+  /**
+   * Card background color
+   */
+  card?: string;
+
+  /**
+   * Card foreground color
+   */
+  cardForeground?: string;
+
+  /**
+   * Popover background color
+   */
+  popover?: string;
+
+  /**
+   * Popover foreground color
+   */
+  popoverForeground?: string;
+}
+
+/**
+ * Typography Configuration
+ */
+export interface Typography {
+  /**
+   * Font family for sans-serif text
+   */
+  fontSans?: string[];
+
+  /**
+   * Font family for serif text
+   */
+  fontSerif?: string[];
+
+  /**
+   * Font family for monospace text
+   */
+  fontMono?: string[];
+
+  /**
+   * Base font size (in rem)
+   */
+  fontSize?: number;
+
+  /**
+   * Line height
+   */
+  lineHeight?: number;
+
+  /**
+   * Font weight for headings
+   */
+  headingWeight?: number;
+
+  /**
+   * Font weight for body text
+   */
+  bodyWeight?: number;
+}
+
+/**
+ * Spacing Scale Configuration
+ */
+export interface SpacingScale {
+  /**
+   * Base spacing unit (in rem)
+   */
+  base?: number;
+
+  /**
+   * Custom spacing values
+   */
+  scale?: Record<string, string>;
+}
+
+/**
+ * Border Radius Configuration
+ */
+export interface BorderRadius {
+  /**
+   * Small radius
+   */
+  sm?: string;
+
+  /**
+   * Default radius
+   */
+  default?: string;
+
+  /**
+   * Medium radius
+   */
+  md?: string;
+
+  /**
+   * Large radius
+   */
+  lg?: string;
+
+  /**
+   * Extra large radius
+   */
+  xl?: string;
+}
+
+/**
+ * Theme Mode
+ */
+export type ThemeMode = 'light' | 'dark' | 'system';
+
+/**
+ * Complete Theme Definition
+ */
+export interface ThemeDefinition {
+  /**
+   * Theme name/identifier
+   */
+  name: string;
+
+  /**
+   * Theme display label
+   */
+  label?: string;
+
+  /**
+   * Light mode color palette
+   */
+  light?: ColorPalette;
+
+  /**
+   * Dark mode color palette
+   */
+  dark?: ColorPalette;
+
+  /**
+   * Typography configuration
+   */
+  typography?: Typography;
+
+  /**
+   * Spacing scale configuration
+   */
+  spacing?: SpacingScale;
+
+  /**
+   * Border radius configuration
+   */
+  radius?: BorderRadius;
+
+  /**
+   * Custom CSS variables
+   */
+  cssVariables?: Record<string, string>;
+
+  /**
+   * Tailwind configuration overrides
+   */
+  tailwind?: Record<string, any>;
+}
+
+/**
+ * Theme Schema - Theme configuration and switching
+ */
+export interface ThemeSchema extends BaseSchema {
+  type: 'theme';
+
+  /**
+   * Current theme mode
+   */
+  mode?: ThemeMode;
+
+  /**
+   * Available themes
+   */
+  themes?: ThemeDefinition[];
+
+  /**
+   * Active theme name
+   */
+  activeTheme?: string;
+
+  /**
+   * Allow user theme switching
+   */
+  allowSwitching?: boolean;
+
+  /**
+   * Persist theme preference
+   */
+  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?: ThemeDefinition;
+
+  /**
+   * Preview mode
+   */
+  mode?: ThemeMode;
+
+  /**
+   * Show color palette
+   */
+  showColors?: boolean;
+
+  /**
+   * Show typography samples
+   */
+  showTypography?: boolean;
+
+  /**
+   * Show component samples
+   */
+  showComponents?: boolean;
+}

package/src/ui-action.ts

@@ -0,0 +1,276 @@
+/**
+ * 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 v0.7.1 compliant action schema with enhanced capabilities:
+ * - Location-based action placement
+ * - Parameter collection
+ * - Conditional visibility and enablement
+ * - Rich feedback mechanisms
+ * 
+ * @module ui-action
+ * @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';
+
+/**
+ * Action placement locations (ObjectStack Spec v0.7.1)
+ */
+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 (ObjectStack Spec v0.7.1)
+ */
+export type ActionComponent = 
+  | 'action:button'      // Standard button
+  | 'action:icon'        // Icon-only button
+  | 'action:menu'        // Menu item
+  | 'action:group';      // Action group/dropdown
+
+/**
+ * Action execution type (ObjectStack Spec v0.7.1)
+ */
+export type ActionType = 
+  | 'script'             // Execute JavaScript/expression
+  | 'url'                // Navigate to URL
+  | 'modal'              // Open modal dialog
+  | 'flow'               // Start workflow/automation
+  | 'api';               // Call API endpoint
+
+/**
+ * Action parameter definition (ObjectStack Spec v0.7.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 v0.7.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>;