@object-ui/react 0.5.0 → 3.0.0

package/dist/hooks/useFocusTrap.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { useEffect, useRef, useCallback } from 'react';
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(', ');
+/**
+ * Hook that traps focus within a container element.
+ * Implements FocusTrapConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * function Modal({ onClose }: { onClose: () => void }) {
+ *   const trapRef = useFocusTrap({
+ *     enabled: true,
+ *     autoFocus: true,
+ *     restoreFocus: true,
+ *     escapeDeactivates: true,
+ *     onEscape: onClose,
+ *   });
+ *
+ *   return <div ref={trapRef}>...</div>;
+ * }
+ * ```
+ */
+export function useFocusTrap(options = {}) {
+    const { enabled = true, autoFocus = true, restoreFocus = true, escapeDeactivates = false, onEscape, initialFocus, } = options;
+    const containerRef = useRef(null);
+    const previousFocusRef = useRef(null);
+    const getFocusableElements = useCallback(() => {
+        if (!containerRef.current)
+            return [];
+        return Array.from(containerRef.current.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => !el.hasAttribute('disabled') && el.tabIndex >= 0);
+    }, []);
+    useEffect(() => {
+        if (!enabled || !containerRef.current)
+            return;
+        // Save previously focused element
+        previousFocusRef.current = document.activeElement;
+        // Auto-focus
+        if (autoFocus) {
+            const focusableElements = getFocusableElements();
+            if (initialFocus) {
+                const target = containerRef.current.querySelector(initialFocus);
+                if (target) {
+                    target.focus();
+                }
+                else if (focusableElements.length > 0) {
+                    focusableElements[0].focus();
+                }
+            }
+            else if (focusableElements.length > 0) {
+                focusableElements[0].focus();
+            }
+        }
+        const handleKeyDown = (event) => {
+            if (!containerRef.current)
+                return;
+            if (event.key === 'Escape' && escapeDeactivates) {
+                onEscape?.();
+                return;
+            }
+            if (event.key !== 'Tab')
+                return;
+            const focusableElements = getFocusableElements();
+            if (focusableElements.length === 0)
+                return;
+            const firstElement = focusableElements[0];
+            const lastElement = focusableElements[focusableElements.length - 1];
+            if (event.shiftKey) {
+                if (document.activeElement === firstElement) {
+                    event.preventDefault();
+                    lastElement.focus();
+                }
+            }
+            else {
+                if (document.activeElement === lastElement) {
+                    event.preventDefault();
+                    firstElement.focus();
+                }
+            }
+        };
+        const container = containerRef.current;
+        container.addEventListener('keydown', handleKeyDown);
+        return () => {
+            container.removeEventListener('keydown', handleKeyDown);
+            if (restoreFocus && previousFocusRef.current) {
+                previousFocusRef.current.focus();
+            }
+        };
+    }, [enabled, autoFocus, restoreFocus, escapeDeactivates, onEscape, initialFocus, getFocusableElements]);
+    return containerRef;
+}

package/dist/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 KeyboardShortcutDefinition {
+    /** The key to listen for (e.g., 'k', 'Enter', 'Escape') */
+    key: string;
+    /** Whether Ctrl/Cmd is required */
+    ctrlOrMeta?: boolean;
+    /** Whether Shift is required */
+    shift?: boolean;
+    /** Whether Alt is required */
+    alt?: boolean;
+    /** Handler to call when the shortcut is triggered */
+    handler: (event: KeyboardEvent) => void;
+    /** Human-readable description for the help dialog */
+    description?: string;
+    /** Whether to prevent default browser behavior */
+    preventDefault?: boolean;
+    /** Whether the shortcut is currently enabled */
+    enabled?: boolean;
+}
+/**
+ * Hook for registering keyboard shortcuts.
+ * Implements KeyboardShortcutSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcuts([
+ *   { key: 'k', ctrlOrMeta: true, handler: () => openSearch(), description: 'Open search' },
+ *   { key: 'n', ctrlOrMeta: true, handler: () => createNew(), description: 'Create new record' },
+ *   { key: 'Escape', handler: () => closeModal(), description: 'Close dialog' },
+ * ]);
+ * ```
+ */
+export declare function useKeyboardShortcuts(shortcuts: KeyboardShortcutDefinition[], options?: {
+    enabled?: boolean;
+}): void;
+/**
+ * Returns a list of all registered shortcut descriptions.
+ * Useful for building a help dialog (? key).
+ */
+export declare function getShortcutDescriptions(shortcuts: KeyboardShortcutDefinition[]): Array<{
+    keys: string;
+    description: string;
+}>;

package/dist/hooks/useKeyboardShortcuts.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { useEffect, useRef, useCallback } from 'react';
+/**
+ * Hook for registering keyboard shortcuts.
+ * Implements KeyboardShortcutSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcuts([
+ *   { key: 'k', ctrlOrMeta: true, handler: () => openSearch(), description: 'Open search' },
+ *   { key: 'n', ctrlOrMeta: true, handler: () => createNew(), description: 'Create new record' },
+ *   { key: 'Escape', handler: () => closeModal(), description: 'Close dialog' },
+ * ]);
+ * ```
+ */
+export function useKeyboardShortcuts(shortcuts, options = {}) {
+    const { enabled = true } = options;
+    const shortcutsRef = useRef(shortcuts);
+    useEffect(() => {
+        shortcutsRef.current = shortcuts;
+    }, [shortcuts]);
+    const handleKeyDown = useCallback((event) => {
+        // Don't trigger shortcuts when typing in form elements
+        const target = event.target;
+        const isFormElement = target.tagName === 'INPUT' ||
+            target.tagName === 'TEXTAREA' ||
+            target.tagName === 'SELECT' ||
+            target.isContentEditable;
+        for (const shortcut of shortcutsRef.current) {
+            if (shortcut.enabled === false)
+                continue;
+            const keyMatch = event.key.toLowerCase() === shortcut.key.toLowerCase();
+            const ctrlMatch = shortcut.ctrlOrMeta
+                ? event.ctrlKey || event.metaKey
+                : !event.ctrlKey && !event.metaKey;
+            const shiftMatch = shortcut.shift ? event.shiftKey : !event.shiftKey;
+            const altMatch = shortcut.alt ? event.altKey : !event.altKey;
+            if (keyMatch && ctrlMatch && shiftMatch && altMatch) {
+                // Allow shortcuts with modifiers even in form elements
+                if (isFormElement && !shortcut.ctrlOrMeta && !shortcut.alt)
+                    continue;
+                if (shortcut.preventDefault !== false) {
+                    event.preventDefault();
+                }
+                shortcut.handler(event);
+                return;
+            }
+        }
+    }, []);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [enabled, handleKeyDown]);
+}
+/**
+ * Returns a list of all registered shortcut descriptions.
+ * Useful for building a help dialog (? key).
+ */
+export function getShortcutDescriptions(shortcuts) {
+    return shortcuts
+        .filter((s) => s.description && s.enabled !== false)
+        .map((s) => {
+        const parts = [];
+        if (s.ctrlOrMeta)
+            parts.push('⌘/Ctrl');
+        if (s.shift)
+            parts.push('Shift');
+        if (s.alt)
+            parts.push('Alt');
+        parts.push(s.key.length === 1 ? s.key.toUpperCase() : s.key);
+        return {
+            keys: parts.join(' + '),
+            description: s.description,
+        };
+    });
+}

package/dist/hooks/useNavigationOverlay.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.
+ */
+/**
+ * Inline ViewNavigationConfig to avoid importing from @object-ui/types
+ * (which may not be a direct dependency of @object-ui/react).
+ * Mirrors the canonical definition in @object-ui/types/objectql.ts.
+ */
+export interface NavigationConfig {
+    mode: 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none';
+    view?: string;
+    preventNavigation?: boolean;
+    openNewTab?: boolean;
+    width?: string | number;
+}
+export type NavigationMode = NavigationConfig['mode'];
+export interface UseNavigationOverlayOptions {
+    /** The navigation configuration from the schema */
+    navigation?: NavigationConfig;
+    /** Object name — used to build default URLs for page/new_window modes */
+    objectName?: string;
+    /** External onNavigate callback (e.g., from ActionProvider or parent) */
+    onNavigate?: (recordId: string | number, action?: string) => void;
+    /** External onRowClick callback — if set, takes full priority */
+    onRowClick?: (record: Record<string, unknown>) => void;
+}
+export interface NavigationOverlayState {
+    /** Whether the overlay (drawer/modal/split/popover) is open */
+    isOpen: boolean;
+    /** The record that triggered the navigation */
+    selectedRecord: Record<string, unknown> | null;
+    /** The resolved navigation mode */
+    mode: NavigationMode;
+    /** Close the overlay */
+    close: () => void;
+    /** Open the overlay with a specific record */
+    open: (record: Record<string, unknown>) => void;
+    /** Set the open state (for controlled Sheet/Dialog `onOpenChange`) */
+    setIsOpen: (open: boolean) => void;
+    /** The click handler to attach to rows/items */
+    handleClick: (record: Record<string, unknown>) => void;
+    /** The width from NavigationConfig (for drawer/modal/split sizing) */
+    width: string | number | undefined;
+    /** Whether navigation is an overlay mode (drawer/modal/split/popover) */
+    isOverlay: boolean;
+}
+/**
+ * Hook for NavigationConfig-driven navigation overlay.
+ *
+ * @example
+ * ```tsx
+ * const { handleClick, isOpen, selectedRecord, mode, close, width } =
+ *   useNavigationOverlay({
+ *     navigation: schema.navigation,
+ *     objectName: schema.objectName,
+ *     onNavigate: schema.onNavigate,
+ *     onRowClick: props.onRowClick,
+ *   });
+ *
+ * return (
+ *   <>
+ *     <DataTable onRowClick={handleClick} ... />
+ *     {isOpen && mode === 'drawer' && (
+ *       <Sheet open onOpenChange={() => close()}>
+ *         <SheetContent style={{ maxWidth: width }}>
+ *           <RecordDetail record={selectedRecord} />
+ *         </SheetContent>
+ *       </Sheet>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export declare function useNavigationOverlay(options: UseNavigationOverlayOptions): NavigationOverlayState;

package/dist/hooks/useNavigationOverlay.js

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+/**
+ * useNavigationOverlay
+ *
+ * A reusable hook for handling NavigationConfig-driven row/item click behavior.
+ * Manages overlay state (drawer/modal/split/popover) and generates click handlers
+ * that respect the ViewNavigationConfig specification.
+ *
+ * Used by plugin-grid, plugin-list, plugin-detail and any component that needs
+ * NavigationConfig support.
+ */
+import { useState, useCallback, useMemo } from 'react';
+/**
+ * Hook for NavigationConfig-driven navigation overlay.
+ *
+ * @example
+ * ```tsx
+ * const { handleClick, isOpen, selectedRecord, mode, close, width } =
+ *   useNavigationOverlay({
+ *     navigation: schema.navigation,
+ *     objectName: schema.objectName,
+ *     onNavigate: schema.onNavigate,
+ *     onRowClick: props.onRowClick,
+ *   });
+ *
+ * return (
+ *   <>
+ *     <DataTable onRowClick={handleClick} ... />
+ *     {isOpen && mode === 'drawer' && (
+ *       <Sheet open onOpenChange={() => close()}>
+ *         <SheetContent style={{ maxWidth: width }}>
+ *           <RecordDetail record={selectedRecord} />
+ *         </SheetContent>
+ *       </Sheet>
+ *     )}
+ *   </>
+ * );
+ * ```
+ */
+export function useNavigationOverlay(options) {
+    const { navigation, objectName, onNavigate, onRowClick } = options;
+    const [isOpen, setIsOpen] = useState(false);
+    const [selectedRecord, setSelectedRecord] = useState(null);
+    const mode = navigation?.mode ?? 'page';
+    const width = navigation?.width;
+    const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
+    const close = useCallback(() => {
+        setIsOpen(false);
+        setSelectedRecord(null);
+    }, []);
+    const open = useCallback((record) => {
+        setSelectedRecord(record);
+        setIsOpen(true);
+    }, []);
+    const handleClick = useCallback((record) => {
+        // External onRowClick takes full priority
+        if (onRowClick) {
+            onRowClick(record);
+            return;
+        }
+        // No navigation config — default to page navigation
+        if (!navigation) {
+            const recordId = record._id || record.id;
+            if (onNavigate && recordId != null) {
+                onNavigate(recordId, 'view');
+            }
+            return;
+        }
+        // 'none' or preventNavigation — do nothing
+        if (mode === 'none' || navigation.preventNavigation) {
+            return;
+        }
+        // new_window / openNewTab — open in new browser tab
+        if (mode === 'new_window' || navigation.openNewTab) {
+            const recordId = record._id || record.id;
+            const url = objectName ? `/${objectName}/${recordId}` : `/${recordId}`;
+            window.open(url, '_blank');
+            return;
+        }
+        // page — delegate to onNavigate callback
+        if (mode === 'page') {
+            const recordId = record._id || record.id;
+            if (onNavigate && recordId != null) {
+                onNavigate(recordId, 'view');
+            }
+            return;
+        }
+        // Overlay modes: drawer, modal, split, popover
+        if (isOverlay) {
+            setSelectedRecord(record);
+            setIsOpen(true);
+            return;
+        }
+    }, [onRowClick, navigation, mode, objectName, onNavigate, isOverlay]);
+    return useMemo(() => ({
+        isOpen,
+        selectedRecord,
+        mode,
+        close,
+        open,
+        setIsOpen,
+        handleClick,
+        width,
+        isOverlay,
+    }), [isOpen, selectedRecord, mode, close, open, handleClick, width, isOverlay]);
+}

package/dist/hooks/useOffline.d.ts

@@ -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.
+ */
+/** Offline strategy determines how data is fetched when connectivity is limited. */
+export type OfflineStrategy = 'cache_first' | 'network_first' | 'stale_while_revalidate' | 'network_only' | 'cache_only';
+/** Conflict resolution strategy for sync operations. */
+export type ConflictResolutionStrategy = 'manual' | 'client_wins' | 'server_wins' | 'last_write_wins';
+/** Persist storage backend. */
+export type PersistStorageType = 'indexeddb' | 'localstorage' | 'sqlite';
+/** Eviction policy for cache management. */
+export type EvictionPolicyType = 'lru' | 'lfu' | 'fifo';
+/** Sync state of the offline system. */
+export type SyncState = 'idle' | 'syncing' | 'error' | 'offline';
+/** A queued mutation waiting to be synced. */
+export interface QueuedMutation {
+    id: string;
+    timestamp: number;
+    operation: 'create' | 'update' | 'delete';
+    resource: string;
+    data?: Record<string, unknown>;
+}
+/** Cache configuration aligned with OfflineCacheConfigSchema. */
+export interface OfflineCacheConfig {
+    maxSize?: number;
+    ttl?: number;
+    persistStorage?: PersistStorageType;
+    evictionPolicy?: EvictionPolicyType;
+}
+/** Sync configuration aligned with SyncConfigSchema. */
+export interface OfflineSyncConfig {
+    strategy?: OfflineStrategy;
+    conflictResolution?: ConflictResolutionStrategy;
+    retryInterval?: number;
+    maxRetries?: number;
+    batchSize?: number;
+}
+/** Top-level offline configuration aligned with OfflineConfigSchema. */
+export interface OfflineConfig {
+    enabled?: boolean;
+    strategy?: OfflineStrategy;
+    cache?: OfflineCacheConfig;
+    sync?: OfflineSyncConfig;
+    offlineIndicator?: boolean;
+    offlineMessage?: string;
+    queueMaxSize?: number;
+}
+/** Result returned by the useOffline hook. */
+export interface OfflineResult {
+    /** Whether the browser is currently online. */
+    isOnline: boolean;
+    /** Whether offline mode is enabled in config. */
+    enabled: boolean;
+    /** Current sync state. */
+    syncState: SyncState;
+    /** The active offline strategy. */
+    strategy: OfflineStrategy;
+    /** Number of pending mutations in the queue. */
+    pendingCount: number;
+    /** Queue a mutation for later sync. */
+    queueMutation: (mutation: Omit<QueuedMutation, 'id' | 'timestamp'>) => void;
+    /** Manually trigger a sync attempt. */
+    sync: () => Promise<void>;
+    /** Clear the mutation queue. */
+    clearQueue: () => void;
+    /** Whether to show the offline indicator UI. */
+    showIndicator: boolean;
+    /** The offline message to display. */
+    offlineMessage: string;
+}
+/**
+ * Hook for offline mode detection and sync queue management.
+ * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
+ * from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const offline = useOffline({
+ *     enabled: true,
+ *     strategy: 'cache_first',
+ *     sync: { conflictResolution: 'last_write_wins' },
+ *   });
+ *
+ *   if (!offline.isOnline && offline.showIndicator) {
+ *     return <Banner>{offline.offlineMessage}</Banner>;
+ *   }
+ *
+ *   return <div>Pending mutations: {offline.pendingCount}</div>;
+ * }
+ * ```
+ */
+export declare function useOffline(config?: OfflineConfig): OfflineResult;