@rapidmx/web-client 0.9.0 → 0.11.0

package/apps/shared/components/sharing/PrincipalPicker.tsx

@@ -0,0 +1,145 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { FormEvent, useEffect, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import {
+    MailboxAccessRole,
+    ResolvedPrincipal,
+    resolveMailboxPrincipal,
+    setMailboxAccess,
+} from "@rapidmx/react-shared/mail/mailboxAccessApi.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+
+export interface PrincipalPickerProps {
+    mailboxUid: string;
+    /** What each access level is called on this page. */
+    roleLabels: Record<MailboxAccessRole, string>;
+    /** Text put in the box to start with - a stored entry being replaced, say. */
+    initialPrincipal?: string;
+    /** The access level pre-selected. */
+    defaultRole?: MailboxAccessRole;
+    /** What the box asks for. */
+    placeholder?: string;
+    /** Called once the grant is saved, with the person it went to. */
+    onGranted: (person: ResolvedPrincipal, role: MailboxAccessRole) => void | Promise<void>;
+    /** Shown as a Cancel button next to the box when set (replacing an entry). */
+    onCancel?: () => void;
+}
+
+/** Who a resolved person is, for a person to check before saving: their name and address, else their uid. */
+export function describePerson(person: ResolvedPrincipal): string {
+    if (person.displayName && person.address) return `${person.displayName} <${person.address}>`;
+    return person.displayName ?? person.address ?? `user ${person.userUid}`;
+}
+
+/**
+ * "Who?" for a sharing screen. What is typed - a mailbox address, an auth-server username or e-mail alias, or a user id -
+ * is RESOLVED by the server (`resolveMailboxPrincipal()`) to the person it names before anything is saved, and the person
+ * is shown (name and address) for the caller to confirm; only then is the grant made, against that person's uid. Free text
+ * is never stored: an ACL record matches a user uid and nothing else, so a grant to a typed username applies to nobody.
+ */
+export default function PrincipalPicker({ mailboxUid, roleLabels, initialPrincipal, defaultRole = "viewer", placeholder, onGranted, onCancel }: PrincipalPickerProps) {
+    const [typed, setTyped] = useState(initialPrincipal ?? "");
+    const [role, setRole] = useState<MailboxAccessRole>(defaultRole);
+    const [person, setPerson] = useState<ResolvedPrincipal | null>(null);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+
+    // A stored entry being replaced is looked up straight away, so its person is shown without a click.
+    useEffect(() => {
+        if (initialPrincipal) {
+            void find(initialPrincipal);
+        }
+    }, [initialPrincipal]);
+
+    async function find(principal: string) {
+        setBusy(true);
+        setError(null);
+        setPerson(null);
+        try {
+            setPerson(await resolveMailboxPrincipal(mailboxUid, principal));
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not look that person up.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    function handleFind(e: FormEvent) {
+        e.preventDefault();
+        const principal = typed.trim();
+        if (principal) {
+            void find(principal);
+        }
+    }
+
+    // Only reachable from the confirm button, which only renders once `person` is set.
+    async function handleGrant() {
+        setBusy(true);
+        setError(null);
+        try {
+            await setMailboxAccess(mailboxUid, person!.userUid, role);
+            await onGranted(person!, role);
+            setTyped("");
+            setPerson(null);
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not grant access.");
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    return (
+        <div className="flex flex-col gap-2">
+            {error && <Alert>{error}</Alert>}
+            <form onSubmit={handleFind} className="flex gap-2">
+                <input
+                    type="text"
+                    aria-label="Who to share with"
+                    placeholder={placeholder ?? "Email address, username or user id"}
+                    className="flex-1 text-sm border border-border rounded-sm py-1.5 px-2 bg-surface text-text"
+                    value={typed}
+                    onChange={(e) => {
+                        setTyped(e.target.value);
+                        setPerson(null);
+                    }}
+                    disabled={busy}
+                />
+                <select
+                    aria-label="Access level"
+                    className="text-sm border border-border rounded-sm py-1.5 px-2 bg-surface text-text"
+                    value={role}
+                    onChange={(e) => setRole(e.target.value as MailboxAccessRole)}
+                    disabled={busy}
+                >
+                    {(Object.keys(roleLabels) as MailboxAccessRole[]).map((value) => (
+                        <option key={value} value={value}>
+                            {roleLabels[value]}
+                        </option>
+                    ))}
+                </select>
+                <Button type="submit" variant="secondary" loading={busy && !person} disabled={busy} className="!w-auto">
+                    Find
+                </Button>
+                {onCancel && (
+                    <Button type="button" variant="text" className="!w-auto" onClick={onCancel}>
+                        Cancel
+                    </Button>
+                )}
+            </form>
+            {person && (
+                <div className="flex items-center justify-between gap-3 text-sm py-2 px-3 border border-border rounded-sm">
+                    <span>
+                        Share with <strong className="break-all">{describePerson(person)}</strong> as <em>{roleLabels[role]}</em>?
+                    </span>
+                    <Button type="button" loading={busy} disabled={busy} className="!w-auto" onClick={() => void handleGrant()}>
+                        Grant
+                    </Button>
+                </div>
+            )}
+        </div>
+    );
+}

package/apps/shared/components/tasks/TasksSidebar.tsx

@@ -7,6 +7,7 @@ import { HiOutlineBars3 } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { Task, TaskList, createTaskList, listTaskLists } from "@rapidmx/react-shared/tasks/tasksApi.js";
 import Drawer from "@rapidmx/react-shared/components/overlays/Drawer.js";
+import { notifyApiError } from "../../notifications/apiErrors.js";
 
 export type TasksView =
     | { type: "myDay" }
@@ -102,7 +103,8 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
             setNewListName("");
             setAddingList(false);
         } catch (err) {
-            setListsError(err instanceof ApiRequestError ? err.message : "Could not create this list.");
+            // A pop-up: `listsError` is only the lists' own load failure.
+            notifyApiError(err, "Couldn't create the list");
         }
     }
 
@@ -184,13 +186,13 @@ export default function TasksSidebar({ mailboxUid, tasks, userUid, active, onSel
         <>
             <button
                 type="button"
-                className="md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
+                className="lg:hidden m-3 mb-0 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
                 aria-label="Open tasks menu"
                 onClick={() => setDrawerOpen(true)}
             >
                 <HiOutlineBars3 size={20} aria-hidden="true" />
             </button>
-            <nav aria-label="Tasks" className="hidden md:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto">
+            <nav aria-label="Tasks" className="hidden lg:flex w-56 shrink-0 border-r border-border flex-col gap-4 p-3 overflow-y-auto">
                 {navContent("desktop")}
             </nav>
             <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Tasks">

package/apps/shared/components/tasks/layout/TasksShell.tsx

@@ -10,6 +10,7 @@ import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shar
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
+import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 
 export type TasksShellProps = Omit<AppShellProps, "active">;
@@ -47,6 +48,7 @@ export default function TasksShell({
     impersonating,
     impersonationBaseUrl,
     trusted,
+    trustedRoles,
     pluginNav,
     children,
 }: PropsWithChildren<TasksShellProps>) {
@@ -58,9 +60,18 @@ export default function TasksShell({
     const [requestedMailboxUid, setRequestedMailboxUid] = useState<string | null>(null);
     const [drawerOpen, setDrawerOpen] = useState(false);
 
+    // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
+    // effect, not during render, so the server render and the hydrating render agree.
+    const search = useLocationSearch();
+    const navigate = useNavigate();
     useEffect(() => {
-        setRequestedMailboxUid(new URLSearchParams(window.location.search).get("mailboxUid"));
-    }, []);
+        setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
+    }, [search]);
+    // Choosing a folder (or mailbox) changes the URL without a page load now, so the drawer that held the choice - which used to go
+    // with the page - is closed here.
+    useEffect(() => {
+        setDrawerOpen(false);
+    }, [search]);
 
     useEffect(() => {
         if (!userUid) {
@@ -144,7 +155,7 @@ export default function TasksShell({
                             className="w-full text-sm border border-border rounded-sm py-1.5 px-2 bg-surface"
                             value={mailboxUid}
                             onChange={(e) => {
-                                window.location.href = `/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`;
+                                navigate(`/tasks?mailboxUid=${encodeURIComponent(e.target.value)}`);
                             }}
                         >
                             {mailboxes.map((mb) => (
@@ -160,19 +171,23 @@ export default function TasksShell({
             </>
         );
 
+        // With a single mailbox and no error this column would be empty: no 224 px of nothing beside the tasks' own menu.
+        const hasSidebar = mailboxes.length > 1 || !!folderError;
         inner = (
             <>
-                <aside className="hidden md:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
-                    {sidebarContent("desktop")}
-                </aside>
+                {hasSidebar && (
+                    <aside className="hidden lg:flex w-56 shrink-0 bg-surface border-r border-border flex-col p-3 gap-3">
+                        {sidebarContent("desktop")}
+                    </aside>
+                )}
                 <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} title="Mailbox">
                     <div className="flex flex-col gap-3">{sidebarContent("mobile")}</div>
                 </Drawer>
                 <main className="flex-1 min-w-0 flex flex-col">
-                    {(mailboxes.length > 1 || folderError) && (
+                    {hasSidebar && (
                         <button
                             type="button"
-                            className="md:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
+                            className="lg:hidden m-3 w-9 h-9 flex items-center justify-center rounded-sm text-text-muted hover:bg-surface-alt hover:text-text"
                             aria-label="Open mailbox switcher"
                             onClick={() => setDrawerOpen(true)}
                         >
@@ -193,6 +208,7 @@ export default function TasksShell({
             impersonating={impersonating}
             impersonationBaseUrl={impersonationBaseUrl}
             trusted={trusted}
+            trustedRoles={trustedRoles}
             pluginNav={pluginNav}
         >
             {inner}

package/apps/shared/keyboard/GlobalShortcuts.tsx

@@ -0,0 +1,51 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { accountUrlOf } from "../auth/accountUrl.js";
+import { APP_HREFS, SETTINGS_HREF, isSettingsPath } from "../navigation/appHrefs.js";
+import { useNavigate } from "../navigation/routerContext.js";
+import { SHORTCUTS } from "./keymap.js";
+import { useShortcut } from "./useShortcut.js";
+
+export interface GlobalShortcutsProps {
+    /** auth-server's base URL - "Go to Account" is offered only when it is set. */
+    authServerUrl?: string;
+    /** Opens the keyboard shortcuts dialog, or closes it if it is open. */
+    onToggleHelp: () => void;
+}
+
+/**
+ * The shortcuts that work in every view: the "Go to ..." navigation set and the keyboard help. Mounted once by `AppChrome`, next to the
+ * `ShortcutProvider`, so it works from Settings and every app alike. Renders nothing.
+ *
+ * In-app places go through the client-side router (`useNavigate()`); Account is another origin, so it is a plain navigation. Asking for the
+ * page you are already on does nothing - but the key is still taken, so the browser doesn't act on it either.
+ */
+export function GlobalShortcuts({ authServerUrl, onToggleHelp }: GlobalShortcutsProps) {
+    const navigate = useNavigate();
+    const accountUrl = accountUrlOf(authServerUrl);
+
+    /** A handler that goes to `href` unless the address bar's path says it is already there. */
+    const goTo = (href: string, isHere: (pathname: string) => boolean) => () => {
+        if (!isHere(window.location.pathname)) {
+            navigate(href);
+        }
+    };
+    const isPath = (path: string) => (pathname: string) => pathname === path;
+
+    useShortcut(SHORTCUTS.global.mail, goTo(APP_HREFS.mail, isPath(APP_HREFS.mail)));
+    useShortcut(SHORTCUTS.global.calendar, goTo(APP_HREFS.calendar, isPath(APP_HREFS.calendar)));
+    useShortcut(SHORTCUTS.global.contacts, goTo(APP_HREFS.contacts, isPath(APP_HREFS.contacts)));
+    useShortcut(SHORTCUTS.global.tasks, goTo(APP_HREFS.tasks, isPath(APP_HREFS.tasks)));
+    useShortcut(SHORTCUTS.global.settings, goTo(SETTINGS_HREF, isSettingsPath));
+    useShortcut(
+        SHORTCUTS.global.account,
+        () => {
+            window.location.href = accountUrl!;
+        },
+        { enabled: !!accountUrl },
+    );
+    useShortcut(SHORTCUTS.global.help, onToggleHelp);
+    return null;
+}

package/apps/shared/keyboard/ShortcutProvider.tsx

@@ -0,0 +1,62 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren, createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { dispatchKeyEvent } from "./dispatch.js";
+import { KeyEnvironment, SERVER_ENVIRONMENT, currentEnvironment } from "./platform.js";
+import { Registration, ShortcutRegistry } from "./registry.js";
+
+interface ShortcutContextValue {
+    registry: ShortcutRegistry;
+    env: KeyEnvironment;
+}
+
+const ShortcutContext = createContext<ShortcutContextValue | null>(null);
+
+/**
+ * The web client's one keyboard layer. Mounted once, by `AppChrome` (the frame that stays mounted as the router swaps pages), so shortcuts
+ * work in every view - mail, calendar, contacts, tasks, settings - and a page change only changes which handlers are registered.
+ *
+ * One `keydown` listener on `document` (bubbling, so what a widget handles itself and `preventDefault()`s is left alone) hands each key to
+ * `dispatchKeyEvent()`. Views claim keys with `useShortcut()`. Outside a provider - an admin page, a component rendered on its own - that
+ * hook does nothing.
+ *
+ * The platform (macOS, the desktop client) is read after mount, never during render, so the server render and hydration agree.
+ */
+export function ShortcutProvider({ children }: PropsWithChildren) {
+    const registry = useMemo(() => new ShortcutRegistry(), []);
+    const [env, setEnv] = useState<KeyEnvironment>(SERVER_ENVIRONMENT);
+    useEffect(() => {
+        setEnv(currentEnvironment());
+    }, []);
+    useEffect(() => {
+        function handleKeyDown(event: KeyboardEvent) {
+            dispatchKeyEvent(registry, event, currentEnvironment(), document);
+        }
+        document.addEventListener("keydown", handleKeyDown);
+        return () => document.removeEventListener("keydown", handleKeyDown);
+    }, [registry]);
+    const value = useMemo(() => ({ registry, env }), [registry, env]);
+    return <ShortcutContext.Provider value={value}>{children}</ShortcutContext.Provider>;
+}
+
+/** The registry, or `null` outside a `ShortcutProvider`. */
+export function useShortcutRegistry(): ShortcutRegistry | null {
+    return useContext(ShortcutContext)?.registry ?? null;
+}
+
+/** The platform as the keyboard layer sees it - `SERVER_ENVIRONMENT` until the client has mounted, and outside a provider. */
+export function useKeyEnvironment(): KeyEnvironment {
+    return useContext(ShortcutContext)?.env ?? SERVER_ENVIRONMENT;
+}
+
+const NO_REGISTRATIONS: readonly Registration[] = [];
+const getNoRegistrations = () => NO_REGISTRATIONS;
+const NEVER = () => () => undefined;
+
+/** Everything registered right now, updating as views mount and unmount - what the help dialog lists. Empty outside a provider. */
+export function useRegisteredShortcuts(): readonly Registration[] {
+    const registry = useShortcutRegistry();
+    return useSyncExternalStore(registry?.subscribe ?? NEVER, registry?.getSnapshot ?? getNoRegistrations, getNoRegistrations);
+}

package/apps/shared/keyboard/ShortcutsDialog.tsx

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
+import { formatSpec, specsFor } from "./format.js";
+import { HELP_SCOPES, SCOPE_LABELS, SHORTCUTS, ShortcutDef, shortcutRank } from "./keymap.js";
+import { useKeyEnvironment, useRegisteredShortcuts } from "./ShortcutProvider.js";
+import { useShortcut } from "./useShortcut.js";
+
+export interface ShortcutsDialogProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+function Keys({ shortcut }: { shortcut: ShortcutDef }) {
+    const env = useKeyEnvironment();
+    return (
+        <span className="flex flex-wrap justify-end gap-x-1.5 gap-y-1 shrink-0">
+            {specsFor(shortcut, env).map((spec, index) => (
+                <React.Fragment key={spec}>
+                    {index > 0 && <span className="text-xs text-text-muted self-center">or</span>}
+                    <kbd className="px-1.5 py-0.5 rounded-sm border border-border bg-surface-alt text-xs font-sans font-semibold whitespace-nowrap">
+                        {formatSpec(spec, env)}
+                    </kbd>
+                </React.Fragment>
+            ))}
+        </span>
+    );
+}
+
+/**
+ * The keyboard shortcuts help dialog: what can be done from the keyboard *here*. It lists what is registered right now (see
+ * `useRegisteredShortcuts()`), so it shows the global shortcuts and those of the view that is on screen - and the compose window's while one
+ * is open - in groups, with the platform's own key names (Ctrl or Cmd, Alt or Option), and in the desktop client also the keys only it has.
+ * A shortcut a view cannot do at the moment (no message selected) is not registered, and so not listed.
+ *
+ * Built on `Modal`: focus moves into the dialog and stays there, Escape closes it, and it has an accessible name. `?` and Ctrl+/ close it too.
+ */
+export default function ShortcutsDialog({ open, onClose }: ShortcutsDialogProps) {
+    // Mounted only while open: the body subscribes to the registry, which every view's shortcuts change as it mounts - not something the
+    // whole app should re-render for while the dialog is closed.
+    return open ? <ShortcutsDialogBody onClose={onClose} /> : null;
+}
+
+function ShortcutsDialogBody({ onClose }: { onClose: () => void }) {
+    const registrations = useRegisteredShortcuts();
+    useShortcut(SHORTCUTS.global.help, onClose, { scope: "dialog" });
+    const groups = HELP_SCOPES.map((scope) => {
+        const listed = new Map<string, ShortcutDef>();
+        for (const registration of registrations) {
+            if (registration.scope === scope) {
+                listed.set(registration.shortcut.id, registration.shortcut);
+            }
+        }
+        return { scope, shortcuts: [...listed.values()].sort((a, b) => shortcutRank(a) - shortcutRank(b)) };
+    }).filter((group) => group.shortcuts.length > 0);
+
+    return (
+        <Modal open onClose={onClose} title="Keyboard shortcuts">
+            <div className="flex flex-col gap-5">
+                {groups.map(({ scope, shortcuts }) => (
+                    <section key={scope} aria-labelledby={`shortcuts-${scope}`}>
+                        <h3 id={`shortcuts-${scope}`} className="text-xs font-bold uppercase tracking-wide text-text-muted mb-2">
+                            {SCOPE_LABELS[scope]}
+                        </h3>
+                        <ul className="flex flex-col gap-1.5">
+                            {shortcuts.map((shortcut) => (
+                                <li key={shortcut.id} className="flex items-start justify-between gap-4 text-sm">
+                                    <span>{shortcut.label}</span>
+                                    <Keys shortcut={shortcut} />
+                                </li>
+                            ))}
+                        </ul>
+                    </section>
+                ))}
+                <p className="text-xs text-text-muted border-t border-border pt-3">
+                    Some browsers keep a few keys for themselves, so a shortcut may not work everywhere.
+                </p>
+            </div>
+        </Modal>
+    );
+}

package/apps/shared/keyboard/dispatch.ts

@@ -0,0 +1,124 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import type { ShortcutScope } from "./keymap.js";
+import { matchesEvent } from "./match.js";
+import { ParsedSpec, resolveModifiers } from "./parse.js";
+import type { KeyEnvironment } from "./platform.js";
+import type { Registration, ShortcutRegistry } from "./registry.js";
+import { isActivatable, isInPopoverDialog, isInWidget, isModalOpen, isPopupOpenAt, isTextEntry, regionScopeOf } from "./targets.js";
+
+/** The keys of the four view scopes: only the mounted view has registrations, so precedence among them is moot. */
+const VIEW_SCOPES: readonly ShortcutScope[] = ["mail", "calendar", "contacts", "tasks"];
+
+/** Keys that move the caret or delete text, which a text field owns even with Ctrl or Alt held (word jumps, delete-word). */
+const EDITING_KEYS = new Set(["arrowup", "arrowdown", "arrowleft", "arrowright", "home", "end", "pageup", "pagedown", "backspace", "delete"]);
+
+/** The Copy / Cut / Paste / Select all / Undo / Redo / Find chords: never a shortcut, anywhere - they act on the page's selection, not on a view. */
+function isReservedChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && !modifiers.shift && ["a", "c", "v", "x", "z", "y", "f"].includes(parsed.key);
+}
+
+/** Paste as plain text (Ctrl+Shift+V) and Redo (Ctrl+Shift+Z): text-editing chords in a field, free everywhere else (Ctrl+Shift+V is Move to). */
+function isShiftedEditingChord(parsed: ParsedSpec, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    return (modifiers.ctrl || modifiers.meta) && !modifiers.alt && modifiers.shift && ["z", "v"].includes(parsed.key);
+}
+
+/**
+ * Whether `parsed` may fire with the event on this target.
+ *
+ * A text field (input, textarea, select, contenteditable - the rich-text editor) keeps everything that types or edits: bare keys
+ * (`j`, `?`, Delete), the caret keys with any modifier, and paste-as-plain-text and redo. A chord with Ctrl/Cmd/Alt works from one (that is how Ctrl+Enter sends from
+ * the body), except that Option on a Mac and Ctrl+Alt (AltGr) elsewhere type characters, so those don't. Escape works from a field unless a
+ * popup it owns is open (or it is in a popover dialog of its own). Outside a field, a bare key still isn't taken from a widget that reads keys itself (an open menu, a list box), and
+ * Enter/Space are left to the button or link that has the focus - unless the shortcut asked for them.
+ */
+function allowedOnTarget(registration: Registration, parsed: ParsedSpec, target: EventTarget | null, env: KeyEnvironment): boolean {
+    const modifiers = resolveModifiers(parsed, env);
+    const command = modifiers.ctrl || modifiers.meta || modifiers.alt;
+    if (parsed.key === "escape" && (isPopupOpenAt(target) || isInPopoverDialog(target))) {
+        return false;
+    }
+    if (isTextEntry(target)) {
+        if (parsed.key === "escape") {
+            return true;
+        }
+        if (!command || EDITING_KEYS.has(parsed.key) || isShiftedEditingChord(parsed, env)) {
+            return false;
+        }
+        return !(modifiers.alt && !modifiers.meta && (env.mac || modifiers.ctrl));
+    }
+    if (!command) {
+        if (isInWidget(target)) {
+            return false;
+        }
+        if ((parsed.key === "enter" || parsed.key === " ") && !registration.shortcut.allowOnActivatable && isActivatable(target)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** The scopes that may act on this event, highest precedence first. */
+function activeScopes(event: KeyboardEvent, doc: Document): readonly ShortcutScope[] {
+    if (isModalOpen(doc)) {
+        return ["dialog"];
+    }
+    if (regionScopeOf(event.target) === "compose") {
+        return ["compose", "global"];
+    }
+    return [...VIEW_SCOPES, "global"];
+}
+
+/** Whether the registration applies to where the event happened (a compose window's shortcuts only inside it). */
+function inContainer(registration: Registration, event: KeyboardEvent): boolean {
+    if (!registration.container) {
+        return true;
+    }
+    return !!registration.container.current?.contains(event.target as Node | null);
+}
+
+/**
+ * Handles one `keydown`: finds the registered shortcut it is, and runs its handler. Returns whether a handler ran - and only then is the
+ * event's default prevented and its propagation stopped, so a key nobody claims (or a handler that declines) behaves exactly as if this layer
+ * did not exist.
+ *
+ * Skipped outright: an event some other handler already `defaultPrevented` (a menu, the rich-text editor's own bindings), one from an IME
+ * composition, a bare modifier key, and the Copy/Cut/Paste/Select all/Undo/Redo/Find chords. A held key repeats: an action that is not
+ * marked `repeat` runs on the first press only, and the repeats are swallowed (so a browser doesn't reload on a held Ctrl+R) without running it.
+ *
+ * Which registration wins: the dialog scope alone while a modal is open; else, inside a compose window, `compose` then `global`; else
+ * whichever view is mounted, then `global`. Within a scope the most recently mounted registration goes first, and one that returns
+ * `false` passes the key on to the next.
+ */
+export function dispatchKeyEvent(registry: ShortcutRegistry, event: KeyboardEvent, env: KeyEnvironment, doc: Document): boolean {
+    if (event.defaultPrevented || event.isComposing || event.key === "Process" || ["Control", "Shift", "Alt", "Meta"].includes(event.key)) {
+        return false;
+    }
+    const scopes = activeScopes(event, doc);
+    const candidates = registry
+        .getSnapshot()
+        .filter((registration) => scopes.includes(registration.scope) && inContainer(registration, event))
+        .sort((a, b) => scopes.indexOf(a.scope) - scopes.indexOf(b.scope) || b.order - a.order);
+    for (const registration of candidates) {
+        const specs = env.electron ? [...registration.keys, ...registration.electronKeys] : registration.keys;
+        const parsed = specs.find((spec) => matchesEvent(spec, event, env));
+        if (!parsed || isReservedChord(parsed, env) || !allowedOnTarget(registration, parsed, event.target, env)) {
+            continue;
+        }
+        if (event.repeat && !registration.shortcut.repeat) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+        if (registration.run(event) !== false) {
+            event.preventDefault();
+            event.stopPropagation();
+            return true;
+        }
+    }
+    return false;
+}