@object-ui/react 0.5.0 → 2.0.0

package/dist/context/ActionContext.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { ActionRunner, } from '@object-ui/core';
+const ActionCtxReact = createContext(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 = ({ children, context = {}, onConfirm, onToast, onModal, onNavigate, onParamCollection, handlers, }) => {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(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) => {
+        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.message;
+            setError(errorMessage);
+            const failureResult = { success: false, error: errorMessage };
+            setResult(failureResult);
+            return failureResult;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [runner]);
+    const executeChain = useCallback(async (actions, mode) => {
+        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.message;
+            setError(errorMessage);
+            const failureResult = { success: false, error: errorMessage };
+            setResult(failureResult);
+            return failureResult;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [runner]);
+    const updateContext = useCallback((newContext) => {
+        runner.updateContext(newContext);
+    }, [runner]);
+    const value = useMemo(() => ({ execute, executeChain, loading, error, result, runner, updateContext }), [execute, executeChain, loading, error, result, runner, updateContext]);
+    return (_jsx(ActionCtxReact.Provider, { value: value, children: children }));
+};
+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() {
+    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) => runner.execute(action),
+            executeChain: (actions, mode) => runner.executeChain(actions, mode),
+            loading: false,
+            error: null,
+            result: null,
+            runner,
+            updateContext: (ctx) => runner.updateContext(ctx),
+        };
+    }
+    return ctx;
+}
+/**
+ * Hook to check if an ActionProvider is available.
+ */
+export function useHasActionProvider() {
+    return useContext(ActionCtxReact) !== null;
+}

package/dist/context/ThemeContext.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 from 'react';
+import type { Theme, ThemeMode } from '@object-ui/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;
+}
+/**
+ * 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 declare function ThemeProvider({ themes: themesInput, defaultTheme, defaultMode, persist, storageKey, target, children, }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * useTheme — access the current theme context.
+ *
+ * @example
+ * ```tsx
+ * const { theme, resolvedMode, setMode, setTheme } = useTheme();
+ * ```
+ *
+ * @throws Error if used outside a ThemeProvider
+ */
+export declare function useTheme(): ThemeContextValue;
+/**
+ * useOptionalTheme — like useTheme() but returns null outside a provider.
+ * Useful for components that should work with or without a theme.
+ */
+export declare function useOptionalTheme(): ThemeContextValue | null;

package/dist/context/ThemeContext.js

@@ -0,0 +1,215 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 { createContext, useContext, useState, useEffect, useMemo, useCallback, } from 'react';
+import { generateThemeVars, resolveThemeInheritance, resolveMode, } from '@object-ui/core';
+// ============================================================================
+// Context
+// ============================================================================
+const ThemeContext = createContext(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, }) {
+    // ---- Build theme registry ----
+    const registry = useMemo(() => {
+        const map = new Map();
+        for (const t of themesInput) {
+            map.set(t.name, t);
+        }
+        return map;
+    }, [themesInput]);
+    // ---- Load persisted state ----
+    const loadPersistedTheme = useCallback(() => {
+        if (!persist)
+            return undefined;
+        try {
+            if (typeof window !== 'undefined') {
+                return localStorage.getItem(`${storageKey}-name`) ?? undefined;
+            }
+        }
+        catch { /* ignore */ }
+        return undefined;
+    }, [persist, storageKey]);
+    const loadPersistedMode = useCallback(() => {
+        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(() => loadPersistedTheme() ?? defaultTheme ?? themesInput[0]?.name ?? null);
+    const [mode, setModeState] = useState(() => 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(() => {
+        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) => 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 = {};
+        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('link[rel="icon"]')
+                ?? document.querySelector('#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) => {
+        if (registry.has(name)) {
+            setActiveThemeName(name);
+        }
+    }, [registry]);
+    const setMode = useCallback((newMode) => {
+        setModeState(newMode);
+    }, []);
+    // ---- Context value ----
+    const value = useMemo(() => ({
+        theme: resolvedTheme,
+        resolvedMode,
+        mode,
+        activeTheme: activeThemeName,
+        themes: themesInput,
+        setTheme,
+        setMode,
+        cssVars,
+    }), [resolvedTheme, resolvedMode, mode, activeThemeName, themesInput, setTheme, setMode, cssVars]);
+    return (_jsx(ThemeContext.Provider, { value: value, children: children }));
+}
+// ============================================================================
+// 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() {
+    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() {
+    return useContext(ThemeContext);
+}

package/dist/context/index.d.ts

@@ -6,3 +6,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './SchemaRendererContext';
+export * from './ActionContext';
+export * from './ThemeContext';

package/dist/context/index.js

@@ -6,3 +6,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './SchemaRendererContext';
+export * from './ActionContext';
+export * from './ThemeContext';

package/dist/hooks/index.d.ts

@@ -7,3 +7,8 @@
  */
 export * from './useExpression';
 export * from './useActionRunner';
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';

package/dist/hooks/index.js

@@ -7,3 +7,8 @@
  */
 export * from './useExpression';
 export * from './useActionRunner';
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';

package/dist/hooks/useActionRunner.d.ts

@@ -5,25 +5,39 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { ActionRunner, type ActionContext, type ActionResult } from '@object-ui/core';
+import { ActionRunner, type ActionContext, type ActionDef, type ActionResult, type ConfirmationHandler, type ToastHandler, type ModalHandler, type NavigationHandler } from '@object-ui/core';
+export interface UseActionRunnerOptions {
+    context?: ActionContext;
+    /** Custom confirmation handler — wire to Shadcn AlertDialog or similar */
+    onConfirm?: ConfirmationHandler;
+    /** Custom toast handler — wire to Sonner or similar */
+    onToast?: ToastHandler;
+    /** Custom modal handler — render modals in response to modal actions */
+    onModal?: ModalHandler;
+    /** Custom navigation handler — SPA-aware routing */
+    onNavigate?: NavigationHandler;
+}
 /**
- * Hook for executing actions with loading state
+ * Hook for executing actions with loading state, typed with ActionDef.
  *
  * @example
  * ```tsx
- * const { execute, loading, error, result } = useActionRunner({ data: formData });
+ * const { execute, loading, error, result } = useActionRunner({
+ *   context: { data: formData },
+ *   onToast: (msg, opts) => toast[opts?.type || 'info'](msg),
+ * });
  *
  * const handleClick = () => {
  *   execute({
- *     type: 'action',
+ *     type: 'api',
  *     api: '/api/save',
- *     successMessage: 'Saved successfully!'
+ *     successMessage: 'Saved successfully!',
  *   });
  * };
  * ```
  */
-export declare function useActionRunner(context?: ActionContext): {
-    execute: (action: any) => Promise<ActionResult>;
+export declare function useActionRunner(optionsOrContext?: UseActionRunnerOptions | ActionContext): {
+    execute: (action: ActionDef) => Promise<ActionResult>;
     loading: boolean;
     error: string | null;
     result: ActionResult | null;

package/dist/hooks/useActionRunner.js

@@ -6,28 +6,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useState, useCallback, useMemo } from 'react';
-import { ActionRunner } from '@object-ui/core';
+import { ActionRunner, } from '@object-ui/core';
 /**
- * Hook for executing actions with loading state
+ * Hook for executing actions with loading state, typed with ActionDef.
  *
  * @example
  * ```tsx
- * const { execute, loading, error, result } = useActionRunner({ data: formData });
+ * const { execute, loading, error, result } = useActionRunner({
+ *   context: { data: formData },
+ *   onToast: (msg, opts) => toast[opts?.type || 'info'](msg),
+ * });
  *
  * const handleClick = () => {
  *   execute({
- *     type: 'action',
+ *     type: 'api',
  *     api: '/api/save',
- *     successMessage: 'Saved successfully!'
+ *     successMessage: 'Saved successfully!',
  *   });
  * };
  * ```
  */
-export function useActionRunner(context = {}) {
+export function useActionRunner(optionsOrContext = {}) {
+    // Backwards compat: if no 'context' key, treat entire object as context
+    const options = 'context' in optionsOrContext
+        ? optionsOrContext
+        : { context: optionsOrContext };
+    const { context = {}, onConfirm, onToast, onModal, onNavigate } = options;
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [result, setResult] = useState(null);
-    const runner = useMemo(() => new ActionRunner(context), [JSON.stringify(context)]);
+    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);
+        return r;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [JSON.stringify(context)]);
     const execute = useCallback(async (action) => {
         setLoading(true);
         setError(null);

package/dist/hooks/useDiscovery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/**
+ * Discovery service information structure.
+ * Represents server capabilities and service status.
+ */
+export interface DiscoveryInfo {
+    /** Server name and version */
+    name?: string;
+    version?: string;
+    /** Service availability status */
+    services?: {
+        /** Authentication service status */
+        auth?: {
+            enabled: boolean;
+            status?: 'available' | 'unavailable';
+            message?: string;
+        };
+        /** Data access service status */
+        data?: {
+            enabled: boolean;
+            status?: 'available' | 'unavailable';
+        };
+        /** Metadata service status */
+        metadata?: {
+            enabled: boolean;
+            status?: 'available' | 'unavailable';
+        };
+        [key: string]: any;
+    };
+    /** API capabilities */
+    capabilities?: string[];
+    /** Additional discovery metadata */
+    [key: string]: any;
+}
+/**
+ * Hook to access discovery information from the ObjectStack server.
+ *
+ * This hook retrieves server capabilities and service status, which can be used
+ * to conditionally enable/disable features based on server configuration.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { discovery, isLoading } = useDiscovery();
+ *
+ *   if (isLoading) {
+ *     return <LoadingScreen />;
+ *   }
+ *
+ *   // Check if auth is enabled on the server
+ *   const authEnabled = discovery?.services?.auth?.enabled ?? true;
+ *
+ *   return (
+ *     <div>
+ *       {authEnabled ? <AuthProvider>...</AuthProvider> : <App />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Discovery information and loading state
+ */
+export declare function useDiscovery(): {
+    discovery: DiscoveryInfo | null;
+    isLoading: boolean;
+    error: Error | null;
+    /**
+     * Check if authentication is enabled on the server.
+     * Defaults to true if discovery data is not available.
+     */
+    isAuthEnabled: boolean;
+};