@trackunit/react-components 1.15.21 → 1.15.22

package/index.esm.js

@@ -7571,6 +7571,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 = 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
+    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 = useRef(onTrigger);
+    const preventDefaultRef = useRef(preventDefault);
+    // Track when the shortcut was last triggered for browser fallback
+    const lastTriggerRef = useRef(0);
+    // Keep refs up to date
+    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 = 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]);
+    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 = useMemo(() => formatShortcutLabel(shortcut), [shortcut]);
+    // Memoize the return object for referential stability
+    return useMemo(() => ({ label }), [label]);
+};
+
 /**
  * Hook that returns true if any modifier key (Ctrl, Alt, Shift, Meta/Cmd) is pressed
  *
@@ -7939,4 +8339,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getResponsiveRandomWidthPercentage, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getResponsiveRandomWidthPercentage, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.15.21",
+  "version": "1.15.22",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/hooks/useKeyboardShortcut/formatShortcutLabel.d.ts

@@ -0,0 +1,24 @@
+import { ShortcutDefinition } from "./types";
+/**
+ * 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"
+ */
+export declare const formatShortcutLabel: (shortcut: ShortcutDefinition, separator?: string) => string;

package/src/hooks/useKeyboardShortcut/platformUtils.d.ts

@@ -0,0 +1,20 @@
+import { Platform } from "./types";
+/**
+ * Detects the current platform based on the user agent.
+ *
+ * @returns {Platform} The detected platform: "mac", "windows", or "linux"
+ */
+export declare const getPlatform: () => Platform;
+/**
+ * Checks if the primary modifier key is pressed based on platform.
+ * - Mac: metaKey (Cmd)
+ * - Windows/Linux: ctrlKey
+ */
+export declare const isModKeyPressed: (event: KeyboardEvent) => boolean;
+/**
+ * Checks if the opposite modifier key is pressed (the one NOT used for "mod").
+ * This helps detect when a user presses the wrong modifier for their platform.
+ * - Mac: ctrlKey (Ctrl pressed when Cmd expected)
+ * - Windows/Linux: metaKey (Win key pressed when Ctrl expected)
+ */
+export declare const isOppositeModKeyPressed: (event: KeyboardEvent) => boolean;

package/src/hooks/useKeyboardShortcut/reservedShortcutTypes.d.ts

@@ -0,0 +1,188 @@
+import { ShortcutDefinition } from "./types";
+/**
+ * Type-level utilities for preventing reserved shortcuts from being used.
+ *
+ * There are two categories of reserved shortcuts:
+ *
+ * 1. APP-RESERVED: Host-level shortcuts used by our application
+ *    - mod+k: Global search
+ *    - mod+shift+l: Local dev mode toggle
+ *
+ * 2. BROWSER-RESERVED: Native browser shortcuts that should not be overridden
+ *    - Clipboard: mod+c, mod+v, mod+x, mod+a
+ *    - Undo/Redo: mod+z, mod+shift+z, mod+y
+ *    - Find: mod+f, mod+g, mod+shift+g
+ *    - Navigation: mod+r, mod+shift+r, mod+t, mod+w, mod+shift+t, mod+n, mod+shift+n, mod+l, mod+d
+ *    - Zoom: mod+=, mod+-, mod+0
+ *    - Other: mod+p, mod+s, mod+o, mod+h, mod+j, mod+q
+ *
+ * The type system prevents their use. Legitimate uses (in host-navigation)
+ * must use ts-expect-error comments with an explanation.
+ */
+/** Template for reserved shortcut error messages */
+type ReservedMessage<TCategory extends string, TKeys extends string, TFeature extends string> = `${TCategory} reserved: ${TKeys} is used for ${TFeature}, which should not be overwritten`;
+/** App reserved: mod+k for Global Search */
+type AppReservedModK = {
+    readonly key: "k";
+    readonly modifiers: "mod";
+};
+/** App reserved: mod+shift+l for Local Dev Mode Toggle */
+type AppReservedModShiftL = {
+    readonly key: "l";
+    readonly modifiers: "mod+shift";
+};
+/** Union of all app-reserved shortcuts */
+type AppReservedShortcut = AppReservedModK | AppReservedModShiftL;
+/** Maps each app-reserved shortcut to its feature description */
+type AppShortcutFeature<TShortcut> = TShortcut extends AppReservedModK ? "Global Search" : TShortcut extends AppReservedModShiftL ? "Local Dev Mode Toggle" : never;
+/** Maps each app-reserved shortcut to its key string */
+type AppShortcutKeys<TShortcut> = TShortcut extends AppReservedModK ? "mod+k" : TShortcut extends AppReservedModShiftL ? "mod+shift+l" : never;
+/** Maps each app-reserved shortcut to its error message */
+type AppReservedErrorMessage<TShortcut> = ReservedMessage<"App", AppShortcutKeys<TShortcut>, AppShortcutFeature<TShortcut>>;
+type BrowserReservedModC = {
+    readonly key: "c";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModV = {
+    readonly key: "v";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModX = {
+    readonly key: "x";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModA = {
+    readonly key: "a";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModZ = {
+    readonly key: "z";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModShiftZ = {
+    readonly key: "z";
+    readonly modifiers: "mod+shift";
+};
+type BrowserReservedModY = {
+    readonly key: "y";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModF = {
+    readonly key: "f";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModG = {
+    readonly key: "g";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModShiftG = {
+    readonly key: "g";
+    readonly modifiers: "mod+shift";
+};
+type BrowserReservedModR = {
+    readonly key: "r";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModShiftR = {
+    readonly key: "r";
+    readonly modifiers: "mod+shift";
+};
+type BrowserReservedModT = {
+    readonly key: "t";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModW = {
+    readonly key: "w";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModShiftT = {
+    readonly key: "t";
+    readonly modifiers: "mod+shift";
+};
+type BrowserReservedModN = {
+    readonly key: "n";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModShiftN = {
+    readonly key: "n";
+    readonly modifiers: "mod+shift";
+};
+type BrowserReservedModL = {
+    readonly key: "l";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModD = {
+    readonly key: "d";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModEquals = {
+    readonly key: "=";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModMinus = {
+    readonly key: "-";
+    readonly modifiers: "mod";
+};
+type BrowserReservedMod0 = {
+    readonly key: "0";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModP = {
+    readonly key: "p";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModS = {
+    readonly key: "s";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModO = {
+    readonly key: "o";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModH = {
+    readonly key: "h";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModJ = {
+    readonly key: "j";
+    readonly modifiers: "mod";
+};
+type BrowserReservedModQ = {
+    readonly key: "q";
+    readonly modifiers: "mod";
+};
+/** Union of all browser-reserved shortcuts */
+type BrowserReservedShortcut = BrowserReservedModC | BrowserReservedModV | BrowserReservedModX | BrowserReservedModA | BrowserReservedModZ | BrowserReservedModShiftZ | BrowserReservedModY | BrowserReservedModF | BrowserReservedModG | BrowserReservedModShiftG | BrowserReservedModR | BrowserReservedModShiftR | BrowserReservedModT | BrowserReservedModW | BrowserReservedModShiftT | BrowserReservedModN | BrowserReservedModShiftN | BrowserReservedModL | BrowserReservedModD | BrowserReservedModEquals | BrowserReservedModMinus | BrowserReservedMod0 | BrowserReservedModP | BrowserReservedModS | BrowserReservedModO | BrowserReservedModH | BrowserReservedModJ | BrowserReservedModQ;
+/** Maps each browser-reserved shortcut to its feature description */
+type BrowserShortcutFeature<TShortcut> = TShortcut extends BrowserReservedModC ? "Copy" : TShortcut extends BrowserReservedModV ? "Paste" : TShortcut extends BrowserReservedModX ? "Cut" : TShortcut extends BrowserReservedModA ? "Select All" : TShortcut extends BrowserReservedModZ ? "Undo" : TShortcut extends BrowserReservedModShiftZ ? "Redo (Mac)" : TShortcut extends BrowserReservedModY ? "Redo (Windows/Linux)" : TShortcut extends BrowserReservedModF ? "Find on page" : TShortcut extends BrowserReservedModG ? "Find next" : TShortcut extends BrowserReservedModShiftG ? "Find previous" : TShortcut extends BrowserReservedModR ? "Reload page" : TShortcut extends BrowserReservedModShiftR ? "Hard reload" : TShortcut extends BrowserReservedModT ? "New tab" : TShortcut extends BrowserReservedModW ? "Close tab" : TShortcut extends BrowserReservedModShiftT ? "Reopen closed tab" : TShortcut extends BrowserReservedModN ? "New window" : TShortcut extends BrowserReservedModShiftN ? "New incognito/private window" : TShortcut extends BrowserReservedModL ? "Focus address bar" : TShortcut extends BrowserReservedModD ? "Bookmark page" : TShortcut extends BrowserReservedModEquals ? "Zoom in" : TShortcut extends BrowserReservedModMinus ? "Zoom out" : TShortcut extends BrowserReservedMod0 ? "Reset zoom" : TShortcut extends BrowserReservedModP ? "Print" : TShortcut extends BrowserReservedModS ? "Save page" : TShortcut extends BrowserReservedModO ? "Open file" : TShortcut extends BrowserReservedModH ? "History (Chrome) / Hide window (Mac)" : TShortcut extends BrowserReservedModJ ? "Downloads" : TShortcut extends BrowserReservedModQ ? "Quit application (Mac only)" : never;
+/** Maps each browser-reserved shortcut to its key string */
+type BrowserShortcutKeys<TShortcut> = TShortcut extends BrowserReservedModC ? "mod+c" : TShortcut extends BrowserReservedModV ? "mod+v" : TShortcut extends BrowserReservedModX ? "mod+x" : TShortcut extends BrowserReservedModA ? "mod+a" : TShortcut extends BrowserReservedModZ ? "mod+z" : TShortcut extends BrowserReservedModShiftZ ? "mod+shift+z" : TShortcut extends BrowserReservedModY ? "mod+y" : TShortcut extends BrowserReservedModF ? "mod+f" : TShortcut extends BrowserReservedModG ? "mod+g" : TShortcut extends BrowserReservedModShiftG ? "mod+shift+g" : TShortcut extends BrowserReservedModR ? "mod+r" : TShortcut extends BrowserReservedModShiftR ? "mod+shift+r" : TShortcut extends BrowserReservedModT ? "mod+t" : TShortcut extends BrowserReservedModW ? "mod+w" : TShortcut extends BrowserReservedModShiftT ? "mod+shift+t" : TShortcut extends BrowserReservedModN ? "mod+n" : TShortcut extends BrowserReservedModShiftN ? "mod+shift+n" : TShortcut extends BrowserReservedModL ? "mod+l" : TShortcut extends BrowserReservedModD ? "mod+d" : TShortcut extends BrowserReservedModEquals ? "mod+=" : TShortcut extends BrowserReservedModMinus ? "mod+-" : TShortcut extends BrowserReservedMod0 ? "mod+0" : TShortcut extends BrowserReservedModP ? "mod+p" : TShortcut extends BrowserReservedModS ? "mod+s" : TShortcut extends BrowserReservedModO ? "mod+o" : TShortcut extends BrowserReservedModH ? "mod+h" : TShortcut extends BrowserReservedModJ ? "mod+j" : TShortcut extends BrowserReservedModQ ? "mod+q" : never;
+/** Maps each browser-reserved shortcut to its error message */
+type BrowserReservedErrorMessage<TShortcut> = ReservedMessage<"Browser", BrowserShortcutKeys<TShortcut>, BrowserShortcutFeature<TShortcut>>;
+/** Union of all reserved shortcuts (app + browser) */
+type ReservedShortcut = AppReservedShortcut | BrowserReservedShortcut;
+/**
+ * Type predicate that returns true if the shortcut is reserved.
+ * Reserved shortcuts cannot be used without explicit ts-expect-error.
+ */
+export type IsReservedShortcut<TShortcut extends ShortcutDefinition> = TShortcut extends ReservedShortcut ? true : false;
+/** Maps any reserved shortcut to its specific error message */
+type ReservedErrorMessage<TShortcut> = TShortcut extends AppReservedShortcut ? AppReservedErrorMessage<TShortcut> : TShortcut extends BrowserReservedShortcut ? BrowserReservedErrorMessage<TShortcut> : never;
+/**
+ * Validates a shortcut parameter at the type level.
+ * Returns the shortcut type if valid, or a specific error message if reserved.
+ *
+ * @example
+ * // This type-checks:
+ * const shortcut: ValidShortcutParam<{ key: "m"; modifiers: "mod" }> = { key: "m", modifiers: "mod" };
+ *
+ * // This fails type-checking with app-reserved error:
+ * const reserved: ValidShortcutParam<{ key: "k"; modifiers: "mod" }> = { key: "k", modifiers: "mod" };
+ * // Error: Type '...' is not assignable to type '"App reserved: mod+k is used for Global Search, which should not be overwritten"'
+ *
+ * // This fails type-checking with browser-reserved error:
+ * const browserReserved: ValidShortcutParam<{ key: "c"; modifiers: "mod" }> = { key: "c", modifiers: "mod" };
+ * // Error: Type '...' is not assignable to type '"Browser reserved: mod+c is used for Copy, which should not be overwritten"'
+ */
+export type ValidShortcutParam<TShortcut extends ShortcutDefinition> = TShortcut extends ReservedShortcut ? ReservedErrorMessage<TShortcut> : TShortcut;
+export {};