brain-of-reese/frontend/assets/document-modal.js

/* Brain of Reese — document modal (phase 26, task 02).
 *
 * "New documents should open in an almost-fullscreen modal, not in a new
 * page" (TODO.md L4). This module is the SINGLE owner of the modal (the
 * way header.js owns the shared header): the chat page (app.js source
 * chips) and the Sources page (sources.js table links) each import
 * openDocumentModal(...) from here — one implementation, no duplicate
 * module instance, no direct <script> tag (esbuild inlines it into the
 * page bundle, same single-evaluation design as header.js).
 *
 * Contract:
 *   • openDocumentModal(source, path, triggerEl) — shows the #doc-modal
 *     overlay (the phase-26 task-01 skeleton) in its loading state,
 *     moves focus into #doc-modal-content (tabindex="-1" — programmatic
 *     focus target), fetches GET /api/documents/content (the SAME
 *     stateless endpoint the /document.html page uses — identical
 *     percent-encoding), and renders through document.js's shared
 *     renderDocument: md/markdown → .doc-md via the escape-first
 *     renderer, other formats → <pre class="doc-raw"> via textContent.
 *     A !ok / network failure renders a short "document not found" line
 *     in the content area.
 *   • closeDocumentModal() — hides the overlay, removes the Escape/Tab
 *     capture, and restores focus to the element that opened the modal
 *     (best-effort: the trigger may have been removed from the DOM, e.g.
 *     "New chat" clearing the list while the modal is open).
 *   • Close affordances (modal UX standard): #doc-modal-close button,
 *     backdrop click, and the Escape key (captured on document, so it
 *     works no matter where focus is). While open, Tab / Shift+Tab are
 *     trapped inside the panel.
 *   • History (phase 144, TODO L6): the open owns ONE state-only
 *     entry ({ modal: "doc", source, path } — the URL does not move, so
 *     the router's pathname-only popstate is a no-op and the Sources
 *     drill re-adopts the state it was already showing): Back closes
 *     the modal (view/URL/drill untouched), a button/Escape/backdrop
 *     close removes the entry IN PLACE (the next Back behaves as if the
 *     modal never opened), and Forward onto the entry re-opens the same
 *     document (the browser owns its entries — the phase-99 D2
 *     convention).
 *   • #doc-modal-open ("Full page") is the escape hatch to the
 *     dedicated viewer: its href is set on open to the same
 *     /document.html?source=…&path=… URL the chip/table link carries,
 *     so the no-JS / direct-link page is always one click away.
 *
 * Import safety: the top level only binds controls that exist on the
 * page (a missing element is a no-op — the header.js pattern). document
 * .js is imported for renderDocument alone; its /document.html-specific
 * init is guarded there, so importing this module on the chat/sources
 * pages has no side effects beyond binding the modal itself.
 */

import { renderDocument } from "./document.js";

const modalEl = document.querySelector("#doc-modal");
const backdropEl = document.querySelector("#doc-modal-backdrop");
const panelEl = document.querySelector("#doc-modal-panel");
const titleEl = document.querySelector("#doc-modal-title");
const metaEl = document.querySelector("#doc-modal-meta");
const contentEl = document.querySelector("#doc-modal-content");
const openEl = document.querySelector("#doc-modal-open");
const closeEl = document.querySelector("#doc-modal-close");
const descEl = document.querySelector("#doc-modal-desc");

/* The element that opened the modal — closeDocumentModal restores focus
 * to it (best-effort, see the header note). */
let triggerEl = null;
/* Monotonic fetch sequence: a close or a re-open for another document
 * must not render a stale response into the modal (rapid
 * open → close → open). */
let fetchSeq = 0;
/* The modal's history entry (phase 144, TODO L6): { prev, source,
 * path } while the modal is open — prev is the below-entry to restore
 * on a non-back close; source/path name the doc the entry carries.
 * Written ONLY by openDocumentModal (push on a normal open, adopt on
 * the forward re-open, in-place replace on a defensive re-open-while-
 * open); nulled by closeDocumentModal. */
let entry = null;
/* The below-entry remembered at each back-close (the popstate handler
 * is its only writer): a forward re-open adopts it as the entry's
 * prev — at that moment the browser sits ON the modal entry, so the
 * below-entry is known only from here. Null/stale otherwise. */
let lastPrev = null;
/* True ONLY around the popstate handler's closeDocumentModal call
 * (a back press already moved us off the entry, so that close must
 * not replaceState it again). Set and reset by the popstate handler
 * alone. */
let closingViaBack = false;

/* Same encoding the chips and the Sources table links use — both query
 * values percent-encoded (real paths contain slashes, sometimes spaces). */
function contentUrl(source, path) {
  return "/api/documents/content?source=" + encodeURIComponent(source) + "&path=" + encodeURIComponent(path);
}

function fullPageUrl(source, path) {
  return "/document.html?source=" + encodeURIComponent(source) + "&path=" + encodeURIComponent(path);
}

function statusLine(text) {
  const p = document.createElement("p");
  p.className = "doc-modal-loading";
  p.setAttribute("role", "status");
  p.textContent = text;
  return p;
}

function setDesc(text) {
  if (descEl) descEl.textContent = text; // the #doc-modal-desc role=status announcer
}

function showLoading() {
  if (titleEl) titleEl.textContent = "Loading…";
  if (metaEl) metaEl.replaceChildren();
  if (contentEl) contentEl.replaceChildren(statusLine("Loading document…"));
  setDesc("Document content is loading.");
}

function renderNotFound(path) {
  if (titleEl) titleEl.textContent = "Document not found";
  if (metaEl) metaEl.replaceChildren();
  if (contentEl) {
    contentEl.replaceChildren(
      statusLine(`“${path}” was not found — it may have been removed in a re-import.`),
    );
  }
  setDesc("Document not found.");
}

/* Focus trap while the modal is open: Tab / Shift+Tab cycle within the
 * panel (the visible controls are "Full page" + Close; the content
 * target is programmatic-focus only, tabindex="-1"). */
const FOCUSABLE =
  'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])';

function onModalKeydown(e) {
  if (e.key === "Escape") {
    e.preventDefault();
    closeDocumentModal();
    return;
  }
  if (e.key !== "Tab" || !panelEl) return;
  const focusable = Array.from(panelEl.querySelectorAll(FOCUSABLE)).filter(
    (el) => el.getClientRects().length > 0,
  );
  if (!focusable.length) {
    e.preventDefault();
    if (contentEl) contentEl.focus({ preventScroll: true });
    return;
  }
  const first = focusable[0];
  const last = focusable[focusable.length - 1];
  const active = document.activeElement;
  const inside = active !== null && panelEl.contains(active);
  if (e.shiftKey) {
    if (!inside || active === first) {
      e.preventDefault();
      last.focus();
    }
  } else if (!inside || active === last) {
    e.preventDefault();
    first.focus();
  }
}

/* Show the modal for (source, path) and fetch + render the document.
 * `trigger` (the chip / table link that was clicked) is remembered so
 * closeDocumentModal can return focus to it. */
export function openDocumentModal(source, path, trigger = null) {
  if (!modalEl || !titleEl || !metaEl || !contentEl) {
    // No modal skeleton on this page (should not happen for the pages
    // that import this module) — fall back to the dedicated viewer
    // instead of swallowing the click.
    window.open(fullPageUrl(source, path), "_blank", "noopener");
    return;
  }
  /* Phase 144 (TODO L6): the modal owns ONE state-only history entry —
   * Back closes the modal instead of navigating the view behind it.
   * The entry is state-only (second arg "" — the URL does not move),
   * so the router's pathname-only popstate is a no-op and the Sources
   * drill re-adopts the state it was already showing (the sources.js
   * state-only-entry convention, L1539). The current entry is a modal
   * entry only on the forward re-open (the popstate handler below
   * calls us sitting on it) — then we ADOPT it; otherwise we push. */
  const st = history.state;
  if (entry) {
    // Defensive re-open while open: replace our entry in place (the
    // remembered prev is kept) — never stack a second entry.
    entry.source = source;
    entry.path = path;
    history.replaceState({ modal: "doc", source, path }, "");
  } else if (st && st.modal === "doc") {
    // Forward onto our own entry: adopt — the browser already sits on
    // it (lastPrev is the below-entry remembered at the back-close).
    entry = { prev: lastPrev, source, path };
  } else {
    entry = { prev: st, source, path };
    history.pushState({ modal: "doc", source, path }, "");
  }
  triggerEl = trigger && typeof trigger.focus === "function" ? trigger : null;
  modalEl.hidden = false; // .doc-modal[hidden] { display:none } — visible now
  showLoading();
  if (openEl) {
    openEl.href = fullPageUrl(source, path); // the "Full page" escape hatch
    openEl.hidden = false;
  }
  document.addEventListener("keydown", onModalKeydown, true); // Escape + Tab trap
  contentEl.focus({ preventScroll: true }); // a11y: focus moves INTO the dialog

  const seq = ++fetchSeq;
  fetch(contentUrl(source, path))
    .then(async (r) => {
      if (seq !== fetchSeq) return; // stale — closed or re-opened meanwhile
      if (!r.ok) {
        renderNotFound(path);
        return;
      }
      const doc = await r.json();
      if (seq !== fetchSeq) return;
      renderDocument(doc, { titleEl, metaEl, contentEl });
      setDesc("Document loaded.");
    })
    .catch(() => {
      if (seq === fetchSeq) renderNotFound(path);
    });
}

/* Hide the modal, drop the Escape/Tab capture, and restore focus to the
 * triggering control (best-effort — it may have been removed from the
 * DOM since the modal opened). */
export function closeDocumentModal() {
  if (!modalEl || modalEl.hidden) return;
  /* Phase 144: a NON-back close removes the modal's entry IN PLACE —
   * no popstate fires, no other listener runs, the view state is back
   * byte-for-byte, so the next Back behaves as if the modal never
   * opened. A back close (closingViaBack — the popstate handler) has
   * already been moved off the entry by the browser: no replace. */
  if (entry && !closingViaBack && history.state && history.state.modal === "doc") {
    history.replaceState(entry.prev, "");
  }
  entry = null;
  fetchSeq += 1; // any in-flight fetch is stale now
  modalEl.hidden = true;
  document.removeEventListener("keydown", onModalKeydown, true);
  if (openEl) {
    openEl.hidden = true;
    openEl.removeAttribute("href");
  }
  if (triggerEl && typeof triggerEl.focus === "function" && document.contains(triggerEl)) {
    triggerEl.focus({ preventScroll: true });
  }
  triggerEl = null;
}

/* Top-level bindings — only on pages that carry the modal skeleton
 * (a missing element is a no-op, the header.js pattern). The Escape /
 * Tab capture is per-open (added/removed in open/close), so it never
 * leaks into the page behind a closed modal. */
if (closeEl) closeEl.addEventListener("click", closeDocumentModal);
if (backdropEl) backdropEl.addEventListener("click", closeDocumentModal);

/* Phase 144 (TODO L6): back/forward onto the modal's entry. popstate
 * fires with the state of the entry we LANDED on. Back: the modal is
 * open and we landed on a non-modal state — the browser moved off our
 * entry; close the modal (remember the landed state as lastPrev for
 * the forward re-open; closingViaBack keeps the close from also
 * replaceState-ing). Forward: the modal is closed and we landed on a
 * modal entry — the browser owns its entries (the phase-99 D2
 * convention) — re-open the doc the entry names (the open adopts the
 * entry — no second push). Every other popstate (the router's view
 * entries, the drill's kb entries) passes through untouched. A missing
 * skeleton is a no-op via the entry/modalEl guards (the header.js
 * pattern). */
window.addEventListener("popstate", (event) => {
  const st = event.state;
  const isModalEntry = st && st.modal === "doc";
  if (isModalEntry && modalEl && modalEl.hidden) {
    openDocumentModal(st.source, st.path, null);
    return;
  }
  if (!isModalEntry && modalEl && !modalEl.hidden && entry) {
    lastPrev = st;
    closingViaBack = true;
    closeDocumentModal();
    closingViaBack = false;
  }
});