@object-ui/react 0.5.0 → 2.0.0

package/src/context/ActionContext.tsx

@@ -0,0 +1,213 @@
+/**
+ * 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/react - Action Context
+ *
+ * Provides a shared ActionRunner instance and handlers to the component tree.
+ * Components can consume actions without creating their own runner instances.
+ */
+
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import {
+  ActionRunner,
+  type ActionContext as ActionCtx,
+  type ActionDef,
+  type ActionResult,
+  type ConfirmationHandler,
+  type ToastHandler,
+  type ModalHandler,
+  type NavigationHandler,
+  type ParamCollectionHandler,
+} from '@object-ui/core';
+
+export interface ActionProviderProps {
+  children: React.ReactNode;
+  /** Initial action context (record, user, data, etc.) */
+  context?: ActionCtx;
+  /** Custom confirmation handler (e.g., Shadcn AlertDialog) */
+  onConfirm?: ConfirmationHandler;
+  /** Custom toast handler (e.g., Sonner) */
+  onToast?: ToastHandler;
+  /** Custom modal handler — render modals in response to modal actions */
+  onModal?: ModalHandler;
+  /** Custom navigation handler — SPA-aware routing (e.g., React Router navigate) */
+  onNavigate?: NavigationHandler;
+  /** Custom param collection handler — show dialog to collect ActionParam values */
+  onParamCollection?: ParamCollectionHandler;
+  /** Pre-registered custom action handlers */
+  handlers?: Record<string, (action: ActionDef, ctx: ActionCtx) => Promise<ActionResult>>;
+}
+
+interface ActionContextValue {
+  /** Execute an action */
+  execute: (action: ActionDef) => Promise<ActionResult>;
+  /** Execute multiple actions in chain */
+  executeChain: (actions: ActionDef[], mode?: 'sequential' | 'parallel') => Promise<ActionResult>;
+  /** Whether an action is currently being executed */
+  loading: boolean;
+  /** Last error message */
+  error: string | null;
+  /** Last action result */
+  result: ActionResult | null;
+  /** The underlying ActionRunner instance */
+  runner: ActionRunner;
+  /** Update context data */
+  updateContext: (ctx: Partial<ActionCtx>) => void;
+}
+
+const ActionCtxReact = createContext<ActionContextValue | null>(null);
+
+/**
+ * ActionProvider — Provides a shared ActionRunner to the tree.
+ *
+ * @example
+ * ```tsx
+ * <ActionProvider
+ *   context={{ record: currentRecord, user }}
+ *   onToast={(msg, opts) => toast[opts?.type ?? 'info'](msg)}
+ *   onConfirm={async (msg) => showConfirmDialog(msg)}
+ *   onNavigate={(url) => router.push(url)}
+ * >
+ *   <SchemaRenderer schema={pageSchema} />
+ * </ActionProvider>
+ * ```
+ */
+export const ActionProvider: React.FC<ActionProviderProps> = ({
+  children,
+  context = {},
+  onConfirm,
+  onToast,
+  onModal,
+  onNavigate,
+  onParamCollection,
+  handlers,
+}) => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [result, setResult] = useState<ActionResult | null>(null);
+
+  const runner = useMemo(() => {
+    const r = new ActionRunner(context);
+    if (onConfirm) r.setConfirmHandler(onConfirm);
+    if (onToast) r.setToastHandler(onToast);
+    if (onModal) r.setModalHandler(onModal);
+    if (onNavigate) r.setNavigationHandler(onNavigate);
+    if (onParamCollection) r.setParamCollectionHandler(onParamCollection);
+    if (handlers) {
+      Object.entries(handlers).forEach(([name, handler]) => {
+        r.registerHandler(name, handler);
+      });
+    }
+    return r;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(context)]);
+
+  const execute = useCallback(
+    async (action: ActionDef): Promise<ActionResult> => {
+      setLoading(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        const actionResult = await runner.execute(action);
+        setResult(actionResult);
+        if (!actionResult.success) {
+          setError(actionResult.error || 'Action failed');
+        }
+        return actionResult;
+      } catch (err) {
+        const errorMessage = (err as Error).message;
+        setError(errorMessage);
+        const failureResult: ActionResult = { success: false, error: errorMessage };
+        setResult(failureResult);
+        return failureResult;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runner],
+  );
+
+  const executeChain = useCallback(
+    async (actions: ActionDef[], mode?: 'sequential' | 'parallel'): Promise<ActionResult> => {
+      setLoading(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        const actionResult = await runner.executeChain(actions, mode);
+        setResult(actionResult);
+        if (!actionResult.success) {
+          setError(actionResult.error || 'Chain failed');
+        }
+        return actionResult;
+      } catch (err) {
+        const errorMessage = (err as Error).message;
+        setError(errorMessage);
+        const failureResult: ActionResult = { success: false, error: errorMessage };
+        setResult(failureResult);
+        return failureResult;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [runner],
+  );
+
+  const updateContext = useCallback(
+    (newContext: Partial<ActionCtx>) => {
+      runner.updateContext(newContext);
+    },
+    [runner],
+  );
+
+  const value = useMemo<ActionContextValue>(
+    () => ({ execute, executeChain, loading, error, result, runner, updateContext }),
+    [execute, executeChain, loading, error, result, runner, updateContext],
+  );
+
+  return (
+    <ActionCtxReact.Provider value={value}>{children}</ActionCtxReact.Provider>
+  );
+};
+
+ActionProvider.displayName = 'ActionProvider';
+
+/**
+ * Hook to consume the ActionProvider context.
+ * Returns the shared ActionRunner execute function, loading state, and more.
+ *
+ * Falls back to a local ActionRunner if no ActionProvider is present.
+ */
+export function useAction(): ActionContextValue {
+  const ctx = useContext(ActionCtxReact);
+  if (!ctx) {
+    // Graceful fallback: create a local runner
+    // This allows action components to work even without an ActionProvider
+    const runner = new ActionRunner();
+    return {
+      execute: (action: ActionDef) => runner.execute(action),
+      executeChain: (actions: ActionDef[], mode?: 'sequential' | 'parallel') =>
+        runner.executeChain(actions, mode),
+      loading: false,
+      error: null,
+      result: null,
+      runner,
+      updateContext: (ctx: Partial<ActionCtx>) => runner.updateContext(ctx),
+    };
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if an ActionProvider is available.
+ */
+export function useHasActionProvider(): boolean {
+  return useContext(ActionCtxReact) !== null;
+}

package/src/context/ThemeContext.tsx

@@ -0,0 +1,325 @@
+/**
+ * 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/react - ThemeContext
+ *
+ * React context + provider for the Theme System.
+ * Converts a spec-aligned Theme JSON into CSS custom properties
+ * and manages mode switching, theme registration, and persistence.
+ *
+ * @module context/ThemeContext
+ * @packageDocumentation
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useMemo,
+  useCallback,
+} from 'react';
+import type { Theme, ThemeMode } from '@object-ui/types';
+import {
+  generateThemeVars,
+  mergeThemes,
+  resolveThemeInheritance,
+  resolveMode,
+} from '@object-ui/core';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * The public API surface of the theme system, available via useTheme().
+ */
+export interface ThemeContextValue {
+  /** The fully resolved active theme (after inheritance) */
+  theme: Theme | null;
+
+  /** The effective mode: 'light' or 'dark' (resolved from 'auto') */
+  resolvedMode: 'light' | 'dark';
+
+  /** The raw mode setting (may be 'auto') */
+  mode: ThemeMode;
+
+  /** Name of the active theme */
+  activeTheme: string | null;
+
+  /** List of available themes */
+  themes: Theme[];
+
+  /** Switch to a different theme by name */
+  setTheme: (name: string) => void;
+
+  /** Switch mode (light / dark / auto) */
+  setMode: (mode: ThemeMode) => void;
+
+  /** The generated CSS custom property map */
+  cssVars: Record<string, string>;
+}
+
+/**
+ * Props for the ThemeProvider component.
+ */
+export interface ThemeProviderProps {
+  /** Available theme definitions */
+  themes?: Theme[];
+
+  /** Initial active theme name (default: first theme) */
+  defaultTheme?: string;
+
+  /** Initial mode (default: 'auto') */
+  defaultMode?: ThemeMode;
+
+  /** Persist theme/mode to localStorage */
+  persist?: boolean;
+
+  /** localStorage key prefix */
+  storageKey?: string;
+
+  /** Target element for CSS variable injection (default: document.documentElement) */
+  target?: HTMLElement | null;
+
+  /** Children */
+  children: React.ReactNode;
+}
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+/**
+ * Default storage keys
+ */
+const DEFAULT_STORAGE_KEY = 'objectui-theme';
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+/**
+ * ThemeProvider
+ *
+ * Wraps a subtree with theme context. It:
+ * 1. Maintains theme + mode state
+ * 2. Resolves theme inheritance (extends)
+ * 3. Converts the active theme → CSS custom properties
+ * 4. Injects those CSS variables into the DOM
+ * 5. Applies 'dark' / 'light' class to the target element
+ * 6. Optionally persists user preference to localStorage
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider themes={[myTheme]} defaultTheme="my-theme" defaultMode="auto">
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+  themes: themesInput = [],
+  defaultTheme,
+  defaultMode = 'auto',
+  persist = false,
+  storageKey = DEFAULT_STORAGE_KEY,
+  target,
+  children,
+}: ThemeProviderProps) {
+  // ---- Build theme registry ----
+  const registry = useMemo(() => {
+    const map = new Map<string, Theme>();
+    for (const t of themesInput) {
+      map.set(t.name, t);
+    }
+    return map;
+  }, [themesInput]);
+
+  // ---- Load persisted state ----
+  const loadPersistedTheme = useCallback((): string | undefined => {
+    if (!persist) return undefined;
+    try {
+      if (typeof window !== 'undefined') {
+        return localStorage.getItem(`${storageKey}-name`) ?? undefined;
+      }
+    } catch { /* ignore */ }
+    return undefined;
+  }, [persist, storageKey]);
+
+  const loadPersistedMode = useCallback((): ThemeMode | undefined => {
+    if (!persist) return undefined;
+    try {
+      if (typeof window !== 'undefined') {
+        const stored = localStorage.getItem(`${storageKey}-mode`);
+        if (stored === 'light' || stored === 'dark' || stored === 'auto') {
+          return stored;
+        }
+      }
+    } catch { /* ignore */ }
+    return undefined;
+  }, [persist, storageKey]);
+
+  // ---- State ----
+  const [activeThemeName, setActiveThemeName] = useState<string | null>(
+    () => loadPersistedTheme() ?? defaultTheme ?? themesInput[0]?.name ?? null,
+  );
+
+  const [mode, setModeState] = useState<ThemeMode>(
+    () => loadPersistedMode() ?? defaultMode,
+  );
+
+  // ---- Resolve theme ----
+  const resolvedTheme = useMemo(() => {
+    if (!activeThemeName) return null;
+    const base = registry.get(activeThemeName);
+    if (!base) return null;
+    return resolveThemeInheritance(base, registry);
+  }, [activeThemeName, registry]);
+
+  // ---- Resolve mode ----
+  const [systemDark, setSystemDark] = useState<boolean>(() => {
+    if (typeof window !== 'undefined' && window.matchMedia) {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches;
+    }
+    return false;
+  });
+
+  // Listen to system preference changes
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = (e: MediaQueryListEvent) => setSystemDark(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  const resolvedMode = useMemo(
+    () => resolveMode(mode, systemDark),
+    [mode, systemDark],
+  );
+
+  // ---- Generate CSS variables ----
+  const cssVars = useMemo(() => {
+    if (!resolvedTheme) return {};
+    return generateThemeVars(resolvedTheme);
+  }, [resolvedTheme]);
+
+  // ---- Inject CSS variables into the DOM ----
+  useEffect(() => {
+    const el = target ?? (typeof document !== 'undefined' ? document.documentElement : null);
+    if (!el) return;
+
+    // Apply CSS variables
+    const previousValues: Record<string, string> = {};
+    for (const [prop, value] of Object.entries(cssVars)) {
+      previousValues[prop] = el.style.getPropertyValue(prop);
+      el.style.setProperty(prop, value);
+    }
+
+    // Apply mode class
+    el.classList.remove('light', 'dark');
+    el.classList.add(resolvedMode);
+
+    // Apply logo / favicon
+    if (resolvedTheme?.logo?.favicon && typeof document !== 'undefined') {
+      const link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+        ?? document.querySelector<HTMLLinkElement>('#favicon');
+      if (link) {
+        link.href = resolvedTheme.logo.favicon;
+      }
+    }
+
+    return () => {
+      // Cleanup: remove injected vars
+      for (const prop of Object.keys(cssVars)) {
+        if (previousValues[prop]) {
+          el.style.setProperty(prop, previousValues[prop]);
+        } else {
+          el.style.removeProperty(prop);
+        }
+      }
+      el.classList.remove(resolvedMode);
+    };
+  }, [cssVars, resolvedMode, resolvedTheme, target]);
+
+  // ---- Persistence ----
+  useEffect(() => {
+    if (!persist) return;
+    try {
+      if (activeThemeName) {
+        localStorage.setItem(`${storageKey}-name`, activeThemeName);
+      }
+      localStorage.setItem(`${storageKey}-mode`, mode);
+    } catch { /* ignore */ }
+  }, [persist, storageKey, activeThemeName, mode]);
+
+  // ---- Actions ----
+  const setTheme = useCallback((name: string) => {
+    if (registry.has(name)) {
+      setActiveThemeName(name);
+    }
+  }, [registry]);
+
+  const setMode = useCallback((newMode: ThemeMode) => {
+    setModeState(newMode);
+  }, []);
+
+  // ---- Context value ----
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme: resolvedTheme,
+      resolvedMode,
+      mode,
+      activeTheme: activeThemeName,
+      themes: themesInput,
+      setTheme,
+      setMode,
+      cssVars,
+    }),
+    [resolvedTheme, resolvedMode, mode, activeThemeName, themesInput, setTheme, setMode, cssVars],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * useTheme — access the current theme context.
+ *
+ * @example
+ * ```tsx
+ * const { theme, resolvedMode, setMode, setTheme } = useTheme();
+ * ```
+ *
+ * @throws Error if used outside a ThemeProvider
+ */
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error('useTheme must be used within a <ThemeProvider>');
+  }
+  return ctx;
+}
+
+/**
+ * useOptionalTheme — like useTheme() but returns null outside a provider.
+ * Useful for components that should work with or without a theme.
+ */
+export function useOptionalTheme(): ThemeContextValue | null {
+  return useContext(ThemeContext);
+}

package/src/context/__tests__/ActionContext.test.tsx

@@ -0,0 +1,174 @@
+/**
+ * Tests for ActionContext — ActionProvider, useAction, useHasActionProvider
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, waitFor, act } from '@testing-library/react';
+import React from 'react';
+import { ActionProvider, useAction, useHasActionProvider } from '../ActionContext';
+
+describe('ActionContext', () => {
+  describe('useAction without ActionProvider', () => {
+    it('falls back to local ActionRunner with default state', () => {
+      const { result } = renderHook(() => useAction());
+
+      expect(result.current.loading).toBe(false);
+      expect(result.current.error).toBeNull();
+      expect(result.current.result).toBeNull();
+      expect(typeof result.current.execute).toBe('function');
+      expect(typeof result.current.executeChain).toBe('function');
+      expect(typeof result.current.updateContext).toBe('function');
+      expect(result.current.runner).toBeDefined();
+    });
+  });
+
+  describe('useHasActionProvider', () => {
+    it('returns false without provider', () => {
+      const { result } = renderHook(() => useHasActionProvider());
+
+      expect(result.current).toBe(false);
+    });
+
+    it('returns true with provider', () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useHasActionProvider(), { wrapper });
+
+      expect(result.current).toBe(true);
+    });
+  });
+
+  describe('ActionProvider basic', () => {
+    it('children can access execute function', () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      expect(typeof result.current.execute).toBe('function');
+      expect(typeof result.current.executeChain).toBe('function');
+      expect(typeof result.current.updateContext).toBe('function');
+      expect(result.current.loading).toBe(false);
+      expect(result.current.error).toBeNull();
+      expect(result.current.result).toBeNull();
+    });
+  });
+
+  describe('ActionProvider execute', () => {
+    it('executes a toast action and returns result', async () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      let actionResult: any;
+      await act(async () => {
+        actionResult = await result.current.execute({
+          type: 'script',
+          execute: 'true',
+          toast: { showOnSuccess: true },
+          successMessage: 'Done!',
+        });
+      });
+
+      expect(actionResult.success).toBe(true);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.result).toEqual(actionResult);
+      expect(result.current.error).toBeNull();
+    });
+  });
+
+  describe('ActionProvider execute error', () => {
+    it('executes an action that fails and sets error state', async () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      let actionResult: any;
+      await act(async () => {
+        actionResult = await result.current.execute({
+          onClick: vi.fn().mockRejectedValue(new Error('boom')),
+        });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(actionResult.success).toBe(false);
+      expect(result.current.error).toBeTruthy();
+      expect(result.current.result?.success).toBe(false);
+    });
+  });
+
+  describe('ActionProvider executeChain', () => {
+    it('executes a chain of actions', async () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      let chainResult: any;
+      await act(async () => {
+        chainResult = await result.current.executeChain([
+          { type: 'script', execute: 'true' },
+          { type: 'script', execute: 'true' },
+        ]);
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(chainResult.success).toBe(true);
+      expect(result.current.result).toEqual(chainResult);
+      expect(result.current.error).toBeNull();
+    });
+  });
+
+  describe('ActionProvider updateContext', () => {
+    it('updateContext is callable', () => {
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(ActionProvider, { context: {} }, children);
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      expect(() => {
+        result.current.updateContext({ record: { id: 1 } });
+      }).not.toThrow();
+    });
+  });
+
+  describe('ActionProvider with handlers', () => {
+    it('invokes onToast handler when a toast action is executed', async () => {
+      const onToast = vi.fn();
+      const onNavigate = vi.fn();
+
+      const wrapper = ({ children }: { children: React.ReactNode }) =>
+        React.createElement(
+          ActionProvider,
+          { context: {}, onToast, onNavigate },
+          children,
+        );
+
+      const { result } = renderHook(() => useAction(), { wrapper });
+
+      await act(async () => {
+        await result.current.execute({
+          type: 'script',
+          execute: 'true',
+          toast: { showOnSuccess: true },
+          successMessage: 'Saved!',
+        });
+      });
+
+      expect(onToast).toHaveBeenCalledWith('Saved!', expect.objectContaining({ type: 'success' }));
+    });
+  });
+});