@griddo/ax 12.9.0 → 12.9.1-rc.0

package/src/hooks/shortcuts/engine.ts

@@ -0,0 +1,205 @@
+import type { KeyCombo, ModifierKey, ShortcutConfig } from "./types";
+
+const CHORD_TIMEOUT_MS = 1000;
+
+function isMac(): boolean {
+	if (typeof navigator === "undefined") return false;
+	if ("userAgentData" in navigator) {
+		return (navigator as Navigator & { userAgentData?: { platform?: string } }).userAgentData?.platform === "macOS";
+	}
+	return /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+}
+
+function isInputElement(el: EventTarget | null): boolean {
+	if (!(el instanceof HTMLElement)) return false;
+	const tag = el.tagName;
+	if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+	if (el.isContentEditable) return true;
+	return false;
+}
+
+function normalizeCombos(keys: ShortcutConfig["keys"]): readonly KeyCombo[] {
+	return Array.isArray(keys) ? (keys as readonly KeyCombo[]) : [keys as KeyCombo];
+}
+
+function matchesCombo(event: KeyboardEvent, combo: KeyCombo): boolean {
+	if (!event.key) return false;
+	if (event.key.toLowerCase() !== combo.key.toLowerCase()) return false;
+
+	const mac = isMac();
+	const hasModifier = (mod: ModifierKey): boolean => {
+		switch (mod) {
+			case "mod":
+				return mac ? event.metaKey : event.ctrlKey;
+			case "shift":
+				return event.shiftKey;
+			case "alt":
+				return event.altKey;
+		}
+	};
+
+	for (const mod of combo.modifiers) {
+		if (!hasModifier(mod)) return false;
+	}
+
+	// No unexpected modifiers.
+	// For symbol keys (non-letter, single char) shift/alt may be required by the
+	// keyboard layout to produce that character — event.key already encodes the
+	// result, so we skip those modifier checks.
+	const isSymbolKey = combo.key.length === 1 && !/[a-z]/i.test(combo.key);
+	const required = new Set<ModifierKey>(combo.modifiers);
+	if (!isSymbolKey && !required.has("shift") && event.shiftKey) return false;
+	if (!isSymbolKey && !required.has("alt") && event.altKey) return false;
+	if (!required.has("mod")) {
+		if (mac && event.metaKey) return false;
+		if (!mac && event.ctrlKey) return false;
+	}
+
+	return true;
+}
+
+interface InternalEntry {
+	readonly config: ShortcutConfig;
+	readonly combos: readonly KeyCombo[];
+}
+
+interface TargetState {
+	readonly listener: (event: Event) => void;
+	/** Sorted by priority descending — updated on register/unregister */
+	orderedIds: number[];
+}
+
+/**
+ * Centralized shortcut dispatcher.
+ *
+ * Uses one `keydown` listener per target. When a key is pressed, all registered
+ * shortcuts for that target are checked in priority order (highest first).
+ * The first matching shortcut wins — lower-priority shortcuts are skipped.
+ * If a handler returns `false`, dispatch continues to the next match.
+ */
+class ShortcutEngine {
+	private nextId = 0;
+	private entries = new Map<number, InternalEntry>();
+	private targets = new Map<EventTarget, TargetState>();
+	private activeChords = new Map<string, number>();
+	private chordTimerId: ReturnType<typeof setTimeout> | null = null;
+
+	register(config: ShortcutConfig, target: EventTarget = window): () => void {
+		const id = this.nextId++;
+		const combos = normalizeCombos(config.keys);
+		this.entries.set(id, { config, combos });
+
+		if (!this.targets.has(target)) {
+			const listener = (event: Event) => this.dispatch(event as KeyboardEvent, target);
+			target.addEventListener("keydown", listener);
+			this.targets.set(target, { listener, orderedIds: [] });
+		}
+		const targetState = this.targets.get(target)!;
+		targetState.orderedIds.push(id);
+		this.sortTargetIds(targetState);
+
+		return () => {
+			this.entries.delete(id);
+			this.activeChords.delete(config.id);
+			const state = this.targets.get(target);
+			if (state) {
+				state.orderedIds = state.orderedIds.filter((eid) => eid !== id);
+				if (state.orderedIds.length === 0) {
+					target.removeEventListener("keydown", state.listener);
+					this.targets.delete(target);
+				}
+			}
+		};
+	}
+
+	private dispatch(event: KeyboardEvent, target: EventTarget): void {
+		const state = this.targets.get(target);
+		if (!state) return;
+
+		let chordAdvanced = false;
+
+		for (const id of state.orderedIds) {
+			const entry = this.entries.get(id);
+			if (!entry) continue;
+			const { config, combos } = entry;
+			if (config.enabled === false) continue;
+			if (!config.allowInInput && isInputElement(event.target) && event.key !== "Escape") continue;
+
+			if (combos.length === 1) {
+				// Don't fire single-key shortcuts while a chord is advancing
+				if (chordAdvanced) continue;
+				if (matchesCombo(event, combos[0])) {
+					if (this.execute(event, config)) return;
+				}
+				continue;
+			}
+
+			// Chord sequence
+			const chordIdx = this.activeChords.get(config.id) ?? 0;
+			if (matchesCombo(event, combos[chordIdx])) {
+				const nextIdx = chordIdx + 1;
+				if (nextIdx >= combos.length) {
+					this.activeChords.clear();
+					this.clearChordTimer();
+					if (this.execute(event, config)) return;
+				} else {
+					this.activeChords.set(config.id, nextIdx);
+					this.resetChordTimer(config.id);
+					chordAdvanced = true;
+				}
+			} else if (chordIdx > 0) {
+				this.activeChords.delete(config.id);
+			}
+		}
+
+		if (chordAdvanced) {
+			event.preventDefault();
+		}
+	}
+
+	/** @returns `true` if handled (preventDefault was called) */
+	private execute(event: KeyboardEvent, config: ShortcutConfig): boolean {
+		const result = config.handler(event);
+		if (result !== false) {
+			event.preventDefault();
+			event.stopPropagation();
+			return true;
+		}
+		return false;
+	}
+
+	private sortTargetIds(state: TargetState): void {
+		state.orderedIds.sort((a, b) => {
+			const pa = this.entries.get(a)?.config.priority ?? 0;
+			const pb = this.entries.get(b)?.config.priority ?? 0;
+			return pb - pa;
+		});
+	}
+
+	private resetChordTimer(id: string): void {
+		this.clearChordTimer();
+		this.chordTimerId = setTimeout(() => {
+			this.activeChords.delete(id);
+		}, CHORD_TIMEOUT_MS);
+	}
+
+	private clearChordTimer(): void {
+		if (this.chordTimerId !== null) {
+			clearTimeout(this.chordTimerId);
+			this.chordTimerId = null;
+		}
+	}
+}
+
+const shortcutEngine = new ShortcutEngine();
+
+function parseShortcut(str: string): KeyCombo[] {
+	return str.split(" ").map((part) => {
+		const tokens = part.toLowerCase().split("+");
+		const key = tokens.pop()!;
+		const modifiers = tokens as ModifierKey[];
+		return { modifiers, key };
+	});
+}
+
+export { parseShortcut, shortcutEngine };

package/src/hooks/shortcuts/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Keyboard shortcuts module for Griddo AX.
+ *
+ * Provides a declarative way to register keyboard shortcuts in React components
+ * with automatic cleanup and support for chord sequences (multi-key shortcuts).
+ *
+ * @example Quick start
+ * ```tsx
+ * import { useShortcuts, shortcut } from "@ax/hooks";
+ *
+ * function MyComponent() {
+ *   useShortcuts([
+ *     shortcut("save", "mod+s", (e) => {
+ *       e.preventDefault();
+ *       handleSave();
+ *     }),
+ *     shortcut("delete", "del", handleDelete),
+ *   ]);
+ *
+ *   return <div>Press Ctrl/Cmd+S to save</div>;
+ * }
+ * ```
+ *
+ * Key features:
+ * - Automatic cleanup on unmount
+ * - Chord sequences: "g l" means press 'g' then 'l'
+ * - Mod key: "mod" maps to Cmd (Mac) or Ctrl (Windows/Linux)
+ * - Ref-based handlers: always use latest state values
+ * - Escape key works in inputs (for cancel/close actions)
+ *
+ * @module @ax/hooks/shortcuts
+ */
+export { parseShortcut, shortcutEngine } from "./engine";
+export {
+	useEscapeShortcut,
+	useForwardShortcutKeys,
+	useGlobalShortcuts,
+	useIframeShortcutBridge,
+	useSaveShortcut,
+	useUndoRedoShortcuts,
+} from "./presets";
+export type {
+	KeyCombo,
+	ModifierKey,
+	ShortcutConfig,
+	UseShortcutsOptions,
+} from "./types";
+export { shortcut, useShortcuts } from "./useShortcuts";

package/src/hooks/shortcuts/presets.ts

@@ -0,0 +1,144 @@
+import { useEffect } from "react";
+
+import { shortcut, useShortcuts } from "./useShortcuts";
+
+const GLOBAL_PRIORITY = -1;
+
+/**
+ * `mod+s` shortcut with `allowInInput` enabled.
+ *
+ * @param handler - Called when the shortcut is triggered
+ * @param enabled - Whether the shortcut is active (defaults to true)
+ */
+function useSaveShortcut(handler: () => void, enabled = true): void {
+	useShortcuts([shortcut("save", "mod+s", handler, { allowInInput: true })], { enabled });
+}
+
+/**
+ * `Escape` shortcut. Works in inputs by default.
+ *
+ * @param handler - Called when Escape is pressed
+ * @param enabled - Whether the shortcut is active (defaults to true)
+ */
+function useEscapeShortcut(handler: () => void, enabled = true): void {
+	useShortcuts([shortcut("escape", "escape", handler, { allowInInput: true })], { enabled });
+}
+
+/**
+ * `mod+z` / `mod+shift+z` undo/redo pair.
+ *
+ * @param onUndo - Called on mod+z
+ * @param onRedo - Called on mod+shift+z
+ * @param enabled - Whether both shortcuts are active (defaults to true)
+ */
+function useUndoRedoShortcuts(onUndo: () => void, onRedo: () => void, enabled = true): void {
+	useShortcuts(
+		[
+			shortcut("undo", "mod+z", onUndo, { allowInInput: true }),
+			shortcut("redo", "mod+shift+z", onRedo, { allowInInput: true }),
+		],
+		{ enabled },
+	);
+}
+
+/**
+ * Global shortcut safety net. Prevents browser defaults (e.g. Save As on `mod+s`)
+ * across all routes. Component-level presets override these via higher priority.
+ *
+ * Call once at the app root.
+ */
+function useGlobalShortcuts(): void {
+	useShortcuts([
+		shortcut("global:save", "mod+s", () => {}, {
+			allowInInput: true,
+			priority: GLOBAL_PRIORITY,
+		}),
+	]);
+}
+
+/**
+ * Bridges shortcut keydown events forwarded from iframes (via `postMessage`)
+ * back into the parent window so the ShortcutEngine can handle them.
+ *
+ * Call once at the app root alongside `useGlobalShortcuts()`.
+ */
+function useIframeShortcutBridge(): void {
+	useEffect(() => {
+		// Only run in the top-level window, not inside iframes
+		if (window !== window.parent) return;
+
+		const handleMessage = (ev: MessageEvent) => {
+			if (ev.origin !== window.location.origin) return;
+			if (typeof ev.data !== "object" || ev.data?.type !== "shortcut-keydown") return;
+			const { key, code, metaKey, ctrlKey, shiftKey, altKey } = ev.data.message;
+			window.dispatchEvent(
+				new KeyboardEvent("keydown", {
+					key,
+					code,
+					metaKey,
+					ctrlKey,
+					shiftKey,
+					altKey,
+					bubbles: true,
+					cancelable: true,
+				}),
+			);
+		};
+
+		window.addEventListener("message", handleMessage);
+		return () => window.removeEventListener("message", handleMessage);
+	}, []);
+}
+
+/** Clipboard combos that must NOT be intercepted inside the iframe. */
+const CLIPBOARD_KEYS = new Set(["c", "v", "x", "a"]);
+
+/**
+ * Forwards shortcut keydown events from inside an iframe to the parent window
+ * via `postMessage`. Pairs with `useIframeShortcutBridge` on the parent side.
+ *
+ * Call once inside the iframe entry component (e.g. `FramePreview`).
+ */
+function useForwardShortcutKeys(): void {
+	useEffect(() => {
+		// Only run inside iframes
+		if (window === window.parent) return;
+
+		const handleKeyDown = (e: KeyboardEvent) => {
+			const hasModifier = e.metaKey || e.ctrlKey;
+			const isEscape = e.key === "Escape";
+
+			if (!hasModifier && !isEscape) return;
+			if (hasModifier && CLIPBOARD_KEYS.has(e.key.toLowerCase())) return;
+
+			e.preventDefault();
+
+			window.parent.postMessage(
+				{
+					type: "shortcut-keydown",
+					message: {
+						key: e.key,
+						code: e.code,
+						metaKey: e.metaKey,
+						ctrlKey: e.ctrlKey,
+						shiftKey: e.shiftKey,
+						altKey: e.altKey,
+					},
+				},
+				window.location.origin,
+			);
+		};
+
+		window.addEventListener("keydown", handleKeyDown, true);
+		return () => window.removeEventListener("keydown", handleKeyDown, true);
+	}, []);
+}
+
+export {
+	useEscapeShortcut,
+	useForwardShortcutKeys,
+	useGlobalShortcuts,
+	useIframeShortcutBridge,
+	useSaveShortcut,
+	useUndoRedoShortcuts,
+};

package/src/hooks/shortcuts/types.ts

@@ -0,0 +1,23 @@
+import type { RefObject } from "react";
+
+export type ModifierKey = "mod" | "shift" | "alt";
+
+export interface KeyCombo {
+	readonly modifiers: readonly ModifierKey[];
+	readonly key: string;
+}
+
+export interface ShortcutConfig {
+	readonly id: string;
+	readonly keys: KeyCombo | readonly KeyCombo[];
+	readonly handler: (event: KeyboardEvent) => void | boolean;
+	readonly enabled?: boolean;
+	readonly allowInInput?: boolean;
+	readonly priority?: number;
+	readonly description?: string;
+}
+
+export interface UseShortcutsOptions {
+	readonly ref?: RefObject<HTMLElement>;
+	readonly enabled?: boolean;
+}

package/src/hooks/shortcuts/useShortcuts.ts

@@ -0,0 +1,106 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+import { parseShortcut, shortcutEngine } from "./engine";
+import type { ShortcutConfig, UseShortcutsOptions } from "./types";
+
+/**
+ * Register keyboard shortcuts for a component.
+ *
+ * **Important:** The shortcuts array should be memoized:
+ *
+ * ```tsx
+ * const shortcuts = useMemo(
+ *   () => [shortcut("id", "key", handler)],
+ *   [handler]
+ * );
+ * useShortcuts(shortcuts);
+ * ```
+ *
+ * **For modals/overlays:** Always pass `enabled={isOpen}` to prevent conflicts
+ * when multiple modals are open:
+ *
+ * ```tsx
+ * useShortcuts(shortcuts, { enabled: isOpen });
+ * ```
+ *
+ * @param shortcuts - Memoized array of shortcut configurations
+ * @param options - Optional configuration
+ * @param options.ref - Target element for keydown events (defaults to window)
+ * @param options.enabled - Whether shortcuts are active (defaults to true)
+ *
+ * @example Basic usage with single shortcut
+ * ```tsx
+ * useShortcuts([
+ *   shortcut("save", "mod+s", (e) => {
+ *     e.preventDefault();
+ *     saveDocument();
+ *   }),
+ * ]);
+ */
+function useShortcuts(shortcuts: ShortcutConfig[], options: UseShortcutsOptions = {}): void {
+	const { ref, enabled = true } = options;
+	const latestHandlersRef = useRef(new Map<string, ShortcutConfig["handler"]>());
+
+	// Sync handlers to ref inside a layout effect (not during render)
+	// to avoid mutating refs in the render phase (Strict Mode / Concurrent safe)
+	useLayoutEffect(() => {
+		latestHandlersRef.current.clear();
+		shortcuts.forEach((s) => {
+			latestHandlersRef.current.set(s.id, s.handler);
+		});
+	});
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		const target = ref?.current ?? window;
+
+		const cleanups = shortcuts.map((config) =>
+			shortcutEngine.register(
+				{
+					...config,
+					// Call latest handler from ref to avoid stale closures
+					handler: (event) => {
+						const latestHandler = latestHandlersRef.current.get(config.id);
+						if (latestHandler) {
+							latestHandler(event);
+						}
+					},
+				},
+				target,
+			),
+		);
+
+		return () =>
+			cleanups.forEach((cleanup) => {
+				cleanup();
+			});
+	}, [shortcuts, enabled, ref]);
+}
+
+/**
+ * Create a shortcut configuration object.
+ *
+ * @param id - Unique identifier (e.g., "close:modal", "save:document")
+ * @param keys - Key combination: "mod+s", "ctrl+shift+p", or chords "g g"
+ * @param handler - Called when shortcut triggers. Return false to skip preventDefault
+ * @param overrides - Optional config
+ *
+ * @example
+ * ```tsx
+ * shortcut("save", "mod+s", (e) => {
+ *   e.preventDefault();
+ *   handleSave();
+ * })
+ * ```
+ */
+function shortcut(
+	id: string,
+	keys: string,
+	handler: ShortcutConfig["handler"],
+	overrides?: Partial<Pick<ShortcutConfig, "allowInInput" | "priority" | "description" | "enabled">>,
+): ShortcutConfig {
+	return { id, keys: parseShortcut(keys), handler, ...overrides };
+}
+
+export { shortcut, useShortcuts };