@griddo/ax 12.9.0-rc.1 → 12.9.0

package/src/hooks/shortcuts/engine.ts

@@ -1,205 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,106 +0,0 @@
-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 };