@dxos/keyboard 0.10.0 → 0.11.0

package/dist/lib/index.mjs

@@ -0,0 +1,168 @@
+import { invariant } from "@dxos/invariant";
+import { getHostPlatform } from "@dxos/util";
+//#region src/keyboard.ts
+var __dxlog_file = "/__w/dxos/dxos/packages/common/keyboard/src/keyboard.ts";
+var modifiers = [
+	"ctrl",
+	"shift",
+	"alt",
+	"meta"
+];
+var parseShortcut = (shortcut, delimiter = /[+-]/) => {
+	const parts = shortcut.toLowerCase().split(delimiter);
+	const mods = modifiers.filter((key) => parts.includes(key));
+	invariant(mods.length === 0 || mods.length === parts.length - 1, void 0, {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 32,
+		S: void 0,
+		A: ["mods.length === 0 || mods.length === parts.length - 1", ""]
+	});
+	return mods.length ? [...mods, parts[parts.length - 1]].join("+") : shortcut;
+};
+var KeyboardContext = class {
+	_keyMap = /* @__PURE__ */ new Map();
+	get bindings() {
+		return Array.from(this._keyMap.values());
+	}
+	get(binding) {
+		return this._keyMap.get(binding);
+	}
+	bind(config) {
+		config.shortcut = parseShortcut(config.shortcut);
+		this._keyMap.set(config.shortcut, config);
+	}
+	unbind(binding) {
+		this._keyMap.delete(binding);
+	}
+};
+var ROOT = "";
+/** Graph root segment; matches `@dxos/plugin-graph` `Node.RootId`. */
+var GRAPH_ROOT_ID = "root";
+/**
+* Nest an attendable segment under the graph root so plank context inherits root-level bindings.
+* An empty/absent segment resolves to the graph root itself.
+*/
+var nestKeyboardContext = (segment) => segment ? segment === "root" || segment.startsWith(`root/`) ? segment : `${GRAPH_ROOT_ID}/${segment}` : GRAPH_ROOT_ID;
+/**
+* Manages context-aware key bindings.
+*/
+var Keyboard = class Keyboard {
+	static singleton = new Keyboard();
+	_root = new KeyboardContext();
+	_keyMap = /* @__PURE__ */ new Map([[ROOT, this._root]]);
+	_contexts = [ROOT];
+	_keyHandler = this.handleKeyDown.bind(this);
+	_path = ROOT;
+	initialize() {
+		document.addEventListener("keydown", this._keyHandler);
+	}
+	destroy() {
+		document.removeEventListener("keydown", this._keyHandler);
+	}
+	bind = this._root.bind.bind(this._root);
+	unbind = this._root.unbind.bind(this._root);
+	setCurrentContext(path = ROOT) {
+		this._path = path;
+	}
+	getCurrentContext() {
+		return this._path;
+	}
+	getContext(path = ROOT) {
+		let context = this._keyMap.get(path);
+		if (!context) {
+			context = new KeyboardContext();
+			this._keyMap.set(path, context);
+			this._contexts.push(path);
+			this._contexts.sort();
+		}
+		return context;
+	}
+	getBindings() {
+		const bindings = /* @__PURE__ */ new Map();
+		for (let i = 0; i < this._contexts.length; ++i) {
+			const path = this._contexts[i];
+			if (this._path.startsWith(path)) this.getContext(path).bindings.forEach((binding) => {
+				bindings.set(binding.shortcut, binding);
+			});
+		}
+		return Array.from(bindings.values());
+	}
+	async handleKeyDown(event) {
+		const { altKey, ctrlKey, metaKey, shiftKey, key } = event;
+		if (key !== "Alt" && key !== "Control" && key !== "Meta" && key !== "Shift") {
+			const tagName = event.target?.tagName;
+			const isInput = tagName === "INPUT" || tagName === "TEXTAREA" || event.target?.getAttribute("contenteditable");
+			const str = parseShortcut([
+				ctrlKey && "ctrl",
+				shiftKey && "shift",
+				altKey && "alt",
+				metaKey && "meta",
+				key
+			].filter(Boolean).join("+"));
+			for (let i = this._contexts.length - 1; i >= 0; --i) {
+				const path = this._contexts[i];
+				if (this._path.startsWith(path)) {
+					const { data, handler, disableInput } = this.getContext(path).get(str) ?? {};
+					if (handler && (!isInput || !disableInput)) {
+						if (await handler({
+							context: path,
+							shortcut: str,
+							data,
+							event
+						}) !== false) {
+							event.preventDefault();
+							event.stopPropagation();
+						}
+						return;
+					}
+				}
+			}
+		}
+	}
+};
+//#endregion
+//#region src/util.ts
+var ctrl = {
+	macos: "⌃",
+	ios: "⌃",
+	windows: "Ctrl",
+	linux: "Ctrl",
+	unknown: "Ctrl"
+};
+var alt = {
+	macos: "⌥",
+	ios: "⌥",
+	windows: "Alt",
+	linux: "Alt",
+	unknown: "Alt"
+};
+var meta = {
+	macos: "⌘",
+	ios: "⌘",
+	windows: "⊞",
+	linux: "❖",
+	unknown: "❖"
+};
+var getSymbol = (part) => {
+	const platform = getHostPlatform();
+	switch (part.toLowerCase()) {
+		case "alt": return alt[platform];
+		case "ctrl": return ctrl[platform];
+		case "meta": return meta[platform];
+		case "shift": return "⇧";
+		case "backspace": return "⌫";
+		case "enter": return "⏎";
+		case "escape": return "⎋";
+		case "space": return "␣";
+		case "tab": return "⇥";
+		default: return part.toUpperCase();
+	}
+};
+var keySymbols = (keyBinding) => {
+	return keyBinding.split("+").map(getSymbol);
+};
+//#endregion
+export { GRAPH_ROOT_ID, Keyboard, keySymbols, nestKeyboardContext, parseShortcut };
+
+//# sourceMappingURL=index.mjs.map

package/dist/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/keyboard.ts","../../src/util.ts"],"sourcesContent":["//\n// Copyright 2023 DXOS.org\n//\n\nimport { invariant } from '@dxos/invariant';\nimport { type MaybePromise } from '@dxos/util';\n\n// TODO(burdon): Replace with hotkeys-js, react-hotkeys, and react-hotkeys-hook.\n\nexport type KeyHandler = (props: {\n  context: string;\n  shortcut: string;\n  data?: any;\n  event: KeyboardEvent;\n}) => MaybePromise<boolean | void>;\n\nexport type KeyBinding = {\n  shortcut: string;\n  handler: KeyHandler;\n  disableInput?: boolean;\n  data?: any;\n};\n\n// Keybinding is normalized to this order.\n// https://support.apple.com/en-us/HT201236\nconst modifiers = ['ctrl', 'shift', 'alt', 'meta'];\n\n// Normalize order and case of modifiers.\nexport const parseShortcut = (shortcut: string, delimiter = /[+-]/): string => {\n  const parts = shortcut.toLowerCase().split(delimiter);\n  const mods = modifiers.filter((key) => parts.includes(key));\n  invariant(mods.length === 0 || mods.length === parts.length - 1);\n  // Assume single natural key.\n  return mods.length ? [...mods, parts[parts.length - 1]].join('+') : shortcut;\n};\n\nclass KeyboardContext {\n  readonly _keyMap = new Map<string, KeyBinding>();\n\n  get bindings() {\n    return Array.from(this._keyMap.values());\n  }\n\n  get(binding: string): KeyBinding | undefined {\n    return this._keyMap.get(binding);\n  }\n\n  bind(config: KeyBinding): void {\n    config.shortcut = parseShortcut(config.shortcut);\n    this._keyMap.set(config.shortcut, config);\n  }\n\n  unbind(binding: string): void {\n    this._keyMap.delete(binding);\n  }\n}\n\nconst ROOT = '';\n\n/** Graph root segment; matches `@dxos/plugin-graph` `Node.RootId`. */\nexport const GRAPH_ROOT_ID = 'root';\n\n/**\n * Nest an attendable segment under the graph root so plank context inherits root-level bindings.\n * An empty/absent segment resolves to the graph root itself.\n */\nexport const nestKeyboardContext = (segment?: string): string =>\n  segment\n    ? segment === GRAPH_ROOT_ID || segment.startsWith(`${GRAPH_ROOT_ID}/`)\n      ? segment\n      : `${GRAPH_ROOT_ID}/${segment}`\n    : GRAPH_ROOT_ID;\n\n/**\n * Manages context-aware key bindings.\n */\nexport class Keyboard {\n  static singleton = new Keyboard();\n\n  private readonly _root = new KeyboardContext();\n  private readonly _keyMap = new Map<string, KeyboardContext>([[ROOT, this._root]]);\n  private readonly _contexts: string[] = [ROOT];\n  private readonly _keyHandler = this.handleKeyDown.bind(this);\n  private _path = ROOT;\n\n  initialize(): void {\n    document.addEventListener('keydown', this._keyHandler);\n  }\n\n  destroy(): void {\n    document.removeEventListener('keydown', this._keyHandler);\n  }\n\n  bind = this._root.bind.bind(this._root);\n  unbind = this._root.unbind.bind(this._root);\n\n  setCurrentContext(path = ROOT): void {\n    this._path = path;\n  }\n\n  getCurrentContext(): string {\n    return this._path;\n  }\n\n  getContext(path = ROOT): KeyboardContext {\n    let context = this._keyMap.get(path);\n    if (!context) {\n      context = new KeyboardContext();\n      this._keyMap.set(path, context);\n      this._contexts.push(path);\n      this._contexts.sort();\n    }\n\n    return context;\n  }\n\n  getBindings(): KeyBinding[] {\n    const bindings = new Map<string, KeyBinding>();\n    for (let i = 0; i < this._contexts.length; ++i) {\n      const path = this._contexts[i];\n      if (this._path.startsWith(path)) {\n        this.getContext(path).bindings.forEach((binding) => {\n          bindings.set(binding.shortcut, binding);\n        });\n      }\n    }\n\n    return Array.from(bindings.values());\n  }\n\n  async handleKeyDown(event: KeyboardEvent): Promise<void> {\n    const { altKey, ctrlKey, metaKey, shiftKey, key } = event;\n\n    if (key !== 'Alt' && key !== 'Control' && key !== 'Meta' && key !== 'Shift') {\n      // Binding option to check for input or contenteditable.\n      const tagName = (event.target as any)?.tagName;\n      const isInput =\n        tagName === 'INPUT' || tagName === 'TEXTAREA' || (event.target as any)?.getAttribute('contenteditable');\n\n      // Normalized key binding (order and case; see parseShortcut).\n      const str = parseShortcut(\n        [ctrlKey && 'ctrl', shiftKey && 'shift', altKey && 'alt', metaKey && 'meta', key].filter(Boolean).join('+'),\n      );\n\n      // Scan matching contexts.\n      for (let i = this._contexts.length - 1; i >= 0; --i) {\n        const path = this._contexts[i];\n        if (this._path.startsWith(path)) {\n          const { data, handler, disableInput } = this.getContext(path).get(str) ?? {};\n          if (handler && (!isInput || !disableInput)) {\n            const result = await handler({ context: path, shortcut: str, data, event });\n            if (result !== false) {\n              // TODO(burdon): This doesn't prevent actions in markdown editor.\n              //  Reference: https://codemirror.net/docs/ref/#view.KeyBinding\n              event.preventDefault();\n              event.stopPropagation();\n            }\n\n            return;\n          }\n        }\n      }\n    }\n  }\n}\n","//\n// Copyright 2023 DXOS.org\n//\n\nimport { getHostPlatform } from '@dxos/util';\n\n// Resources.\n// https://www.w3.org/TR/DOM-Level-3-Events/#events-keyboardevents\n// https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key\n// https://developer.apple.com/design/human-interface-guidelines/designing-for-macos\n// https://support.apple.com/en-us/HT201236\n// https://support.apple.com/guide/mac-help/what-are-those-symbols-shown-in-menus-cpmh0011/mac\n\nconst ctrl: Record<string, string> = {\n  macos: '⌃',\n  ios: '⌃',\n  windows: 'Ctrl',\n  linux: 'Ctrl',\n  unknown: 'Ctrl',\n};\n\nconst alt: Record<string, string> = {\n  macos: '⌥',\n  ios: '⌥',\n  windows: 'Alt',\n  linux: 'Alt',\n  unknown: 'Alt',\n};\n\nconst meta: Record<string, string> = {\n  macos: '⌘',\n  ios: '⌘',\n  windows: '⊞',\n  // TODO(wittjosiah): Use ⌘ or ⊞ instead? Wait for user feedback.\n  // From https://en.wikipedia.org/wiki/Super_key_(keyboard_button).\n  linux: '❖',\n  unknown: '❖',\n};\n\nconst getSymbol = (part: string) => {\n  const platform = getHostPlatform();\n  switch (part.toLowerCase()) {\n    // Mods.\n    case 'alt':\n      return alt[platform];\n    case 'ctrl':\n      return ctrl[platform];\n    case 'meta':\n      return meta[platform];\n    case 'shift':\n      return '⇧';\n    // Special keys.\n    case 'backspace':\n      return '⌫';\n    case 'enter':\n      return '⏎';\n    case 'escape':\n      return '⎋';\n    case 'space':\n      return '␣';\n    case 'tab':\n      return '⇥';\n    default:\n      return part.toUpperCase();\n  }\n};\n\nexport const keySymbols = (keyBinding: string): string[] => {\n  const parts = keyBinding.split('+');\n  return parts.map(getSymbol);\n};\n"],"mappings":"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"}