@trackunit/react-components 1.15.21 → 1.15.22

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

@@ -0,0 +1,20 @@
+import { ReservedShortcutInfo } from "./types";
+/**
+ * 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.
+ */
+export declare const RESERVED_SHORTCUTS: Record<string, ReservedShortcutInfo>;
+/**
+ * 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.
+ */
+export declare const BROWSER_SHORTCUTS: Record<string, string>;

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

@@ -0,0 +1,18 @@
+import { ShortcutDefinition } from "./types";
+/**
+ * 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" });
+ */
+export declare const matchesShortcut: (event: KeyboardEvent, shortcut: ShortcutDefinition) => boolean;

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

@@ -0,0 +1,6 @@
+import { ShortcutDefinition } from "./types";
+/**
+ * Converts a ShortcutDefinition to a normalized string key for lookup.
+ * Format: "mod+shift+k" (modifiers sorted alphabetically, then key)
+ */
+export declare const shortcutToString: (shortcut: ShortcutDefinition) => string;

package/src/hooks/useKeyboardShortcut/shortcutUtils.testUtils.d.ts

@@ -0,0 +1,12 @@
+import { ShortcutDefinition } from "./types";
+/**
+ * Parses a string shortcut into a ShortcutDefinition.
+ * Useful for debugging and testing.
+ *
+ * @param shortcutStr - The shortcut string to parse (e.g., "mod+k")
+ * @returns {ShortcutDefinition} The parsed shortcut definition
+ * @example
+ * parseShortcut("mod+k") // { key: "k", modifiers: "mod" }
+ * parseShortcut("mod+shift+l") // { key: "l", modifiers: "mod+shift" }
+ */
+export declare const parseShortcut: (shortcutStr: string) => ShortcutDefinition;

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

@@ -0,0 +1,97 @@
+import { RefObject } from "react";
+/**
+ * Individual semantic modifier keys (internal use for parsing).
+ *
+ * - `mod`: Primary action modifier - Cmd on Mac, Ctrl on Windows/Linux
+ * - `alt`: Alternative/Option key - Option on Mac, Alt on Windows/Linux
+ * - `shift`: Shift key on all platforms
+ *
+ * Note: Explicit ctrl/meta are intentionally not supported.
+ * Use "mod" for cross-platform shortcuts.
+ */
+export type SemanticModifier = "mod" | "alt" | "shift";
+/**
+ * Valid modifier combinations as a string.
+ * Modifiers are joined with "+" in alphabetical order.
+ *
+ * @example
+ * "mod" // Cmd on Mac, Ctrl on Windows/Linux
+ * "mod+shift" // Cmd+Shift on Mac, Ctrl+Shift on Windows/Linux
+ * "alt+mod+shift" // Option+Cmd+Shift on Mac, Alt+Ctrl+Shift on Windows/Linux
+ */
+export type ModifierString = "mod" | "alt" | "shift" | "alt+mod" | "alt+shift" | "mod+shift" | "alt+mod+shift";
+/**
+ * Supported shortcut keys.
+ * These map to the `event.key` values from KeyboardEvent.
+ */
+export type ShortcutKey = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "Enter" | "Escape" | "Tab" | "Space" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "/" | "[" | "]" | "," | "." | "-" | "=" | "`" | "\\";
+/**
+ * Defines a keyboard shortcut with a key and optional modifiers.
+ */
+export type ShortcutDefinition = {
+    /** The primary key for the shortcut */
+    readonly key: ShortcutKey;
+    /**
+     * Optional modifier string. Modifiers are joined with "+" in alphabetical order.
+     *
+     * @example "mod" | "mod+shift" | "alt+mod+shift"
+     */
+    readonly modifiers?: ModifierString;
+};
+/**
+ * Controls how the shortcut handles the browser's default behavior.
+ *
+ * - `"never"` - Never prevent default. Browser handles the event normally.
+ * - `"once"` - Prevent default on first trigger. Pressing the same shortcut
+ *   twice within 400ms passes through to the browser, providing an escape
+ *   hatch for accessing native browser shortcuts that are overridden.
+ * - `"always"` - Always prevent default on every press, including rapid repeats.
+ *   No browser escape hatch.
+ */
+export type PreventDefaultMode = "never" | "once" | "always";
+/**
+ * Options for the useKeyboardShortcut hook.
+ */
+export type UseKeyboardShortcutOptions = {
+    /** Called when the shortcut is triggered */
+    onTrigger: () => void;
+    /**
+     * Disable the shortcut conditionally.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Controls how the shortcut handles the browser's default behavior.
+     *
+     * - `"never"` - Never prevent default. Browser handles the event normally.
+     * - `"once"` - Prevent default on first trigger. Pressing the same shortcut
+     *   twice within 400ms passes through to the browser, providing an escape
+     *   hatch for accessing native browser shortcuts that are overridden.
+     * - `"always"` - Always prevent default on every press, including rapid repeats.
+     *   No browser escape hatch.
+     *
+     * @default "never"
+     */
+    preventDefault?: PreventDefaultMode;
+    /**
+     * Target element for the keyboard listener.
+     * Can be a ref to an HTMLElement or "window" for global shortcuts.
+     *
+     * @default "window"
+     */
+    target?: RefObject<HTMLElement | null> | "window";
+};
+/**
+ * Detected platform for keyboard shortcut handling.
+ */
+export type Platform = "mac" | "windows" | "linux";
+/**
+ * Information about a reserved shortcut.
+ */
+export type ReservedShortcutInfo = {
+    /** Human-readable name of the shortcut */
+    name: string;
+    /** The module/feature that owns this shortcut */
+    owner: string;
+};

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

@@ -0,0 +1,56 @@
+import { ValidShortcutParam } from "./reservedShortcutTypes";
+import { ShortcutDefinition, UseKeyboardShortcutOptions } from "./types";
+/**
+ * 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)
+ */
+export declare const useKeyboardShortcut: <const TShortcut extends ShortcutDefinition>(shortcut: TShortcut extends ValidShortcutParam<TShortcut> ? TShortcut : never, { onTrigger, disabled, preventDefault, target }: UseKeyboardShortcutOptions) => {
+    label: string;
+};

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

@@ -0,0 +1,41 @@
+import { ReservedShortcutInfo, ShortcutDefinition } from "./types";
+/**
+ * Information about shortcut conflicts.
+ */
+export type ShortcutConflictInfo = {
+    /** True if shortcut is reserved by the application */
+    isReserved: boolean;
+    /** Info about the reservation if reserved */
+    reservedInfo: ReservedShortcutInfo | undefined;
+    /** Browser action description if conflicts with browser shortcut */
+    browserConflict: string | undefined;
+};
+type UseShortcutConflictsOptions = {
+    /**
+     * If true, skip conflict checking and warnings.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+};
+/**
+ * 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}`);
+ * }
+ */
+export declare const useShortcutConflicts: (shortcut: ShortcutDefinition, options?: UseShortcutConflictsOptions) => ShortcutConflictInfo;
+export {};

package/src/index.d.ts

@@ -117,6 +117,7 @@ export * from "./hooks/useInfiniteScroll";
 export * from "./hooks/useIsFirstRender";
 export * from "./hooks/useIsFullScreen";
 export * from "./hooks/useIsTextTruncated";
+export { useKeyboardShortcut } from "./hooks/useKeyboardShortcut/useKeyboardShortcut";
 export * from "./hooks/useMeasure";
 export * from "./hooks/useMergeRefs";
 export * from "./hooks/useModifierKey";