@rapidmx/web-client 0.9.0 → 0.11.0

package/dist/apps/shared/keyboard/keymap.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Where a shortcut applies. `global` works in every view; a view scope (`mail`, `calendar`, `contacts`, `tasks`) exists only while that
+ * view is mounted; `compose` applies while focus is inside a compose window; `dialog` is for what a modal dialog binds itself - a
+ * dialog on screen silences every other scope.
+ */
+export type ShortcutScope = "global" | "mail" | "compose" | "calendar" | "contacts" | "tasks" | "dialog";
+/** The scopes the help dialog lists, in the order it lists them. */
+export declare const HELP_SCOPES: readonly ShortcutScope[];
+export declare const SCOPE_LABELS: Record<ShortcutScope, string>;
+/** One action the keyboard can trigger, and the keys that trigger it. Views register handlers for these; nothing else defines a key. */
+export interface ShortcutDef {
+    /** Stable name, unique across the map - what the help dialog de-duplicates on. */
+    id: string;
+    /** Specs (see `parseSpec()`) that trigger it, the first being the one shown first. `mod` is Ctrl, or Cmd on macOS. */
+    keys: readonly string[];
+    /** Extra specs that apply only in the desktop client, where the browser's own reserved keys (Ctrl+N, Ctrl+T) are the app's. */
+    electronKeys?: readonly string[];
+    /** What the help dialog and a button's tooltip call it. */
+    label: string;
+    scope: ShortcutScope;
+    /** Fires from a focused button or link too (Enter on a message row); by default Enter/Space are left to what has the focus. */
+    allowOnActivatable?: boolean;
+    /** Keeps firing while the key is held (arrows); by default a held key runs a one-shot action once. */
+    repeat?: boolean;
+}
+/**
+ * The whole key map, in the order the help dialog lists it. The navigation set is literally Ctrl+Shift+<letter> on every platform (Cmd+Shift
+ * on macOS collides with the browsers' own - Cmd+Shift+A/B/C/L/M/S are tab search, the bookmarks bar, Inspect, the sidebar, the profile
+ * switcher and Save As - so it is not offered); the mail actions use `mod`, so Reply is Ctrl+R on Windows and Linux and Cmd+R on a Mac.
+ * Ctrl+Q (mark read) stays Ctrl on a Mac because Cmd+Q is the system's Quit.
+ */
+export declare const SHORTCUTS: {
+    readonly global: {
+        readonly account: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly settings: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly contacts: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly mail: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly calendar: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly tasks: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "global";
+        };
+        readonly help: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "global";
+        };
+    };
+    readonly mail: {
+        readonly create: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly reply: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly replyAll: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly forward: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly delete: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly archive: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly move: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly markRead: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly markUnread: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly flag: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly next: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+            repeat: true;
+        };
+        readonly previous: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+            repeat: true;
+        };
+        readonly nextUnread: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly previousUnread: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly open: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+            allowOnActivatable: true;
+        };
+        readonly close: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+        readonly search: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "mail";
+        };
+    };
+    readonly compose: {
+        readonly create: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "compose";
+        };
+        readonly send: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "compose";
+        };
+        readonly saveDraft: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "compose";
+        };
+        readonly close: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "compose";
+        };
+    };
+    readonly calendar: {
+        readonly create: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "calendar";
+        };
+        readonly today: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+        };
+        readonly previous: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+            repeat: true;
+        };
+        readonly next: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+            repeat: true;
+        };
+        readonly day: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+        };
+        readonly workWeek: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+        };
+        readonly week: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+        };
+        readonly month: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "calendar";
+        };
+    };
+    readonly contacts: {
+        readonly create: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "contacts";
+        };
+        readonly search: {
+            id: string;
+            keys: string[];
+            label: string;
+            scope: "contacts";
+        };
+    };
+    readonly tasks: {
+        readonly create: {
+            id: string;
+            keys: string[];
+            electronKeys: string[];
+            label: string;
+            scope: "tasks";
+        };
+    };
+};
+/** Every shortcut of the map flattened, in listing order. */
+export declare const ALL_SHORTCUTS: readonly ShortcutDef[];
+/** Where a shortcut sits in the listing, for ordering registrations that arrive in whatever order components mount. */
+export declare function shortcutRank(shortcut: ShortcutDef): number;

package/dist/apps/shared/keyboard/keymap.js

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The scopes the help dialog lists, in the order it lists them. */
+export const HELP_SCOPES = ["global", "mail", "compose", "calendar", "contacts", "tasks"];
+export const SCOPE_LABELS = {
+    global: "Global",
+    mail: "Mail",
+    compose: "Compose",
+    calendar: "Calendar",
+    contacts: "Contacts",
+    tasks: "Tasks",
+    dialog: "Dialog",
+};
+function def(shortcut) {
+    return shortcut;
+}
+/**
+ * The whole key map, in the order the help dialog lists it. The navigation set is literally Ctrl+Shift+<letter> on every platform (Cmd+Shift
+ * on macOS collides with the browsers' own - Cmd+Shift+A/B/C/L/M/S are tab search, the bookmarks bar, Inspect, the sidebar, the profile
+ * switcher and Save As - so it is not offered); the mail actions use `mod`, so Reply is Ctrl+R on Windows and Linux and Cmd+R on a Mac.
+ * Ctrl+Q (mark read) stays Ctrl on a Mac because Cmd+Q is the system's Quit.
+ */
+export const SHORTCUTS = {
+    global: {
+        account: def({ id: "go.account", keys: ["ctrl+shift+a"], label: "Go to Account", scope: "global" }),
+        settings: def({ id: "go.settings", keys: ["ctrl+shift+s"], label: "Go to Settings", scope: "global" }),
+        contacts: def({ id: "go.contacts", keys: ["ctrl+shift+b"], label: "Go to Contacts", scope: "global" }),
+        mail: def({ id: "go.mail", keys: ["ctrl+shift+m"], label: "Go to Mail", scope: "global" }),
+        calendar: def({ id: "go.calendar", keys: ["ctrl+shift+c"], label: "Go to Calendar", scope: "global" }),
+        tasks: def({ id: "go.tasks", keys: ["ctrl+shift+l"], electronKeys: ["ctrl+shift+t"], label: "Go to Tasks", scope: "global" }),
+        help: def({ id: "help", keys: ["?", "ctrl+/"], label: "Keyboard shortcuts", scope: "global" }),
+    },
+    mail: {
+        create: def({ id: "mail.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New message", scope: "mail" }),
+        reply: def({ id: "mail.reply", keys: ["mod+r"], label: "Reply", scope: "mail" }),
+        replyAll: def({ id: "mail.replyAll", keys: ["mod+shift+r"], label: "Reply all", scope: "mail" }),
+        forward: def({ id: "mail.forward", keys: ["mod+shift+f"], label: "Forward", scope: "mail" }),
+        delete: def({ id: "mail.delete", keys: ["mod+d", "delete"], label: "Delete", scope: "mail" }),
+        archive: def({ id: "mail.archive", keys: ["e", "backspace"], label: "Archive", scope: "mail" }),
+        move: def({ id: "mail.move", keys: ["mod+shift+v"], label: "Move to folder", scope: "mail" }),
+        markRead: def({ id: "mail.markRead", keys: ["ctrl+q"], label: "Mark as read", scope: "mail" }),
+        markUnread: def({ id: "mail.markUnread", keys: ["mod+u"], label: "Mark as unread", scope: "mail" }),
+        flag: def({ id: "mail.flag", keys: ["insert"], label: "Flag or unflag", scope: "mail" }),
+        next: def({ id: "mail.next", keys: ["arrowdown", "j"], label: "Next message", scope: "mail", repeat: true }),
+        previous: def({ id: "mail.previous", keys: ["arrowup", "k"], label: "Previous message", scope: "mail", repeat: true }),
+        nextUnread: def({ id: "mail.nextUnread", keys: ["ctrl+."], label: "Next unread message", scope: "mail" }),
+        previousUnread: def({ id: "mail.previousUnread", keys: ["ctrl+,"], label: "Previous unread message", scope: "mail" }),
+        open: def({ id: "mail.open", keys: ["enter"], label: "Open the message on its own page", scope: "mail", allowOnActivatable: true }),
+        close: def({ id: "mail.close", keys: ["escape"], label: "Clear the selection", scope: "mail" }),
+        search: def({ id: "mail.search", keys: ["/", "mod+e"], label: "Search mail", scope: "mail" }),
+    },
+    compose: {
+        create: def({ id: "compose.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New message", scope: "compose" }),
+        send: def({ id: "compose.send", keys: ["mod+enter"], label: "Send", scope: "compose" }),
+        saveDraft: def({ id: "compose.saveDraft", keys: ["mod+s"], label: "Save draft", scope: "compose" }),
+        close: def({ id: "compose.close", keys: ["escape"], label: "Close (keeps the draft)", scope: "compose" }),
+    },
+    calendar: {
+        create: def({ id: "calendar.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New event", scope: "calendar" }),
+        today: def({ id: "calendar.today", keys: ["t"], label: "Go to today", scope: "calendar" }),
+        previous: def({ id: "calendar.previous", keys: ["arrowleft", "mod+arrowleft"], label: "Previous period", scope: "calendar", repeat: true }),
+        next: def({ id: "calendar.next", keys: ["arrowright", "mod+arrowright"], label: "Next period", scope: "calendar", repeat: true }),
+        day: def({ id: "calendar.day", keys: ["ctrl+alt+1"], label: "Day view", scope: "calendar" }),
+        workWeek: def({ id: "calendar.workWeek", keys: ["ctrl+alt+2"], label: "Work week view", scope: "calendar" }),
+        week: def({ id: "calendar.week", keys: ["ctrl+alt+3"], label: "Week view", scope: "calendar" }),
+        month: def({ id: "calendar.month", keys: ["ctrl+alt+4"], label: "Month view", scope: "calendar" }),
+    },
+    contacts: {
+        create: def({ id: "contacts.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New contact", scope: "contacts" }),
+        search: def({ id: "contacts.search", keys: ["/", "mod+e"], label: "Search contacts", scope: "contacts" }),
+    },
+    tasks: {
+        create: def({ id: "tasks.new", keys: ["alt+n"], electronKeys: ["mod+n"], label: "New task", scope: "tasks" }),
+    },
+};
+/** Every shortcut of the map flattened, in listing order. */
+export const ALL_SHORTCUTS = Object.values(SHORTCUTS).flatMap((group) => Object.values(group));
+/** Where a shortcut sits in the listing, for ordering registrations that arrive in whatever order components mount. */
+export function shortcutRank(shortcut) {
+    const index = ALL_SHORTCUTS.findIndex((candidate) => candidate.id === shortcut.id);
+    return index === -1 ? ALL_SHORTCUTS.length : index;
+}

package/dist/apps/shared/keyboard/match.d.ts

@@ -0,0 +1,20 @@
+import { ParsedSpec } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+/** The part of a `KeyboardEvent` matching reads. */
+export interface KeyEventLike {
+    key: string;
+    code?: string;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Whether a key event is the shortcut `parsed`, on `env`.
+ *
+ * The key is matched on `event.key` (case-insensitively), so a shortcut means the letter on the key cap on any layout that has it -
+ * Dvorak, AZERTY - and falls back to `event.code` only when `event.key` is not a Latin character at all: macOS Option+N produces a
+ * dead key or `~`-like symbol, and a Cyrillic or Greek layout produces `ф`/`α` for the key that is A on a QWERTY board. Modifiers must
+ * match exactly (Ctrl+Shift+R is not Ctrl+R), except Shift for a printable symbol, which some layouts need to type it (`?`).
+ */
+export declare function matchesEvent(parsed: ParsedSpec, event: KeyEventLike, env: KeyEnvironment): boolean;

package/dist/apps/shared/keyboard/match.js

@@ -0,0 +1,31 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { isSymbolKey, resolveModifiers } from "./parse.js";
+/** Whether `key` is what a Latin layout produces for a printable key: then `event.key` says which key it is, whatever `event.code` is. */
+function isAsciiKey(key) {
+    return /^[\x21-\x7e]$/.test(key);
+}
+/**
+ * Whether a key event is the shortcut `parsed`, on `env`.
+ *
+ * The key is matched on `event.key` (case-insensitively), so a shortcut means the letter on the key cap on any layout that has it -
+ * Dvorak, AZERTY - and falls back to `event.code` only when `event.key` is not a Latin character at all: macOS Option+N produces a
+ * dead key or `~`-like symbol, and a Cyrillic or Greek layout produces `ф`/`α` for the key that is A on a QWERTY board. Modifiers must
+ * match exactly (Ctrl+Shift+R is not Ctrl+R), except Shift for a printable symbol, which some layouts need to type it (`?`).
+ */
+export function matchesEvent(parsed, event, env) {
+    const modifiers = resolveModifiers(parsed, env);
+    if (event.ctrlKey !== modifiers.ctrl || event.altKey !== modifiers.alt || event.metaKey !== modifiers.meta) {
+        return false;
+    }
+    if (event.shiftKey !== modifiers.shift && !(isSymbolKey(parsed.key) && !parsed.shift)) {
+        return false;
+    }
+    const key = (event.key ?? "").toLowerCase();
+    if (key === parsed.key) {
+        return true;
+    }
+    return !!parsed.code && event.code === parsed.code && !isAsciiKey(key);
+}

package/dist/apps/shared/keyboard/parse.d.ts

@@ -0,0 +1,31 @@
+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;
+}
+/**
+ * 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 declare function parseSpec(spec: string): ParsedSpec;
+/** The modifiers a spec needs on a given platform, with `mod` turned into Cmd (macOS) or Ctrl. */
+export declare function resolveModifiers(parsed: ParsedSpec, env: KeyEnvironment): {
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+};
+/** Whether the key is a printable symbol whose shifted-ness depends on the layout (`?` is Shift+/ on a US keyboard, not on others). */
+export declare function isSymbolKey(key: string): boolean;

package/dist/apps/shared/keyboard/parse.js

@@ -0,0 +1,107 @@
+const MODIFIERS = {
+    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 = {
+    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 = { "/": "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) {
+    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) {
+    // 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 = { 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, env) {
+    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) {
+    return [...key].length === 1 && !/[a-z0-9]/.test(key);
+}

package/dist/apps/shared/keyboard/platform.d.ts

@@ -0,0 +1,15 @@
+/** 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 declare const SERVER_ENVIRONMENT: KeyEnvironment;
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export declare function isMacPlatform(): boolean;
+/** Whether the page is running inside the desktop client, which is what `window.rapidmx` (its preload's `contextBridge`) tells. */
+export declare function isElectronClient(): boolean;
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export declare function currentEnvironment(): KeyEnvironment;

package/dist/apps/shared/keyboard/platform.js

@@ -0,0 +1,22 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** 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 = { mac: false, electron: false };
+/** Whether this is an Apple platform. Prefers `navigator.userAgentData` (Chromium), then the older `navigator.platform`. */
+export function isMacPlatform() {
+    if (typeof navigator === "undefined") {
+        return false;
+    }
+    const uaData = navigator.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() {
+    return typeof window !== "undefined" && window.rapidmx !== undefined;
+}
+/** The environment as it is right now. Only meaningful in a browser: on the server it is `SERVER_ENVIRONMENT`. */
+export function currentEnvironment() {
+    return { mac: isMacPlatform(), electron: isElectronClient() };
+}

package/dist/apps/shared/keyboard/registry.d.ts

@@ -0,0 +1,39 @@
+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 declare class ShortcutRegistry {
+    private registrations;
+    private counter;
+    private listeners;
+    /** Adds a claim; returns what removes it. */
+    add(claim: Omit<Registration, "id" | "order">): () => void;
+    /** The current claims, oldest first. A new array whenever they change (so it can be a `useSyncExternalStore()` snapshot). */
+    getSnapshot: () => readonly Registration[];
+    subscribe: (listener: () => void) => (() => void);
+    private publish;
+}