explico 0.12.0 → 0.13.1

package/src/components/float-toolbar.ts

@@ -0,0 +1,274 @@
+/**
+ * The toolbar on a float's number. Hovering or focusing the number of an
+ * equation, a figure, a table or a diagram shows Pin and Dock just above the
+ * number and Copy link just below it, none of them over the number. Pin and
+ * Dock open the float's own reference card already kept, hung from the
+ * number (`card-manager.ts`, `keepCardFor`): pinned next to the float, or
+ * docked beside the article. Copy link is a `data-copy-link` link, so
+ * `HeadingAnchorEnhancer.astro` copies it, names it and confirms it, as it
+ * did for the chain icon this replaced, and the click still puts the anchor
+ * in the address bar. A click on the number itself only does that.
+ *
+ * There is one toolbar, moved next to the number in use, so Tab runs from
+ * the number through Pin, Dock and Copy link. A screen with no hover gets
+ * none: no pinning or docking there, and a long press on the number already
+ * offers the browser's own "Copy link".
+ *
+ * An equation's Copy LaTeX button is its own (`remark-notation.mjs`) and
+ * sits on the bottom border of the equation, which this module measures:
+ * under the number when the link button fits between the two, else slid
+ * along the border, clear of the number (`--eq-copy-inline-end`,
+ * `data-eq-compact`). The geometry is `copyLatexPlace`, pure, so
+ * `tests/unit/float-toolbar.test.ts` checks it in Node.
+ */
+import { keepCardFor } from './card-manager';
+
+/** A float's own number: an equation's, or a figure's, table's or diagram's caption number. */
+export const FLOAT_NUMBER = 'a.keyed-equation__number, a.float-caption__number';
+
+/** Between the number and a button, in px. */
+const GAP = 3;
+const HIDE_DELAY_MS = 250;
+
+const PIN_ICON =
+  '<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M6 1.75h4v4.25l2.25 2.75h-8.5L6 6z"/><path d="M8 8.75V14.5"/></svg>';
+const DOCK_ICON =
+  '<svg viewBox="0 0 16 16" aria-hidden="true"><rect x="1.75" y="2.75" width="12.5" height="10.5" rx="1.5"/><path d="M10.25 2.75v10.5"/></svg>';
+const LINK_ICON =
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42"/></svg>';
+
+// ---------------------------------------------------------------------------
+// The geometry, pure.
+// ---------------------------------------------------------------------------
+
+export interface CopyLatexInput {
+  /** The equation's box: its inline-end edge and its bottom, in px along each axis. */
+  readonly blockEnd: number;
+  readonly blockBottom: number;
+  /** The number's box. */
+  readonly numberStart: number;
+  readonly numberEnd: number;
+  readonly numberBottom: number;
+  /** The buttons' size, and the gap between the number and a button. */
+  readonly size: number;
+  readonly gap: number;
+}
+
+export interface CopyLatexPlace {
+  /** From the block's inline-end edge to the button's. */
+  readonly inlineEnd: number;
+  /** Too short for the link button between the number and the border. */
+  readonly compact: boolean;
+}
+
+/**
+ * Where an equation's Copy LaTeX button sits on its bottom border. Its
+ * centre is on the border. Under the number when the number's Copy link
+ * button (right below the number) fits above it; otherwise just past the
+ * number's inline-start edge, so neither button covers the number or the
+ * other. Coordinates run along the inline axis from the block's start, so
+ * the same arithmetic serves a right-to-left page.
+ */
+export function copyLatexPlace(input: CopyLatexInput): CopyLatexPlace {
+  const { blockEnd, blockBottom, numberStart, numberEnd, numberBottom, size, gap } = input;
+  const linkBottom = numberBottom + gap + size + gap;
+  const copyTop = blockBottom - size / 2;
+  const compact = linkBottom > copyTop;
+  const numberCentre = (numberStart + numberEnd) / 2;
+  const inlineEnd = compact
+    ? blockEnd - numberStart + gap
+    : blockEnd - numberCentre - size / 2;
+  return { inlineEnd: Math.max(0, Math.round(inlineEnd)), compact };
+}
+
+// ---------------------------------------------------------------------------
+// The DOM layer.
+// ---------------------------------------------------------------------------
+
+interface Toolbar {
+  readonly root: HTMLElement;
+  readonly above: HTMLElement;
+  readonly pin: HTMLButtonElement;
+  readonly dock: HTMLButtonElement;
+  readonly link: HTMLAnchorElement;
+  number: HTMLAnchorElement | null;
+  hideTimer: number | null;
+}
+
+function button(icon: string, label: string, title: string): HTMLButtonElement {
+  const el = document.createElement('button');
+  el.type = 'button';
+  el.className = 'float-toolbar__button';
+  el.innerHTML = icon;
+  el.setAttribute('aria-label', label);
+  el.title = title;
+  return el;
+}
+
+function build(): Toolbar {
+  const root = document.createElement('span');
+  // `not-content`: Starlight's article styles (the flow margin between
+  // siblings) stay off the buttons.
+  root.className = 'float-toolbar not-content';
+  root.hidden = true;
+  const above = document.createElement('span');
+  above.className = 'float-toolbar__above';
+  const pin = button(PIN_ICON, 'Pin', 'Keep this card open');
+  pin.dataset.floatPin = '';
+  const dock = button(DOCK_ICON, 'Beside the article', 'Keep this card beside the article');
+  dock.dataset.floatDock = '';
+  const link = document.createElement('a');
+  link.className = 'float-toolbar__link';
+  link.innerHTML = LINK_ICON;
+  link.title = 'Copy link';
+  above.append(pin, dock);
+  root.append(above, link);
+  return { root, above, pin, dock, link, number: null, hideTimer: null };
+}
+
+/** "Equation (2.1.1)", "Figure 2.1.1": what Copy link names the float. */
+function nameOf(number: HTMLElement): string {
+  const text = (number.textContent ?? '').trim();
+  return number.matches('a.keyed-equation__number') ? `Equation ${text}` : text;
+}
+
+/** Each part against the number, in the coordinates of the box they are placed in. */
+function place(toolbar: Toolbar, number: HTMLElement): void {
+  const parent = (toolbar.above.offsetParent as HTMLElement | null) ?? document.body;
+  const box = parent.getBoundingClientRect();
+  const n = number.getBoundingClientRect();
+  const centre = n.left + n.width / 2 - box.left - parent.clientLeft + parent.scrollLeft;
+  const top = n.top - box.top - parent.clientTop + parent.scrollTop;
+  toolbar.above.style.left = `${Math.round(centre - toolbar.above.offsetWidth / 2)}px`;
+  toolbar.above.style.top = `${Math.round(top - toolbar.above.offsetHeight - GAP)}px`;
+  toolbar.link.style.left = `${Math.round(centre - toolbar.link.offsetWidth / 2)}px`;
+  toolbar.link.style.top = `${Math.round(top + n.height + GAP)}px`;
+}
+
+function layoutEquation(equation: HTMLElement): void {
+  const number = equation.querySelector<HTMLElement>('a.keyed-equation__number');
+  const copy = equation.querySelector<HTMLElement>('.keyed-equation__copy');
+  if (!number || !copy) return;
+  const e = equation.getBoundingClientRect();
+  const n = number.getBoundingClientRect();
+  if (e.height === 0 || n.width === 0) return;
+  const rtl = getComputedStyle(equation).direction === 'rtl';
+  // Along the inline axis, from the block's start edge.
+  const along = (x: number) => (rtl ? e.right - x : x - e.left);
+  const { inlineEnd, compact } = copyLatexPlace({
+    blockEnd: e.width,
+    blockBottom: e.height,
+    numberStart: Math.min(along(n.left), along(n.right)),
+    numberEnd: Math.max(along(n.left), along(n.right)),
+    numberBottom: n.bottom - e.top,
+    size: copy.offsetWidth || 22,
+    gap: GAP,
+  });
+  equation.style.setProperty('--eq-copy-inline-end', `${inlineEnd}px`);
+  equation.toggleAttribute('data-eq-compact', compact);
+}
+
+/** Place every equation's Copy LaTeX button, and again whenever an equation changes size. */
+function watchEquations(root: ParentNode): void {
+  const equations = Array.from(root.querySelectorAll<HTMLElement>('.keyed-equation'));
+  if (equations.length === 0) return;
+  const observer = new ResizeObserver((entries) => {
+    for (const entry of entries) layoutEquation(entry.target as HTMLElement);
+  });
+  for (const equation of equations) {
+    layoutEquation(equation);
+    observer.observe(equation);
+  }
+  document.fonts?.ready.then(() => equations.forEach(layoutEquation), () => {});
+}
+
+/** Wire the toolbar for every float number in `root`, the article. */
+export function startFloatToolbar(root: HTMLElement): void {
+  watchEquations(root);
+
+  const canHover = window.matchMedia('(hover: hover)');
+  const toolbar = build();
+
+  const numberFrom = (node: EventTarget | null): HTMLAnchorElement | null => {
+    if (!(node instanceof Element)) return null;
+    const number = node.closest<HTMLAnchorElement>(FLOAT_NUMBER);
+    return number && root.contains(number) ? number : null;
+  };
+  const inToolbar = (node: EventTarget | null) =>
+    node instanceof Node && toolbar.root.contains(node);
+  const keeps = (node: EventTarget | null) =>
+    inToolbar(node) || (node instanceof Node && !!toolbar.number?.contains(node));
+
+  const cancelHide = () => {
+    if (toolbar.hideTimer !== null) window.clearTimeout(toolbar.hideTimer);
+    toolbar.hideTimer = null;
+  };
+  const hide = () => {
+    cancelHide();
+    toolbar.root.hidden = true;
+  };
+  const scheduleHide = () => {
+    cancelHide();
+    toolbar.hideTimer = window.setTimeout(hide, HIDE_DELAY_MS);
+  };
+
+  const show = (number: HTMLAnchorElement) => {
+    cancelHide();
+    if (toolbar.number !== number || !toolbar.root.isConnected) {
+      const name = nameOf(number);
+      number.after(toolbar.root);
+      toolbar.number = number;
+      toolbar.link.href = number.getAttribute('href') ?? '';
+      toolbar.link.dataset.copyLink = name;
+      toolbar.link.setAttribute('aria-label', `Copy the link to ${name}`);
+      toolbar.pin.setAttribute('aria-label', `Pin ${name}`);
+      toolbar.dock.setAttribute('aria-label', `Keep ${name} beside the article`);
+    }
+    toolbar.root.hidden = false;
+    place(toolbar, number);
+  };
+
+  root.addEventListener('pointerover', (event) => {
+    if (event.pointerType === 'touch' || !canHover.matches) return;
+    const number = numberFrom(event.target);
+    if (number) show(number);
+    else if (inToolbar(event.target)) cancelHide();
+  });
+  root.addEventListener('pointerout', (event) => {
+    if (toolbar.root.hidden || !keeps(event.target)) return;
+    if (keeps(event.relatedTarget)) return;
+    scheduleHide();
+  });
+  // Escape gives focus back to the number without showing the toolbar again.
+  let quietFocus = false;
+  root.addEventListener('focusin', (event) => {
+    if (quietFocus) return;
+    const number = numberFrom(event.target);
+    if (number && canHover.matches && number.matches(':focus-visible')) show(number);
+    else if (inToolbar(event.target)) cancelHide();
+  });
+  root.addEventListener('focusout', (event) => {
+    if (toolbar.root.hidden || keeps(event.relatedTarget)) return;
+    scheduleHide();
+  });
+  root.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape' || toolbar.root.hidden) return;
+    const inside = inToolbar(document.activeElement);
+    hide();
+    if (inside && toolbar.number) {
+      quietFocus = true;
+      toolbar.number.focus();
+      quietFocus = false;
+    }
+  });
+
+  const keep = (mode: 'pinned' | 'side') => {
+    const number = toolbar.number;
+    hide();
+    if (number) keepCardFor('reference', number, mode);
+  };
+  toolbar.pin.addEventListener('click', () => keep('pinned'));
+  toolbar.dock.addEventListener('click', () => keep('side'));
+  // Copy link copies and navigates through `HeadingAnchorEnhancer.astro`.
+  toolbar.link.addEventListener('click', () => window.setTimeout(hide, 0));
+}

package/src/components/memo/Memo.astro

@@ -358,16 +358,10 @@ const name = `Memo ${number}: ${short ?? caption}`;
 
         // The marker opens the memo where it is and goes there, and closes
         // it again: the section's own summary does the folding, so the
-        // animation, the peek and the saved choice stay the section's.
-        marker.addEventListener('click', (event) => {
-          const details = sectionOf(heading);
-          const summary = details?.querySelector<HTMLElement>(':scope > summary');
-          if (!details || !summary) return;
-          event.preventDefault();
-          const opening = !isOpen();
-          summary.click();
-          if (!opening) return;
-
+        // animation, the peek and the saved choice stay the section's. An
+        // open memo the reader cannot see is gone to, not folded: closing it
+        // off-screen would look as if the click did nothing.
+        const goTo = () => {
           closeHoverPeek(marker);
           if (location.hash !== `#${heading.id}`) {
             history.pushState(null, '', `#${heading.id}`);
@@ -375,6 +369,23 @@ const name = `Memo ${number}: ${short ?? caption}`;
           requestAnimationFrame(() => {
             animatedScrollIntoView(frame, { block: 'start' });
           });
+        };
+        const onScreen = () => {
+          const box = frame.getBoundingClientRect();
+          return box.bottom > 0 && box.top < window.innerHeight;
+        };
+        marker.addEventListener('click', (event) => {
+          const details = sectionOf(heading);
+          const summary = details?.querySelector<HTMLElement>(':scope > summary');
+          if (!details || !summary) return;
+          event.preventDefault();
+          const opening = !isOpen();
+          if (!opening && !onScreen()) {
+            goTo();
+            return;
+          }
+          summary.click();
+          if (opening) goTo();
         });
       }
     });

package/src/components/memo/ShortNote.astro

@@ -216,5 +216,9 @@ if (!anchorId) {
       };
       window.addEventListener('hashchange', revealForHash);
       revealForHash();
+      // A number alias (`#eq-2.1.1`) is rewritten to its named anchor by
+      // `KeyedFloatEnhancer.astro`, whose script runs after this one and
+      // fires no event; look again once every script has run.
+      document.addEventListener('DOMContentLoaded', revealForHash, { once: true });
     });
 </script>

package/src/components/notation/NotationGlossary.astro

@@ -13,6 +13,8 @@ import {
   lessonIdFromSlug,
 } from '../../compiler/lesson-derivation';
 import { loadManifest } from '../../compiler/manifest';
+import { isIndexEntryLatex } from '../../compiler/content-schemas';
+import { indexEntryFormula } from '../../reference/derived-notation.mjs';
 
 const [notationEntries, lessonEntries, manifest] = await Promise.all([
   getCollection('notation'),
@@ -22,14 +24,20 @@ const [notationEntries, lessonEntries, manifest] = await Promise.all([
 // Starlight's `link-alt` icon — the same glyph its own heading anchors use
 // (`rehype-heading-anchors.mjs`). Reimplemented here rather than reused via
 // `.sl-anchor-link`/`.sl-heading-wrapper` because that CSS assumes a single
-// inline prose heading, not this entry's three-column grid header (symbol,
-// name, editorial status) — the glyph carries over, the layout doesn't, so
-// this file supplies its own reveal styling (below).
+// inline prose heading, not this entry's two-column grid header (symbol,
+// name) — the glyph carries over, the layout doesn't, so this file supplies
+// its own reveal styling (below).
 const HEADING_LINK_ICON_PATH =
   'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42';
 
 const labelOf = (data: { key: string; label?: string }) =>
   resolveLabel(data.key, data.label);
+// An index entry's formula names what it indexes as `{base}` (rule N23); on
+// its own card that is a square bound to the entry.
+const formulaOf = (data: { key: string; latex: string; formula?: string }) =>
+  data.formula !== undefined && isIndexEntryLatex(data.latex)
+    ? indexEntryFormula(data.formula, data.key)
+    : data.formula;
 const notationLabelByKey = new Map(
   notationEntries.map((entry) => [entry.data.key, labelOf(entry.data)]),
 );
@@ -72,7 +80,7 @@ const formulaScopeByKey = new Map<string, GlyphScopeEntry[]>(
     formulaGlyphScope({
       key: entry.data.key,
       notation: entry.data.latex,
-      formula: entry.data.formula,
+      formula: formulaOf(entry.data),
       glosses: glossesByKey.get(entry.data.key) ?? [],
       cardsByKey,
     }),
@@ -113,12 +121,12 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     notation: entry.data.latex,
     label: labelOf(entry.data),
     summary: entry.data.meaning,
-    formula: entry.data.formula,
+    formula: formulaOf(entry.data),
     formulaScope: formulaScopeByKey.get(entry.data.key),
     glosses: glossesByKey.get(entry.data.key),
     units: entry.data.units,
+    range: entry.data.range,
     seeAlso: entry.data.seeAlso,
-    editorialStatus: entry.data.editorialStatus,
     scope: 'shared',
     href: `#notation-${entry.data.key}`,
   }),
@@ -186,7 +194,6 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
               </div>
               <code>{entry.data.key}</code>
             </div>
-            <span class="glossary-status">{entry.data.editorialStatus}</span>
           </header>
 
           <dl class="glossary-metadata">
@@ -200,6 +207,12 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
                 <dd>{entry.data.units}</dd>
               </div>
             )}
+            {entry.data.range && (
+              <div>
+                <dt>Runs over</dt>
+                <dd><NotationMath latex={entry.data.range} /></dd>
+              </div>
+            )}
             {entry.data.aliases.length > 0 && (
               <div>
                 <dt>Aliases</dt>
@@ -225,7 +238,7 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
           {entry.data.formula && (
             <div class="glossary-formula">
               <NotationFormula
-                formula={entry.data.formula}
+                formula={formulaOf(entry.data) ?? ''}
                 scope={formulaScopeByKey.get(entry.data.key) ?? []}
                 glosses={glossesByKey.get(entry.data.key)}
                 entryLabel={labelOf(entry.data)}
@@ -325,7 +338,7 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
 
   article > header {
     display: grid;
-    grid-template-columns: minmax(4rem, auto) 1fr auto;
+    grid-template-columns: minmax(4rem, auto) 1fr;
     align-items: center;
     gap: 1rem;
   }
@@ -425,14 +438,6 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     }
   }
 
-  .glossary-status {
-    padding: 0.15rem 0.5rem;
-    border: 1px solid var(--sl-color-gray-5);
-    border-radius: 999px;
-    color: var(--sl-color-gray-3);
-    font-size: var(--sl-text-xs);
-  }
-
   .glossary-metadata {
     display: grid;
     gap: 0.45rem;