@trackunit/react-components 1.15.21 → 1.15.22

package/index.cjs.js

@@ -7573,6 +7573,406 @@ const useIsFullscreen = () => {
     return isFullScreen;
 };
 
+/**
+ * Detects the current platform based on the user agent.
+ *
+ * @returns {Platform} The detected platform: "mac", "windows", or "linux"
+ */
+const getPlatform = () => {
+    if (typeof navigator === "undefined") {
+        // SSR default - most users are on Windows
+        return "windows";
+    }
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes("mac")) {
+        return "mac";
+    }
+    if (ua.includes("linux")) {
+        return "linux";
+    }
+    return "windows";
+};
+
+/** Display order for modifiers: mod first, then alt, then shift */
+const MODIFIER_DISPLAY_ORDER = ["mod", "alt", "shift"];
+/** Labels for each modifier, mapped per platform */
+const MODIFIER_LABELS = {
+    mod: { mac: "Cmd", other: "Ctrl" },
+    alt: { mac: "Option", other: "Alt" },
+    shift: { mac: "Shift", other: "Shift" },
+};
+/**
+ * Maps a semantic modifier to a display label based on the current platform.
+ */
+const getModifierLabel = (mod) => {
+    const labels = MODIFIER_LABELS[mod];
+    return getPlatform() === "mac" ? labels.mac : labels.other;
+};
+/**
+ * Maps a key to a more readable display label.
+ */
+const getKeyLabel = (key) => {
+    const keyLabels = {
+        arrowup: "↑",
+        arrowdown: "↓",
+        arrowleft: "←",
+        arrowright: "→",
+        enter: "Enter",
+        escape: "Esc",
+        tab: "Tab",
+        space: "Space",
+        backspace: "Backspace",
+        delete: "Delete",
+    };
+    const lowerKey = key.toLowerCase();
+    return keyLabels[lowerKey] ?? key.toUpperCase();
+};
+/**
+ * Formats a shortcut definition into a human-readable label.
+ *
+ * The label is platform-aware:
+ * - Mac: "Cmd + K", "Option + Shift + L"
+ * - Windows/Linux: "Ctrl + K", "Alt + Shift + L"
+ *
+ * @param shortcut - The shortcut definition to format
+ * @param separator - The separator between parts (default: " + ")
+ * @returns {string} A formatted string like "Cmd + K" or "Ctrl + Shift + L"
+ * @example
+ * formatShortcutLabel({ key: "k", modifiers: "mod" })
+ * // Mac: "Cmd + K"
+ * // Windows: "Ctrl + K"
+ * @example
+ * formatShortcutLabel({ key: "l", modifiers: "mod+shift" })
+ * // Mac: "Cmd + Shift + L"
+ * // Windows: "Ctrl + Shift + L"
+ * @example
+ * formatShortcutLabel({ key: "Escape" })
+ * // "Esc"
+ */
+const formatShortcutLabel = (shortcut, separator = " + ") => {
+    // Parse modifier string and sort in display order (mod, alt, shift)
+    const modifierSet = new Set(shortcut.modifiers?.split("+") ?? []);
+    const sortedModifiers = MODIFIER_DISPLAY_ORDER.filter(mod => modifierSet.has(mod));
+    const modLabels = sortedModifiers.map(getModifierLabel);
+    const keyLabel = getKeyLabel(shortcut.key);
+    return [...modLabels, keyLabel].join(separator);
+};
+
+/**
+ * Parses a modifier string into a Set for easy lookup.
+ *
+ * @param modifiers - The modifier string (e.g., "mod+shift")
+ * @returns {Set<string>} A Set containing the individual modifiers
+ */
+const parseModifiers = (modifiers) => {
+    if (!modifiers) {
+        return new Set();
+    }
+    return new Set(modifiers.split("+"));
+};
+/**
+ * Checks if a keyboard event matches the shortcut definition.
+ *
+ * This is a pure function that handles:
+ * - Case-insensitive key matching
+ * - Platform-aware modifier key checking (Cmd on Mac, Ctrl on Windows/Linux)
+ * - Space key normalization
+ * - Extra modifier rejection (ensures only expected modifiers are pressed)
+ *
+ * @param event - The keyboard event to check
+ * @param shortcut - The shortcut definition to match against
+ * @returns {boolean} true if the event matches the shortcut, false otherwise
+ * @example
+ * // Check if Cmd+K (Mac) or Ctrl+K (Windows) was pressed
+ * const isMatch = matchesShortcut(event, { key: "k", modifiers: "mod" });
+ */
+const matchesShortcut = (event, shortcut) => {
+    // Check the primary key (case-insensitive)
+    const eventKey = event.key.toLowerCase();
+    const shortcutKey = shortcut.key.toLowerCase();
+    // Handle special keys that might have different representations
+    // Normalize both to the same representation for comparison
+    const normalizedEventKey = eventKey === " " ? "space" : eventKey;
+    const normalizedShortcutKey = shortcutKey === " " ? "space" : shortcutKey;
+    if (normalizedEventKey !== normalizedShortcutKey) {
+        return false;
+    }
+    const modifiers = parseModifiers(shortcut.modifiers);
+    // Check "mod" modifier (Cmd on Mac, Ctrl on Windows/Linux)
+    const expectMod = modifiers.has("mod");
+    const hasMod = getPlatform() === "mac" ? event.metaKey : event.ctrlKey;
+    if (expectMod !== hasMod) {
+        return false;
+    }
+    // Check "alt" modifier (Option on Mac, Alt on Windows/Linux)
+    const expectAlt = modifiers.has("alt");
+    if (expectAlt !== event.altKey) {
+        return false;
+    }
+    // Check "shift" modifier
+    const expectShift = modifiers.has("shift");
+    if (expectShift !== event.shiftKey) {
+        return false;
+    }
+    // Make sure no extra modifiers are pressed
+    // If mod is expected, we've already checked the right key (meta or ctrl)
+    // But we need to ensure the OTHER mod key isn't also pressed
+    if (!expectMod) {
+        // If we don't expect mod, neither metaKey nor ctrlKey should be pressed
+        if (event.metaKey || event.ctrlKey) {
+            return false;
+        }
+    }
+    else {
+        // If we expect mod, the opposite mod key shouldn't be pressed
+        const oppositeModPressed = getPlatform() === "mac" ? event.ctrlKey : event.metaKey;
+        if (oppositeModPressed) {
+            return false;
+        }
+    }
+    return true;
+};
+
+/**
+ * Reserved application shortcuts.
+ * These are host-level shortcuts that are blocked at the type level.
+ * See reservedShortcutTypes.ts for the type-level enforcement.
+ *
+ * IMPORTANT: When adding a new reserved shortcut here, you must also
+ * update the type definitions in reservedShortcutTypes.ts and the
+ * isGlobalShortcut() function in apps/iris-app-loader/src/forward-events-to-host.ts.
+ */
+const RESERVED_SHORTCUTS = {
+    "mod+k": {
+        name: "Global Search",
+        owner: "host-navigation",
+    },
+    "mod+shift+l": {
+        name: "Local Dev Mode Toggle",
+        owner: "host-navigation",
+    },
+};
+/**
+ * Common browser shortcuts that cannot be reliably overridden.
+ * Using these shortcuts will trigger a development warning since
+ * the browser typically intercepts them before JavaScript can handle them.
+ *
+ * Note: Some of these can be overridden with preventDefault(), but it's
+ * generally a bad UX to override expected browser behavior.
+ */
+const BROWSER_SHORTCUTS = {
+    // Tab management
+    "mod+t": "New tab",
+    "mod+w": "Close tab",
+    "mod+shift+t": "Reopen closed tab",
+    "mod+n": "New window",
+    "mod+shift+n": "New incognito window",
+    // Navigation
+    "mod+l": "Focus address bar",
+    "mod+r": "Reload page",
+    "mod+shift+r": "Hard reload",
+    // Page actions
+    "mod+s": "Save page",
+    "mod+p": "Print",
+    "mod+f": "Find in page",
+    "mod+g": "Find next",
+    "mod+shift+g": "Find previous",
+    "mod+o": "Open file",
+    // Browser features
+    "mod+h": "History (Chrome) / Hide window (Mac)",
+    "mod+j": "Downloads",
+    "mod+d": "Bookmark page",
+    "mod+shift+b": "Toggle bookmarks bar",
+    // Developer tools
+    "mod+shift+i": "Developer tools",
+    "mod+shift+j": "JavaScript console",
+    "mod+shift+c": "Inspect element",
+    // Function keys
+    f1: "Help",
+    f3: "Find next",
+    f5: "Reload",
+    f11: "Fullscreen",
+    f12: "Developer tools",
+    // Zoom
+    "mod+0": "Reset zoom",
+    "mod+-": "Zoom out",
+    "mod+=": "Zoom in",
+};
+
+/**
+ * Converts a ShortcutDefinition to a normalized string key for lookup.
+ * Format: "mod+shift+k" (modifiers sorted alphabetically, then key)
+ */
+const shortcutToString = (shortcut) => {
+    if (!shortcut.modifiers) {
+        return shortcut.key.toLowerCase();
+    }
+    // Modifiers are already in alphabetical order (enforced by type)
+    return `${shortcut.modifiers}+${shortcut.key.toLowerCase()}`;
+};
+
+/**
+ * Hook for checking keyboard shortcut conflicts.
+ *
+ * This hook checks if a shortcut conflicts with:
+ * - Reserved application shortcuts (host-level features)
+ * - Browser shortcuts (that cannot be reliably overridden)
+ *
+ * In development mode, it logs a warning if the shortcut conflicts with
+ * browser shortcuts. Reserved shortcuts are blocked at the type level.
+ *
+ * @param shortcut - The shortcut definition to check
+ * @param options - Optional configuration
+ * @returns {ShortcutConflictInfo} Conflict information for the shortcut
+ * @example
+ * const conflicts = useShortcutConflicts({ key: "k", modifiers: "mod" });
+ * if (conflicts.isReserved) {
+ *   console.log(`Reserved by: ${conflicts.reservedInfo?.owner}`);
+ * }
+ */
+const useShortcutConflicts = (shortcut, options) => {
+    const disabled = options?.disabled ?? false;
+    const conflictInfo = react.useMemo(() => {
+        if (disabled) {
+            return {
+                isReserved: false,
+                reservedInfo: undefined,
+                browserConflict: undefined,
+            };
+        }
+        const key = shortcutToString(shortcut);
+        const reservedInfo = RESERVED_SHORTCUTS[key];
+        const browserConflict = BROWSER_SHORTCUTS[key];
+        return {
+            isReserved: reservedInfo !== undefined,
+            reservedInfo,
+            browserConflict,
+        };
+    }, [shortcut, disabled]);
+    // Log development warning for browser conflicts
+    react.useEffect(() => {
+        if (disabled || process.env.NODE_ENV === "production") {
+            return;
+        }
+        if (conflictInfo.browserConflict) {
+            const shortcutStr = shortcutToString(shortcut);
+            // eslint-disable-next-line no-console -- Development warning for browser shortcut conflicts
+            console.warn(`[useKeyboardShortcut] Shortcut "${shortcutStr}" conflicts with browser shortcut: "${conflictInfo.browserConflict}". ` +
+                `This shortcut may not work reliably as the browser may intercept it.`);
+        }
+        // Only run on mount
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return conflictInfo;
+};
+
+/** Time window in ms for the browser fallback escape hatch. */
+const REPEAT_WINDOW_MS = 400;
+/**
+ * Hook for handling keyboard shortcuts with platform-aware modifiers.
+ *
+ * Reserved shortcuts are blocked at the type level and will show specific error messages.
+ * There are two categories:
+ *
+ * **App-reserved** (host-level features):
+ * - mod+k: Global Search
+ * - mod+shift+l: Local Dev Mode Toggle
+ *
+ * **Browser-reserved** (native browser shortcuts):
+ * - Clipboard: mod+c (Copy), mod+v (Paste), mod+x (Cut), mod+a (Select All)
+ * - Undo/Redo: mod+z (Undo), mod+shift+z (Redo Mac), mod+y (Redo Win/Linux)
+ * - Find: mod+f (Find), mod+g (Find next), mod+shift+g (Find previous)
+ * - Navigation: mod+r (Reload), mod+shift+r (Hard reload), mod+t (New tab),
+ *   mod+w (Close tab), mod+shift+t (Reopen tab), mod+n (New window),
+ *   mod+shift+n (Incognito), mod+l (Address bar), mod+d (Bookmark)
+ * - Zoom: mod+= (Zoom in), mod+- (Zoom out), mod+0 (Reset zoom)
+ * - Other: mod+p (Print), mod+s (Save), mod+o (Open), mod+h (History/Hide),
+ *   mod+j (Downloads), mod+q (Quit Mac)
+ *
+ * See reservedShortcutTypes.ts for the full list with error messages.
+ *
+ * @param shortcut - The shortcut definition with key and optional modifiers
+ * @param options - Configuration options for the shortcut handler
+ * @param options.onTrigger - Callback invoked when the shortcut is triggered
+ * @param options.disabled - Disable the shortcut conditionally (default: false)
+ * @param options.preventDefault - Controls browser default behavior:
+ *   - `"never"` (default) - Browser handles the event normally
+ *   - `"once"` - Prevent default, but rapid repeat (within 400ms) passes to browser
+ *   - `"always"` - Always prevent default, no browser escape hatch
+ * @param options.target - Target element for the listener (default: "window")
+ * @returns {{ label: string }} Object containing the formatted shortcut label (e.g., "Cmd + K" on Mac)
+ * @example
+ * // Simple Escape key handler (no preventDefault)
+ * const { label } = useKeyboardShortcut(
+ *   { key: "Escape" },
+ *   { onTrigger: () => closeModal() }
+ * );
+ * // label = "Esc"
+ * @example
+ * // Always prevent default, allow rapid re-triggering
+ * const { label } = useKeyboardShortcut(
+ *   { key: "m", modifiers: "mod" },
+ *   {
+ *     onTrigger: () => createNewItem(),
+ *     preventDefault: "always",
+ *   }
+ * );
+ * // label = "Cmd + M" (Mac) or "Ctrl + M" (Windows/Linux)
+ */
+const useKeyboardShortcut = (shortcut, { onTrigger, disabled = false, preventDefault = "never", target = "window" }) => {
+    // Use refs to avoid recreating the handler on every render
+    const onTriggerRef = react.useRef(onTrigger);
+    const preventDefaultRef = react.useRef(preventDefault);
+    // Track when the shortcut was last triggered for browser fallback
+    const lastTriggerRef = react.useRef(0);
+    // Keep refs up to date
+    react.useEffect(() => {
+        onTriggerRef.current = onTrigger;
+        preventDefaultRef.current = preventDefault;
+    }, [onTrigger, preventDefault]);
+    // Check for conflicts and warn in development (handled internally by the hook)
+    useShortcutConflicts(shortcut, { disabled });
+    const handleKeyDown = react.useCallback((event) => {
+        if (matchesShortcut(event, shortcut)) {
+            const now = Date.now();
+            const timeSinceLastTrigger = now - lastTriggerRef.current;
+            const mode = preventDefaultRef.current;
+            // Browser fallback: "once" mode skips handling if pressed within the repeat window
+            if (mode === "once" && timeSinceLastTrigger < REPEAT_WINDOW_MS) {
+                return;
+            }
+            if (mode !== "never") {
+                event.preventDefault();
+            }
+            lastTriggerRef.current = now;
+            onTriggerRef.current();
+        }
+    }, [shortcut]);
+    react.useEffect(() => {
+        if (disabled) {
+            return;
+        }
+        const targetElement = target === "window" ? window : target.current;
+        if (!targetElement) {
+            return;
+        }
+        // Use a wrapper that properly handles the event type for both Window and HTMLElement
+        const keydownHandler = (e) => {
+            if (e instanceof KeyboardEvent) {
+                handleKeyDown(e);
+            }
+        };
+        targetElement.addEventListener("keydown", keydownHandler);
+        return () => {
+            targetElement.removeEventListener("keydown", keydownHandler);
+        };
+    }, [disabled, target, handleKeyDown]);
+    // Compute the human-readable label for the shortcut
+    const label = react.useMemo(() => formatShortcutLabel(shortcut), [shortcut]);
+    // Memoize the return object for referential stability
+    return react.useMemo(() => ({ label }), [label]);
+};
+
 /**
  * Hook that returns true if any modifier key (Ctrl, Alt, Shift, Meta/Cmd) is pressed
  *
@@ -8084,6 +8484,7 @@ exports.useInfiniteScroll = useInfiniteScroll;
 exports.useIsFirstRender = useIsFirstRender;
 exports.useIsFullscreen = useIsFullscreen;
 exports.useIsTextTruncated = useIsTextTruncated;
+exports.useKeyboardShortcut = useKeyboardShortcut;
 exports.useList = useList;
 exports.useListItemHeight = useListItemHeight;
 exports.useLocalStorage = useLocalStorage;