@griddo/ax 12.9.0-rc.1 → 12.9.0

package/src/__tests__/hooks/shortcuts/engine.test.ts

@@ -1,344 +0,0 @@
-import { parseShortcut, type ShortcutConfig, shortcutEngine } from "@ax/hooks";
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Dispatch a keydown on `window` and return the event. */
-function keydown(init: KeyboardEventInit): KeyboardEvent {
-	const event = new KeyboardEvent("keydown", { ...init, bubbles: true, cancelable: true });
-	window.dispatchEvent(event);
-	return event;
-}
-
-/** Register a shortcut, track its cleanup automatically. */
-let cleanups: Array<() => void> = [];
-
-function register(
-	overrides: Partial<ShortcutConfig> & Pick<ShortcutConfig, "id" | "keys">,
-	target?: EventTarget,
-): ShortcutConfig {
-	const config: ShortcutConfig = { handler: jest.fn(), ...overrides };
-	const cleanup = shortcutEngine.register(config, target);
-	cleanups.push(cleanup);
-	return config;
-}
-
-afterEach(() => {
-	cleanups.forEach((fn) => {
-		fn();
-	});
-	cleanups = [];
-});
-
-// ---------------------------------------------------------------------------
-// parseShortcut
-// ---------------------------------------------------------------------------
-
-describe("parseShortcut", () => {
-	it("parses a single key", () => {
-		expect(parseShortcut("escape")).toEqual([{ modifiers: [], key: "escape" }]);
-	});
-
-	it("parses key with one modifier", () => {
-		expect(parseShortcut("mod+s")).toEqual([{ modifiers: ["mod"], key: "s" }]);
-	});
-
-	it("parses key with multiple modifiers", () => {
-		expect(parseShortcut("mod+shift+z")).toEqual([{ modifiers: ["mod", "shift"], key: "z" }]);
-	});
-
-	it("parses chord (multi-step sequence)", () => {
-		expect(parseShortcut("g l")).toEqual([
-			{ modifiers: [], key: "g" },
-			{ modifiers: [], key: "l" },
-		]);
-	});
-
-	it("parses chord with modifiers", () => {
-		expect(parseShortcut("mod+k mod+d")).toEqual([
-			{ modifiers: ["mod"], key: "k" },
-			{ modifiers: ["mod"], key: "d" },
-		]);
-	});
-});
-
-// ---------------------------------------------------------------------------
-// ShortcutEngine — basic dispatch
-// ---------------------------------------------------------------------------
-// In jsdom, isMac() → false, so "mod" maps to ctrlKey.
-
-describe("ShortcutEngine", () => {
-	describe("basic dispatch", () => {
-		it("fires handler on matching key", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			keydown({ key: "s", ctrlKey: true });
-			expect(config.handler).toHaveBeenCalledTimes(1);
-		});
-
-		it("ignores non-matching key", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			keydown({ key: "a", ctrlKey: true });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("ignores when required modifier is missing", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			keydown({ key: "s" });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("ignores when unexpected modifier is present", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			keydown({ key: "s", ctrlKey: true, shiftKey: true });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("matches shift+alt combo", () => {
-			const config = register({ id: "s1", keys: parseShortcut("shift+alt+n") });
-			keydown({ key: "n", shiftKey: true, altKey: true });
-			expect(config.handler).toHaveBeenCalledTimes(1);
-		});
-
-		it("ignores events with falsy event.key", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			// KeyboardEvent with no key option defaults to ""
-			window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, bubbles: true }));
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// preventDefault / stopPropagation
-	// -----------------------------------------------------------------------
-
-	describe("event control", () => {
-		it("calls preventDefault when handler does not return false", () => {
-			register({ id: "s1", keys: parseShortcut("mod+s") });
-			const event = keydown({ key: "s", ctrlKey: true });
-			expect(event.defaultPrevented).toBe(true);
-		});
-
-		it("skips preventDefault when handler returns false", () => {
-			register({ id: "s1", keys: parseShortcut("mod+s"), handler: () => false });
-			const event = keydown({ key: "s", ctrlKey: true });
-			expect(event.defaultPrevented).toBe(false);
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// enabled flag
-	// -----------------------------------------------------------------------
-
-	describe("enabled flag", () => {
-		it("skips disabled shortcuts", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s"), enabled: false });
-			keydown({ key: "s", ctrlKey: true });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// Priority
-	// -----------------------------------------------------------------------
-
-	describe("priority", () => {
-		it("dispatches higher priority first", () => {
-			const order: string[] = [];
-			register({
-				id: "low",
-				keys: parseShortcut("mod+s"),
-				priority: 0,
-				handler: () => {
-					order.push("low");
-				},
-			});
-			register({
-				id: "high",
-				keys: parseShortcut("mod+s"),
-				priority: 10,
-				handler: () => {
-					order.push("high");
-				},
-			});
-
-			keydown({ key: "s", ctrlKey: true });
-			// "high" wins and stops propagation
-			expect(order).toEqual(["high"]);
-		});
-
-		it("falls through when higher priority handler returns false", () => {
-			const order: string[] = [];
-			register({
-				id: "high",
-				keys: parseShortcut("mod+s"),
-				priority: 10,
-				handler: () => {
-					order.push("high");
-					return false;
-				},
-			});
-			register({
-				id: "low",
-				keys: parseShortcut("mod+s"),
-				priority: 0,
-				handler: () => {
-					order.push("low");
-				},
-			});
-
-			keydown({ key: "s", ctrlKey: true });
-			expect(order).toEqual(["high", "low"]);
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// Input element filtering
-	// -----------------------------------------------------------------------
-
-	describe("input element filtering", () => {
-		let input: HTMLInputElement;
-
-		beforeEach(() => {
-			input = document.createElement("input");
-			document.body.appendChild(input);
-		});
-
-		afterEach(() => {
-			document.body.removeChild(input);
-		});
-
-		it("does not fire inside input by default", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			input.dispatchEvent(new KeyboardEvent("keydown", { key: "s", ctrlKey: true, bubbles: true }));
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("fires inside input when allowInInput is true", () => {
-			const config = register({ id: "s1", keys: parseShortcut("mod+s"), allowInInput: true });
-			input.dispatchEvent(new KeyboardEvent("keydown", { key: "s", ctrlKey: true, bubbles: true }));
-			expect(config.handler).toHaveBeenCalledTimes(1);
-		});
-
-		it("Escape always fires inside input even without allowInInput", () => {
-			const config = register({ id: "s1", keys: parseShortcut("escape") });
-			input.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
-			expect(config.handler).toHaveBeenCalledTimes(1);
-		});
-
-		it("does not fire inside textarea by default", () => {
-			const textarea = document.createElement("textarea");
-			document.body.appendChild(textarea);
-			const config = register({ id: "s1", keys: parseShortcut("mod+s") });
-			textarea.dispatchEvent(new KeyboardEvent("keydown", { key: "s", ctrlKey: true, bubbles: true }));
-			expect(config.handler).not.toHaveBeenCalled();
-			document.body.removeChild(textarea);
-		});
-
-		// Note: contentEditable filtering cannot be tested in jsdom
-		// (isContentEditable is not properly implemented).
-	});
-
-	// -----------------------------------------------------------------------
-	// Chords
-	// -----------------------------------------------------------------------
-
-	describe("chords", () => {
-		it("fires on completed chord sequence", () => {
-			const config = register({ id: "goto", keys: parseShortcut("g l") });
-			keydown({ key: "g" });
-			keydown({ key: "l" });
-			expect(config.handler).toHaveBeenCalledTimes(1);
-		});
-
-		it("does not fire on first key alone", () => {
-			const config = register({ id: "goto", keys: parseShortcut("g l") });
-			keydown({ key: "g" });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("resets on wrong second key", () => {
-			const config = register({ id: "goto", keys: parseShortcut("g l") });
-			keydown({ key: "g" });
-			keydown({ key: "x" });
-			keydown({ key: "l" });
-			expect(config.handler).not.toHaveBeenCalled();
-		});
-
-		it("resets on timeout", () => {
-			jest.useFakeTimers();
-			const config = register({ id: "goto", keys: parseShortcut("g l") });
-			keydown({ key: "g" });
-			jest.advanceTimersByTime(1100);
-			keydown({ key: "l" });
-			expect(config.handler).not.toHaveBeenCalled();
-			jest.useRealTimers();
-		});
-
-		it("calls preventDefault on first key of chord", () => {
-			register({ id: "goto", keys: parseShortcut("g l") });
-			const event = keydown({ key: "g" });
-			expect(event.defaultPrevented).toBe(true);
-		});
-
-		it("does not fire single-key shortcuts while chord is advancing", () => {
-			const chordHandler = jest.fn();
-			const singleHandler = jest.fn();
-			register({ id: "chord", keys: parseShortcut("g l") });
-			register({ id: "single-g", keys: parseShortcut("g"), handler: singleHandler });
-
-			keydown({ key: "g" });
-			expect(singleHandler).not.toHaveBeenCalled();
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// Scoped target
-	// -----------------------------------------------------------------------
-
-	describe("scoped target", () => {
-		it("fires only on registered target", () => {
-			const div = document.createElement("div");
-			document.body.appendChild(div);
-			const config = register({ id: "scoped", keys: parseShortcut("mod+b") }, div);
-
-			// Event on window — should NOT trigger
-			keydown({ key: "b", ctrlKey: true });
-			expect(config.handler).not.toHaveBeenCalled();
-
-			// Event on the registered target — should trigger
-			div.dispatchEvent(new KeyboardEvent("keydown", { key: "b", ctrlKey: true, bubbles: true }));
-			expect(config.handler).toHaveBeenCalledTimes(1);
-
-			document.body.removeChild(div);
-		});
-	});
-
-	// -----------------------------------------------------------------------
-	// Cleanup
-	// -----------------------------------------------------------------------
-
-	describe("cleanup", () => {
-		it("unregisters shortcut when cleanup is called", () => {
-			const handler = jest.fn();
-			const cleanup = shortcutEngine.register({ id: "tmp", keys: parseShortcut("mod+s"), handler }, window);
-			cleanup();
-
-			keydown({ key: "s", ctrlKey: true });
-			expect(handler).not.toHaveBeenCalled();
-		});
-
-		it("removes listener when last shortcut on a target is unregistered", () => {
-			const div = document.createElement("div");
-			document.body.appendChild(div);
-			const spy = jest.spyOn(div, "removeEventListener");
-
-			const cleanup = shortcutEngine.register({ id: "tmp", keys: parseShortcut("mod+x"), handler: jest.fn() }, div);
-			cleanup();
-
-			expect(spy).toHaveBeenCalledWith("keydown", expect.any(Function));
-			spy.mockRestore();
-			document.body.removeChild(div);
-		});
-	});
-});

package/src/__tests__/hooks/shortcuts/hooks.test.tsx

@@ -1,259 +0,0 @@
-import {
-	shortcut,
-	useEscapeShortcut,
-	useGlobalShortcuts,
-	useIframeShortcutBridge,
-	useSaveShortcut,
-	useShortcuts,
-	useUndoRedoShortcuts,
-} from "@ax/hooks";
-
-import { renderHook } from "@testing-library/react";
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function keydown(init: KeyboardEventInit): KeyboardEvent {
-	const event = new KeyboardEvent("keydown", { ...init, bubbles: true, cancelable: true });
-	window.dispatchEvent(event);
-	return event;
-}
-
-// ---------------------------------------------------------------------------
-// shortcut builder
-// ---------------------------------------------------------------------------
-
-describe("shortcut()", () => {
-	it("creates a ShortcutConfig with parsed keys", () => {
-		const handler = jest.fn();
-		const config = shortcut("save", "mod+s", handler);
-		expect(config.id).toBe("save");
-		expect(config.keys).toEqual([{ modifiers: ["mod"], key: "s" }]);
-		expect(config.handler).toBe(handler);
-	});
-
-	it("applies overrides", () => {
-		const config = shortcut("save", "mod+s", jest.fn(), {
-			allowInInput: true,
-			priority: 5,
-			description: "Save document",
-		});
-		expect(config.allowInInput).toBe(true);
-		expect(config.priority).toBe(5);
-		expect(config.description).toBe("Save document");
-	});
-});
-
-// ---------------------------------------------------------------------------
-// useShortcuts
-// ---------------------------------------------------------------------------
-
-describe("useShortcuts", () => {
-	it("registers and fires shortcut on matching key", () => {
-		const handler = jest.fn();
-		renderHook(() => useShortcuts([shortcut("s1", "mod+s", handler)]));
-		keydown({ key: "s", ctrlKey: true });
-		expect(handler).toHaveBeenCalledTimes(1);
-	});
-
-	it("cleans up shortcuts on unmount", () => {
-		const handler = jest.fn();
-		const { unmount } = renderHook(() => useShortcuts([shortcut("s1", "mod+s", handler)]));
-		unmount();
-		keydown({ key: "s", ctrlKey: true });
-		expect(handler).not.toHaveBeenCalled();
-	});
-
-	it("does not fire when enabled is false", () => {
-		const handler = jest.fn();
-		renderHook(() => useShortcuts([shortcut("s1", "mod+s", handler)], { enabled: false }));
-		keydown({ key: "s", ctrlKey: true });
-		expect(handler).not.toHaveBeenCalled();
-	});
-
-	it("always calls the latest handler (no stale closures)", () => {
-		let value = 0;
-		const { rerender } = renderHook(({ handler }) => useShortcuts([shortcut("s1", "mod+s", handler)]), {
-			initialProps: {
-				handler: () => {
-					value = 1;
-				},
-			},
-		});
-		rerender({
-			handler: () => {
-				value = 2;
-			},
-		});
-		keydown({ key: "s", ctrlKey: true });
-		expect(value).toBe(2);
-	});
-
-	it("scopes shortcuts to a ref element", () => {
-		const div = document.createElement("div");
-		document.body.appendChild(div);
-		const ref = { current: div } as React.RefObject<HTMLDivElement>;
-		const handler = jest.fn();
-
-		renderHook(() => useShortcuts([shortcut("s1", "mod+b", handler)], { ref }));
-
-		// Event on window — should NOT trigger
-		keydown({ key: "b", ctrlKey: true });
-		expect(handler).not.toHaveBeenCalled();
-
-		// Event on ref element — should trigger
-		div.dispatchEvent(new KeyboardEvent("keydown", { key: "b", ctrlKey: true, bubbles: true }));
-		expect(handler).toHaveBeenCalledTimes(1);
-
-		document.body.removeChild(div);
-	});
-});
-
-// ---------------------------------------------------------------------------
-// Preset hooks
-// ---------------------------------------------------------------------------
-
-describe("useSaveShortcut", () => {
-	it("fires handler on mod+s", () => {
-		const handler = jest.fn();
-		renderHook(() => useSaveShortcut(handler));
-		keydown({ key: "s", ctrlKey: true });
-		expect(handler).toHaveBeenCalledTimes(1);
-	});
-
-	it("does not fire when disabled", () => {
-		const handler = jest.fn();
-		renderHook(() => useSaveShortcut(handler, false));
-		keydown({ key: "s", ctrlKey: true });
-		expect(handler).not.toHaveBeenCalled();
-	});
-
-	it("works inside input elements", () => {
-		const handler = jest.fn();
-		renderHook(() => useSaveShortcut(handler));
-		const input = document.createElement("input");
-		document.body.appendChild(input);
-		input.dispatchEvent(new KeyboardEvent("keydown", { key: "s", ctrlKey: true, bubbles: true }));
-		expect(handler).toHaveBeenCalledTimes(1);
-		document.body.removeChild(input);
-	});
-});
-
-describe("useEscapeShortcut", () => {
-	it("fires handler on Escape", () => {
-		const handler = jest.fn();
-		renderHook(() => useEscapeShortcut(handler));
-		keydown({ key: "Escape" });
-		expect(handler).toHaveBeenCalledTimes(1);
-	});
-
-	it("does not fire when disabled", () => {
-		const handler = jest.fn();
-		renderHook(() => useEscapeShortcut(handler, false));
-		keydown({ key: "Escape" });
-		expect(handler).not.toHaveBeenCalled();
-	});
-});
-
-describe("useUndoRedoShortcuts", () => {
-	it("fires onUndo on mod+z", () => {
-		const onUndo = jest.fn();
-		const onRedo = jest.fn();
-		renderHook(() => useUndoRedoShortcuts(onUndo, onRedo));
-		keydown({ key: "z", ctrlKey: true });
-		expect(onUndo).toHaveBeenCalledTimes(1);
-		expect(onRedo).not.toHaveBeenCalled();
-	});
-
-	it("fires onRedo on mod+shift+z", () => {
-		const onUndo = jest.fn();
-		const onRedo = jest.fn();
-		renderHook(() => useUndoRedoShortcuts(onUndo, onRedo));
-		keydown({ key: "z", ctrlKey: true, shiftKey: true });
-		expect(onRedo).toHaveBeenCalledTimes(1);
-		expect(onUndo).not.toHaveBeenCalled();
-	});
-});
-
-describe("useGlobalShortcuts", () => {
-	it("prevents browser default on mod+s", () => {
-		renderHook(() => useGlobalShortcuts());
-		const event = keydown({ key: "s", ctrlKey: true });
-		expect(event.defaultPrevented).toBe(true);
-	});
-
-	it("yields to higher-priority shortcut", () => {
-		const handler = jest.fn();
-		renderHook(() => useGlobalShortcuts());
-		renderHook(() => useSaveShortcut(handler));
-
-		keydown({ key: "s", ctrlKey: true });
-		// The preset (priority 0) wins over global (priority -1)
-		expect(handler).toHaveBeenCalledTimes(1);
-	});
-});
-
-// ---------------------------------------------------------------------------
-// useIframeShortcutBridge
-// ---------------------------------------------------------------------------
-
-describe("useIframeShortcutBridge", () => {
-	it("re-dispatches same-origin shortcut messages as keydown", () => {
-		renderHook(() => useIframeShortcutBridge());
-		const spy = jest.fn();
-		window.addEventListener("keydown", spy);
-
-		window.dispatchEvent(
-			new MessageEvent("message", {
-				origin: window.location.origin,
-				data: {
-					type: "shortcut-keydown",
-					message: { key: "s", code: "KeyS", metaKey: false, ctrlKey: true, shiftKey: false, altKey: false },
-				},
-			}),
-		);
-
-		expect(spy).toHaveBeenCalled();
-		const event = spy.mock.calls[0][0] as KeyboardEvent;
-		expect(event.key).toBe("s");
-		expect(event.ctrlKey).toBe(true);
-
-		window.removeEventListener("keydown", spy);
-	});
-
-	it("ignores cross-origin messages", () => {
-		renderHook(() => useIframeShortcutBridge());
-		const spy = jest.fn();
-		window.addEventListener("keydown", spy);
-
-		window.dispatchEvent(
-			new MessageEvent("message", {
-				origin: "https://evil.example.com",
-				data: {
-					type: "shortcut-keydown",
-					message: { key: "s", code: "KeyS", metaKey: false, ctrlKey: true, shiftKey: false, altKey: false },
-				},
-			}),
-		);
-
-		expect(spy).not.toHaveBeenCalled();
-		window.removeEventListener("keydown", spy);
-	});
-
-	it("ignores messages with unrecognized type", () => {
-		renderHook(() => useIframeShortcutBridge());
-		const spy = jest.fn();
-		window.addEventListener("keydown", spy);
-
-		window.dispatchEvent(
-			new MessageEvent("message", {
-				origin: window.location.origin,
-				data: { type: "unrelated-message" },
-			}),
-		);
-
-		expect(spy).not.toHaveBeenCalled();
-		window.removeEventListener("keydown", spy);
-	});
-});