@object-ui/react 0.5.0 → 3.0.0

package/src/hooks/useFocusManagement.ts

@@ -0,0 +1,248 @@
+/**
+ * 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';
+
+// ─── useFocusReturn ────────────────────────────────────────────────────────────
+
+export interface FocusReturnOptions {
+  /** Whether focus restoration is enabled. @default true */
+  enabled?: boolean;
+  /** Whether to focus the previously active element on unmount. @default true */
+  restoreOnUnmount?: boolean;
+}
+
+/**
+ * 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: FocusReturnOptions = {}): {
+  /** Manually restore focus to the previously focused element. */
+  returnFocus: () => void;
+} {
+  const { enabled = true, restoreOnUnmount = true } = options;
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  // Capture focused element on mount
+  useEffect(() => {
+    if (!enabled) return;
+    previousFocusRef.current = document.activeElement as HTMLElement | null;
+  }, [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 };
+}
+
+// ─── useRovingFocus ────────────────────────────────────────────────────────────
+
+export type RovingOrientation = 'horizontal' | 'vertical' | 'both';
+
+export interface RovingFocusOptions {
+  /** Whether roving focus is enabled. @default true */
+  enabled?: boolean;
+  /** Navigation orientation. @default 'vertical' */
+  orientation?: RovingOrientation;
+  /** Whether focus wraps from last to first item and vice-versa. @default true */
+  loop?: boolean;
+  /** Callback fired when the focused index changes. */
+  onFocusChange?: (index: number) => void;
+}
+
+export interface RovingFocusReturn<T extends HTMLElement> {
+  /** Ref to attach to the container element. */
+  containerRef: React.RefObject<T | null>;
+  /** The index of the currently focused item (-1 if none). */
+  focusedIndex: number;
+  /** Programmatically focus a specific item by index. */
+  setFocusedIndex: (index: number) => void;
+}
+
+/**
+ * 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<T extends HTMLElement = HTMLDivElement>(
+  options: RovingFocusOptions = {}
+): RovingFocusReturn<T> {
+  const {
+    enabled = true,
+    orientation = 'vertical',
+    loop = true,
+    onFocusChange,
+  } = options;
+
+  const containerRef = useRef<T | null>(null);
+  const [focusedIndex, setFocusedIndexState] = useState(-1);
+  const onFocusChangeRef = useRef(onFocusChange);
+  useEffect(() => {
+    onFocusChangeRef.current = onFocusChange;
+  }, [onFocusChange]);
+
+  const getItems = useCallback((): HTMLElement[] => {
+    if (!containerRef.current) return [];
+    return Array.from(
+      containerRef.current.querySelectorAll<HTMLElement>('[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: number) => {
+      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: KeyboardEvent) => {
+      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: number | null = 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: FocusEvent) => {
+      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/src/hooks/useFocusTrap.ts

@@ -0,0 +1,138 @@
+/**
+ * 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/useKeyboardShortcuts.ts

@@ -0,0 +1,119 @@
+/**
+ * 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

@@ -0,0 +1,180 @@
+/**
+ * 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;
+}
+
+/**
+ * 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 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');
+        }
+        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 as string | number, '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]
+  );
+}