@openpresentation/opf-editor 0.29.1 → 0.31.0

package/dist/toolbar-actions.d.ts

@@ -0,0 +1,59 @@
+import type { OpfIcon } from "./icons.js";
+/** One host button in the toolbar. */
+export interface ToolbarAction {
+  /** Unique within the list. Becomes `data-action` on the button and `actions:<id>` in the overflow menu. */
+  id: string;
+  /** The visible text of the button (and its accessible name). */
+  label: string;
+  /**
+   * The button's icon: an SVG element (copied into the toolbar's document), a function returning one, or SVG path data for a 24x24 stroked icon
+   * (`"M5 12h14"`); see `OpfIcon`. Optional. The icon is `.opf-actions-icon`; its name is the action id (`data-opf-icon`).
+   */
+  icon?: OpfIcon;
+  /** The tooltip. */
+  title?: string;
+  /** What the button does. Called on a click, and from the overflow menu, only while the action is enabled. The button refreshes afterwards. */
+  run(): void | Promise<void>;
+  /** Whether the button can be used. Default: always. Read again by `refresh()`. A throw counts as false. */
+  enabled?(): boolean;
+  /** Makes it a toggle: `aria-pressed` follows this. Read again by `refresh()`. Without it the button is not a toggle. */
+  pressed?(): boolean;
+  /** Style the button with the accent color. */
+  primary?: boolean;
+}
+export interface ToolbarActionsLabels {
+  /** The accessible name of the group of buttons. Default: "Actions". */
+  group?: string;
+}
+export interface ToolbarActionsOptions {
+  actions?: ToolbarAction[];
+  /** `"comfortable"` (32px, default) or `"touch"` (40px; 44px under a coarse pointer either way). */
+  density?: "comfortable" | "touch";
+  labels?: ToolbarActionsLabels;
+}
+export interface ToolbarActionsMenuItem {
+  /** `actions:<action id>`. */
+  id: string;
+  label: string;
+  disabled: boolean;
+  /** Present for toggles. */
+  pressed?: boolean;
+  run(): void | Promise<void> | undefined;
+}
+export interface ToolbarActions {
+  /** The group element (`role="group"`); hidden while there are no actions. */
+  readonly element: HTMLElement;
+  /** Replace the buttons. Throws a TypeError for an action without an id, a label or `run`, or for a repeated id. A focused button keeps the focus. */
+  setActions(actions: ToolbarAction[]): void;
+  /** Read every `enabled()` and `pressed()` again. The state is not watched; call this when the host's state changes. */
+  refresh(): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  /** Disables every button (the editor does this while the source is invalid or read-only). */
+  setDisabled(disabled: boolean): void;
+  /** One entry per action, for the toolbar's overflow menu. */
+  menuItems(): ToolbarActionsMenuItem[];
+  /** Removes the element. Safe twice. */
+  destroy(): void;
+}
+/** The host's own buttons in the toolbar: labelled, optionally iconed, with enabled and pressed state read on `refresh()`. */
+export declare function createToolbarActions(container: HTMLElement, options?: ToolbarActionsOptions): ToolbarActions;

package/dist/toolbar-actions.js

@@ -0,0 +1,136 @@
+// CE-29, toolbar actions: the `actions` item. The host's own buttons in the editor's toolbar ("Share", "Publish", "Save as template"), each with a visible
+// label, an optional icon and optional enabled and pressed state. The editor never decides what they do: `run()` is the host's. Plain DOM, no framework,
+// no network. An icon is an SVG element (copied into the toolbar's document) or SVG path data (24x24, stroked like the editor's own icons).
+import { resolveIcon } from "./icons.js";
+
+const DEFAULT_LABELS = {
+  /** The accessible name of the group of buttons. */
+  group: "Actions",
+};
+
+function checkAction(action, seen) {
+  if (!action || typeof action !== "object") throw new TypeError("An action must be an object.");
+  if (typeof action.id !== "string" || !action.id) throw new TypeError("An action needs a string id.");
+  if (typeof action.label !== "string" || !action.label) throw new TypeError(`The action "${action.id}" needs a label.`);
+  if (typeof action.run !== "function") throw new TypeError(`The action "${action.id}" needs a run() function.`);
+  if (seen.has(action.id)) throw new TypeError(`Two actions have the id "${action.id}".`);
+  seen.add(action.id);
+}
+
+function iconNode(doc, action) {
+  return action.icon ? resolveIcon(doc, action.icon, null, { name: action.id, className: "opf-actions-icon" }) : null;
+}
+
+/**
+ * Mount the host's action buttons into `container`.
+ *
+ * Options: `actions` (`[{ id, label, icon?, title?, run(), enabled?(), pressed?(), primary? }]`), `density` (`"comfortable"` or `"touch"`), `labels`
+ * (`group`).
+ *
+ * Returns `{ element, setActions(actions), refresh(), setDensity(density), setDisabled(disabled), menuItems(), destroy() }`. `refresh()` reads every
+ * `enabled()` and `pressed()` again (they are not watched); a button also refreshes after its own `run()`.
+ */
+export function createToolbarActions(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const doc = container.ownerDocument;
+  const labels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  let density = options.density === "touch" ? "touch" : "comfortable";
+  let disabled = false;
+  let destroyed = false;
+  let actions = [];
+  let buttons = new Map();
+
+  const element = doc.createElement("div");
+  element.className = "opf-actions";
+  element.dataset.density = density;
+  element.setAttribute("role", "group");
+  element.setAttribute("aria-label", labels.group);
+  container.append(element);
+
+  const isEnabled = (action) => {
+    if (typeof action.enabled !== "function") return true;
+    try { return action.enabled() !== false; } catch { return false; }
+  };
+  const isPressed = (action) => {
+    if (typeof action.pressed !== "function") return undefined;
+    try { return Boolean(action.pressed()); } catch { return false; }
+  };
+
+  function refresh() {
+    if (destroyed) return;
+    for (const action of actions) {
+      const button = buttons.get(action.id);
+      if (!button) continue;
+      button.disabled = disabled || !isEnabled(action);
+      const pressed = isPressed(action);
+      if (pressed === undefined) button.removeAttribute("aria-pressed"); else button.setAttribute("aria-pressed", String(pressed));
+    }
+  }
+
+  function run(action) {
+    if (destroyed || disabled || !isEnabled(action)) return undefined;
+    const result = action.run();
+    refresh();
+    return result;
+  }
+
+  function build(action) {
+    const button = doc.createElement("button");
+    button.type = "button";
+    button.className = `opf-actions-button${action.primary ? " is-primary" : ""}`;
+    button.dataset.action = action.id;
+    if (action.title) button.title = action.title;
+    const icon = iconNode(doc, action);
+    if (icon) button.append(icon);
+    const label = doc.createElement("span");
+    label.className = "opf-actions-label";
+    label.textContent = action.label;
+    button.append(label);
+    button.addEventListener("click", () => { run(action); });
+    return button;
+  }
+
+  function setActions(next) {
+    if (destroyed) return;
+    const list = Array.isArray(next) ? next : [];
+    const seen = new Set();
+    for (const action of list) checkAction(action, seen);
+    // A focused button keeps the focus across the rebuild.
+    const focused = element.contains(doc.activeElement) ? doc.activeElement.dataset.action : null;
+    actions = list.slice();
+    buttons = new Map(actions.map((action) => [action.id, build(action)]));
+    element.replaceChildren(...buttons.values());
+    element.hidden = actions.length === 0;
+    refresh();
+    if (focused && buttons.has(focused) && !buttons.get(focused).disabled) buttons.get(focused).focus({ preventScroll: true });
+  }
+  setActions(options.actions);
+
+  return {
+    element,
+    setActions,
+    refresh,
+    setDensity(next) {
+      density = next === "touch" ? "touch" : "comfortable";
+      element.dataset.density = density;
+    },
+    setDisabled(next) {
+      disabled = Boolean(next);
+      refresh();
+    },
+    /** `[{ id: "actions:<id>", label, disabled, pressed?, run }]`, one per action, in order. */
+    menuItems() {
+      return actions.map((action) => {
+        const pressed = isPressed(action);
+        return { id: `actions:${action.id}`, label: action.label, disabled: disabled || !isEnabled(action), ...(pressed === undefined ? {} : { pressed }), run: () => run(action) };
+      });
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      element.remove();
+      buttons.clear();
+      actions = [];
+    },
+  };
+}

package/dist/toolbar.d.ts

@@ -0,0 +1,113 @@
+import type { OpfIcons } from "./icons.js";
+/**
+ * CE-28: the editor's title bar. Named items in order, each in its own slot element; when the row does not fit the width of the bar (its
+ * container decides, not the window), the collapsible items are hidden lowest priority first and what they offer is listed in the `more` (⋯)
+ * menu, built from each mounted part's `menuItems()`. `createOpfEditor` builds one for its default layouts (`toolbar` option); a host can build
+ * its own and mount the editor's parts in its slots. CSS: `src/styles/toolbar.css`, classes `opf-tb-*`.
+ */
+
+/** The item names. `zoom` is the Studio's own (the workspace leaves it out). */
+export type ToolbarItemName =
+  | "title"
+  | "history"
+  | "counter"
+  | "views"
+  | "find"
+  | "zoom"
+  | "design"
+  | "review"
+  | "autosave"
+  | "export"
+  | "present"
+  | "expand"
+  | "actions"
+  | "help"
+  | "more"
+  | "spacer"
+  | "|";
+
+/** An item name, or the name of a host's own item. */
+export type ToolbarItemId = ToolbarItemName | (string & {});
+
+/**
+ * An item by name, or with its own priority (higher stays visible longer) and whether it may move into the more menu. A host's own item is
+ * `{ id, priority }` with a name that is not one of the above (lowercase letters, digits and dashes): its slot starts empty, the host fills it
+ * (`slot(id)`) and registers what it offers in the more menu with `mount(id, part)`. A bare unknown name throws, so a misspelt item is caught.
+ */
+export type ToolbarItemSpec =
+  | ToolbarItemName
+  | { id: ToolbarItemName; priority?: number; collapsible?: boolean }
+  | { id: string; priority: number; collapsible?: boolean };
+
+export interface ToolbarItem {
+  id: ToolbarItemId;
+  priority: number;
+  collapsible: boolean;
+}
+
+/** The defaults of every item: `more` and `title` stay (the title shrinks instead), `spacer` and `|` are layout. */
+export declare const TOOLBAR_ITEMS: Readonly<Record<ToolbarItemName, Readonly<{ priority: number; collapsible: boolean }>>>;
+
+/** The items with their priorities. Throws on a name that is not an item (or a host item), and on a named item given twice (`spacer` and `|` may repeat). */
+export declare function normalizeToolbarItems(items: readonly ToolbarItemSpec[]): ToolbarItem[];
+
+/** One entry of the more menu. `pressed` makes it a checkbox item (`aria-checked`); a `disabled` item is listed but does not run. */
+export interface ToolbarMenuItem {
+  id?: string;
+  label: string;
+  disabled?: boolean;
+  pressed?: boolean;
+  run(): void;
+}
+
+/** What a part registers with `mount`: the part contract's `menuItems()` is all the toolbar reads. */
+export interface ToolbarPart {
+  menuItems?(): ToolbarMenuItem[];
+  [key: string]: unknown;
+}
+
+export interface ToolbarOptions {
+  items?: readonly ToolbarItemSpec[];
+  /** `"comfortable"` (default) or `"touch"`; under `(pointer: coarse)` the trigger and the menu items are 44px either way. */
+  density?: "comfortable" | "touch";
+  /** `more`: the name of the ⋯ button (default "More"); `menu`: the name of its menu (default "More actions"). */
+  labels?: { more?: string; menu?: string };
+  /** Replace the ⋯ glyph: `more` (`.opf-tb-more-icon`). See `OpfIcon`. */
+  icons?: OpfIcons<"more">;
+  /** The set of collapsed items changed. */
+  onCollapse?(detail: { collapsed: ToolbarItemId[] }): void;
+  /** A part's `menuItems()` or an item's `run()` threw. */
+  onError?(error: unknown): void;
+}
+
+export interface Toolbar {
+  /** The row (`.opf-tb`), appended to the container. */
+  readonly element: HTMLElement;
+  readonly items: ToolbarItem[];
+  /** One element per named item (`data-opf-toolbar-item`), in bar order, host items included. Mount a part in it, then `mount(name, part)`. */
+  readonly slots: Partial<Record<ToolbarItemId, HTMLElement>>;
+  slot(name: ToolbarItemId): HTMLElement | undefined;
+  /** The items in the more menu now, in bar order. */
+  readonly collapsed: ToolbarItemId[];
+  readonly menuOpen: boolean;
+  /** Change an item's priority or whether it collapses; false for an item that is not in the bar (or `more`, `spacer`, `|`). */
+  setItem(name: ToolbarItemId, change: { priority?: number; collapsible?: boolean }): boolean;
+  /** Register the part mounted in a slot, for its menu items. Returns the function that unregisters it. */
+  mount(name: ToolbarItemId, part: ToolbarPart): () => void;
+  /** What the more menu would list now, one group per collapsed part. */
+  menuItems(): { id: ToolbarItemId; items: ToolbarMenuItem[] }[];
+  /** Fit the row now (it also fits itself on the next frame after a resize). Returns the collapsed items. */
+  update(): ToolbarItemId[];
+  /** Open the more menu and focus its first (or last) item. False when there is nothing to list. */
+  openMenu(which?: "first" | "last"): boolean;
+  closeMenu(options?: { restoreFocus?: boolean }): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  /** Remove the row, its observers and listeners. Safe twice. */
+  destroy(): void;
+}
+
+/**
+ * Build a toolbar in `container`. The menu is a `role="menu"`: Arrow keys, Home and End move, Enter and Space run an item, Escape closes it and
+ * returns the focus to the ⋯ button, Tab leaves it.
+ */
+export declare function createToolbar(container: HTMLElement, options?: ToolbarOptions): Toolbar;