explico 0.3.0 → 0.5.0

package/src/components/reference/FloatRefLayer.astro

@@ -1,8 +1,9 @@
 ---
 /**
- * Progressive enhancement for `[[eq-key]]` / `[[tab-key]]` / `[[fig-key]]`
+ * Progressive enhancement for `[[eq-key]]` / `[[tab-key]]` / `[[fig-key]]` /
+ * `[[dia-key]]`
  * references in prose (F4, extended F-tables-figures) — one hover/pin/jump
- * engine shared by all three keyed floats. This generalizes the original
+ * engine shared by all four keyed floats. This generalizes the original
  * equation-only `EquationRefLayer`; the positioning, mutual-exclusion, and
  * pin/jump/Escape mechanics are unchanged, parameterized over `KIND_CONFIG`
  * below so a hover on any of the three trigger classes is handled the same
@@ -93,7 +94,10 @@ import HoverPanel from '../HoverPanel.astro';
     clone.removeAttribute('data-eq-key');
     clone.removeAttribute('data-eq-auto');
     clone.classList.remove('keyed-equation', 'eq-ref-highlight');
-    clone.querySelector('.keyed-equation__number')?.remove();
+    // The number link and the "Copy LaTeX" button both belong on the real
+    // equation, not a hover preview of it — same principle as the table
+    // preview below never offering its live pagination/expand controls.
+    clone.querySelector('.keyed-equation__controls')?.remove();
     return clone;
   }
 
@@ -102,7 +106,104 @@ import HoverPanel from '../HoverPanel.astro';
     return body ? document.importNode(body, true) : null;
   }
 
-  const KINDS: Record<'equation' | 'table' | 'figure', KindConfig> = {
+  // A table preview card is a static snapshot, not another place to keep
+  // paginating/expanding from — regardless of the live table's own current
+  // state (minimized, fully expanded, mid-scroll…) the clone always shows
+  // at most `KEEP_EACH_END * 2` rows with the "… N more rows …" separator
+  // centered, and never offers a way to reveal the rest or widen the table
+  // from inside the card (`Table.astro`'s own row-pagination and
+  // `TableOverflowExpander.astro`'s horizontal expand button, respectively —
+  // both belong on the real table, not a hover preview of it).
+  const TABLE_PREVIEW_KEEP_EACH_END = 3;
+
+  function capTablePreview(clone: HTMLElement): void {
+    const tbody = clone.querySelector('table')?.tBodies[0];
+    if (!tbody) return;
+
+    const moreRow = tbody.querySelector<HTMLElement>('.keyed-table__more-row');
+    const dataRows = Array.from(tbody.rows).filter((row) => row !== moreRow);
+    const totalRows = dataRows.length;
+
+    if (moreRow && totalRows > TABLE_PREVIEW_KEEP_EACH_END * 2) {
+      dataRows.forEach((row, index) => {
+        const inMiddle =
+          index >= TABLE_PREVIEW_KEEP_EACH_END &&
+          index < totalRows - TABLE_PREVIEW_KEEP_EACH_END;
+        row.hidden = inMiddle;
+      });
+      moreRow.hidden = false;
+      // `importNode` clones attributes (role/tabindex/class) but never JS
+      // listeners, so this row is already functionally inert here — strip
+      // the affordance too so it doesn't *look* clickable with nothing
+      // behind it.
+      moreRow.classList.remove('keyed-table__more-row--interactive');
+      moreRow.removeAttribute('role');
+      moreRow.removeAttribute('tabindex');
+      moreRow.removeAttribute('aria-label');
+    } else {
+      dataRows.forEach((row) => row.removeAttribute('hidden'));
+      moreRow?.remove();
+    }
+
+    // The pagination toggle/"Show less"/"Minimize" controls live outside
+    // `.keyed-table__body` (in the caption and after the body respectively),
+    // so cloning just the body already excludes them — only the horizontal
+    // overflow-expand button (`TableOverflowExpander.astro`) lives inside it.
+    clone
+      .querySelectorAll('.table-overflow-expand-btn')
+      .forEach((button) => button.remove());
+  }
+
+  let diagramCloneSerial = 0;
+
+  /**
+   * A diagram preview contains SVG fragment references (`url(#marker-id)`).
+   * Prefix every cloned id and rewrite those references so the preview cannot
+   * steal the moved/original diagram's arrow markers — or vice versa.
+   */
+  function cloneDiagramBody(target: HTMLElement): HTMLElement | null {
+    const clone = cloneBody(target, 'diagram-scroll');
+    if (!clone) return null;
+    clone.removeAttribute('id');
+    clone.removeAttribute('tabindex');
+    clone.removeAttribute('aria-labelledby');
+    clone.setAttribute('aria-label', 'Diagram preview');
+
+    const prefix = `float-ref-diagram-${++diagramCloneSerial}-`;
+    const ids = new Map<string, string>();
+    for (const element of clone.querySelectorAll<HTMLElement>('[id]')) {
+      const oldId = element.id;
+      const nextId = `${prefix}${oldId}`;
+      ids.set(oldId, nextId);
+      element.id = nextId;
+    }
+    const referenceAttributes = [
+      'marker-start',
+      'marker-mid',
+      'marker-end',
+      'clip-path',
+      'mask',
+      'filter',
+      'fill',
+      'stroke',
+      'href',
+      'xlink:href',
+    ];
+    for (const element of clone.querySelectorAll<HTMLElement>('*')) {
+      for (const attribute of referenceAttributes) {
+        const value = element.getAttribute(attribute);
+        if (!value) continue;
+        let rewritten = value;
+        for (const [oldId, nextId] of ids) {
+          rewritten = rewritten.split(`#${oldId}`).join(`#${nextId}`);
+        }
+        if (rewritten !== value) element.setAttribute(attribute, rewritten);
+      }
+    }
+    return clone;
+  }
+
+  const KINDS: Record<'equation' | 'table' | 'figure' | 'diagram', KindConfig> = {
     equation: {
       triggerClass: 'equation-ref',
       hrefPrefix: '#eq-',
@@ -128,6 +229,7 @@ import HoverPanel from '../HoverPanel.astro';
       revealOnPin: false,
       fillContent(target, contentEl) {
         const clone = cloneBody(target, 'keyed-table__body');
+        if (clone) capTablePreview(clone);
         contentEl.replaceChildren(...(clone ? [clone] : []));
       },
       captionFor(target) {
@@ -155,6 +257,22 @@ import HoverPanel from '../HoverPanel.astro';
         );
       },
     },
+    diagram: {
+      triggerClass: 'diagram-ref',
+      hrefPrefix: '#dia-',
+      numberClass: 'diagram__number',
+      numberDataKey: 'diaNumber',
+      highlightClass: 'dia-ref-highlight',
+      jumpLabel: 'diagram',
+      revealOnPin: false,
+      fillContent(target, contentEl) {
+        const clone = cloneDiagramBody(target);
+        contentEl.replaceChildren(...(clone ? [clone] : []));
+      },
+      captionFor(target) {
+        return target.querySelector('.diagram__caption-text')?.textContent ?? '';
+      },
+    },
   };
 
   const TRIGGER_SELECTOR = Object.values(KINDS)
@@ -197,6 +315,11 @@ import HoverPanel from '../HoverPanel.astro';
    */
   const pageCache = new Map<string, Promise<Document>>();
 
+  /** A standalone lesson deliberately has no other course pages to fetch. */
+  const standalone = document.documentElement.hasAttribute(
+    'data-explico-standalone',
+  );
+
   function fetchDoc(page: string): Promise<Document> {
     let pending = pageCache.get(page);
     if (!pending) {
@@ -232,6 +355,21 @@ import HoverPanel from '../HoverPanel.astro';
     const panel = document.querySelector<HTMLElement>('[data-float-ref-panel]')!;
     if (!panel || panel.dataset.floatRefReady === 'true') return;
 
+    // `.main-pane` (Starlight's `TwoColumnContent.astro`) sets
+    // `isolation: isolate`, which traps this panel's z-index inside it — the
+    // right "On this page" rail sits outside that isolation as a
+    // `position: fixed` sibling with no z-index of its own, and CSS still
+    // paints any positioned box ahead of a plain in-flow one regardless of
+    // z-index or DOM order. No z-index set here could ever win against that
+    // from inside `.main-pane`, so the panel is allowed to cover the rail
+    // (per its own design) by moving it out to `<body>` instead — the same
+    // fix the notation layer's popups already use for this exact trap (see
+    // `PopupStackConfig.container` in `popup-stack.ts`). `position: fixed`
+    // means the DOM parent doesn't affect its layout.
+    if (panel.parentElement !== document.body) {
+      document.body.appendChild(panel);
+    }
+
     const refs = Array.from(
       document.querySelectorAll<HTMLAnchorElement>(
         Object.values(KINDS)
@@ -292,6 +430,32 @@ import HoverPanel from '../HoverPanel.astro';
       target.querySelector(`.${kind.numberClass}`)?.classList.add('eq-number-revealed');
     };
 
+    /**
+     * How much horizontal room the card may use: from the right edge of the
+     * left sidebar nav to the viewport edge. Unlike the old article-column
+     * clamp, this deliberately does not stop at the right "On this page"
+     * rail — a wide equation (e.g. an OLS estimator) needs the room more
+     * than the card needs to respect the ToC's column, and readers can
+     * still reach the ToC once the card closes.
+     *
+     * `.sidebar-pane` is `position: fixed` and reports its full-viewport
+     * geometry even while hidden below the sidebar breakpoint (Starlight
+     * hides it with `visibility`, not `display`), so that has to be checked
+     * explicitly rather than trusted from the rect alone.
+     */
+    function horizontalRegion(edge: number): { start: number; end: number } {
+      const sidebarPane = document.querySelector<HTMLElement>('.sidebar-pane');
+      const sidebarVisible =
+        !!sidebarPane && getComputedStyle(sidebarPane).visibility !== 'hidden';
+      const sidebarRect = sidebarVisible
+        ? sidebarPane!.getBoundingClientRect()
+        : null;
+      return {
+        start: Math.max(edge, sidebarRect?.right ?? edge),
+        end: window.innerWidth - edge,
+      };
+    }
+
     function position(trigger: HTMLElement) {
       const edge = 12;
       const gap = 10;
@@ -300,6 +464,16 @@ import HoverPanel from '../HoverPanel.astro';
       const regionRect = safeRegion.getBoundingClientRect();
       const anchorRect = trigger.getBoundingClientRect();
 
+      // Set before any width-dependent measurement below so the card has
+      // already grown (or not) to its final width by the time its rect is
+      // read for placement.
+      const { start: horizontalStart, end: horizontalEnd } =
+        horizontalRegion(edge);
+      panel.style.setProperty(
+        '--float-ref-max-width',
+        `${Math.max(horizontalEnd - horizontalStart, 0)}px`,
+      );
+
       const headerBottom =
         document
           .querySelector<HTMLElement>('.header')
@@ -320,14 +494,6 @@ import HoverPanel from '../HoverPanel.astro';
         : regionRect.top - gap - rect.height;
       let left = anchorRect.left + anchorRect.width / 2 - rect.width / 2;
 
-      const article = document.querySelector<HTMLElement>('.sl-markdown-content');
-      const articleRect = article?.getBoundingClientRect();
-      const horizontalStart = Math.max(edge, articleRect?.left ?? edge);
-      const horizontalEnd = Math.min(
-        window.innerWidth - edge,
-        articleRect?.right ?? window.innerWidth - edge,
-      );
-
       top = Math.max(verticalStart, Math.min(top, verticalEnd - rect.height));
       left =
         horizontalEnd - horizontalStart >= rect.width
@@ -391,6 +557,7 @@ import HoverPanel from '../HoverPanel.astro';
 
       const crossPage = crossPageHref(trigger, kind);
       if (crossPage) {
+        if (standalone) return;
         void showCrossPage(trigger, kind, crossPage);
         return;
       }
@@ -533,6 +700,14 @@ import HoverPanel from '../HoverPanel.astro';
 
         const isCrossPage = crossPageHref(trigger, kind) !== null;
 
+        // A diagram reference remains an ordinary navigation link. Hover may
+        // preview an off-screen diagram, but clicking must dismiss that card
+        // and take the reader to the real diagram in one gesture.
+        if (kind.jumpLabel === 'diagram' && !isCrossPage) {
+          clearAll();
+          return;
+        }
+
         // A card that is already open for this trigger — same-page *or*
         // cross-page — pins in place instead of navigating. The only way to
         // the float itself is now the card's own number/"Jump to …" link.
@@ -543,6 +718,12 @@ import HoverPanel from '../HoverPanel.astro';
         }
 
         if (isCrossPage) {
+          // The exporter rewrites this to the canonical course URL. Leave it
+          // as an ordinary link; an offline hover/click must never fetch it.
+          if (standalone) {
+            clearAll();
+            return;
+          }
           // No card open yet (keyboard, or a click that beat the hover): open
           // it — pinned — rather than leave the page.
           event.preventDefault();
@@ -599,7 +780,15 @@ import HoverPanel from '../HoverPanel.astro';
     window.addEventListener(
       'scroll',
       () => {
-        if (mode === 'panel' && activeTrigger) position(activeTrigger);
+        if (mode !== 'panel' || !activeTrigger) return;
+        if (
+          activeTarget?.ownerDocument === document &&
+          isFullyVisible(activeTarget)
+        ) {
+          clearAll();
+          return;
+        }
+        position(activeTrigger);
       },
       { passive: true, capture: true },
     );
@@ -613,19 +802,28 @@ import HoverPanel from '../HoverPanel.astro';
   @layer starlight.components {
     .float-ref-panel-body {
       display: grid;
+      /* Grid items default to a content-based automatic minimum size, which
+         would let a wide equation inflate this track (and the card itself)
+         outward instead of scrolling inside `.float-ref-panel-content`. */
+      min-width: 0;
       gap: 0.6rem;
     }
 
     .float-ref-panel-main {
       display: flex;
-      align-items: baseline;
+      min-width: 0;
+      /* Center, not baseline: a tall equation's own baseline sits wherever
+         its glyphs put it, which for a fraction or multi-row expression can
+         be well above center — baseline-aligning the number to that point
+         would leave it looking pinned near the top of the card, seemingly
+         above the equation, instead of beside it. */
+      align-items: center;
       justify-content: space-between;
       gap: 0.75rem;
     }
 
     .float-ref-panel-number {
       flex: none;
-      align-self: flex-start;
       margin: 0;
       color: var(--sl-color-gray-3);
       font-weight: 600;
@@ -642,6 +840,12 @@ import HoverPanel from '../HoverPanel.astro';
     .float-ref-panel-content {
       min-width: 0;
       overflow-x: auto;
+      /* `overflow-x: auto` alone makes the block axis compute to `auto` too
+         (CSS Overflow §3), which would let a merely-tall equation grow its
+         own vertical scrollbar independent of the card's. Equations must
+         never scroll vertically on their own — only sideways, and only the
+         card as a whole. */
+      overflow-y: hidden;
       color: var(--sl-color-text);
     }
 
@@ -655,6 +859,20 @@ import HoverPanel from '../HoverPanel.astro';
 
     .float-ref-panel-content :global(table) {
       margin: 0;
+      /* 60% of the real table's own font-size (`global.css`'s
+         `.sl-markdown-content table` rule puts that at 90% of body text) —
+         this card sits outside `.sl-markdown-content` (moved to `<body>` at
+         runtime), so it's anchored to `--sl-text-base` directly rather than
+         inheriting that 90% rule. */
+      font-size: calc(var(--sl-text-base) * 0.9 * 0.6);
+    }
+
+    /* Same zebra striping formula as the real table
+       (`global.css`'s `.sl-markdown-content table … tbody tr:nth-child(even)`
+       rule), reproduced here because that rule is scoped to
+       `.sl-markdown-content`, which this cloned table sits outside of. */
+    .float-ref-panel-content :global(table tbody tr:nth-child(even)) {
+      background: color-mix(in srgb, var(--sl-color-bg) 85%, var(--sl-color-gray-5) 15%);
     }
 
     .float-ref-panel-caption {