@object-ui/react 3.3.0 → 3.3.2

package/src/hooks/useFocusTrap.ts

@@ -1,138 +0,0 @@
-/**
- * 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';
-
-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;
-}
-
-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<T extends HTMLElement = HTMLDivElement>(
-  options: FocusTrapOptions = {}
-): React.RefObject<T | null> {
-  const {
-    enabled = true,
-    autoFocus = true,
-    restoreFocus = true,
-    escapeDeactivates = false,
-    onEscape,
-    initialFocus,
-  } = options;
-
-  const containerRef = useRef<T | null>(null);
-  const previousFocusRef = useRef<HTMLElement | null>(null);
-
-  const getFocusableElements = useCallback(() => {
-    if (!containerRef.current) return [];
-    return Array.from(
-      containerRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)
-    ).filter((el) => !el.hasAttribute('disabled') && el.tabIndex >= 0);
-  }, []);
-
-  useEffect(() => {
-    if (!enabled || !containerRef.current) return;
-
-    // Save previously focused element
-    previousFocusRef.current = document.activeElement as HTMLElement;
-
-    // Auto-focus
-    if (autoFocus) {
-      const focusableElements = getFocusableElements();
-      if (initialFocus) {
-        const target = containerRef.current.querySelector<HTMLElement>(initialFocus);
-        if (target) {
-          target.focus();
-        } else if (focusableElements.length > 0) {
-          focusableElements[0].focus();
-        }
-      } else if (focusableElements.length > 0) {
-        focusableElements[0].focus();
-      }
-    }
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      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/src/hooks/useGlobalUndo.ts

@@ -1,98 +0,0 @@
-/**
- * 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 { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
-import { globalUndoManager, type UndoableOperation } from '@object-ui/core';
-
-export interface UseGlobalUndoOptions {
-  /** DataSource to execute undo/redo operations. */
-  dataSource?: {
-    create(objectName: string, data: Record<string, unknown>): Promise<unknown>;
-    update(objectName: string, recordId: string, data: Record<string, unknown>): Promise<unknown>;
-    delete(objectName: string, recordId: string): Promise<unknown>;
-  };
-  /** Callback after successful undo. */
-  onUndo?: (op: UndoableOperation) => void;
-  /** Callback after successful redo. */
-  onRedo?: (op: UndoableOperation) => void;
-}
-
-function getSnapshot() {
-  return {
-    canUndo: globalUndoManager.canUndo,
-    canRedo: globalUndoManager.canRedo,
-    undoDescription: globalUndoManager.peekUndo()?.description,
-    redoDescription: globalUndoManager.peekRedo()?.description,
-    history: globalUndoManager.getHistory(),
-  };
-}
-
-function getServerSnapshot() {
-  return { canUndo: false, canRedo: false, undoDescription: undefined, redoDescription: undefined, history: [] as UndoableOperation[] };
-}
-
-// Cache reference to avoid re-renders when nothing changed
-let cachedSnapshot = getSnapshot();
-function subscribe(callback: () => void) {
-  return globalUndoManager.subscribe(() => {
-    cachedSnapshot = getSnapshot();
-    callback();
-  });
-}
-function getCachedSnapshot() { return cachedSnapshot; }
-
-/**
- * React hook that wraps the global UndoManager for use in console components.
- *
- * Provides reactive undo/redo state, executes data operations through the
- * supplied dataSource, and registers Ctrl+Z / Ctrl+Shift+Z keyboard shortcuts.
- */
-export function useGlobalUndo(options: UseGlobalUndoOptions = {}) {
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  const state = useSyncExternalStore(subscribe, getCachedSnapshot, getServerSnapshot);
-
-  const executeOp = useCallback(async (op: UndoableOperation, data: Record<string, unknown>, mode: 'undo' | 'redo') => {
-    const ds = optionsRef.current.dataSource;
-    if (!ds) return;
-    const action = mode === 'undo'
-      ? ({ create: 'delete', update: 'update', delete: 'create' } as const)[op.type]
-      : op.type;
-    if (action === 'delete') await ds.delete(op.objectName, op.recordId);
-    else if (action === 'update') await ds.update(op.objectName, op.recordId, data);
-    else await ds.create(op.objectName, data);
-  }, []);
-
-  const undo = useCallback(async () => {
-    const op = globalUndoManager.popUndo();
-    if (!op) return;
-    await executeOp(op, op.undoData, 'undo');
-    optionsRef.current.onUndo?.(op);
-  }, [executeOp]);
-
-  const redo = useCallback(async () => {
-    const op = globalUndoManager.popRedo();
-    if (!op) return;
-    await executeOp(op, op.redoData, 'redo');
-    optionsRef.current.onRedo?.(op);
-  }, [executeOp]);
-
-  // Keyboard shortcuts: Ctrl+Z (undo), Ctrl+Shift+Z (redo)
-  useEffect(() => {
-    const handler = (e: KeyboardEvent) => {
-      if (!(e.ctrlKey || e.metaKey) || e.key.toLowerCase() !== 'z') return;
-      e.preventDefault();
-      if (e.shiftKey) { void redo(); } else { void undo(); }
-    };
-    window.addEventListener('keydown', handler);
-    return () => window.removeEventListener('keydown', handler);
-  }, [undo, redo]);
-
-  return useMemo(() => ({ ...state, undo, redo }), [state, undo, redo]);
-}

package/src/hooks/useKeyboardShortcuts.ts

@@ -1,119 +0,0 @@
-/**
- * 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';
-
-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 function useKeyboardShortcuts(
-  shortcuts: KeyboardShortcutDefinition[],
-  options: { enabled?: boolean } = {}
-): void {
-  const { enabled = true } = options;
-  const shortcutsRef = useRef(shortcuts);
-  useEffect(() => {
-    shortcutsRef.current = shortcuts;
-  }, [shortcuts]);
-
-  const handleKeyDown = useCallback(
-    (event: KeyboardEvent) => {
-      // Don't trigger shortcuts when typing in form elements
-      const target = event.target as HTMLElement;
-      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: KeyboardShortcutDefinition[]
-): Array<{ keys: string; description: string }> {
-  return shortcuts
-    .filter((s) => s.description && s.enabled !== false)
-    .map((s) => {
-      const parts: string[] = [];
-      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/src/hooks/useNavigationOverlay.ts

@@ -1,190 +0,0 @@
-/**
- * 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';
-
-/**
- * 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;
-  /** The target view/form name from NavigationConfig */
-  view: string | undefined;
-}
-
-/**
- * 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: UseNavigationOverlayOptions
-): NavigationOverlayState {
-  const { navigation, objectName, onNavigate, onRowClick } = options;
-  const [isOpen, setIsOpen] = useState(false);
-  const [selectedRecord, setSelectedRecord] = useState<Record<string, unknown> | null>(null);
-
-  const mode: NavigationMode = navigation?.mode ?? 'page';
-  const width = navigation?.width;
-  const view = navigation?.view;
-  const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
-
-  const close = useCallback(() => {
-    setIsOpen(false);
-    setSelectedRecord(null);
-  }, []);
-
-  const open = useCallback((record: Record<string, unknown>) => {
-    setSelectedRecord(record);
-    setIsOpen(true);
-  }, []);
-
-  const handleClick = useCallback(
-    (record: Record<string, unknown>) => {
-      // 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 as string | number, view ?? 'view');
-        }
-        return;
-      }
-
-      // 'none' or preventNavigation — do nothing
-      if (mode === 'none' || navigation.preventNavigation) {
-        return;
-      }
-
-      // new_window / openNewTab — delegate to onNavigate when available, else open directly
-      if (mode === 'new_window' || navigation.openNewTab) {
-        const recordId = record.id || record._id;
-        if (onNavigate && recordId != null) {
-          onNavigate(recordId as string | number, 'new_window');
-          return;
-        }
-        const viewPath = view ? `/${view}` : '';
-        const encodedId = encodeURIComponent(String(recordId));
-        const url = objectName ? `/${objectName}/${encodedId}${viewPath}` : `/${encodedId}${viewPath}`;
-        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 as string | number, view ?? '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,
-      view,
-      isOverlay,
-    }),
-    [isOpen, selectedRecord, mode, close, open, handleClick, width, view, isOverlay]
-  );
-}