@rapidmx/web-client 0.9.0 → 0.10.0

package/apps/shared/keyboard/parse.ts

@@ -0,0 +1,136 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { KeyEnvironment } from "./platform.js";
+
+/** A shortcut such as `ctrl+shift+a`, `alt+n`, `Delete` or `?`, broken into what a key event is compared with. */
+export interface ParsedSpec {
+    /** The spec as written. */
+    spec: string;
+    /** The key, lower-case: a letter or digit, a symbol (`?`, `/`, `.`, `,`), or a named key (`enter`, `delete`, `arrowup`, ...). */
+    key: string;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+    /** Ctrl on Windows and Linux, Cmd on macOS - resolved against the environment by `resolveModifiers()`. */
+    mod: boolean;
+    /** The `KeyboardEvent.code` of the key on a QWERTY keyboard, for layouts where `event.key` is not the letter (see `match.ts`). */
+    code?: string;
+}
+
+const MODIFIERS: Record<string, "ctrl" | "shift" | "alt" | "meta" | "mod"> = {
+    ctrl: "ctrl",
+    control: "ctrl",
+    shift: "shift",
+    alt: "alt",
+    option: "alt",
+    opt: "alt",
+    meta: "meta",
+    cmd: "meta",
+    command: "meta",
+    mod: "mod",
+};
+
+/** Spec spellings of keys whose `event.key` is something else. */
+const KEY_ALIASES: Record<string, string> = {
+    esc: "escape",
+    del: "delete",
+    ins: "insert",
+    return: "enter",
+    up: "arrowup",
+    down: "arrowdown",
+    left: "arrowleft",
+    right: "arrowright",
+    space: " ",
+    spacebar: " ",
+    plus: "+",
+    pgup: "pageup",
+    pgdn: "pagedown",
+};
+
+/** The named keys a spec may use besides a single character and `F1`-`F12`. */
+const NAMED_KEYS = new Set([
+    "escape",
+    "enter",
+    "tab",
+    "backspace",
+    "delete",
+    "insert",
+    "home",
+    "end",
+    "pageup",
+    "pagedown",
+    "arrowup",
+    "arrowdown",
+    "arrowleft",
+    "arrowright",
+]);
+
+const SYMBOL_CODES: Record<string, string> = { "/": "Slash", ".": "Period", ",": "Comma" };
+
+/** The `code` a key has on a QWERTY keyboard, for the keys where one is worth falling back to. */
+function codeFor(key: string): string | undefined {
+    if (/^[a-z]$/.test(key)) {
+        return `Key${key.toUpperCase()}`;
+    }
+    if (/^[0-9]$/.test(key)) {
+        return `Digit${key}`;
+    }
+    return SYMBOL_CODES[key];
+}
+
+/**
+ * Parses a shortcut spec: modifiers and one key joined by `+`, in any order and any case - `ctrl+shift+a`, `Alt+N`, `mod+enter`,
+ * `Delete`, `?`, `ctrl+/`, `ctrl++`. `mod` is Ctrl on Windows/Linux and Cmd on macOS. Throws on a spec that cannot be understood, so a
+ * typo in a key map fails at once rather than silently never matching.
+ */
+export function parseSpec(spec: string): ParsedSpec {
+    // A trailing `+` is the plus key itself (`ctrl++`), which a plain split would lose.
+    const plusKey = spec.length > 1 && spec.endsWith("++");
+    const tokens = (plusKey ? spec.slice(0, -2) : spec).split("+").map((token) => token.trim());
+    if (plusKey) {
+        tokens.push("+");
+    }
+    const parsed: ParsedSpec = { spec, key: "", ctrl: false, shift: false, alt: false, meta: false, mod: false };
+    for (const token of tokens) {
+        if (token === "") {
+            throw new Error(`Invalid shortcut "${spec}": empty part.`);
+        }
+        const lower = token.toLowerCase();
+        const modifier = MODIFIERS[lower];
+        if (modifier) {
+            parsed[modifier] = true;
+            continue;
+        }
+        if (parsed.key !== "") {
+            throw new Error(`Invalid shortcut "${spec}": more than one key.`);
+        }
+        const key = KEY_ALIASES[lower] ?? lower;
+        if ([...key].length > 1 && !NAMED_KEYS.has(key) && !/^f([1-9]|1[0-2])$/.test(key)) {
+            throw new Error(`Invalid shortcut "${spec}": unknown key "${token}".`);
+        }
+        parsed.key = key;
+        parsed.code = codeFor(key);
+    }
+    if (parsed.key === "") {
+        throw new Error(`Invalid shortcut "${spec}": no key.`);
+    }
+    return parsed;
+}
+
+/** The modifiers a spec needs on a given platform, with `mod` turned into Cmd (macOS) or Ctrl. */
+export function resolveModifiers(parsed: ParsedSpec, env: KeyEnvironment): { ctrl: boolean; shift: boolean; alt: boolean; meta: boolean } {
+    return {
+        ctrl: parsed.ctrl || (parsed.mod && !env.mac),
+        shift: parsed.shift,
+        alt: parsed.alt,
+        meta: parsed.meta || (parsed.mod && env.mac),
+    };
+}
+
+/** Whether the key is a printable symbol whose shifted-ness depends on the layout (`?` is Shift+/ on a US keyboard, not on others). */
+export function isSymbolKey(key: string): boolean {
+    return [...key].length === 1 && !/[a-z0-9]/.test(key);
+}

package/apps/shared/keyboard/platform.ts

@@ -0,0 +1,34 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** What the keyboard layer needs to know about where it runs. */
+export interface KeyEnvironment {
+    /** macOS (and iOS/iPadOS): `mod` is Cmd there, and Option is a text-entry modifier. */
+    mac: boolean;
+    /** The desktop client (`electron-client`), which exposes `window.rapidmx` from its preload script. */
+    electron: boolean;
+}
+
+/** What the server render and the first client render use, so the two agree; the real environment is read after mount. */
+export const SERVER_ENVIRONMENT: KeyEnvironment = { mac: false, electron: false };
+
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export function isMacPlatform(): boolean {
+    if (typeof navigator === "undefined") {
+        return false;
+    }
+    const uaData = (navigator as { userAgentData?: { platform?: string } }).userAgentData;
+    return /mac|iphone|ipad|ipod/i.test(uaData?.platform || navigator.platform || "");
+}
+
+/** Whether the page is running inside the desktop client, which is what `window.rapidmx` (its preload's `contextBridge`) tells. */
+export function isElectronClient(): boolean {
+    return typeof window !== "undefined" && (window as { rapidmx?: unknown }).rapidmx !== undefined;
+}
+
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export function currentEnvironment(): KeyEnvironment {
+    return { mac: isMacPlatform(), electron: isElectronClient() };
+}

package/apps/shared/keyboard/registry.ts

@@ -0,0 +1,65 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { RefObject } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import { ParsedSpec } from "./parse.js";
+
+/**
+ * What a handler does with its key. Returning `false` says it did not handle it (nothing selected, a button that is disabled right now)
+ * - the key is then left alone, and a handler of a lower scope may take it. Anything else means it did, and the key is consumed.
+ */
+export type ShortcutHandler = (event: KeyboardEvent) => boolean | void;
+
+/** One mounted view's claim on a shortcut. */
+export interface Registration {
+    /** Unique per registration. */
+    id: number;
+    shortcut: ShortcutDef;
+    scope: ShortcutScope;
+    /** Called at event time; reads whatever the component holds now. */
+    run: ShortcutHandler;
+    /** Applies only to events whose target is inside this element (a compose window). */
+    container?: RefObject<Element | null>;
+    keys: ParsedSpec[];
+    electronKeys: ParsedSpec[];
+    /** Later registrations win over earlier ones in the same scope. */
+    order: number;
+}
+
+/**
+ * The shortcuts that are mounted right now. Components add and remove their claims as they mount and unmount, so a page switch changes
+ * what a key does with nothing to re-wire; the dispatcher (`dispatchKeyEvent()`) looks handlers up here at the time of the key press,
+ * and the help dialog lists what is here.
+ */
+export class ShortcutRegistry {
+    private registrations: readonly Registration[] = [];
+    private counter = 0;
+    private listeners = new Set<() => void>();
+
+    /** Adds a claim; returns what removes it. */
+    add(claim: Omit<Registration, "id" | "order">): () => void {
+        const registration: Registration = { ...claim, id: ++this.counter, order: this.counter };
+        this.registrations = [...this.registrations, registration];
+        this.publish();
+        return () => {
+            this.registrations = this.registrations.filter((existing) => existing.id !== registration.id);
+            this.publish();
+        };
+    }
+
+    /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+    getSnapshot = (): readonly Registration[] => this.registrations;
+
+    subscribe = (listener: () => void): (() => void) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+
+    private publish(): void {
+        this.listeners.forEach((listener) => listener());
+    }
+}

package/apps/shared/keyboard/targets.ts

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** `<input>` types that take no typed text, so a letter pressed on one is a shortcut, not input. (Radios and ranges use the arrows.) */
+const NON_TEXT_INPUT_TYPES = new Set(["button", "checkbox", "submit", "reset", "image", "file", "color"]);
+
+/** Roles whose members have keys of their own (arrows, Enter, Escape, type-ahead): a bare key pressed inside one belongs to the widget. */
+const WIDGET_SELECTOR = [
+    "menu",
+    "menubar",
+    "listbox",
+    "tablist",
+    "tree",
+    "grid",
+    "radiogroup",
+    "slider",
+    "spinbutton",
+    "combobox",
+]
+    .map((role) => `[role="${role}"]`)
+    .join(",");
+
+/** Elements Enter (and Space) already does something on. */
+const ACTIVATABLE_SELECTOR = 'a[href], button, summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"]';
+
+/** An open popup's trigger: Escape closes the popup, so it is not a shortcut then. */
+const OPEN_POPUP_TRIGGER = '[aria-haspopup][aria-expanded="true"], [role="combobox"][aria-expanded="true"]';
+
+function elementOf(target: EventTarget | null): Element | null {
+    return target instanceof Element ? target : null;
+}
+
+/** Whether the event target takes typed text: a text field, a select, a textarea, or anything contenteditable (the rich-text editor). */
+export function isTextEntry(target: EventTarget | null): boolean {
+    const element = elementOf(target);
+    if (!element) {
+        return false;
+    }
+    const tag = element.tagName;
+    if (tag === "TEXTAREA" || tag === "SELECT") {
+        return true;
+    }
+    if (tag === "INPUT") {
+        return !NON_TEXT_INPUT_TYPES.has((element as HTMLInputElement).type);
+    }
+    return !!element.closest('[contenteditable]:not([contenteditable="false"]), [role="textbox"], [role="searchbox"]');
+}
+
+/** Whether the target is inside a widget that reads bare keys itself (an open menu, a listbox, a tab list, ...). */
+export function isInWidget(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(WIDGET_SELECTOR);
+}
+
+/** Whether Enter/Space on the target already activates it (a button, a link, a menu item). */
+export function isActivatable(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(ACTIVATABLE_SELECTOR);
+}
+
+/** Whether the target is the trigger of a popup that is open right now (or the combobox that owns an open list). */
+export function isPopupOpenAt(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest(OPEN_POPUP_TRIGGER);
+}
+
+/** Whether a modal dialog (`aria-modal="true"`: react-shared's `Modal` and `Drawer`, the unlock prompts, ...) is on screen. */
+export function isModalOpen(doc: Document): boolean {
+    return doc.querySelector('[aria-modal="true"]') !== null;
+}
+
+/** Whether the target is inside a popover that is a dialog of its own (the emoji and GIF pickers, the send-later picker): Escape is theirs, not a view's. A region that declares a shortcut scope (a compose window) is not one. */
+export function isInPopoverDialog(target: EventTarget | null): boolean {
+    return !!elementOf(target)?.closest('[role="dialog"]:not([data-shortcut-scope])');
+}
+
+/** The `data-shortcut-scope` of the region the target is in (a compose window), if any. */
+export function regionScopeOf(target: EventTarget | null): string | undefined {
+    return elementOf(target)?.closest("[data-shortcut-scope]")?.getAttribute("data-shortcut-scope") ?? undefined;
+}

package/apps/shared/keyboard/useShortcut.ts

@@ -0,0 +1,50 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { RefObject, useEffect, useMemo, useRef } from "react";
+import type { ShortcutDef, ShortcutScope } from "./keymap.js";
+import { parseSpec } from "./parse.js";
+import type { ShortcutHandler } from "./registry.js";
+import { useShortcutRegistry } from "./ShortcutProvider.js";
+
+export interface UseShortcutOptions {
+    /** Overrides the scope the shortcut is defined with - required for a bare spec string, which has none. Default `global`. */
+    scope?: ShortcutScope;
+    /** Registers only while true: a view offers a shortcut only when it can really do the thing. Default true. */
+    enabled?: boolean;
+    /** Restricts it to events whose target is inside this element (a compose window). */
+    container?: RefObject<Element | null>;
+}
+
+/**
+ * Claims a shortcut for as long as the calling component is mounted (and `enabled`). `shortcut` is an entry of `SHORTCUTS` - which is what
+ * the help dialog and tooltips describe - or a bare spec such as `"alt+n"` for a one-off. The handler is read at the time of the key press,
+ * so it always sees the component's current state without the registration being redone; return `false` from it to decline the key.
+ *
+ * Does nothing outside a `ShortcutProvider`.
+ */
+export function useShortcut(shortcut: ShortcutDef | string, handler: ShortcutHandler, options: UseShortcutOptions = {}): void {
+    const { scope, enabled = true, container } = options;
+    const registry = useShortcutRegistry();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const def = useMemo<ShortcutDef>(
+        () => (typeof shortcut === "string" ? { id: `custom:${shortcut}`, keys: [shortcut], label: shortcut, scope: "global" } : shortcut),
+        [shortcut],
+    );
+    const resolvedScope = scope ?? def.scope;
+    useEffect(() => {
+        if (!registry || !enabled) {
+            return;
+        }
+        return registry.add({
+            shortcut: def,
+            scope: resolvedScope,
+            run: (event) => handlerRef.current(event),
+            container,
+            keys: def.keys.map(parseSpec),
+            electronKeys: (def.electronKeys ?? []).map(parseSpec),
+        });
+    }, [registry, enabled, def, resolvedScope, container]);
+}

package/apps/shared/keyboard/useShortcutProps.ts

@@ -0,0 +1,17 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ariaKeyShortcuts, withHint } from "./format.js";
+import type { ShortcutDef } from "./keymap.js";
+import { useKeyEnvironment } from "./ShortcutProvider.js";
+
+/**
+ * What a control that a keyboard shortcut also triggers gets: a tooltip naming the key - `Reply (Ctrl+R)`, in this platform's own key names -
+ * and `aria-keyshortcuts` for assistive technology. The accessible name is left alone (the control keeps its own label), so a tooltip suffix never
+ * changes what a screen reader or a test finds it by. With `active` false - the shortcut isn't registered right now - it is just the plain label.
+ */
+export function useShortcutProps(label: string, shortcut: ShortcutDef, active = true): { title: string; "aria-keyshortcuts"?: string } {
+    const env = useKeyEnvironment();
+    return active ? { title: withHint(label, shortcut, env), "aria-keyshortcuts": ariaKeyShortcuts(shortcut, env) } : { title: label };
+}