@openpresentation/opf-editor 0.29.1 → 0.30.0

package/README.md

@@ -6,6 +6,25 @@ Unfinished prepared shaping work is preserved in the [September 15 roadmap](docs
 
 One call mounts the whole editor, over one session and one fonts handle: the source pane, the canvas, the slide row, Present, Export, the sorter, the outline, Layout Studio, Review, Find and autosave, each part optional.
 
+**Quick start: a deck in a card.** The `embed` layout is the slide alone under a compact bar (the deck's name, Undo and Redo, the slide counter, Design, Expand and Present), for a page that shows a deck:
+
+```js
+import "@openpresentation/opf-editor/styles.css";
+import { createOpfEditor } from "@openpresentation/opf-editor/workspace";
+import { gallery } from "@openpresentation/gallery";
+import { loadPreviewFonts } from "@openpresentation/opf-render/preview-fonts";
+
+const editor = createOpfEditor(document.querySelector("#card"), {
+  document: deck, catalogs: [gallery], layout: "embed",
+  fonts: loadPreviewFonts("/opf-fonts/"),   // npx opf-preview-fonts public/opf-fonts
+});
+editor.on("deckName", ({ name }) => (label.textContent = name));
+```
+
+The bar is a list of named items (`toolbar: ["title", "history", "counter", "spacer", "expand"]`), and each item can sit in your own header instead (`toolbar: false`, `slots: { title, history, counter, expand }`) or be replaced by your own controls through the handle (`getDeckName`, `setDeckName`, `undo`, `setSlide`, `expand`, `markSaved`) and its events (`deckName`, `slide`, `dirty`, `save`). The same editor is a tag (`<opf-editor layout="embed" toolbar="title,history,counter,expand">`), a React component and a Svelte store. [docs/chrome-guide.md](docs/chrome-guide.md) walks through each task with code from eight runnable pages in [`examples/chrome/`](examples/chrome) (`pnpm run build:chrome-examples`, then open `artifacts/chrome-examples/index.html` from a static server): the presets and the bar of each, choosing and ordering items, items in your own header, headless, renaming, expand, unsaved changes and Ctrl/Cmd+S, host buttons, restyling with the layered stylesheet and tokens, the web component, React and Svelte, and an iframe.
+
+**The whole editor in one call.**
+
 ```js
 import "@openpresentation/opf-editor/styles.css";
 import { createOpfEditor } from "@openpresentation/opf-editor/workspace";

package/dist/deck-title.d.ts

@@ -0,0 +1,59 @@
+import type { EditorSession, JsonPatchOperation } from "./index.js";
+
+/**
+ * The JSON Patch that renames a deck. `current` is the deck's `name` now (`undefined` when it has none); `next` is the text typed, which is
+ * trimmed. Returns `null` when nothing changes (the trimmed text equals `current`, or it is empty and there is no name to remove), a
+ * `remove` of `/name` for an empty text, and an `add` of `/name` (which also replaces) otherwise.
+ */
+export declare function deckNamePatch(current: string | undefined, next: string): JsonPatchOperation[] | null;
+
+export interface DeckTitleLabels {
+  /** The accessible name of the field. Default: "Presentation name". */
+  label?: string;
+  /** The placeholder shown while the deck has no name. Default: "Untitled presentation". */
+  placeholder?: string;
+}
+export interface DeckTitleRename {
+  /** The new trimmed name; `""` when the name was removed. */
+  name: string;
+  /** The name before the rename; `undefined` when the deck had none. */
+  previous: string | undefined;
+}
+export interface DeckTitleOptions {
+  /** The editor session: the field shows `snapshot().presentation.name`, follows its changes and renames through `applyPatch`. */
+  editor: EditorSession;
+  /** Default: "Untitled presentation". Overrides `labels.placeholder`. */
+  placeholder?: string;
+  /** The accessible name (`aria-label`). Default: "Presentation name". Overrides `labels.label`. */
+  label?: string;
+  /** The name is shown as text and cannot be edited. Default false. */
+  readOnly?: boolean;
+  /** `"comfortable"` (default) or `"touch"` (40px field). */
+  density?: "comfortable" | "touch";
+  labels?: DeckTitleLabels;
+  /**
+   * Called before a rename is applied. Return `false` to stop it (the workspace uses this to commit an open canvas edit first and stops
+   * when that fails). The typed text stays in the field.
+   */
+  beforeCommit?: () => boolean | void;
+  /** Called after a successful rename (not for an unchanged name). */
+  onRename?: (rename: DeckTitleRename) => void;
+  /** Called when the session refuses the patch; the field shows the current name again. */
+  onError?: (error: unknown) => void;
+}
+export interface DeckTitle {
+  /** The part's root element (holds the input). */
+  readonly element: HTMLElement;
+  /** The text field. */
+  readonly input: HTMLInputElement;
+  setDensity(density: "comfortable" | "touch"): void;
+  /** Disabled shows the name as text, like read-only; any typed text is dropped. */
+  setDisabled(disabled: boolean): void;
+  setReadOnly(readOnly: boolean): void;
+  /** Read the name again (not while the person is typing). The field also follows the editor on its own. */
+  refresh(): void;
+  focus(): void;
+  /** Remove the element and the editor subscription. Safe twice. */
+  destroy(): void;
+}
+export declare function createDeckTitle(container: HTMLElement, options: DeckTitleOptions): DeckTitle;

package/dist/deck-title.js

@@ -0,0 +1,184 @@
+// Deck title (CE-28): the presentation's `name`, edited in place. It reads as plain heading text until it is hovered or focused, then shows a
+// border and a focus ring. Enter or blur commits through the editor session as one undoable edit (an empty name removes the key); Escape puts the
+// current name back. The field follows the document (undo, the source pane, the host) unless the person is typing. Plain DOM, no framework, no network.
+
+const DEFAULT_LABELS = {
+  /** The accessible name of the field. */
+  label: "Presentation name",
+  /** The placeholder shown while the deck has no name. */
+  placeholder: "Untitled presentation",
+};
+
+const MIN_CHARS = 6;
+const MAX_CHARS = 120;
+
+/**
+ * The JSON Patch that renames a deck: `current` is the deck's `name` now (`undefined` when it has none), `next` the text the person typed.
+ * The text is trimmed. Returns `null` when nothing changes: the trimmed text equals `current`, or it is empty and there is no name to remove.
+ * A non-empty name is an `add` (which also replaces); an empty one removes the key, so the deck falls back to "no name".
+ */
+export function deckNamePatch(current, next) {
+  const name = String(next ?? "").trim();
+  const before = typeof current === "string" ? current : undefined;
+  if (name === "") return before === undefined ? null : [{ op: "remove", path: "/name" }];
+  if (name === before) return null;
+  return [{ op: "add", path: "/name", value: name }];
+}
+
+/**
+ * Mount the editable deck name into `container`.
+ *
+ * Options: `editor` (an editor session), `placeholder`, `label` (the accessible name), `readOnly`, `density` (`"comfortable"` or `"touch"`),
+ * `labels` (`label`, `placeholder`), `beforeCommit()` (return `false` to stop the rename, for example when committing an open canvas edit
+ * failed; the typed text stays), `onRename({ name, previous })` (after a successful rename; `name` is `""` when the name was removed) and
+ * `onError(error)` (when the session refuses the patch; the field shows the current name again).
+ *
+ * Returns `{ element, input, setDensity(d), setDisabled(b), setReadOnly(b), refresh(), focus(), destroy() }`.
+ */
+export function createDeckTitle(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const { editor } = options;
+  if (!editor || typeof editor.snapshot !== "function" || typeof editor.applyPatch !== "function") throw new TypeError("An editor session is required.");
+  const doc = container.ownerDocument;
+  const labels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  const placeholder = options.placeholder ?? labels.placeholder;
+  const label = options.label ?? labels.label;
+  let readOnly = Boolean(options.readOnly);
+  let disabled = false;
+  let editing = false;
+  let painted = "";
+  let disposed = false;
+
+  const element = doc.createElement("div");
+  element.className = "opf-title";
+  const input = doc.createElement("input");
+  input.type = "text";
+  input.className = "opf-title-input";
+  input.placeholder = placeholder;
+  input.setAttribute("aria-label", label);
+  input.setAttribute("autocomplete", "off");
+  input.setAttribute("autocapitalize", "off");
+  input.spellcheck = false;
+  element.append(input);
+  container.append(element);
+
+  const currentName = () => {
+    const name = editor.snapshot().presentation?.name;
+    return typeof name === "string" ? name : undefined;
+  };
+  function fit() {
+    // `field-sizing: content` sizes the field in current browsers; `size` is the fallback elsewhere.
+    const length = (input.value || placeholder).length;
+    input.size = Math.max(MIN_CHARS, Math.min(MAX_CHARS, length));
+  }
+  function paintState() {
+    input.readOnly = readOnly || disabled;
+    if (disabled) input.setAttribute("aria-disabled", "true");
+    else input.removeAttribute("aria-disabled");
+    element.dataset.state = disabled ? "disabled" : readOnly ? "readonly" : "editable";
+    input.title = input.value;
+  }
+  function paint() {
+    const name = currentName() ?? "";
+    painted = name;
+    if (input.value !== name) input.value = name;
+    paintState();
+    fit();
+  }
+  function refresh() {
+    if (disposed || editing) return;
+    paint();
+  }
+
+  // Put the document's name back in the field and stop the edit.
+  function revert() {
+    editing = false;
+    paint();
+  }
+  // Commit the typed text. Returns "done" (applied, unchanged or refused: the field shows the document again) or "aborted" (`beforeCommit` said no).
+  function commit() {
+    if (!editing && input.value === painted) return "done";
+    if (options.beforeCommit && options.beforeCommit() === false) return "aborted";
+    const previous = currentName();
+    const patch = deckNamePatch(previous, input.value);
+    editing = false;
+    if (!patch) {
+      paint();
+      return "done";
+    }
+    const name = patch[0].op === "remove" ? "" : patch[0].value;
+    try {
+      // The session's own listeners repaint this field during the call (nothing is being typed any more).
+      editor.applyPatch(patch, { source: "deck-name", rejectInvalid: true });
+    } catch (error) {
+      paint();
+      options.onError?.(error);
+      return "done";
+    }
+    paint();
+    options.onRename?.({ name, previous });
+    return "done";
+  }
+
+  input.addEventListener("input", () => {
+    editing = true;
+    input.title = input.value;
+    fit();
+  });
+  input.addEventListener("keydown", (event) => {
+    if (readOnly || disabled) return;
+    // Enter that confirms an IME candidate is not a commit (Safari reports it with keyCode 229 after compositionend).
+    if (event.isComposing || event.keyCode === 229) return;
+    if (event.key === "Enter") {
+      event.preventDefault();
+      // The focus stays in the field (the name selected, so typing again replaces it); Escape or Tab leaves it. Moving it would drop it on
+      // the page's body, where neither the editor's keys nor a screen reader's place in the bar survive.
+      if (commit() === "done") input.select();
+    } else if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      revert();
+      input.blur();
+    }
+  });
+  input.addEventListener("blur", () => {
+    if (readOnly || disabled) return;
+    commit();
+  });
+  input.addEventListener("focus", () => {
+    if (!readOnly && !disabled) input.select();
+  });
+
+  paint();
+  const unsubscribe = typeof editor.subscribe === "function" ? editor.subscribe(() => refresh()) : undefined;
+
+  const handle = {
+    element,
+    input,
+    setDensity(density) {
+      element.dataset.density = density === "touch" ? "touch" : "comfortable";
+    },
+    setDisabled(value) {
+      disabled = Boolean(value);
+      if (disabled) revert();
+      paintState();
+    },
+    setReadOnly(value) {
+      readOnly = Boolean(value);
+      if (readOnly) revert();
+      paintState();
+    },
+    refresh,
+    focus() {
+      if (!disposed) input.focus();
+    },
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe?.();
+      element.remove();
+    },
+  };
+  handle.setDensity(options.density);
+  return handle;
+}

package/dist/design-menu.d.ts

@@ -0,0 +1,90 @@
+import type { OpfIcons } from "./icons.js";
+import type { Catalog } from "@openpresentation/opf";
+import type { EditorSession } from "./index.js";
+
+export interface DesignMenuLabels {
+  /** The visible text of the toolbar button. Default: "Design". */
+  trigger?: string;
+  /** The accessible name of the popover, and the title of the bottom sheet on a phone. Default: "Design". */
+  title?: string;
+  /** Default: "Theme". */
+  theme?: string;
+  /** The color scheme section. Default: "Colors". */
+  colors?: string;
+  /** The font scheme section. Default: "Fonts". */
+  fonts?: string;
+  /** The section for the current slide's layout. Default: "This slide: Layout". */
+  layout?: string;
+  /** The row that opens the full Design panel (only shown when `onOpenPanel` is given). Default: "More design options…". */
+  more?: string;
+  /** What the toolbar's overflow menu lists (`menuItems()`). Default: "Design…". */
+  menuItem?: string;
+  /** The accessible name of the sheet's close button. Default: "Close". */
+  close?: string;
+  /** Shown when no catalog offers any choice. */
+  empty?: string;
+  /** The status line after a choice. `kind` is "theme", "colors", "fonts" or "layout". Default: "Theme set to Classic.". */
+  applied?: (kind: "theme" | "colors" | "fonts" | "layout", name: string) => string;
+  /** The status line when the choice was already set. */
+  already?: (name: string) => string;
+  /** Appended to the status line when slides keep their own value of a deck-level choice. */
+  shadowed?: (count: number) => string;
+}
+
+export interface DesignMenuOptions {
+  /** The editor session. Every choice is one validated, undoable edit with `source: "design-menu"`. */
+  editor: EditorSession;
+  /** The catalogs that supply the choices (the workspace's merged `catalogs()`). Default: the session's registered catalogs. */
+  catalogs?: readonly Catalog[] | (() => readonly Catalog[]);
+  /** The slide whose layout the layout section shows and changes (0-based). Default: slide 0. */
+  getSlideIndex?: () => number;
+  /** `"comfortable"` (default) or `"touch"` (40px rows; a coarse pointer always gets 44px). */
+  density?: "comfortable" | "touch";
+  labels?: DesignMenuLabels;
+  /**
+   * Replace an icon: `trigger` (the palette on the button), `close` (the X in the phone sheet) and `check` (the mark on the chosen row). See `OpfIcon`.
+   * The icons carry `class="opf-icon"` and `data-opf-icon`.
+   */
+  icons?: OpfIcons<"trigger" | "close" | "check">;
+  /** True to disable the button (the document cannot be edited). Default false. */
+  readOnly?: boolean;
+  /** Adds a "More design options…" row that closes the menu and calls this, to open the host's full Design panel. Hidden when not given. */
+  onOpenPanel?: () => void;
+  /** Receives a short message after every choice (also announced in a polite live region inside the menu). */
+  onStatus?: (message: string) => void;
+}
+
+export interface DesignMenuItem {
+  id: "design";
+  label: string;
+  disabled: boolean;
+  run(): void;
+}
+
+export interface DesignMenu {
+  /** The part's root: the button and its popover. */
+  readonly element: HTMLElement;
+  /** The toolbar button. */
+  readonly trigger: HTMLButtonElement;
+  setDensity(density: "comfortable" | "touch"): void;
+  /** Greys the button (and closes the menu). The editor does this while the source is invalid. */
+  setDisabled(disabled: boolean): void;
+  setReadOnly(readOnly: boolean): void;
+  /** Read the document and catalogs again. The open menu also follows the editor session on its own. */
+  refresh(): void;
+  /** Open the popover and focus the current theme. From a button that is not on screen (the overflow menu) it opens as a sheet. */
+  open(): void;
+  /** Close the popover and return focus to the button (or to what had it when the menu opened). */
+  close(options?: { restoreFocus?: boolean }): void;
+  isOpen(): boolean;
+  /** What this part offers the toolbar's overflow menu: `[{ id: "design", label: "Design…", run: open }]`. */
+  menuItems(): DesignMenuItem[];
+  /** Removes the element and every listener. Safe to call twice. */
+  destroy(): void;
+}
+
+/**
+ * The Design quick menu: a toolbar button and a compact popover for Theme, Colors, Fonts and the current slide's Layout, for embeds that have no room
+ * for the full Design panel. Choosing applies at once (one undoable edit) and keeps the menu open. On a phone (`max-width: 600px`) the popover is a bottom sheet.
+ */
+export declare function createDesignMenu(container: HTMLElement, options: DesignMenuOptions): DesignMenu;