@velumo/cli 0.1.0-beta.0

package/src/browser-overview.ts

@@ -0,0 +1,641 @@
+import type { Manifest } from "@velumo/core";
+import type { RuntimeController } from "@velumo/runtime";
+
+const OVERVIEW_ATTRIBUTE = "data-velumo-overview";
+const OVERVIEW_OVERLAY_ATTRIBUTE = "data-velumo-overview-overlay";
+const OVERVIEW_GRID_ATTRIBUTE = "data-velumo-overview-grid";
+const OVERVIEW_BUTTON_ATTRIBUTE = "data-velumo-overview-button";
+const OVERVIEW_SLIDE_ID_ATTRIBUTE = "data-velumo-overview-slide-id";
+const OVERVIEW_STYLE_ATTRIBUTE = "data-velumo-overview-style";
+const OVERVIEW_ARIA_LABEL = "Slide overview";
+
+const OVERVIEW_CSS = `
+[${OVERVIEW_ATTRIBUTE}="open"] [${OVERVIEW_OVERLAY_ATTRIBUTE}] {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  display: grid;
+  grid-template-rows: auto 1fr;
+  gap: 1rem;
+  padding: 1.5rem;
+  box-sizing: border-box;
+  background: var(--velumo-color-background, #0b1220);
+  color: var(--velumo-color-foreground, #f8fafc);
+  font-family: var(--velumo-typography-body-font-family, system-ui, sans-serif);
+  overflow: auto;
+}
+
+[${OVERVIEW_ATTRIBUTE}="closed"] [${OVERVIEW_OVERLAY_ATTRIBUTE}] {
+  display: none;
+}
+
+[${OVERVIEW_OVERLAY_ATTRIBUTE}] h2 {
+  margin: 0;
+  font-family: var(--velumo-typography-body-font-family, inherit);
+  color: var(--velumo-color-foreground, currentColor);
+}
+
+[${OVERVIEW_GRID_ATTRIBUTE}] {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr));
+  gap: 0.75rem;
+  align-content: start;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}] {
+  background: var(--velumo-color-background, transparent);
+  color: var(--velumo-color-foreground, inherit);
+  border: 1px solid var(--velumo-color-foreground, currentColor);
+  border-radius: 0.5rem;
+  padding: 0.75rem 0.85rem;
+  text-align: left;
+  font: inherit;
+  font-family: var(--velumo-typography-body-font-family, inherit);
+  cursor: pointer;
+  display: grid;
+  gap: 0.2rem;
+  align-self: start;
+  min-height: 5rem;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}] > span:nth-child(1) {
+  font-size: 0.7rem;
+  opacity: 0.55;
+  letter-spacing: 0.04em;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}] > span:nth-child(2) {
+  font-size: 0.95rem;
+  font-weight: 600;
+  word-break: break-word;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}] > span:nth-child(3) {
+  font-size: 0.65rem;
+  opacity: 0.5;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}] > span:nth-child(4) {
+  font-size: 0.85rem;
+  opacity: 0.75;
+  margin-top: 0.2rem;
+  word-break: break-word;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}][aria-current="true"] {
+  border-color: var(--velumo-color-accent, currentColor);
+  box-shadow: 0 0 0 2px var(--velumo-color-accent, currentColor) inset;
+}
+
+[data-velumo-thumbnail-host] {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border-radius: 0.25rem;
+  background: var(--velumo-color-background, #0b1220);
+  margin-bottom: 0.25rem;
+  flex-shrink: 0;
+}
+
+/* Thumbnail mode: the button's children are [thumbnail-host, index, slide-id],
+   so the positional span:nth-child rules above would style the caption by
+   accident. Style the caption intentionally here — a small index prefix over a
+   readable slide-id label (the useful identifier on a contact sheet). */
+[${OVERVIEW_BUTTON_ATTRIBUTE}][data-velumo-overview-thumb] > span:nth-child(2) {
+  font-size: 0.7rem;
+  font-weight: 400;
+  opacity: 0.55;
+  text-transform: none;
+  letter-spacing: 0.04em;
+}
+
+[${OVERVIEW_BUTTON_ATTRIBUTE}][data-velumo-overview-thumb] > span:nth-child(3) {
+  font-size: 0.85rem;
+  font-weight: 600;
+  opacity: 0.9;
+  text-transform: none;
+  letter-spacing: normal;
+  word-break: break-word;
+}
+
+[data-velumo-overview-sr] {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+`;
+
+interface OverviewKeyboardEvent {
+  readonly key: string;
+  readonly target: unknown;
+  preventDefault(): void;
+}
+
+interface OverviewClickEvent {
+  readonly type: string;
+}
+
+type OverviewChild = OverviewElementLike | OverviewTextNodeLike | string;
+
+interface OverviewTextNodeLike {
+  readonly textContent: string;
+}
+
+export interface OverviewElementLike {
+  readonly ownerDocument: OverviewDocumentLike;
+  readonly tagName?: string;
+  readonly isContentEditable?: boolean;
+  addEventListener(
+    type: "click",
+    listener: (event: OverviewClickEvent) => void,
+  ): void;
+  append(...children: OverviewChild[]): void;
+  appendChild(
+    child: OverviewElementLike | OverviewTextNodeLike,
+  ): OverviewElementLike | OverviewTextNodeLike;
+  getAttribute(name: string): string | null;
+  remove?(): void;
+  removeAttribute(name: string): void;
+  replaceChildren(...children: OverviewChild[]): void;
+  setAttribute(name: string, value: string): void;
+  focus?(): void;
+}
+
+export interface OverviewRootLike {
+  readonly ownerDocument: OverviewDocumentLike;
+  focus?(): void;
+}
+
+export interface OverviewDocumentLike {
+  readonly head?: OverviewElementLike;
+  readonly body?: OverviewElementLike;
+  createElement(tagName: string): OverviewElementLike;
+  createTextNode(text: string): OverviewTextNodeLike;
+}
+
+interface OverviewBroadcastChannelConstructor {
+  new (name: string): unknown;
+}
+
+export interface OverviewWindowLike {
+  readonly BroadcastChannel?: OverviewBroadcastChannelConstructor;
+  readonly crypto?: { randomUUID?(): string };
+  addEventListener(
+    type: "keydown",
+    listener: (event: OverviewKeyboardEvent) => void,
+  ): void;
+  removeEventListener(
+    type: "keydown",
+    listener: (event: OverviewKeyboardEvent) => void,
+  ): void;
+}
+
+export type OverviewRoot = OverviewRootLike;
+
+export interface OverviewMountOptions {
+  readonly root: OverviewRoot | null | undefined;
+  readonly runtime: RuntimeController;
+  readonly manifest: Manifest;
+  readonly window?: OverviewWindowLike;
+  readonly document?: OverviewDocumentLike;
+  readonly host?: OverviewElementLike;
+  readonly onAfterJump?: () => void;
+  readonly mountThumbnail?: (opts: {
+    root: OverviewElementLike;
+    manifest: Manifest;
+    slideId: string;
+  }) => { dispose(): void };
+}
+
+export interface OverviewMountResult {
+  dispose(): void;
+}
+
+interface ActiveMountRecord {
+  active: boolean;
+  teardown(): void;
+}
+
+const overviewRegistry = new WeakMap<OverviewWindowLike, ActiveMountRecord>();
+
+export function setupOverviewMode(
+  options: OverviewMountOptions,
+): OverviewMountResult {
+  if (options.root === null || options.root === undefined) {
+    throw new Error("Velumo overview root element not found");
+  }
+
+  const root = options.root;
+  const browserWindow = options.window ?? getGlobalWindow();
+
+  if (browserWindow === undefined) {
+    throw new Error("Velumo overview window is not available");
+  }
+
+  const browserDocument =
+    options.document ?? getDocumentFromRoot(root) ?? getGlobalDocument();
+
+  if (browserDocument === undefined) {
+    throw new Error("Velumo overview document is not available");
+  }
+
+  const documentForOverview: OverviewDocumentLike = browserDocument;
+  const fallbackHost = documentForOverview.body ?? fallbackHostFromRoot(root);
+
+  if (options.host === undefined && fallbackHost === undefined) {
+    throw new Error("Velumo overview host element is not available");
+  }
+
+  const host: OverviewElementLike = options.host ?? fallbackHost!;
+
+  const previous = overviewRegistry.get(browserWindow);
+  if (previous !== undefined) {
+    previous.active = false;
+    overviewRegistry.delete(browserWindow);
+    previous.teardown();
+  }
+
+  ensureStyleInjected(documentForOverview);
+
+  let overlay: OverviewElementLike | undefined;
+  let stateChangeUnsubscribe: (() => void) | undefined;
+  let thumbnailHandles: Array<{ dispose(): void }> = [];
+  host.setAttribute(OVERVIEW_ATTRIBUTE, "closed");
+
+  function disposeThumbnails(): void {
+    for (const handle of thumbnailHandles) {
+      handle.dispose();
+    }
+    thumbnailHandles = [];
+  }
+
+  function isOpen(): boolean {
+    return overlay !== undefined;
+  }
+
+  function openOverview(): void {
+    if (isOpen()) {
+      return;
+    }
+
+    const mountQueue: Array<{ host: OverviewElementLike; slideId: string }> =
+      [];
+    overlay = renderOverlay(
+      documentForOverview,
+      options.runtime,
+      options.manifest,
+      options.mountThumbnail,
+      mountQueue,
+    );
+    host.append(overlay);
+    host.setAttribute(OVERVIEW_ATTRIBUTE, "open");
+
+    // Second pass: mount thumbnails after overlay is in the DOM so each host
+    // has a definite layout width for scale calculations.
+    if (options.mountThumbnail !== undefined) {
+      for (const { host: thumbHost, slideId } of mountQueue) {
+        const handle = options.mountThumbnail({
+          root: thumbHost,
+          manifest: options.manifest,
+          slideId,
+        });
+        thumbnailHandles.push(handle);
+      }
+    }
+
+    moveFocusToCurrentButton(overlay, options.runtime);
+    stateChangeUnsubscribe = options.runtime.on("state:change", () => {
+      refreshCurrentHighlight(overlay, options.runtime);
+    });
+  }
+
+  function closeOverview(): void {
+    if (!isOpen()) {
+      return;
+    }
+
+    stateChangeUnsubscribe?.();
+    stateChangeUnsubscribe = undefined;
+
+    disposeThumbnails();
+
+    if (overlay !== undefined) {
+      removeFromHost(host, overlay);
+      overlay = undefined;
+    }
+
+    host.setAttribute(OVERVIEW_ATTRIBUTE, "closed");
+    root.focus?.();
+  }
+
+  function handleKeydown(event: OverviewKeyboardEvent): void {
+    if (event.key === "Escape") {
+      if (isOpen()) {
+        closeOverview();
+        event.preventDefault();
+      }
+      return;
+    }
+
+    if (isEditableTarget(event.target)) {
+      return;
+    }
+
+    if (event.key === "o" && !isOpen()) {
+      openOverview();
+      event.preventDefault();
+    }
+  }
+
+  function jumpAndClose(slideId: string): void {
+    const changed = options.runtime.jumpToSlide(slideId);
+    if (changed) {
+      options.onAfterJump?.();
+    }
+    closeOverview();
+  }
+
+  function renderOverlay(
+    document: OverviewDocumentLike,
+    runtime: RuntimeController,
+    manifest: Manifest,
+    mountThumbnailOption: OverviewMountOptions["mountThumbnail"] | undefined,
+    mountQueue: Array<{ host: OverviewElementLike; slideId: string }>,
+  ): OverviewElementLike {
+    const overlayElement = document.createElement("div");
+    overlayElement.setAttribute("role", "dialog");
+    overlayElement.setAttribute("aria-label", OVERVIEW_ARIA_LABEL);
+    overlayElement.setAttribute(OVERVIEW_OVERLAY_ATTRIBUTE, "");
+
+    const heading = document.createElement("h2");
+    heading.append(OVERVIEW_ARIA_LABEL);
+    overlayElement.append(heading);
+
+    const grid = document.createElement("div");
+    grid.setAttribute(OVERVIEW_GRID_ATTRIBUTE, "");
+
+    const currentSlideId = runtime.getState().slideId;
+
+    manifest.slides.forEach((slide, index) => {
+      const button = document.createElement("button");
+      button.setAttribute("type", "button");
+      button.setAttribute(OVERVIEW_BUTTON_ATTRIBUTE, "");
+      button.setAttribute(OVERVIEW_SLIDE_ID_ATTRIBUTE, slide.id);
+      if (slide.id === currentSlideId) {
+        button.setAttribute("aria-current", "true");
+      }
+
+      const indexLabel = document.createElement("span");
+      indexLabel.append(`${index + 1}`);
+      const idLabel = document.createElement("span");
+      idLabel.append(slide.id);
+
+      if (mountThumbnailOption !== undefined) {
+        // Thumbnail mode: aria-hidden host + index badge + slide-id caption.
+        // The rendered thumbnail (aria-hidden) replaces the kind/heading VISUALLY,
+        // but the heading/kind is kept as visually-hidden text so screen-reader
+        // users can still identify slides with non-descriptive ids.
+        button.setAttribute("data-velumo-overview-thumb", "");
+        const thumbnailHost = document.createElement("div");
+        thumbnailHost.setAttribute("aria-hidden", "true");
+        thumbnailHost.setAttribute("data-velumo-thumbnail-host", "");
+        button.append(thumbnailHost, indexLabel, idLabel);
+        const headingText = findFirstHeadingText(
+          (slide as { layout?: unknown }).layout,
+        );
+        const srText =
+          headingText !== undefined && headingText !== ""
+            ? `${slide.kind}, ${headingText}`
+            : slide.kind;
+        const srLabel = document.createElement("span");
+        srLabel.setAttribute("data-velumo-overview-sr", "");
+        srLabel.append(srText);
+        button.append(srLabel);
+        // Record for the second-pass mount (after overlay is in the DOM).
+        mountQueue.push({ host: thumbnailHost, slideId: slide.id });
+      } else {
+        // Text-card mode (no mountThumbnail): keep existing behavior.
+        const kindLabel = document.createElement("span");
+        kindLabel.append(slide.kind);
+        button.append(indexLabel, idLabel, kindLabel);
+
+        const headingText = findFirstHeadingText(
+          (slide as { layout?: unknown }).layout,
+        );
+        if (headingText !== undefined && headingText !== "") {
+          const previewLabel = document.createElement("span");
+          previewLabel.append(headingText);
+          button.append(previewLabel);
+        }
+      }
+
+      button.addEventListener("click", () => jumpAndClose(slide.id));
+      grid.append(button);
+    });
+
+    overlayElement.append(grid);
+    return overlayElement;
+  }
+
+  browserWindow.addEventListener("keydown", handleKeydown);
+
+  const record: ActiveMountRecord = {
+    active: true,
+    teardown() {
+      browserWindow.removeEventListener("keydown", handleKeydown);
+      stateChangeUnsubscribe?.();
+      stateChangeUnsubscribe = undefined;
+      disposeThumbnails();
+      if (overlay !== undefined) {
+        removeFromHost(host, overlay);
+        overlay = undefined;
+      }
+      host.removeAttribute(OVERVIEW_ATTRIBUTE);
+    },
+  };
+  overviewRegistry.set(browserWindow, record);
+
+  return {
+    dispose() {
+      if (!record.active) {
+        return;
+      }
+      record.active = false;
+      record.teardown();
+      const current = overviewRegistry.get(browserWindow);
+      if (current === record) {
+        overviewRegistry.delete(browserWindow);
+      }
+    },
+  };
+}
+
+function ensureStyleInjected(document: OverviewDocumentLike): void {
+  const head = document.head;
+  if (head === undefined) {
+    return;
+  }
+
+  const existing = headHasStyleElement(head);
+  if (existing) {
+    return;
+  }
+
+  const style = document.createElement("style");
+  style.setAttribute(OVERVIEW_STYLE_ATTRIBUTE, "");
+  style.append(OVERVIEW_CSS);
+  head.append(style);
+}
+
+function headHasStyleElement(head: OverviewElementLike): boolean {
+  const queryable = head as {
+    querySelector?(selector: string): OverviewElementLike | null;
+  };
+  if (typeof queryable.querySelector === "function") {
+    return queryable.querySelector(`[${OVERVIEW_STYLE_ATTRIBUTE}]`) !== null;
+  }
+  return false;
+}
+
+function moveFocusToCurrentButton(
+  overlay: OverviewElementLike,
+  runtime: RuntimeController,
+): void {
+  const buttons = listButtons(overlay);
+  if (buttons.length === 0) {
+    return;
+  }
+
+  const currentSlideId = runtime.getState().slideId;
+  const currentButton =
+    buttons.find(
+      (button) =>
+        button.getAttribute(OVERVIEW_SLIDE_ID_ATTRIBUTE) === currentSlideId,
+    ) ?? buttons[0];
+
+  currentButton.focus?.();
+}
+
+function refreshCurrentHighlight(
+  overlay: OverviewElementLike | undefined,
+  runtime: RuntimeController,
+): void {
+  if (overlay === undefined) {
+    return;
+  }
+
+  const currentSlideId = runtime.getState().slideId;
+  for (const button of listButtons(overlay)) {
+    if (button.getAttribute(OVERVIEW_SLIDE_ID_ATTRIBUTE) === currentSlideId) {
+      button.setAttribute("aria-current", "true");
+    } else {
+      button.removeAttribute("aria-current");
+    }
+  }
+}
+
+function listButtons(overlay: OverviewElementLike): OverviewElementLike[] {
+  const queryable = overlay as {
+    querySelectorAll?(selector: string): OverviewElementLike[];
+  };
+
+  if (typeof queryable.querySelectorAll === "function") {
+    const collected = queryable.querySelectorAll(
+      `[${OVERVIEW_BUTTON_ATTRIBUTE}]`,
+    );
+    return Array.from(collected as ArrayLike<OverviewElementLike>);
+  }
+
+  return [];
+}
+
+function removeFromHost(
+  host: OverviewElementLike,
+  child: OverviewElementLike,
+): void {
+  if (typeof child.remove === "function") {
+    child.remove();
+    return;
+  }
+
+  const removable = host as {
+    removeChild?(child: OverviewElementLike): OverviewElementLike;
+  };
+  removable.removeChild?.(child);
+}
+
+function isEditableTarget(target: unknown): boolean {
+  if (target === null || typeof target !== "object") {
+    return false;
+  }
+
+  const candidate = target as {
+    readonly isContentEditable?: boolean;
+    readonly tagName?: string;
+  };
+
+  if (candidate.isContentEditable === true) {
+    return true;
+  }
+
+  const tagName = candidate.tagName?.toLowerCase();
+  return (
+    tagName === "input" ||
+    tagName === "textarea" ||
+    tagName === "select" ||
+    tagName === "button"
+  );
+}
+
+function findFirstHeadingText(node: unknown): string | undefined {
+  if (typeof node !== "object" || node === null) {
+    return undefined;
+  }
+  const candidate = node as {
+    readonly kind?: string;
+    readonly text?: string;
+    readonly children?: readonly unknown[];
+  };
+  if (candidate.kind === "heading" && typeof candidate.text === "string") {
+    return candidate.text;
+  }
+  if (Array.isArray(candidate.children)) {
+    for (const child of candidate.children) {
+      const found = findFirstHeadingText(child);
+      if (found !== undefined) {
+        return found;
+      }
+    }
+  }
+  return undefined;
+}
+
+function getGlobalWindow(): OverviewWindowLike | undefined {
+  return (globalThis as { window?: OverviewWindowLike }).window;
+}
+
+function getGlobalDocument(): OverviewDocumentLike | undefined {
+  return (globalThis as { document?: OverviewDocumentLike }).document;
+}
+
+function getDocumentFromRoot(
+  root: OverviewRootLike,
+): OverviewDocumentLike | undefined {
+  return root.ownerDocument;
+}
+
+function fallbackHostFromRoot(
+  root: OverviewRootLike,
+): OverviewElementLike | undefined {
+  const document = getDocumentFromRoot(root);
+  return document?.body;
+}