@object-ui/react 2.0.0 → 3.0.0

package/dist/hooks/useFocusManagement.js

@@ -0,0 +1,188 @@
+/**
+ * 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, useState } from 'react';
+/**
+ * Hook that captures the currently focused element on mount and restores
+ * focus to it when the component unmounts. Useful for modals, drawers,
+ * and overlays that temporarily steal focus.
+ *
+ * @example
+ * ```tsx
+ * function Drawer({ onClose }: { onClose: () => void }) {
+ *   const { returnFocus } = useFocusReturn();
+ *
+ *   const handleClose = () => {
+ *     returnFocus();
+ *     onClose();
+ *   };
+ *
+ *   return <aside>...</aside>;
+ * }
+ * ```
+ */
+export function useFocusReturn(options = {}) {
+    const { enabled = true, restoreOnUnmount = true } = options;
+    const previousFocusRef = useRef(null);
+    // Capture focused element on mount
+    useEffect(() => {
+        if (!enabled)
+            return;
+        previousFocusRef.current = document.activeElement;
+    }, [enabled]);
+    const returnFocus = useCallback(() => {
+        if (!enabled)
+            return;
+        const el = previousFocusRef.current;
+        if (el && typeof el.focus === 'function' && document.body.contains(el)) {
+            el.focus();
+        }
+    }, [enabled]);
+    // Restore on unmount
+    useEffect(() => {
+        if (!enabled || !restoreOnUnmount)
+            return;
+        return () => {
+            const el = previousFocusRef.current;
+            if (el && typeof el.focus === 'function' && document.body.contains(el)) {
+                el.focus();
+            }
+        };
+        // Only run cleanup on unmount — intentionally stable deps
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return { returnFocus };
+}
+/**
+ * Hook that implements roving tabindex / arrow-key navigation for a list of
+ * focusable items inside a container (sidebar items, tab lists, menu items).
+ *
+ * Only the currently active item participates in the tab order (tabindex 0);
+ * all other items are removed from the tab order (tabindex -1). Arrow keys
+ * move focus between items.
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav({ items }: { items: string[] }) {
+ *   const { containerRef, focusedIndex } = useRovingFocus<HTMLUListElement>({
+ *     orientation: 'vertical',
+ *     loop: true,
+ *   });
+ *
+ *   return (
+ *     <ul ref={containerRef} role="tablist">
+ *       {items.map((item, i) => (
+ *         <li
+ *           key={item}
+ *           role="tab"
+ *           tabIndex={i === focusedIndex ? 0 : -1}
+ *           data-roving-item
+ *         >
+ *           {item}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useRovingFocus(options = {}) {
+    const { enabled = true, orientation = 'vertical', loop = true, onFocusChange, } = options;
+    const containerRef = useRef(null);
+    const [focusedIndex, setFocusedIndexState] = useState(-1);
+    const onFocusChangeRef = useRef(onFocusChange);
+    useEffect(() => {
+        onFocusChangeRef.current = onFocusChange;
+    }, [onFocusChange]);
+    const getItems = useCallback(() => {
+        if (!containerRef.current)
+            return [];
+        return Array.from(containerRef.current.querySelectorAll('[data-roving-item]')).filter((el) => {
+            // Exclude hidden or disabled elements
+            if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') {
+                return false;
+            }
+            return el.offsetParent !== null; // visible check
+        });
+    }, []);
+    const setFocusedIndex = useCallback((index) => {
+        const items = getItems();
+        if (items.length === 0)
+            return;
+        const clamped = Math.max(0, Math.min(index, items.length - 1));
+        setFocusedIndexState(clamped);
+        items[clamped]?.focus();
+        onFocusChangeRef.current?.(clamped);
+    }, [getItems]);
+    useEffect(() => {
+        if (!enabled || !containerRef.current)
+            return;
+        const handleKeyDown = (event) => {
+            const items = getItems();
+            if (items.length === 0)
+                return;
+            const currentIndex = items.findIndex((el) => el === document.activeElement);
+            if (currentIndex === -1)
+                return;
+            const prevKeys = orientation === 'horizontal' ? ['ArrowLeft'] :
+                orientation === 'vertical' ? ['ArrowUp'] :
+                    ['ArrowUp', 'ArrowLeft'];
+            const nextKeys = orientation === 'horizontal' ? ['ArrowRight'] :
+                orientation === 'vertical' ? ['ArrowDown'] :
+                    ['ArrowDown', 'ArrowRight'];
+            let nextIndex = null;
+            if (prevKeys.includes(event.key)) {
+                event.preventDefault();
+                if (currentIndex > 0) {
+                    nextIndex = currentIndex - 1;
+                }
+                else if (loop) {
+                    nextIndex = items.length - 1;
+                }
+            }
+            else if (nextKeys.includes(event.key)) {
+                event.preventDefault();
+                if (currentIndex < items.length - 1) {
+                    nextIndex = currentIndex + 1;
+                }
+                else if (loop) {
+                    nextIndex = 0;
+                }
+            }
+            else if (event.key === 'Home') {
+                event.preventDefault();
+                nextIndex = 0;
+            }
+            else if (event.key === 'End') {
+                event.preventDefault();
+                nextIndex = items.length - 1;
+            }
+            if (nextIndex !== null) {
+                setFocusedIndexState(nextIndex);
+                items[nextIndex].focus();
+                onFocusChangeRef.current?.(nextIndex);
+            }
+        };
+        // When an item receives focus (e.g. via click), sync the index
+        const handleFocusIn = (event) => {
+            const items = getItems();
+            const index = items.findIndex((el) => el === event.target);
+            if (index !== -1) {
+                setFocusedIndexState(index);
+                onFocusChangeRef.current?.(index);
+            }
+        };
+        const container = containerRef.current;
+        container.addEventListener('keydown', handleKeyDown);
+        container.addEventListener('focusin', handleFocusIn);
+        return () => {
+            container.removeEventListener('keydown', handleKeyDown);
+            container.removeEventListener('focusin', handleFocusIn);
+        };
+    }, [enabled, orientation, loop, getItems]);
+    return { containerRef, focusedIndex, setFocusedIndex };
+}

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 FocusTrapOptions {
+    /** Whether the focus trap is currently active */
+    enabled?: boolean;
+    /** Whether to auto-focus the first focusable element on mount */
+    autoFocus?: boolean;
+    /** Whether to restore focus to the previously focused element on unmount */
+    restoreFocus?: boolean;
+    /** Whether to release the trap on Escape key */
+    escapeDeactivates?: boolean;
+    /** Callback when Escape is pressed (if escapeDeactivates is true) */
+    onEscape?: () => void;
+    /** Initial element to focus (CSS selector) */
+    initialFocus?: string;
+}
+/**
+ * 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 declare function useFocusTrap<T extends HTMLElement = HTMLDivElement>(options?: FocusTrapOptions): React.RefObject<T | null>;

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/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;