@openpresentation/opf-editor 0.29.0 → 0.30.0

package/dist/icons.js

@@ -0,0 +1,88 @@
+// CE-29: icons the host can replace. Every editor part that draws an icon builds it through `resolveIcon`, so a host that passes
+// `icons: { <name>: <icon> }` swaps it for its own (an SVG element, a function returning one, or SVG path data) and the default stays
+// otherwise. Plain DOM, no framework, no network. The built-in icons are Lucide paths (ISC license), inlined by the parts.
+const SVG_NS = "http://www.w3.org/2000/svg";
+// SVG path data: commands, numbers, separators. Anything else (markup, a URL) is not a path and is rejected.
+const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9eE+\-.,\s]+$/;
+
+const isSvgElement = (value) => Boolean(value) && typeof value === "object" && value.nodeType === 1 && String(value.localName).toLowerCase() === "svg";
+const isPathData = (value) => typeof value === "string" && value.trim() !== "" && PATH_DATA.test(value);
+
+function describeError(label) {
+  return `${label} must be an SVG element, a function returning one, or SVG path data (24x24, stroked, currentColor).`;
+}
+
+/**
+ * Check a part's `icons` option: an object whose keys are in `names` and whose values are an SVG element, a function, path data or null.
+ * Returns a plain copy ({} for undefined); throws a TypeError for a bad shape or value and a RangeError for a name the part does not have,
+ * so a typo does not silently do nothing.
+ */
+export function normalizeIcons(icons, names, label = "icons") {
+  if (icons === undefined || icons === null) return {};
+  if (typeof icons !== "object" || Array.isArray(icons) || isSvgElement(icons)) throw new TypeError(`${label} must be an object of icon names and icons.`);
+  const out = {};
+  for (const [name, value] of Object.entries(icons)) {
+    if (!names.includes(name)) throw new RangeError(`${label}: "${name}" is not an icon of this part. Use one of ${names.join(", ")}.`);
+    if (value === undefined || value === null) continue;
+    if (typeof value !== "function" && !isSvgElement(value) && !isPathData(value)) throw new TypeError(describeError(`${label}.${name}`));
+    out[name] = value;
+  }
+  return out;
+}
+
+function decorate(svg, name, className) {
+  svg.classList.add("opf-icon");
+  if (className) for (const extra of String(className).split(/\s+/).filter(Boolean)) svg.classList.add(extra);
+  svg.setAttribute("aria-hidden", "true");
+  svg.setAttribute("focusable", "false");
+  if (name) svg.setAttribute("data-opf-icon", name);
+  return svg;
+}
+
+function builtin(doc, shapes) {
+  const svg = doc.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("stroke-width", "2");
+  svg.setAttribute("stroke-linecap", "round");
+  svg.setAttribute("stroke-linejoin", "round");
+  for (const [tag, attributes] of shapes) {
+    const node = doc.createElementNS(SVG_NS, tag);
+    for (const [key, value] of Object.entries(attributes)) node.setAttribute(key, String(value));
+    svg.append(node);
+  }
+  return svg;
+}
+
+/**
+ * The icon for one place in a part, as `<svg class="opf-icon" aria-hidden="true" focusable="false">`.
+ *
+ * `given` is the host's choice: an SVG element (cloned into `doc`, never moved), a function that returns one (called with `doc`; it may also
+ * return path data), or SVG path data for a 24x24 icon drawn as a 2px round stroke in `currentColor`. `null` or `undefined` (or a function
+ * that returns nothing) means the default, `fallback`: path data, or a list of `[tag, attributes]` shapes for the few built-in icons that
+ * are more than one stroked path (a filled dot, a circle with a dash). With neither, the result is null.
+ *
+ * `options`: `name` (written as `data-opf-icon`, so CSS can target one icon), `className` (added after `opf-icon`, for the part's own class)
+ * and `size` (the `width` and `height` attributes, in px; a host element that sets its own keeps them, and the part's CSS overrides either).
+ * Throws a TypeError for a given value that is none of the three forms.
+ */
+export function resolveIcon(doc, given, fallback, options = {}) {
+  const { name, className, size } = options;
+  let source = given;
+  if (typeof source === "function") source = source(doc);
+  const finish = (svg) => {
+    if (size !== undefined && !svg.hasAttribute("width") && !svg.hasAttribute("height")) {
+      svg.setAttribute("width", String(size));
+      svg.setAttribute("height", String(size));
+    }
+    return decorate(svg, name, className);
+  };
+  if (source !== undefined && source !== null) {
+    if (isSvgElement(source)) return finish(doc.importNode(source, true));
+    if (isPathData(source)) return finish(builtin(doc, [["path", { d: source }]]));
+    throw new TypeError(describeError("An icon"));
+  }
+  if (fallback === undefined || fallback === null) return null;
+  return finish(builtin(doc, typeof fallback === "string" ? [["path", { d: fallback }]] : fallback));
+}

package/dist/presenter.d.ts

@@ -1,3 +1,4 @@
+import type { OpfIcons } from "./icons.js";
 import type { EditorSession } from "./index.js";
 import type { ToSvgOptions } from "@openpresentation/opf-render";
 import type { EditorFonts } from "./canvas.js";
@@ -85,6 +86,8 @@ export interface PresentButtonOptions {
   label?: string;
   /** `"quiet"` (default): a transparent icon button like the toolbar's undo and redo. `"primary"`: the filled accent look of the Export trigger. */
   variant?: "quiet" | "primary";
+  /** Replace the icon: `present` (the slide on a stand). See `OpfIcon`. */
+  icons?: OpfIcons<"present">;
 }
 
 export interface PresentButton {

package/dist/presenter.js

@@ -7,6 +7,7 @@ import { toSvg } from "@openpresentation/opf-render/svg";
 import { mergeCatalogs } from "./catalogs.js";
 import { el, icon } from "./export-dom.js";
 import { whenFontsReady } from "./font-gate.js";
+import { normalizeIcons, resolveIcon } from "./icons.js";
 import { formatSlideCounter } from "./slide-navigator.js";
 
 const COUNTER_MS = 2000;
@@ -439,7 +440,7 @@ function isInteractiveTarget(target) {
  *
  * Options: `onPresent(event)`, `disabled` (`true`, or a string that says why and is the title), `density` (`"comfortable"` 32px, or `"touch"` 40px)
  * `label` (the accessible name, default "Present") and `variant` (`"quiet"`, the default: a transparent icon button like the toolbar's undo and redo,
- * or `"primary"`: the filled accent look of the Export trigger). A disabled button stays focusable (`aria-disabled`) and does nothing.
+ * or `"primary"`: the filled accent look of the Export trigger) and `icons` (`{ present }`, see `src/icons.js`). A disabled button stays focusable (`aria-disabled`) and does nothing.
  *
  * Returns `{ element, setDisabled(reason), setDensity(density), setVariant(variant), destroy() }`.
  */
@@ -447,12 +448,15 @@ export function createPresentButton(container, options = {}) {
   if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
   const doc = container.ownerDocument;
   const label = options.label ?? "Present";
+  const icons = normalizeIcons(options.icons, ["present"], "createPresentButton icons");
+  const glyph = resolveIcon(doc, icons.present, null, { name: "present", size: 16 }) ?? icon(doc, "Presentation", 16);
+  glyph.setAttribute("data-opf-icon", "present");
   let disabledReason = options.disabled === true ? "Nothing to present." : typeof options.disabled === "string" && options.disabled ? options.disabled : undefined;
   let destroyed = false;
   const button = el(doc, "button", {
     type: "button", class: "opf-present-button opf-ui", "aria-label": label, title: "Present (F5)", "aria-keyshortcuts": "F5",
     "data-density": options.density === "touch" ? "touch" : "comfortable", "data-variant": options.variant === "primary" ? "primary" : "quiet",
-  }, icon(doc, "Presentation", 16));
+  }, glyph);
   const paint = () => {
     if (disabledReason) { button.setAttribute("aria-disabled", "true"); button.title = disabledReason; }
     else { button.removeAttribute("aria-disabled"); button.title = "Present (F5)"; }

package/dist/react.d.ts

@@ -76,3 +76,12 @@ export declare function useOpfCommands(editor: OpfEditorHandle | null | undefine
 export declare function useOpfCursor(editor: OpfEditorHandle | null | undefined): SourceCursor | null;
 
 export type { OpfEditorHandle };
+
+/**
+ * CE-28: the deck's name (`""` without one), read again on every `deckName` event, and its setter (`editor.setDeckName`: one undoable edit, an
+ * empty name removes it; false when it was refused). `["", () => false]` while `editor` is `null`.
+ */
+export declare function useOpfDeckName(editor: OpfEditorHandle | null | undefined): [name: string, setName: (name: string) => boolean];
+
+/** CE-28 wave 2: whether the editor has unsaved changes (the `dirty` event); false while there is no editor. */
+export declare function useOpfDirty(editor: OpfEditorHandle | null | undefined): boolean;

package/dist/react.js

@@ -257,3 +257,21 @@ export function useOpfCursor(editor) {
   const subscribe = useCallback(subscribeTo(editor, "cursor"), [editor]);
   return useSyncExternalStore(subscribe, () => (editor ? editor.sourceCursor : null), () => null);
 }
+
+/** CE-28 wave 2: whether the editor has unsaved changes, following its `dirty` event. */
+export function useOpfDirty(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "dirty"), [editor]);
+  return useSyncExternalStore(subscribe, () => Boolean(editor?.dirty), () => false);
+}
+
+/**
+ * CE-28: the deck's name and a setter, `[name, setName]`. `name` is the document's `name` (`""` without one), read again on every `deckName`
+ * event (a rename from the title, the source pane, undo or the host); `setName(next)` is `editor.setDeckName(next)`: one undoable edit through
+ * the session (an empty name removes it), queued while the editor is not mounted yet. Returns `["", () => false]` while there is no editor.
+ */
+export function useOpfDeckName(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "deckName"), [editor]);
+  const name = useSyncExternalStore(subscribe, () => (editor ? editor.getDeckName() : ""), () => "");
+  const setName = useCallback((next) => (editor ? editor.setDeckName(next) : false), [editor]);
+  return [name, setName];
+}

package/dist/review-pill.d.ts

@@ -0,0 +1,83 @@
+import type { OpfIcons } from "./icons.js";
+/** What the workspace's `review` event carries (and the Review panel's `onChange`). */
+export interface ReviewPillCounts {
+  error: number;
+  warning: number;
+  info: number;
+  /** Findings shown in the panel. 0 reads "Valid". */
+  total: number;
+  /** Every finding, shown or not. The pill reads `total`. */
+  all?: number;
+  sources?: string[];
+  /** True when the review could not run: the pill reads "Review unavailable" and is disabled. */
+  unavailable?: boolean;
+}
+/** What the pill shows, from `describeReview`. */
+export interface ReviewPillView {
+  state: "checking" | "unavailable" | "valid" | "issues";
+  /** The most severe level present, or null. */
+  severity: "error" | "warning" | "info" | null;
+  total: number;
+  /** The visible text. */
+  text: string;
+  /** The non-zero severities, for example `["2 errors", "1 warning"]`. */
+  parts: string[];
+}
+export interface ReviewPillLabels {
+  /** Default: "Checking…". */
+  checking?: string;
+  /** Default: "Valid". */
+  valid?: string;
+  /** Default: "Review unavailable". */
+  unavailable?: string;
+  /** The visible text with findings. Default: "1 issue" / "3 issues". */
+  issues?: (total: number) => string;
+  /** One severity in the accessible name. Defaults: "1 error" / "2 errors". */
+  error?: (count: number) => string;
+  /** Default: "1 warning" / "2 warnings". */
+  warning?: (count: number) => string;
+  /** Default: "1 note" / "2 notes". */
+  info?: (count: number) => string;
+  /** The accessible name. Default: "Review: Valid", "Review: 3 issues (2 errors, 1 warning)", "Review unavailable". */
+  name?: (view: ReviewPillView) => string;
+  /** The overflow menu label. Default: "Review" or "Review (3)". */
+  menu?: (total: number) => string;
+}
+export interface ReviewPillOptions {
+  /** Called when the pill is pressed or its menu item runs. The workspace opens the Review panel here. Not called while the pill is disabled. */
+  onOpen?: () => void;
+  /** `"comfortable"` (32px, default) or `"touch"` (40px; 44px under a coarse pointer either way). */
+  density?: "comfortable" | "touch";
+  labels?: ReviewPillLabels;
+  /**
+   * Replace the glyph of a state: `valid` (no findings), `error`, `warning` and `info` (the most severe level present), `checking` (before the
+   * first update) and `unavailable` (the review could not run). See `OpfIcon`. The glyph is `.opf-review-pill-icon`; `data-opf-icon` names it.
+   */
+  icons?: OpfIcons<"valid" | "error" | "warning" | "info" | "checking" | "unavailable">;
+}
+export interface ReviewPillMenuItem {
+  id: "review";
+  label: string;
+  disabled: boolean;
+  run(): void;
+}
+export interface ReviewPill {
+  /** The status button. `data-state` is `checking`, `valid`, `issues` or `unavailable`; `data-severity` is `error`, `warning` or `info` with issues. */
+  readonly element: HTMLButtonElement;
+  /** Show the counts of a `review` event; null or undefined goes back to "Checking…". */
+  update(counts: ReviewPillCounts | null | undefined): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  setDisabled(disabled: boolean): void;
+  /** The overflow menu entry: `[{ id: "review", label: "Review (3)", disabled, run }]`. */
+  menuItems(): ReviewPillMenuItem[];
+  /** Removes the element and listener. Safe twice. */
+  destroy(): void;
+}
+/** What the pill shows for a `review` event payload, without a DOM. */
+export declare function describeReview(counts: ReviewPillCounts | null | undefined, labels?: ReviewPillLabels): ReviewPillView;
+/**
+ * The review pill: a compact status button ("Valid", "3 issues", "Checking…", "Review unavailable") with a glyph and the color of the most severe
+ * level. The accessible name carries the counts. When the review is unavailable the pill stays visible, muted and disabled (hiding it would make a
+ * broken check look like a clean deck).
+ */
+export declare function createReviewPill(container: HTMLElement, options?: ReviewPillOptions): ReviewPill;

package/dist/review-pill.js

@@ -0,0 +1,137 @@
+// CE-29, the review pill: the toolbar's `review` item. One compact status button that says how the deck checks out ("Valid", "3 issues", "Checking…")
+// and opens the Review panel when pressed. It owns no findings: the host feeds it the counts that the workspace's `review` event carries
+// (`{ error, warning, info, total, all, sources, unavailable }`) through `update(counts)`. Not color alone: every state has a glyph and words.
+// Plain DOM, no framework, no network. Icons are Lucide paths (ISC license), inlined.
+import { normalizeIcons, resolveIcon } from "./icons.js";
+
+// Each glyph is a list of [tag, attributes]. "valid" is a filled success dot (the words carry the meaning), "checking" a ring.
+const GLYPHS = {
+  error: [["circle", { cx: 12, cy: 12, r: 10 }], ["path", { d: "m15 9-6 6" }], ["path", { d: "m9 9 6 6" }]],
+  warning: [["path", { d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }], ["path", { d: "M12 9v4" }], ["path", { d: "M12 17h.01" }]],
+  info: [["circle", { cx: 12, cy: 12, r: 10 }], ["path", { d: "M12 16v-4" }], ["path", { d: "M12 8h.01" }]],
+  valid: [["circle", { cx: 12, cy: 12, r: 5, fill: "currentColor", stroke: "none" }]],
+  checking: [["circle", { cx: 12, cy: 12, r: 8, "stroke-dasharray": "3 3" }]],
+  unavailable: [["circle", { cx: 12, cy: 12, r: 10 }], ["path", { d: "M8 12h8" }]],
+};
+
+const ICON_NAMES = Object.keys(GLYPHS);
+
+const count = (value) => (Number.isFinite(Number(value)) && Number(value) > 0 ? Math.trunc(Number(value)) : 0);
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+const DEFAULT_LABELS = {
+  /** The visible text before the first `update()`. */
+  checking: "Checking…",
+  /** The visible text when the deck has no findings. */
+  valid: "Valid",
+  /** The visible text when the review could not run. */
+  unavailable: "Review unavailable",
+  /** The visible text with findings, for example "3 issues". */
+  issues: (total) => plural(total, "issue", "issues"),
+  /** One severity in the accessible name, for example "2 errors". */
+  error: (n) => plural(n, "error", "errors"),
+  warning: (n) => plural(n, "warning", "warnings"),
+  info: (n) => plural(n, "note", "notes"),
+  /** The accessible name of the button, from the state: "Review: Valid", "Review: 3 issues (2 errors, 1 warning)". `view` is what `describeReview` returns. */
+  name: ({ state, text, parts }) => (state === "issues" ? `Review: ${text} (${parts.join(", ")})` : state === "unavailable" ? text : `Review: ${text}`),
+  /** The overflow menu item: "Review" while there is nothing to count, "Review (3)" with findings. */
+  menu: (total) => (total > 0 ? `Review (${total})` : "Review"),
+};
+
+function glyph(doc, name, icons) {
+  return resolveIcon(doc, icons[name], GLYPHS[name], { name, className: "opf-review-pill-icon" });
+}
+
+/**
+ * What the pill shows for a `review` event payload, without a DOM: `{ state, severity, total, text, parts }`.
+ * `state` is `"checking"` (no counts yet), `"unavailable"`, `"valid"` (`total` is 0) or `"issues"`; `severity` is the most severe level present
+ * (`"error"`, `"warning"` or `"info"`, else null); `parts` lists the non-zero severities for the accessible name.
+ */
+export function describeReview(counts, labels = DEFAULT_LABELS) {
+  const l = { ...DEFAULT_LABELS, ...labels };
+  if (!counts) return { state: "checking", severity: null, total: 0, text: l.checking, parts: [] };
+  const error = count(counts.error), warning = count(counts.warning), info = count(counts.info);
+  const total = count(counts.total);
+  if (counts.unavailable) return { state: "unavailable", severity: null, total, text: l.unavailable, parts: [] };
+  if (total === 0) return { state: "valid", severity: null, total: 0, text: l.valid, parts: [] };
+  const severity = error ? "error" : warning ? "warning" : info ? "info" : null;
+  const parts = [error && l.error(error), warning && l.warning(warning), info && l.info(info)].filter(Boolean);
+  return { state: "issues", severity, total, text: l.issues(total), parts };
+}
+
+/**
+ * Mount the review pill into `container`.
+ *
+ * Options: `onOpen()` (called when the pill is pressed or its menu item runs; the workspace opens the Review panel), `density` (`"comfortable"` or
+ * `"touch"`), `labels` (every string; see `ReviewPillLabels`).
+ *
+ * Returns `{ element, update(counts), setDensity(density), setDisabled(disabled), menuItems(), destroy() }`.
+ *
+ * States: before the first `update()` it reads "Checking…". `update(counts)` with `total` 0 reads "Valid" with a success dot; with findings it reads
+ * "N issues" with the glyph and color of the most severe level. When `counts.unavailable` is true (the review could not run) the pill stays visible,
+ * muted and disabled, and reads "Review unavailable": hiding it would make a broken check look like a clean deck. The accessible name carries the
+ * counts, for example "Review: 3 issues (2 errors, 1 warning)".
+ */
+export function createReviewPill(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const doc = container.ownerDocument;
+  const labels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  const icons = normalizeIcons(options.icons, ICON_NAMES, "createReviewPill icons");
+  let density = options.density === "touch" ? "touch" : "comfortable";
+  let disabled = false;
+  let destroyed = false;
+  let view = describeReview(null, labels);
+
+  const element = doc.createElement("button");
+  element.type = "button";
+  element.className = "opf-review-pill";
+  element.dataset.density = density;
+  const text = doc.createElement("span");
+  text.className = "opf-review-pill-text";
+  let icon = null;
+
+  const blocked = () => disabled || view.state === "unavailable";
+  function draw() {
+    element.dataset.state = view.state;
+    if (view.severity) element.dataset.severity = view.severity; else delete element.dataset.severity;
+    const next = glyph(doc, view.state === "issues" ? view.severity ?? "info" : view.state, icons);
+    if (icon) icon.replaceWith(next); else element.prepend(next);
+    icon = next;
+    text.textContent = view.text;
+    element.setAttribute("aria-label", labels.name(view));
+    element.disabled = blocked();
+  }
+  element.append(text);
+  draw();
+  container.append(element);
+
+  const open = () => { if (!destroyed && !blocked()) options.onOpen?.(); };
+  element.addEventListener("click", open);
+
+  return {
+    element,
+    /** Show the counts of a `review` event. Without counts (null or undefined) the pill goes back to "Checking…". */
+    update(counts) {
+      if (destroyed) return;
+      view = describeReview(counts, labels);
+      draw();
+    },
+    setDensity(next) {
+      density = next === "touch" ? "touch" : "comfortable";
+      element.dataset.density = density;
+    },
+    setDisabled(next) {
+      disabled = Boolean(next);
+      element.disabled = blocked();
+    },
+    menuItems() {
+      return [{ id: "review", label: labels.menu(view.total), disabled: blocked(), run: open }];
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      element.removeEventListener("click", open);
+      element.remove();
+    },
+  };
+}

package/dist/shortcuts-sheet.d.ts

@@ -0,0 +1,82 @@
+import type { OpfIcons } from "./icons.js";
+/** One row of the sheet. Keys are CodeMirror-style names ("Mod-z", "Shift-Mod-z", "Ctrl-y", "F1", "?"); `Mod` is Cmd on a Mac and Ctrl elsewhere. */
+export interface HelpShortcut {
+  label: string;
+  /** The alternatives, for example `["Mod-z"]` or `["Mod-y", "Shift-Mod-z"]`. A chord of strokes is space separated: `"Mod-k Mod-s"`. */
+  keys: string[];
+  /** The heading the row is listed under. Default: "General". */
+  group?: string;
+  /** Optional stable id (a `data-id` on the row). */
+  id?: string;
+}
+export interface HelpButtonLabels {
+  /** The accessible name of the button. Default: "Keyboard shortcuts". */
+  button?: string;
+  /** The tooltip (" (?)" is added when the key is bound). Default: "Keyboard shortcuts". */
+  title?: string;
+  /** The dialog heading. Default: "Keyboard shortcuts". */
+  heading?: string;
+  /** Default: "Close". */
+  close?: string;
+  /** The accessible name of the filter field. Default: "Filter the keyboard shortcuts". */
+  search?: string;
+  /** Default: "Filter shortcuts". */
+  searchPlaceholder?: string;
+  /** The group of a shortcut that names none. Default: "General". */
+  defaultGroup?: string;
+  /** Default: "No shortcut matches." */
+  none?: string;
+  /** Default: "No keyboard shortcuts are available." */
+  empty?: string;
+  /** The sentence under the heading; `platform` is "macOS" or "Windows or Linux". */
+  description?: (platform: string) => string;
+  /** The live status line, for example "3 of 12 shortcuts match". */
+  status?: (shown: number, total: number) => string;
+}
+export interface HelpButtonOptions {
+  /** The element the dialog is added to. Default: the closest `.opf-ui` ancestor of the container, else `document.body`. */
+  overlay?: HTMLElement;
+  /** The shortcuts to list. Called on every open, so the list is current. */
+  getShortcuts?: () => HelpShortcut[];
+  /** `"comfortable"` (32px, default) or `"touch"` (40px; 44px under a coarse pointer either way). */
+  density?: "comfortable" | "touch";
+  labels?: HelpButtonLabels;
+  /**
+   * Replace an icon. `help` is the question mark on the toolbar button (`.opf-help-icon`); `close` replaces the "×" in the dialog's close
+   * button (`.opf-help-close-icon`; without it the button reads "×"). See `OpfIcon`.
+   */
+  icons?: OpfIcons<"help" | "close">;
+  /** Bind "?" and "Shift-?" on the document to open the sheet when focus is not in a field, an editor, a menu or a dialog. Default true. */
+  bindKey?: boolean;
+}
+export interface HelpButtonMenuItem {
+  id: "help";
+  label: string;
+  disabled: boolean;
+  run(): boolean;
+}
+export interface HelpButton {
+  /** The toolbar button (`aria-haspopup="dialog"`, `aria-expanded` follows the sheet). */
+  readonly element: HTMLButtonElement;
+  /** Open the shortcuts sheet. Returns false when the button is disabled or destroyed. Focus goes to the filter field. */
+  open(): boolean;
+  /** Close the sheet; focus returns to where it was. Escape does the same. */
+  close(): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  /** Disables the button and the "?" key, and closes an open sheet. */
+  setDisabled(disabled: boolean): void;
+  /** `[{ id: "help", label: "Keyboard shortcuts", disabled, run }]` for the toolbar's overflow menu. */
+  menuItems(): HelpButtonMenuItem[];
+  /** Closes the sheet, removes the button and the key listener. Safe twice. */
+  destroy(): void;
+}
+/** Strokes as people read them, one string per alternative: `["Mod-z"]` is `["⌘Z"]` on a Mac and `["Ctrl+Z"]` elsewhere. `win` selects the platform. */
+export declare function formatShortcutKeys(keys: string[] | string, win?: Window | null): string[];
+/** The sheet's rows (`{ id, title, group, keys }`, keys formatted for `win`). */
+export declare function shortcutRows(shortcuts: HelpShortcut[] | undefined, win?: Window | null, defaultGroup?: string): { id: string; title: string; group: string; keys: string[] }[];
+/** The rows that match every word of `query` (in the label, group or keys). An empty query keeps all rows. */
+export declare function filterShortcutRows<T extends { title: string; group: string; id: string; keys: string[] }>(rows: T[], query: string): T[];
+/** Whether a "?" key press opens the sheet: a bare "?" (Shift allowed) that is not typed into a field, an editor, a menu or a dialog, and not already handled. */
+export declare function opensOnKey(event: KeyboardEvent): boolean;
+/** The help item: a button and the "?" key that open a modal sheet of the keyboard shortcuts, grouped and filterable by typing. */
+export declare function createHelpButton(container: HTMLElement, options?: HelpButtonOptions): HelpButton;