@fragments-sdk/ui 0.9.7 → 0.11.0

package/dist/utils/keyboard-shortcuts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-shortcuts.cjs","sources":["../../src/utils/keyboard-shortcuts.ts"],"sourcesContent":["'use client';\n\n// ============================================\n// Keyboard Shortcuts Registry\n// ============================================\n//\n// Central source of truth for all keyboard shortcuts in @fragments-sdk/ui.\n// Import from here instead of hardcoding key combinations in components.\n//\n// This prevents conflicts (e.g., Sidebar Ctrl+B vs Editor Ctrl+B) and\n// makes shortcuts discoverable for documentation and customization.\n//\n// ADDING A SHORTCUT:\n//   1. Add an entry to KEYBOARD_SHORTCUTS below\n//   2. Import the constant in your component\n//   3. Use useKeyboardShortcut() or matchesShortcut() in your component\n//\n// CUSTOMIZING SHORTCUTS (consumer API):\n//   configureShortcuts({ SIDEBAR_TOGGLE: { key: '\\\\', label: 'Ctrl+\\\\' } })\n//   configureShortcuts({ SIDEBAR_TOGGLE: null })  // disable\n//\n\nimport { useEffect, useRef, type RefObject } from 'react';\n\n// ============================================\n// Types\n// ============================================\n\nexport interface KeyboardShortcut {\n  /** The key to match (e.g., 'b', 'k', 'Escape'). Case-insensitive. */\n  key: string;\n  /** Require Ctrl (Windows/Linux) or Cmd (macOS) */\n  meta?: boolean;\n  /** Require Shift */\n  shift?: boolean;\n  /** Require Alt/Option */\n  alt?: boolean;\n  /** Human-readable label for display (e.g., \"Ctrl+B\", \"⌘B\") */\n  label: string;\n  /** Which component owns this shortcut */\n  component: string;\n  /** What the shortcut does */\n  description: string;\n  /**\n   * Scope controls when the shortcut is active:\n   * - 'global': Listens on document (e.g., sidebar toggle)\n   * - 'component': Only active when component is focused/mounted\n   */\n  scope: 'global' | 'component';\n}\n\n// ============================================\n// Shortcut Definitions\n// ============================================\n\nexport const KEYBOARD_SHORTCUTS = {\n  // ----- Sidebar -----\n  SIDEBAR_TOGGLE: {\n    key: 'b',\n    meta: true,\n    label: 'Ctrl+B',\n    component: 'Sidebar',\n    description: 'Toggle sidebar collapse/expand',\n    scope: 'global',\n  },\n  SIDEBAR_CLOSE_MOBILE: {\n    key: 'Escape',\n    label: 'Escape',\n    component: 'Sidebar',\n    description: 'Close mobile sidebar drawer',\n    scope: 'global',\n  },\n\n  // ----- Editor (TipTap handles these natively, metadata for display) -----\n  EDITOR_BOLD: {\n    key: 'b',\n    meta: true,\n    label: 'Ctrl+B',\n    component: 'Editor',\n    description: 'Toggle bold formatting',\n    scope: 'component',\n  },\n  EDITOR_ITALIC: {\n    key: 'i',\n    meta: true,\n    label: 'Ctrl+I',\n    component: 'Editor',\n    description: 'Toggle italic formatting',\n    scope: 'component',\n  },\n  EDITOR_STRIKETHROUGH: {\n    key: 's',\n    meta: true,\n    shift: true,\n    label: 'Ctrl+Shift+S',\n    component: 'Editor',\n    description: 'Toggle strikethrough formatting',\n    scope: 'component',\n  },\n  EDITOR_LINK: {\n    key: 'k',\n    meta: true,\n    label: 'Ctrl+K',\n    component: 'Editor',\n    description: 'Insert or edit link',\n    scope: 'component',\n  },\n  EDITOR_CODE: {\n    key: 'e',\n    meta: true,\n    label: 'Ctrl+E',\n    component: 'Editor',\n    description: 'Toggle inline code',\n    scope: 'component',\n  },\n  EDITOR_BULLET_LIST: {\n    key: '8',\n    meta: true,\n    shift: true,\n    label: 'Ctrl+Shift+8',\n    component: 'Editor',\n    description: 'Toggle bullet list',\n    scope: 'component',\n  },\n  EDITOR_ORDERED_LIST: {\n    key: '7',\n    meta: true,\n    shift: true,\n    label: 'Ctrl+Shift+7',\n    component: 'Editor',\n    description: 'Toggle ordered list',\n    scope: 'component',\n  },\n  EDITOR_HEADING1: {\n    key: '1',\n    meta: true,\n    alt: true,\n    label: 'Ctrl+Alt+1',\n    component: 'Editor',\n    description: 'Toggle heading level 1',\n    scope: 'component',\n  },\n  EDITOR_HEADING2: {\n    key: '2',\n    meta: true,\n    alt: true,\n    label: 'Ctrl+Alt+2',\n    component: 'Editor',\n    description: 'Toggle heading level 2',\n    scope: 'component',\n  },\n  EDITOR_HEADING3: {\n    key: '3',\n    meta: true,\n    alt: true,\n    label: 'Ctrl+Alt+3',\n    component: 'Editor',\n    description: 'Toggle heading level 3',\n    scope: 'component',\n  },\n  EDITOR_BLOCKQUOTE: {\n    key: 'b',\n    meta: true,\n    shift: true,\n    label: 'Ctrl+Shift+B',\n    component: 'Editor',\n    description: 'Toggle blockquote',\n    scope: 'component',\n  },\n  EDITOR_UNDO: {\n    key: 'z',\n    meta: true,\n    label: 'Ctrl+Z',\n    component: 'Editor',\n    description: 'Undo last action',\n    scope: 'component',\n  },\n  EDITOR_REDO: {\n    key: 'z',\n    meta: true,\n    shift: true,\n    label: 'Ctrl+Shift+Z',\n    component: 'Editor',\n    description: 'Redo last undone action',\n    scope: 'component',\n  },\n\n  // ----- Prompt -----\n  PROMPT_SUBMIT: {\n    key: 'Enter',\n    label: 'Enter',\n    component: 'Prompt',\n    description: 'Submit prompt (when submitOnEnter is true)',\n    scope: 'component',\n  },\n\n  // ----- NavigationMenu -----\n  NAV_TOGGLE: {\n    key: 'Enter',\n    label: 'Enter',\n    component: 'NavigationMenu',\n    description: 'Toggle menu item open/closed',\n    scope: 'component',\n  },\n  NAV_CLOSE: {\n    key: 'Escape',\n    label: 'Escape',\n    component: 'NavigationMenu',\n    description: 'Close menu and return focus to trigger',\n    scope: 'component',\n  },\n\n  // ----- Command -----\n  COMMAND_SELECT: {\n    key: 'Enter',\n    label: 'Enter',\n    component: 'Command',\n    description: 'Select active command item',\n    scope: 'component',\n  },\n\n  // ----- Collapsible -----\n  COLLAPSIBLE_TOGGLE: {\n    key: 'Enter',\n    label: 'Enter',\n    component: 'Collapsible',\n    description: 'Toggle collapsible open/closed',\n    scope: 'component',\n  },\n} as const satisfies Record<string, KeyboardShortcut>;\n\nexport type ShortcutName = keyof typeof KEYBOARD_SHORTCUTS;\n\n// ============================================\n// Helpers\n// ============================================\n\n/**\n * Check if a KeyboardEvent matches a shortcut definition.\n *\n * Usage:\n * ```ts\n * import { KEYBOARD_SHORTCUTS, matchesShortcut } from '../../utils/keyboard-shortcuts';\n *\n * const handleKeyDown = (e: KeyboardEvent) => {\n *   if (matchesShortcut(e, KEYBOARD_SHORTCUTS.SIDEBAR_TOGGLE)) {\n *     e.preventDefault();\n *     toggleSidebar();\n *   }\n * };\n * ```\n */\nexport function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcut): boolean {\n  if (shortcut.meta && !(event.metaKey || event.ctrlKey)) return false;\n  if (shortcut.shift && !event.shiftKey) return false;\n  if (shortcut.alt && !event.altKey) return false;\n\n  // For modifier-only checks, ensure no extra modifiers are pressed\n  if (!shortcut.meta && (event.metaKey || event.ctrlKey)) return false;\n  if (!shortcut.shift && event.shiftKey) return false;\n  if (!shortcut.alt && event.altKey) return false;\n\n  return event.key.toLowerCase() === shortcut.key.toLowerCase();\n}\n\n/**\n * Get a human-readable shortcut label, adapting for macOS vs other platforms.\n * Returns \"⌘B\" on Mac, \"Ctrl+B\" elsewhere.\n */\nexport function getShortcutLabel(shortcut: KeyboardShortcut): string {\n  if (typeof navigator === 'undefined') return shortcut.label;\n\n  const isMac = navigator.platform?.includes('Mac') || navigator.userAgent?.includes('Mac');\n  if (!isMac) return shortcut.label;\n\n  const parts: string[] = [];\n  if (shortcut.meta) parts.push('⌘');\n  if (shortcut.shift) parts.push('⇧');\n  if (shortcut.alt) parts.push('⌥');\n  parts.push(shortcut.key.toUpperCase());\n  return parts.join('');\n}\n\n/**\n * Find all shortcuts that conflict with a given shortcut (same key combo, different component).\n * Useful for debugging and documentation.\n */\nexport function findConflicts(name: ShortcutName): KeyboardShortcut[] {\n  const target = KEYBOARD_SHORTCUTS[name] as KeyboardShortcut;\n  return (Object.entries(KEYBOARD_SHORTCUTS) as [string, KeyboardShortcut][])\n    .filter(([key, shortcut]) => {\n      if (key === name) return false;\n      return (\n        shortcut.key.toLowerCase() === target.key.toLowerCase() &&\n        !!shortcut.meta === !!target.meta &&\n        !!shortcut.shift === !!target.shift &&\n        !!shortcut.alt === !!target.alt\n      );\n    })\n    .map(([, shortcut]) => shortcut);\n}\n\n/**\n * Get all registered shortcuts, optionally filtered by component or scope.\n */\nexport function getShortcuts(filter?: { component?: string; scope?: 'global' | 'component' }): KeyboardShortcut[] {\n  return (Object.values(KEYBOARD_SHORTCUTS) as KeyboardShortcut[]).filter((shortcut) => {\n    if (filter?.component && shortcut.component !== filter.component) return false;\n    if (filter?.scope && shortcut.scope !== filter.scope) return false;\n    return true;\n  });\n}\n\n// ============================================\n// Editable Element Detection\n// ============================================\n\n/** Text-like input types where typing shortcuts should not fire global handlers */\nconst TEXT_INPUT_TYPES = new Set([\n  'text', 'search', 'url', 'tel', 'email', 'password', 'number',\n]);\n\n/**\n * Check if an element is an editable area (input, textarea, contenteditable, role=\"textbox\").\n * Global shortcuts should skip firing when the user is typing in one of these.\n */\nexport function isEditableElement(element: Element | null): boolean {\n  if (!element || !('tagName' in element)) return false;\n\n  const tag = element.tagName;\n\n  // <textarea>\n  if (tag === 'TEXTAREA') return true;\n\n  // <input> with text-like type\n  if (tag === 'INPUT') {\n    const type = (element as HTMLInputElement).type?.toLowerCase() || 'text';\n    return TEXT_INPUT_TYPES.has(type);\n  }\n\n  // contenteditable=\"true\" or contenteditable=\"\"\n  const htmlEl = element as HTMLElement;\n  if (htmlEl.isContentEditable) return true;\n  // Fallback: check attribute directly (isContentEditable can be unreliable for detached elements)\n  const ceAttr = htmlEl.contentEditable;\n  if (ceAttr === 'true' || ceAttr === '') return true;\n\n  // role=\"textbox\" (TipTap uses this)\n  if (typeof element.getAttribute === 'function' && element.getAttribute('role') === 'textbox') return true;\n\n  // Check ancestors for contenteditable (e.g., a <p> inside a [contenteditable] div)\n  // Walk up manually because jsdom's closest doesn't reliably match property-set contentEditable\n  let ancestor = element.parentElement;\n  while (ancestor) {\n    if ((ancestor as HTMLElement).isContentEditable) return true;\n    const ancestorCe = (ancestor as HTMLElement).contentEditable;\n    if (ancestorCe === 'true' || ancestorCe === '') return true;\n    ancestor = ancestor.parentElement;\n  }\n\n  return false;\n}\n\n// ============================================\n// Shortcut Override API\n// ============================================\n\n/** Module-level override store. null = disabled, Partial<KeyboardShortcut> = merged with default. */\nconst shortcutOverrides = new Map<ShortcutName, Partial<KeyboardShortcut> | null>();\n\n/**\n * Configure shortcut overrides at app startup. Mirrors the `configureTheme()` API.\n *\n * - Partial overrides merge with the default (e.g., `{ key: '\\\\' }` keeps label/component/etc.)\n * - `null` disables a shortcut entirely\n * - Omitted keys are left unchanged\n * - Multiple calls merge additively (last write wins per key)\n *\n * @example\n * ```ts\n * import { configureShortcuts } from '@fragments-sdk/ui';\n *\n * // Remap sidebar toggle to Ctrl+\\\n * configureShortcuts({ SIDEBAR_TOGGLE: { key: '\\\\', label: 'Ctrl+\\\\' } });\n *\n * // Disable sidebar toggle entirely\n * configureShortcuts({ SIDEBAR_TOGGLE: null });\n * ```\n */\nexport function configureShortcuts(\n  overrides: Partial<Record<ShortcutName, Partial<KeyboardShortcut> | null>>\n): void {\n  for (const [name, value] of Object.entries(overrides) as [ShortcutName, Partial<KeyboardShortcut> | null][]) {\n    if (!(name in KEYBOARD_SHORTCUTS)) continue;\n    if (value === undefined) continue;\n    shortcutOverrides.set(name, value);\n  }\n}\n\n/**\n * Resolve a shortcut by name, applying any overrides.\n * Returns `null` if the shortcut has been disabled via `configureShortcuts({ name: null })`.\n */\nexport function getResolvedShortcut(name: ShortcutName): KeyboardShortcut | null {\n  const override = shortcutOverrides.get(name);\n\n  // Explicitly disabled\n  if (override === null) return null;\n\n  const defaultShortcut = KEYBOARD_SHORTCUTS[name] as KeyboardShortcut;\n\n  // No override — return default\n  if (override === undefined) return defaultShortcut;\n\n  // Merge override into default\n  return { ...defaultShortcut, ...override };\n}\n\n/**\n * Clear all shortcut overrides. Primarily useful for tests.\n */\nexport function resetShortcutOverrides(): void {\n  shortcutOverrides.clear();\n}\n\n// ============================================\n// useKeyboardShortcut Hook\n// ============================================\n\nexport interface UseKeyboardShortcutOptions {\n  /** Shortcut name from KEYBOARD_SHORTCUTS */\n  name: ShortcutName;\n  /** Handler called when the shortcut fires */\n  handler: () => void;\n  /** Whether the shortcut is active (default: true) */\n  enabled?: boolean;\n  /**\n   * Override the shortcut's scope for this registration:\n   * - 'global': listens on `document`, skips editable elements\n   * - 'component': listens on `ref` element only\n   * If omitted, uses the scope from the shortcut definition.\n   */\n  scope?: 'global' | 'component';\n  /** Required when scope is 'component' — the element to attach the listener to */\n  ref?: RefObject<Element | null>;\n}\n\n/**\n * Register a keyboard shortcut handler with automatic scope and editable-area handling.\n *\n * For global shortcuts, automatically skips when focus is in an editable element\n * (input, textarea, contenteditable, role=\"textbox\") so component-scoped shortcuts\n * like Editor's Ctrl+B take precedence over Sidebar's Ctrl+B.\n *\n * Respects `configureShortcuts()` overrides — if a shortcut is remapped or disabled,\n * the hook automatically adapts.\n *\n * @example\n * ```tsx\n * useKeyboardShortcut({\n *   name: 'SIDEBAR_TOGGLE',\n *   handler: toggleSidebar,\n *   enabled: enableKeyboardShortcut && collapsible !== 'none',\n * });\n * ```\n */\nexport function useKeyboardShortcut({\n  name,\n  handler,\n  enabled = true,\n  scope: scopeOverride,\n  ref,\n}: UseKeyboardShortcutOptions): void {\n  // Use a ref for handler to avoid re-subscribing on every render\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    if (!enabled) return;\n\n    const resolved = getResolvedShortcut(name);\n    if (!resolved) return; // disabled via configureShortcuts\n\n    const effectiveScope = scopeOverride ?? resolved.scope;\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      if (!matchesShortcut(e, resolved)) return;\n\n      // Global shortcuts skip editable elements\n      if (effectiveScope === 'global' && isEditableElement(e.target as Element)) return;\n\n      e.preventDefault();\n      handlerRef.current();\n    };\n\n    const target = effectiveScope === 'component' ? ref?.current : document;\n    if (!target) return;\n\n    target.addEventListener('keydown', handleKeyDown as EventListener);\n    return () => target.removeEventListener('keydown', handleKeyDown as EventListener);\n  }, [name, enabled, scopeOverride, ref]);\n}\n"],"names":["useRef","useEffect"],"mappings":"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"}

package/dist/utils/keyboard-shortcuts.d.ts

@@ -0,0 +1,293 @@
+import { type RefObject } from 'react';
+export interface KeyboardShortcut {
+    /** The key to match (e.g., 'b', 'k', 'Escape'). Case-insensitive. */
+    key: string;
+    /** Require Ctrl (Windows/Linux) or Cmd (macOS) */
+    meta?: boolean;
+    /** Require Shift */
+    shift?: boolean;
+    /** Require Alt/Option */
+    alt?: boolean;
+    /** Human-readable label for display (e.g., "Ctrl+B", "⌘B") */
+    label: string;
+    /** Which component owns this shortcut */
+    component: string;
+    /** What the shortcut does */
+    description: string;
+    /**
+     * Scope controls when the shortcut is active:
+     * - 'global': Listens on document (e.g., sidebar toggle)
+     * - 'component': Only active when component is focused/mounted
+     */
+    scope: 'global' | 'component';
+}
+export declare const KEYBOARD_SHORTCUTS: {
+    readonly SIDEBAR_TOGGLE: {
+        readonly key: "b";
+        readonly meta: true;
+        readonly label: "Ctrl+B";
+        readonly component: "Sidebar";
+        readonly description: "Toggle sidebar collapse/expand";
+        readonly scope: "global";
+    };
+    readonly SIDEBAR_CLOSE_MOBILE: {
+        readonly key: "Escape";
+        readonly label: "Escape";
+        readonly component: "Sidebar";
+        readonly description: "Close mobile sidebar drawer";
+        readonly scope: "global";
+    };
+    readonly EDITOR_BOLD: {
+        readonly key: "b";
+        readonly meta: true;
+        readonly label: "Ctrl+B";
+        readonly component: "Editor";
+        readonly description: "Toggle bold formatting";
+        readonly scope: "component";
+    };
+    readonly EDITOR_ITALIC: {
+        readonly key: "i";
+        readonly meta: true;
+        readonly label: "Ctrl+I";
+        readonly component: "Editor";
+        readonly description: "Toggle italic formatting";
+        readonly scope: "component";
+    };
+    readonly EDITOR_STRIKETHROUGH: {
+        readonly key: "s";
+        readonly meta: true;
+        readonly shift: true;
+        readonly label: "Ctrl+Shift+S";
+        readonly component: "Editor";
+        readonly description: "Toggle strikethrough formatting";
+        readonly scope: "component";
+    };
+    readonly EDITOR_LINK: {
+        readonly key: "k";
+        readonly meta: true;
+        readonly label: "Ctrl+K";
+        readonly component: "Editor";
+        readonly description: "Insert or edit link";
+        readonly scope: "component";
+    };
+    readonly EDITOR_CODE: {
+        readonly key: "e";
+        readonly meta: true;
+        readonly label: "Ctrl+E";
+        readonly component: "Editor";
+        readonly description: "Toggle inline code";
+        readonly scope: "component";
+    };
+    readonly EDITOR_BULLET_LIST: {
+        readonly key: "8";
+        readonly meta: true;
+        readonly shift: true;
+        readonly label: "Ctrl+Shift+8";
+        readonly component: "Editor";
+        readonly description: "Toggle bullet list";
+        readonly scope: "component";
+    };
+    readonly EDITOR_ORDERED_LIST: {
+        readonly key: "7";
+        readonly meta: true;
+        readonly shift: true;
+        readonly label: "Ctrl+Shift+7";
+        readonly component: "Editor";
+        readonly description: "Toggle ordered list";
+        readonly scope: "component";
+    };
+    readonly EDITOR_HEADING1: {
+        readonly key: "1";
+        readonly meta: true;
+        readonly alt: true;
+        readonly label: "Ctrl+Alt+1";
+        readonly component: "Editor";
+        readonly description: "Toggle heading level 1";
+        readonly scope: "component";
+    };
+    readonly EDITOR_HEADING2: {
+        readonly key: "2";
+        readonly meta: true;
+        readonly alt: true;
+        readonly label: "Ctrl+Alt+2";
+        readonly component: "Editor";
+        readonly description: "Toggle heading level 2";
+        readonly scope: "component";
+    };
+    readonly EDITOR_HEADING3: {
+        readonly key: "3";
+        readonly meta: true;
+        readonly alt: true;
+        readonly label: "Ctrl+Alt+3";
+        readonly component: "Editor";
+        readonly description: "Toggle heading level 3";
+        readonly scope: "component";
+    };
+    readonly EDITOR_BLOCKQUOTE: {
+        readonly key: "b";
+        readonly meta: true;
+        readonly shift: true;
+        readonly label: "Ctrl+Shift+B";
+        readonly component: "Editor";
+        readonly description: "Toggle blockquote";
+        readonly scope: "component";
+    };
+    readonly EDITOR_UNDO: {
+        readonly key: "z";
+        readonly meta: true;
+        readonly label: "Ctrl+Z";
+        readonly component: "Editor";
+        readonly description: "Undo last action";
+        readonly scope: "component";
+    };
+    readonly EDITOR_REDO: {
+        readonly key: "z";
+        readonly meta: true;
+        readonly shift: true;
+        readonly label: "Ctrl+Shift+Z";
+        readonly component: "Editor";
+        readonly description: "Redo last undone action";
+        readonly scope: "component";
+    };
+    readonly PROMPT_SUBMIT: {
+        readonly key: "Enter";
+        readonly label: "Enter";
+        readonly component: "Prompt";
+        readonly description: "Submit prompt (when submitOnEnter is true)";
+        readonly scope: "component";
+    };
+    readonly NAV_TOGGLE: {
+        readonly key: "Enter";
+        readonly label: "Enter";
+        readonly component: "NavigationMenu";
+        readonly description: "Toggle menu item open/closed";
+        readonly scope: "component";
+    };
+    readonly NAV_CLOSE: {
+        readonly key: "Escape";
+        readonly label: "Escape";
+        readonly component: "NavigationMenu";
+        readonly description: "Close menu and return focus to trigger";
+        readonly scope: "component";
+    };
+    readonly COMMAND_SELECT: {
+        readonly key: "Enter";
+        readonly label: "Enter";
+        readonly component: "Command";
+        readonly description: "Select active command item";
+        readonly scope: "component";
+    };
+    readonly COLLAPSIBLE_TOGGLE: {
+        readonly key: "Enter";
+        readonly label: "Enter";
+        readonly component: "Collapsible";
+        readonly description: "Toggle collapsible open/closed";
+        readonly scope: "component";
+    };
+};
+export type ShortcutName = keyof typeof KEYBOARD_SHORTCUTS;
+/**
+ * Check if a KeyboardEvent matches a shortcut definition.
+ *
+ * Usage:
+ * ```ts
+ * import { KEYBOARD_SHORTCUTS, matchesShortcut } from '../../utils/keyboard-shortcuts';
+ *
+ * const handleKeyDown = (e: KeyboardEvent) => {
+ *   if (matchesShortcut(e, KEYBOARD_SHORTCUTS.SIDEBAR_TOGGLE)) {
+ *     e.preventDefault();
+ *     toggleSidebar();
+ *   }
+ * };
+ * ```
+ */
+export declare function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcut): boolean;
+/**
+ * Get a human-readable shortcut label, adapting for macOS vs other platforms.
+ * Returns "⌘B" on Mac, "Ctrl+B" elsewhere.
+ */
+export declare function getShortcutLabel(shortcut: KeyboardShortcut): string;
+/**
+ * Find all shortcuts that conflict with a given shortcut (same key combo, different component).
+ * Useful for debugging and documentation.
+ */
+export declare function findConflicts(name: ShortcutName): KeyboardShortcut[];
+/**
+ * Get all registered shortcuts, optionally filtered by component or scope.
+ */
+export declare function getShortcuts(filter?: {
+    component?: string;
+    scope?: 'global' | 'component';
+}): KeyboardShortcut[];
+/**
+ * Check if an element is an editable area (input, textarea, contenteditable, role="textbox").
+ * Global shortcuts should skip firing when the user is typing in one of these.
+ */
+export declare function isEditableElement(element: Element | null): boolean;
+/**
+ * Configure shortcut overrides at app startup. Mirrors the `configureTheme()` API.
+ *
+ * - Partial overrides merge with the default (e.g., `{ key: '\\' }` keeps label/component/etc.)
+ * - `null` disables a shortcut entirely
+ * - Omitted keys are left unchanged
+ * - Multiple calls merge additively (last write wins per key)
+ *
+ * @example
+ * ```ts
+ * import { configureShortcuts } from '@fragments-sdk/ui';
+ *
+ * // Remap sidebar toggle to Ctrl+\
+ * configureShortcuts({ SIDEBAR_TOGGLE: { key: '\\', label: 'Ctrl+\\' } });
+ *
+ * // Disable sidebar toggle entirely
+ * configureShortcuts({ SIDEBAR_TOGGLE: null });
+ * ```
+ */
+export declare function configureShortcuts(overrides: Partial<Record<ShortcutName, Partial<KeyboardShortcut> | null>>): void;
+/**
+ * Resolve a shortcut by name, applying any overrides.
+ * Returns `null` if the shortcut has been disabled via `configureShortcuts({ name: null })`.
+ */
+export declare function getResolvedShortcut(name: ShortcutName): KeyboardShortcut | null;
+/**
+ * Clear all shortcut overrides. Primarily useful for tests.
+ */
+export declare function resetShortcutOverrides(): void;
+export interface UseKeyboardShortcutOptions {
+    /** Shortcut name from KEYBOARD_SHORTCUTS */
+    name: ShortcutName;
+    /** Handler called when the shortcut fires */
+    handler: () => void;
+    /** Whether the shortcut is active (default: true) */
+    enabled?: boolean;
+    /**
+     * Override the shortcut's scope for this registration:
+     * - 'global': listens on `document`, skips editable elements
+     * - 'component': listens on `ref` element only
+     * If omitted, uses the scope from the shortcut definition.
+     */
+    scope?: 'global' | 'component';
+    /** Required when scope is 'component' — the element to attach the listener to */
+    ref?: RefObject<Element | null>;
+}
+/**
+ * Register a keyboard shortcut handler with automatic scope and editable-area handling.
+ *
+ * For global shortcuts, automatically skips when focus is in an editable element
+ * (input, textarea, contenteditable, role="textbox") so component-scoped shortcuts
+ * like Editor's Ctrl+B take precedence over Sidebar's Ctrl+B.
+ *
+ * Respects `configureShortcuts()` overrides — if a shortcut is remapped or disabled,
+ * the hook automatically adapts.
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcut({
+ *   name: 'SIDEBAR_TOGGLE',
+ *   handler: toggleSidebar,
+ *   enabled: enableKeyboardShortcut && collapsible !== 'none',
+ * });
+ * ```
+ */
+export declare function useKeyboardShortcut({ name, handler, enabled, scope: scopeOverride, ref, }: UseKeyboardShortcutOptions): void;
+//# sourceMappingURL=keyboard-shortcuts.d.ts.map

package/dist/utils/keyboard-shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard-shortcuts.d.ts","sourceRoot":"","sources":["../../src/utils/keyboard-shortcuts.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM1D,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yBAAyB;IACzB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,QAAQ,GAAG,WAAW,CAAC;CAC/B;AAMD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8KsB,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAM3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAWzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAYnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB,EAAE,CAapE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;CAAE,GAAG,gBAAgB,EAAE,CAMhH;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAmClE;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAC,GACzE,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB,GAAG,IAAI,CAa/E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAMD,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,IAAI,EAAE,YAAY,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC/B,iFAAiF;IACjF,GAAG,CAAC,EAAE,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,OAAO,EACP,OAAc,EACd,KAAK,EAAE,aAAa,EACpB,GAAG,GACJ,EAAE,0BAA0B,GAAG,IAAI,CA6BnC"}

package/dist/utils/keyboard-shortcuts.js

@@ -0,0 +1,295 @@
+import { useRef, useEffect } from "react";
+const KEYBOARD_SHORTCUTS = {
+  // ----- Sidebar -----
+  SIDEBAR_TOGGLE: {
+    key: "b",
+    meta: true,
+    label: "Ctrl+B",
+    component: "Sidebar",
+    description: "Toggle sidebar collapse/expand",
+    scope: "global"
+  },
+  SIDEBAR_CLOSE_MOBILE: {
+    key: "Escape",
+    label: "Escape",
+    component: "Sidebar",
+    description: "Close mobile sidebar drawer",
+    scope: "global"
+  },
+  // ----- Editor (TipTap handles these natively, metadata for display) -----
+  EDITOR_BOLD: {
+    key: "b",
+    meta: true,
+    label: "Ctrl+B",
+    component: "Editor",
+    description: "Toggle bold formatting",
+    scope: "component"
+  },
+  EDITOR_ITALIC: {
+    key: "i",
+    meta: true,
+    label: "Ctrl+I",
+    component: "Editor",
+    description: "Toggle italic formatting",
+    scope: "component"
+  },
+  EDITOR_STRIKETHROUGH: {
+    key: "s",
+    meta: true,
+    shift: true,
+    label: "Ctrl+Shift+S",
+    component: "Editor",
+    description: "Toggle strikethrough formatting",
+    scope: "component"
+  },
+  EDITOR_LINK: {
+    key: "k",
+    meta: true,
+    label: "Ctrl+K",
+    component: "Editor",
+    description: "Insert or edit link",
+    scope: "component"
+  },
+  EDITOR_CODE: {
+    key: "e",
+    meta: true,
+    label: "Ctrl+E",
+    component: "Editor",
+    description: "Toggle inline code",
+    scope: "component"
+  },
+  EDITOR_BULLET_LIST: {
+    key: "8",
+    meta: true,
+    shift: true,
+    label: "Ctrl+Shift+8",
+    component: "Editor",
+    description: "Toggle bullet list",
+    scope: "component"
+  },
+  EDITOR_ORDERED_LIST: {
+    key: "7",
+    meta: true,
+    shift: true,
+    label: "Ctrl+Shift+7",
+    component: "Editor",
+    description: "Toggle ordered list",
+    scope: "component"
+  },
+  EDITOR_HEADING1: {
+    key: "1",
+    meta: true,
+    alt: true,
+    label: "Ctrl+Alt+1",
+    component: "Editor",
+    description: "Toggle heading level 1",
+    scope: "component"
+  },
+  EDITOR_HEADING2: {
+    key: "2",
+    meta: true,
+    alt: true,
+    label: "Ctrl+Alt+2",
+    component: "Editor",
+    description: "Toggle heading level 2",
+    scope: "component"
+  },
+  EDITOR_HEADING3: {
+    key: "3",
+    meta: true,
+    alt: true,
+    label: "Ctrl+Alt+3",
+    component: "Editor",
+    description: "Toggle heading level 3",
+    scope: "component"
+  },
+  EDITOR_BLOCKQUOTE: {
+    key: "b",
+    meta: true,
+    shift: true,
+    label: "Ctrl+Shift+B",
+    component: "Editor",
+    description: "Toggle blockquote",
+    scope: "component"
+  },
+  EDITOR_UNDO: {
+    key: "z",
+    meta: true,
+    label: "Ctrl+Z",
+    component: "Editor",
+    description: "Undo last action",
+    scope: "component"
+  },
+  EDITOR_REDO: {
+    key: "z",
+    meta: true,
+    shift: true,
+    label: "Ctrl+Shift+Z",
+    component: "Editor",
+    description: "Redo last undone action",
+    scope: "component"
+  },
+  // ----- Prompt -----
+  PROMPT_SUBMIT: {
+    key: "Enter",
+    label: "Enter",
+    component: "Prompt",
+    description: "Submit prompt (when submitOnEnter is true)",
+    scope: "component"
+  },
+  // ----- NavigationMenu -----
+  NAV_TOGGLE: {
+    key: "Enter",
+    label: "Enter",
+    component: "NavigationMenu",
+    description: "Toggle menu item open/closed",
+    scope: "component"
+  },
+  NAV_CLOSE: {
+    key: "Escape",
+    label: "Escape",
+    component: "NavigationMenu",
+    description: "Close menu and return focus to trigger",
+    scope: "component"
+  },
+  // ----- Command -----
+  COMMAND_SELECT: {
+    key: "Enter",
+    label: "Enter",
+    component: "Command",
+    description: "Select active command item",
+    scope: "component"
+  },
+  // ----- Collapsible -----
+  COLLAPSIBLE_TOGGLE: {
+    key: "Enter",
+    label: "Enter",
+    component: "Collapsible",
+    description: "Toggle collapsible open/closed",
+    scope: "component"
+  }
+};
+function matchesShortcut(event, shortcut) {
+  if (shortcut.meta && !(event.metaKey || event.ctrlKey)) return false;
+  if (shortcut.shift && !event.shiftKey) return false;
+  if (shortcut.alt && !event.altKey) return false;
+  if (!shortcut.meta && (event.metaKey || event.ctrlKey)) return false;
+  if (!shortcut.shift && event.shiftKey) return false;
+  if (!shortcut.alt && event.altKey) return false;
+  return event.key.toLowerCase() === shortcut.key.toLowerCase();
+}
+function getShortcutLabel(shortcut) {
+  var _a, _b;
+  if (typeof navigator === "undefined") return shortcut.label;
+  const isMac = ((_a = navigator.platform) == null ? void 0 : _a.includes("Mac")) || ((_b = navigator.userAgent) == null ? void 0 : _b.includes("Mac"));
+  if (!isMac) return shortcut.label;
+  const parts = [];
+  if (shortcut.meta) parts.push("⌘");
+  if (shortcut.shift) parts.push("⇧");
+  if (shortcut.alt) parts.push("⌥");
+  parts.push(shortcut.key.toUpperCase());
+  return parts.join("");
+}
+function findConflicts(name) {
+  const target = KEYBOARD_SHORTCUTS[name];
+  return Object.entries(KEYBOARD_SHORTCUTS).filter(([key, shortcut]) => {
+    if (key === name) return false;
+    return shortcut.key.toLowerCase() === target.key.toLowerCase() && !!shortcut.meta === !!target.meta && !!shortcut.shift === !!target.shift && !!shortcut.alt === !!target.alt;
+  }).map(([, shortcut]) => shortcut);
+}
+function getShortcuts(filter) {
+  return Object.values(KEYBOARD_SHORTCUTS).filter((shortcut) => {
+    if ((filter == null ? void 0 : filter.component) && shortcut.component !== filter.component) return false;
+    if ((filter == null ? void 0 : filter.scope) && shortcut.scope !== filter.scope) return false;
+    return true;
+  });
+}
+const TEXT_INPUT_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "search",
+  "url",
+  "tel",
+  "email",
+  "password",
+  "number"
+]);
+function isEditableElement(element) {
+  var _a;
+  if (!element || !("tagName" in element)) return false;
+  const tag = element.tagName;
+  if (tag === "TEXTAREA") return true;
+  if (tag === "INPUT") {
+    const type = ((_a = element.type) == null ? void 0 : _a.toLowerCase()) || "text";
+    return TEXT_INPUT_TYPES.has(type);
+  }
+  const htmlEl = element;
+  if (htmlEl.isContentEditable) return true;
+  const ceAttr = htmlEl.contentEditable;
+  if (ceAttr === "true" || ceAttr === "") return true;
+  if (typeof element.getAttribute === "function" && element.getAttribute("role") === "textbox") return true;
+  let ancestor = element.parentElement;
+  while (ancestor) {
+    if (ancestor.isContentEditable) return true;
+    const ancestorCe = ancestor.contentEditable;
+    if (ancestorCe === "true" || ancestorCe === "") return true;
+    ancestor = ancestor.parentElement;
+  }
+  return false;
+}
+const shortcutOverrides = /* @__PURE__ */ new Map();
+function configureShortcuts(overrides) {
+  for (const [name, value] of Object.entries(overrides)) {
+    if (!(name in KEYBOARD_SHORTCUTS)) continue;
+    if (value === void 0) continue;
+    shortcutOverrides.set(name, value);
+  }
+}
+function getResolvedShortcut(name) {
+  const override = shortcutOverrides.get(name);
+  if (override === null) return null;
+  const defaultShortcut = KEYBOARD_SHORTCUTS[name];
+  if (override === void 0) return defaultShortcut;
+  return { ...defaultShortcut, ...override };
+}
+function resetShortcutOverrides() {
+  shortcutOverrides.clear();
+}
+function useKeyboardShortcut({
+  name,
+  handler,
+  enabled = true,
+  scope: scopeOverride,
+  ref
+}) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  useEffect(() => {
+    if (!enabled) return;
+    const resolved = getResolvedShortcut(name);
+    if (!resolved) return;
+    const effectiveScope = scopeOverride ?? resolved.scope;
+    const handleKeyDown = (e) => {
+      if (!matchesShortcut(e, resolved)) return;
+      if (effectiveScope === "global" && isEditableElement(e.target)) return;
+      e.preventDefault();
+      handlerRef.current();
+    };
+    const target = effectiveScope === "component" ? ref == null ? void 0 : ref.current : document;
+    if (!target) return;
+    target.addEventListener("keydown", handleKeyDown);
+    return () => target.removeEventListener("keydown", handleKeyDown);
+  }, [name, enabled, scopeOverride, ref]);
+}
+export {
+  KEYBOARD_SHORTCUTS,
+  configureShortcuts,
+  findConflicts,
+  getResolvedShortcut,
+  getShortcutLabel,
+  getShortcuts,
+  isEditableElement,
+  matchesShortcut,
+  resetShortcutOverrides,
+  useKeyboardShortcut
+};
+//# sourceMappingURL=keyboard-shortcuts.js.map