@object-ui/react 0.5.0 → 3.0.0

package/dist/context/NotificationContext.js

@@ -0,0 +1,130 @@
+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 - Notification Context
+ *
+ * Provides a spec-driven notification system to the component tree.
+ * Implements NotificationSchema, NotificationConfigSchema, and
+ * NotificationActionSchema from @objectstack/spec v2.0.7.
+ */
+import { createContext, useCallback, useContext, useMemo, useState } from 'react';
+let notificationCounter = 0;
+const NotificationCtx = createContext(null);
+/**
+ * NotificationProvider — Provides a spec-driven notification system.
+ *
+ * @example
+ * ```tsx
+ * <NotificationProvider
+ *   config={{ position: 'top-right', defaultDuration: 5000, maxVisible: 5 }}
+ *   onToast={(n) => toast[n.severity](n.title, { description: n.message })}
+ * >
+ *   <App />
+ * </NotificationProvider>
+ * ```
+ */
+export const NotificationProvider = ({ children, config: userConfig = {}, onToast, }) => {
+    const config = useMemo(() => ({
+        position: 'top-right',
+        defaultDuration: 5000,
+        maxVisible: 5,
+        stacking: true,
+        ...userConfig,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(userConfig)]);
+    const [notifications, setNotifications] = useState([]);
+    const notify = useCallback((input) => {
+        const id = `notification-${++notificationCounter}`;
+        const notification = {
+            ...input,
+            id,
+            createdAt: new Date(),
+            read: false,
+        };
+        setNotifications((prev) => [notification, ...prev]);
+        // Delegate to external toast handler if provided
+        if (onToast) {
+            onToast(notification);
+        }
+        // Auto-dismiss non-persistent notifications
+        const duration = input.duration ?? config.defaultDuration ?? 5000;
+        if (duration > 0) {
+            setTimeout(() => {
+                setNotifications((prev) => prev.filter((n) => n.id !== id));
+            }, duration);
+        }
+        return id;
+    }, [config.defaultDuration, onToast]);
+    const info = useCallback((title, message) => notify({ title, message, severity: 'info' }), [notify]);
+    const success = useCallback((title, message) => notify({ title, message, severity: 'success' }), [notify]);
+    const warning = useCallback((title, message) => notify({ title, message, severity: 'warning' }), [notify]);
+    const error = useCallback((title, message) => notify({ title, message, severity: 'error' }), [notify]);
+    const markAsRead = useCallback((id) => {
+        setNotifications((prev) => prev.map((n) => (n.id === id ? { ...n, read: true } : n)));
+    }, []);
+    const markAllAsRead = useCallback(() => {
+        setNotifications((prev) => prev.map((n) => ({ ...n, read: true })));
+    }, []);
+    const dismiss = useCallback((id) => {
+        setNotifications((prev) => prev.filter((n) => n.id !== id));
+    }, []);
+    const clearAll = useCallback(() => {
+        setNotifications([]);
+    }, []);
+    const unreadCount = useMemo(() => notifications.filter((n) => !n.read).length, [notifications]);
+    const value = useMemo(() => ({
+        notifications,
+        unreadCount,
+        notify,
+        info,
+        success,
+        warning,
+        error,
+        markAsRead,
+        markAllAsRead,
+        dismiss,
+        clearAll,
+        config,
+    }), [
+        notifications,
+        unreadCount,
+        notify,
+        info,
+        success,
+        warning,
+        error,
+        markAsRead,
+        markAllAsRead,
+        dismiss,
+        clearAll,
+        config,
+    ]);
+    return (_jsx(NotificationCtx.Provider, { value: value, children: children }));
+};
+NotificationProvider.displayName = 'NotificationProvider';
+/**
+ * Hook to consume the NotificationProvider context.
+ *
+ * @throws Error if used outside a NotificationProvider
+ */
+export function useNotifications() {
+    const ctx = useContext(NotificationCtx);
+    if (!ctx) {
+        throw new Error('useNotifications must be used within a <NotificationProvider>. ' +
+            'Wrap your app with <NotificationProvider> to use the notification system.');
+    }
+    return ctx;
+}
+/**
+ * Hook to check if a NotificationProvider is available.
+ */
+export function useHasNotificationProvider() {
+    return useContext(NotificationCtx) !== 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,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './SchemaRendererContext';
+export * from './ActionContext';
+export * from './ThemeContext';
+export * from './NotificationContext';
+export * from './DndContext';

package/dist/context/index.js

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

package/dist/hooks/index.d.ts

@@ -7,3 +7,25 @@
  */
 export * from './useExpression';
 export * from './useActionRunner';
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';
+export * from './useFocusTrap';
+export * from './useFocusManagement';
+export * from './useKeyboardShortcuts';
+export * from './useCrudShortcuts';
+export * from './useReducedMotion';
+export * from './useAnimation';
+export * from './useColumnSummary';
+export * from './useDensityMode';
+export * from './useViewSharing';
+export * from './useClientNotifications';
+export * from './useOffline';
+export * from './usePerformance';
+export * from './usePerformanceBudget';
+export * from './usePageTransition';
+export * from './useViewTransition';
+export * from './useETagCache';
+export * from './useSchemaPersistence';

package/dist/hooks/index.js

@@ -7,3 +7,25 @@
  */
 export * from './useExpression';
 export * from './useActionRunner';
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';
+export * from './useFocusTrap';
+export * from './useFocusManagement';
+export * from './useKeyboardShortcuts';
+export * from './useCrudShortcuts';
+export * from './useReducedMotion';
+export * from './useAnimation';
+export * from './useColumnSummary';
+export * from './useDensityMode';
+export * from './useViewSharing';
+export * from './useClientNotifications';
+export * from './useOffline';
+export * from './usePerformance';
+export * from './usePerformanceBudget';
+export * from './usePageTransition';
+export * from './useViewTransition';
+export * from './useETagCache';
+export * from './useSchemaPersistence';

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/useAnimation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+/** Animation trigger type */
+export type AnimationTriggerType = 'enter' | 'exit' | 'hover' | 'focus' | 'click';
+/** Easing presets aligned with EasingFunctionSchema */
+export type EasingPreset = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring';
+/** Transition preset aligned with TransitionPresetSchema */
+export type TransitionPresetType = 'fade' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'scale' | 'scale-fade' | 'none';
+export interface AnimationConfig {
+    /** The animation/transition preset */
+    preset?: TransitionPresetType;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Delay in milliseconds */
+    delay?: number;
+    /** Easing function */
+    easing?: EasingPreset;
+    /** Whether animation is enabled */
+    enabled?: boolean;
+}
+/** Resolved CSS classes and styles for animation */
+export interface AnimationResult {
+    /** Tailwind CSS classes for the animation */
+    className: string;
+    /** Inline style for custom durations/delays (only when needed) */
+    style: React.CSSProperties;
+}
+/**
+ * Hook for applying spec-driven animations to components.
+ * Implements ComponentAnimationSchema and TransitionPresetSchema
+ * from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * function Card() {
+ *   const animation = useAnimation({ preset: 'fade', duration: 200, easing: 'ease-out' });
+ *   return <div className={animation.className} style={animation.style}>...</div>;
+ * }
+ * ```
+ */
+export declare function useAnimation(config?: AnimationConfig): AnimationResult;