@object-ui/react 2.0.0 → 3.0.1

package/dist/context/index.d.ts

@@ -8,3 +8,5 @@
 export * from './SchemaRendererContext';
 export * from './ActionContext';
 export * from './ThemeContext';
+export * from './NotificationContext';
+export * from './DndContext';

package/dist/context/index.js

@@ -8,3 +8,5 @@
 export * from './SchemaRendererContext';
 export * from './ActionContext';
 export * from './ThemeContext';
+export * from './NotificationContext';
+export * from './DndContext';

package/dist/hooks/index.d.ts

@@ -12,3 +12,20 @@ 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

@@ -12,3 +12,20 @@ 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/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;

package/dist/hooks/useAnimation.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+import { useMemo } from 'react';
+const EASING_MAP = {
+    linear: 'linear',
+    ease: 'ease',
+    'ease-in': 'ease-in',
+    'ease-out': 'ease-out',
+    'ease-in-out': 'ease-in-out',
+    spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+};
+const PRESET_CLASSES = {
+    fade: 'animate-in fade-in',
+    'slide-up': 'animate-in slide-in-from-bottom-2',
+    'slide-down': 'animate-in slide-in-from-top-2',
+    'slide-left': 'animate-in slide-in-from-right-2',
+    'slide-right': 'animate-in slide-in-from-left-2',
+    scale: 'animate-in zoom-in-95',
+    'scale-fade': 'animate-in fade-in zoom-in-95',
+    none: '',
+};
+/**
+ * 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 function useAnimation(config = {}) {
+    const { preset = 'none', duration, delay, easing = 'ease-out', enabled = true, } = config;
+    return useMemo(() => {
+        if (!enabled || preset === 'none') {
+            return { className: '', style: {} };
+        }
+        const className = PRESET_CLASSES[preset] || '';
+        const style = {};
+        if (duration !== undefined) {
+            style.animationDuration = `${duration}ms`;
+        }
+        if (delay !== undefined) {
+            style.animationDelay = `${delay}ms`;
+        }
+        if (easing) {
+            style.animationTimingFunction = EASING_MAP[easing] || easing;
+        }
+        return { className, style };
+    }, [preset, duration, delay, easing, enabled]);
+}

package/dist/hooks/useClientNotifications.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+export interface UseClientNotificationsOptions {
+    /** ObjectStack client instance (optional, from context if available) */
+    client?: any;
+    /** Whether to auto-fetch notifications on mount */
+    autoFetch?: boolean;
+    /** Polling interval in ms (0 to disable) */
+    pollInterval?: number;
+}
+export interface UseClientNotificationsResult {
+    /** Fetch notifications from server */
+    fetchNotifications: () => Promise<void>;
+    /** Register device for push notifications */
+    registerDevice: (token: string, platform: string) => Promise<void>;
+    /** Get notification preferences */
+    getPreferences: () => Promise<any>;
+    /** Update notification preferences */
+    updatePreferences: (prefs: any) => Promise<void>;
+    /** Mark a notification as read on the server */
+    markAsRead: (id: string) => Promise<void>;
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * Bridge between the `@objectstack/client` notifications API and the
+ * local {@link NotificationContext}.
+ *
+ * The hook resolves the ObjectStack client either from the explicit
+ * `client` option or from the `SchemaRendererContext` dataSource, then
+ * delegates to `client.notifications.*` methods.  Fetched notifications
+ * are fed into the local provider via `useNotifications().notify()`.
+ *
+ * @example
+ * ```tsx
+ * function NotificationBell() {
+ *   const { fetchNotifications, loading } = useClientNotifications({
+ *     autoFetch: true,
+ *     pollInterval: 30_000,
+ *   });
+ *
+ *   return <Button onClick={fetchNotifications} disabled={loading}>🔔</Button>;
+ * }
+ * ```
+ */
+export declare function useClientNotifications(options?: UseClientNotificationsOptions): UseClientNotificationsResult;

package/dist/hooks/useClientNotifications.js

@@ -0,0 +1,190 @@
+/**
+ * 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 - useClientNotifications
+ *
+ * Bridge hook between the @objectstack/client notifications API
+ * and the local NotificationContext state. Fetches server-side
+ * notifications and surfaces them through the existing provider.
+ */
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { useNotifications } from '../context/NotificationContext';
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                           */
+/* ------------------------------------------------------------------ */
+/** Normalise severity coming from the server into a valid local level. */
+function toSeverity(value) {
+    const valid = ['info', 'success', 'warning', 'error'];
+    if (typeof value === 'string' && valid.includes(value)) {
+        return value;
+    }
+    return 'info';
+}
+/**
+ * Resolve the ObjectStack client from explicit option or SchemaRendererContext.
+ *
+ * The dataSource stored in context is typically an ObjectStackAdapter which
+ * exposes `getClient()`.  When the caller passes a client directly we use
+ * that instead.
+ */
+function useResolvedClient(explicit) {
+    const rendererCtx = useContext(SchemaRendererContext);
+    if (explicit)
+        return explicit;
+    const dataSource = rendererCtx?.dataSource;
+    if (dataSource && typeof dataSource.getClient === 'function') {
+        return dataSource.getClient();
+    }
+    return null;
+}
+/* ------------------------------------------------------------------ */
+/*  Hook                                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Bridge between the `@objectstack/client` notifications API and the
+ * local {@link NotificationContext}.
+ *
+ * The hook resolves the ObjectStack client either from the explicit
+ * `client` option or from the `SchemaRendererContext` dataSource, then
+ * delegates to `client.notifications.*` methods.  Fetched notifications
+ * are fed into the local provider via `useNotifications().notify()`.
+ *
+ * @example
+ * ```tsx
+ * function NotificationBell() {
+ *   const { fetchNotifications, loading } = useClientNotifications({
+ *     autoFetch: true,
+ *     pollInterval: 30_000,
+ *   });
+ *
+ *   return <Button onClick={fetchNotifications} disabled={loading}>🔔</Button>;
+ * }
+ * ```
+ */
+export function useClientNotifications(options = {}) {
+    const { client: explicitClient, autoFetch = false, pollInterval = 0 } = options;
+    const client = useResolvedClient(explicitClient);
+    const { notify, markAsRead: localMarkAsRead } = useNotifications();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Track IDs that have already been pushed into the local context so we
+    // don't add duplicates on subsequent fetches / polls.
+    const seenIdsRef = useRef(new Set());
+    /* ---- fetchNotifications ---- */
+    const fetchNotifications = useCallback(async () => {
+        if (!client?.notifications)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await client.notifications.list({});
+            const items = Array.isArray(result) ? result : result?.data ?? result?.items ?? [];
+            for (const item of items) {
+                const id = String(item.id ?? '');
+                if (!id || seenIdsRef.current.has(id))
+                    continue;
+                seenIdsRef.current.add(id);
+                notify({
+                    title: item.title ?? 'Notification',
+                    message: item.message ?? item.body,
+                    severity: toSeverity(item.severity ?? item.level),
+                    duration: 0, // server-driven notifications are persistent
+                });
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error('Failed to fetch notifications'));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, notify]);
+    /* ---- registerDevice ---- */
+    const registerDevice = useCallback(async (token, platform) => {
+        if (!client?.notifications)
+            return;
+        setError(null);
+        try {
+            await client.notifications.registerDevice(token, platform);
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error('Failed to register device');
+            setError(wrapped);
+            throw wrapped;
+        }
+    }, [client]);
+    /* ---- getPreferences ---- */
+    const getPreferences = useCallback(async () => {
+        if (!client?.notifications)
+            return null;
+        setError(null);
+        try {
+            return await client.notifications.getPreferences();
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error('Failed to get preferences');
+            setError(wrapped);
+            throw wrapped;
+        }
+    }, [client]);
+    /* ---- updatePreferences ---- */
+    const updatePreferences = useCallback(async (prefs) => {
+        if (!client?.notifications)
+            return;
+        setError(null);
+        try {
+            await client.notifications.updatePreferences(prefs);
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error('Failed to update preferences');
+            setError(wrapped);
+            throw wrapped;
+        }
+    }, [client]);
+    /* ---- markAsRead (server + local) ---- */
+    const markAsRead = useCallback(async (id) => {
+        // Optimistically mark locally first
+        localMarkAsRead(id);
+        if (!client?.notifications)
+            return;
+        setError(null);
+        try {
+            await client.notifications.markAsRead(id);
+        }
+        catch (err) {
+            const wrapped = err instanceof Error ? err : new Error('Failed to mark as read');
+            setError(wrapped);
+            throw wrapped;
+        }
+    }, [client, localMarkAsRead]);
+    /* ---- auto-fetch on mount ---- */
+    useEffect(() => {
+        if (autoFetch && client?.notifications) {
+            fetchNotifications();
+        }
+    }, [autoFetch, client, fetchNotifications]);
+    /* ---- polling ---- */
+    useEffect(() => {
+        if (!pollInterval || pollInterval <= 0 || !client?.notifications)
+            return;
+        const id = setInterval(() => {
+            fetchNotifications();
+        }, pollInterval);
+        return () => clearInterval(id);
+    }, [pollInterval, client, fetchNotifications]);
+    return {
+        fetchNotifications,
+        registerDevice,
+        getPreferences,
+        updatePreferences,
+        markAsRead,
+        loading,
+        error,
+    };
+}

package/dist/hooks/useColumnSummary.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** Summary function types aligned with ColumnSummarySchema */
+export type SummaryFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct';
+export interface ColumnSummaryConfig {
+    /** The field/column to aggregate */
+    field: string;
+    /** The aggregation function */
+    function: SummaryFunction;
+    /** Optional label for the summary */
+    label?: string;
+    /** Number format options */
+    format?: Intl.NumberFormatOptions;
+}
+export interface ColumnSummaryResult {
+    /** The computed value */
+    value: number;
+    /** Formatted display string */
+    formatted: string;
+    /** The label */
+    label: string;
+}
+/**
+ * Hook for computing column-level summaries (SUM, AVG, COUNT, MIN, MAX, DISTINCT).
+ * Implements ColumnSummarySchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const summary = useColumnSummary(data, { field: 'amount', function: 'sum', label: 'Total' });
+ * // summary.formatted => "$12,345.67"
+ * ```
+ */
+export declare function useColumnSummary(data: Record<string, unknown>[], config: ColumnSummaryConfig, locale?: string): ColumnSummaryResult;

package/dist/hooks/useColumnSummary.js

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+import { useMemo } from 'react';
+/**
+ * Hook for computing column-level summaries (SUM, AVG, COUNT, MIN, MAX, DISTINCT).
+ * Implements ColumnSummarySchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const summary = useColumnSummary(data, { field: 'amount', function: 'sum', label: 'Total' });
+ * // summary.formatted => "$12,345.67"
+ * ```
+ */
+export function useColumnSummary(data, config, locale) {
+    return useMemo(() => {
+        const values = data
+            .map((row) => {
+            const val = row[config.field];
+            return typeof val === 'number' ? val : Number(val);
+        })
+            .filter((v) => !isNaN(v));
+        let value;
+        switch (config.function) {
+            case 'sum':
+                value = values.reduce((acc, v) => acc + v, 0);
+                break;
+            case 'avg':
+                value = values.length > 0 ? values.reduce((acc, v) => acc + v, 0) / values.length : 0;
+                break;
+            case 'count':
+                value = data.length;
+                break;
+            case 'min':
+                value = values.length > 0 ? Math.min(...values) : 0;
+                break;
+            case 'max':
+                value = values.length > 0 ? Math.max(...values) : 0;
+                break;
+            case 'distinct':
+                value = new Set(data.map((row) => row[config.field])).size;
+                break;
+            default:
+                value = 0;
+        }
+        const formatted = new Intl.NumberFormat(locale, config.format).format(value);
+        const label = config.label ?? config.function.toUpperCase();
+        return { value, formatted, label };
+    }, [data, config.field, config.function, config.label, config.format, locale]);
+}

package/dist/hooks/useCrudShortcuts.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export interface CrudShortcutCallbacks {
+    onCreate?: () => void;
+    onEdit?: () => void;
+    onDelete?: () => void;
+    onSave?: () => void;
+    onDuplicate?: () => void;
+    onCancel?: () => void;
+    onSearch?: () => void;
+}
+/**
+ * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
+ *
+ * Shortcuts:
+ * - Ctrl/Cmd+N: Create new record
+ * - Ctrl/Cmd+E: Edit selected record
+ * - Delete / Backspace: Delete selected record(s)
+ * - Ctrl/Cmd+S: Save current record
+ * - Ctrl/Cmd+D: Duplicate selected record
+ * - Escape: Cancel/close current operation
+ * - Ctrl/Cmd+F: Focus search
+ *
+ * @example
+ * ```tsx
+ * useCrudShortcuts({
+ *   onCreate: () => openCreateDialog(),
+ *   onSave: () => saveRecord(),
+ *   onDelete: () => deleteSelected(),
+ *   onCancel: () => closeDialog(),
+ * });
+ * ```
+ */
+export declare function useCrudShortcuts(callbacks: CrudShortcutCallbacks, enabled?: boolean): void;

package/dist/hooks/useCrudShortcuts.js

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import { useMemo } from 'react';
+import { useKeyboardShortcuts, } from './useKeyboardShortcuts';
+/**
+ * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
+ *
+ * Shortcuts:
+ * - Ctrl/Cmd+N: Create new record
+ * - Ctrl/Cmd+E: Edit selected record
+ * - Delete / Backspace: Delete selected record(s)
+ * - Ctrl/Cmd+S: Save current record
+ * - Ctrl/Cmd+D: Duplicate selected record
+ * - Escape: Cancel/close current operation
+ * - Ctrl/Cmd+F: Focus search
+ *
+ * @example
+ * ```tsx
+ * useCrudShortcuts({
+ *   onCreate: () => openCreateDialog(),
+ *   onSave: () => saveRecord(),
+ *   onDelete: () => deleteSelected(),
+ *   onCancel: () => closeDialog(),
+ * });
+ * ```
+ */
+export function useCrudShortcuts(callbacks, enabled = true) {
+    const shortcuts = useMemo(() => {
+        const defs = [];
+        if (callbacks.onCreate) {
+            defs.push({
+                key: 'n',
+                ctrlOrMeta: true,
+                handler: () => callbacks.onCreate(),
+                description: 'New record',
+            });
+        }
+        if (callbacks.onEdit) {
+            defs.push({
+                key: 'e',
+                ctrlOrMeta: true,
+                handler: () => callbacks.onEdit(),
+                description: 'Edit selected record',
+            });
+        }
+        if (callbacks.onDelete) {
+            defs.push({
+                key: 'Delete',
+                handler: () => callbacks.onDelete(),
+                description: 'Delete selected record(s)',
+            }, {
+                key: 'Backspace',
+                handler: () => callbacks.onDelete(),
+                description: 'Delete selected record(s)',
+            });
+        }
+        if (callbacks.onSave) {
+            defs.push({
+                key: 's',
+                ctrlOrMeta: true,
+                handler: () => callbacks.onSave(),
+                description: 'Save current record',
+            });
+        }
+        if (callbacks.onDuplicate) {
+            defs.push({
+                key: 'd',
+                ctrlOrMeta: true,
+                handler: () => callbacks.onDuplicate(),
+                description: 'Duplicate selected record',
+            });
+        }
+        if (callbacks.onCancel) {
+            defs.push({
+                key: 'Escape',
+                handler: () => callbacks.onCancel(),
+                description: 'Cancel/close current operation',
+            });
+        }
+        if (callbacks.onSearch) {
+            defs.push({
+                key: 'f',
+                ctrlOrMeta: true,
+                handler: () => callbacks.onSearch(),
+                description: 'Focus search',
+            });
+        }
+        return defs;
+    }, [callbacks]);
+    useKeyboardShortcuts(shortcuts, { enabled });
+}

package/dist/hooks/useDensityMode.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+/** Density mode aligned with DensityMode from @objectstack/spec v2.0.7 */
+export type DensityModeValue = 'compact' | 'comfortable' | 'spacious';
+export interface DensityConfig {
+    /** Row height in pixels for each density mode */
+    rowHeights?: Record<DensityModeValue, number>;
+    /** Padding classes for each density mode */
+    paddingClasses?: Record<DensityModeValue, string>;
+    /** Font size classes for each density mode */
+    fontSizeClasses?: Record<DensityModeValue, string>;
+}
+export interface DensityResult {
+    /** Current density mode */
+    mode: DensityModeValue;
+    /** Set the density mode */
+    setMode: (mode: DensityModeValue) => void;
+    /** Cycle through density modes */
+    cycle: () => void;
+    /** Row height for the current mode (in pixels) */
+    rowHeight: number;
+    /** Tailwind padding class for the current mode */
+    paddingClass: string;
+    /** Tailwind font-size class for the current mode */
+    fontSizeClass: string;
+}
+/**
+ * Hook for managing view density modes (compact/comfortable/spacious).
+ * Implements DensityMode from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const density = useDensityMode('comfortable');
+ *
+ * return (
+ *   <div className={density.paddingClass}>
+ *     <table style={{ rowHeight: density.rowHeight }}>...</table>
+ *     <button onClick={density.cycle}>Toggle Density</button>
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useDensityMode(initialMode?: DensityModeValue, config?: DensityConfig): DensityResult;