explico 0.6.0 → 0.7.0

package/src/components/notation/NotationFormula.astro

@@ -33,6 +33,10 @@ export interface Props {
   glossLabel?: string;
   /** The owning entry's display label, used to name the scrollable region. */
   entryLabel?: string;
+  /** `G.<n>` — the glossary's own equation numbering. Omitted renders no number. */
+  number?: string;
+  /** Same-page anchor the number links to; ignored unless `number` is set. */
+  numberHref?: string;
 }
 
 const {
@@ -41,6 +45,8 @@ const {
   glosses = [],
   glossLabel = 'Symbols',
   entryLabel,
+  number,
+  numberHref,
 } = Astro.props;
 const { nodes } = renderNotationFormula(formula, scope);
 registerPageNotationDependencies(
@@ -48,20 +54,49 @@ registerPageNotationDependencies(
   notationKeysInMathNodes(nodes),
   `NotationFormula formula "${formula}"`,
 );
+const latex = stripNotationMarkers(formula);
+const numbered = Boolean(number && numberHref);
 ---
 
 <div class="notation-formula-block">
   <div
-    class="notation-formula-math"
+    class:list={['notation-formula-math', numbered && 'notation-formula-math--numbered']}
     data-notation-formula
-    data-latex={stripNotationMarkers(formula)}
+    data-latex={latex}
     role="group"
     aria-label={entryLabel ? `${entryLabel} formula` : 'Formula'}
-    tabindex="0"
   >
-    <span class="notation-math">
-      {nodes.map((node) => <SafeMathNode node={node} />)}
-    </span>
+    <div class="notation-formula-scroll" tabindex="0">
+      <span class="notation-math">
+        {nodes.map((node) => <SafeMathNode node={node} />)}
+      </span>
+    </div>
+    {numbered && (
+      <div class="notation-formula-controls">
+        <a
+          class="notation-formula-number"
+          href={numberHref}
+          aria-label={`Equation ${number}`}
+          title="Anchor to this equation"
+        >
+          ({number})
+        </a>
+        <button
+          class="notation-formula-copy"
+          type="button"
+          data-notation-formula-copy
+          data-latex={latex}
+          aria-label={`Copy LaTeX for Equation ${number}`}
+          title="Copy LaTeX"
+        >
+          <svg viewBox="0 0 24 24" aria-hidden="true">
+            <rect x="9" y="9" width="10" height="10" rx="1"></rect>
+            <path d="M6 15H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v1"
+            ></path>
+          </svg>
+        </button>
+      </div>
+    )}
   </div>
 
   {
@@ -95,25 +130,179 @@ registerPageNotationDependencies(
       gap: 0.5rem;
     }
 
+    /* The outer box is deliberately never a scroll clip itself — it hosts the
+       absolutely-positioned number/copy controls and their "Copied!" flash,
+       which a clipping ancestor would cut off. Mirrors `.keyed-equation` in
+       `global.css`, which splits the same way (its own overflow lives on the
+       nested `.katex-display`, not on `.keyed-equation` itself). Its cursor,
+       hover highlight, and "Copied!" flash are the generic
+       `[data-notation-formula]` rules in `global.css` — shared with every
+       other producer of that attribute, not reimplemented here. */
+    .notation-formula-math {
+      color: var(--sl-color-text);
+    }
+
+    .notation-formula-math--numbered {
+      padding-inline-end: 5.25rem;
+    }
+
     /* A wide equation scrolls inside its own box, which makes the box a
        scrollable region — and a scrollable region a keyboard user cannot reach
        is unreachable content, not just an awkward one. `tabindex` on the
-       container is the fix; this is its focus ring. */
-    .notation-formula-math {
+       scrolling element itself (not an ancestor) is the fix, same convention
+       as `.table-overflow-scroll` in `global.css`; this is its focus ring. */
+    .notation-formula-scroll {
       overflow-x: auto;
       /* `overflow-x: auto` alone makes the block axis compute to `auto` too
          (CSS Overflow §3) — equations must never scroll vertically on their
          own, only sideways. */
       overflow-y: hidden;
       padding-block: 0.15rem;
-      color: var(--sl-color-text);
     }
 
-    .notation-formula-math:focus-visible {
+    .notation-formula-scroll:focus-visible {
       outline: 3px solid var(--sl-color-accent);
       outline-offset: 2px;
     }
 
+    /* Numbered controls — a glossary entry's own equation number and copy
+       button, styled to match `.keyed-equation__controls`/`__number`/`__copy`
+       in `global.css` exactly (same values), so a reader sees one consistent
+       "numbered equation" affordance across lessons and the glossary. */
+    .notation-formula-controls {
+      position: absolute;
+      inset-inline-end: 0.25rem;
+      inset-block-start: 50%;
+      transform: translateY(-50%);
+      display: inline-flex;
+      align-items: center;
+      gap: 0.4rem;
+      /* Starlight's generic prose "sibling spacing" rule adds a margin-top
+         to any block-level element that follows another (here, following
+         `.notation-formula-scroll`) — harmless for flow content, but it
+         shifts an absolutely-positioned box's `top: 50%` off-center, since
+         margin still applies to an out-of-flow element's own offset. */
+      margin: 0;
+    }
+
+    .notation-formula-number {
+      font-variant-numeric: tabular-nums;
+      font-size: var(--sl-text-sm);
+      color: var(--sl-color-text-accent);
+      text-decoration: none;
+      /* Without this it would inherit the container's `cursor: copy` above
+         instead of the link's usual pointer, since an inherited value beats
+         the browser's own "auto → hand cursor for a link" special case. */
+      cursor: pointer;
+      opacity: 0.45;
+      transition: opacity 120ms ease-out;
+    }
+
+    .notation-formula-copy {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.5rem;
+      height: 1.5rem;
+      padding: 0;
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 999px;
+      color: var(--sl-color-gray-1);
+      background: transparent;
+      font: inherit;
+      cursor: pointer;
+      opacity: 0.45;
+      transition:
+        opacity 120ms ease-out,
+        border-color 120ms ease-out,
+        color 120ms ease-out;
+    }
+
+    .notation-formula-copy svg {
+      width: 0.85rem;
+      height: 0.85rem;
+      fill: none;
+      stroke: currentColor;
+      stroke-width: 1.75;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+
+    @media (hover: none) {
+      .notation-formula-number,
+      .notation-formula-copy {
+        opacity: 1;
+      }
+    }
+
+    /* Hovering (or focusing) anywhere in the equation reveals the number and
+       copy button together — the "highlight" that signals the whole box is
+       interactive, not just its own small controls corner. */
+    .notation-formula-math:hover .notation-formula-number,
+    .notation-formula-math:focus-within .notation-formula-number,
+    .notation-formula-number:focus-visible {
+      opacity: 1;
+      text-decoration: underline;
+    }
+
+    .notation-formula-math:hover .notation-formula-copy,
+    .notation-formula-math:focus-within .notation-formula-copy,
+    .notation-formula-copy:focus-visible {
+      opacity: 1;
+    }
+
+    .notation-formula-copy:hover,
+    .notation-formula-copy:focus-visible {
+      border-color: var(--sl-color-accent);
+      color: var(--sl-color-text-accent);
+    }
+
+    .notation-formula-copy:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    /* `data-copied` is set briefly by the click handler in
+       `NotationLayer.astro` — same "flash a tooltip, then remove the
+       attribute" pattern as `.keyed-equation__copy[data-copied]`. */
+    .notation-formula-copy[data-copied] {
+      opacity: 1;
+    }
+
+    .notation-formula-copy[data-copied]::after {
+      content: 'Copied!';
+      position: absolute;
+      inset-block-end: calc(100% + 0.4rem);
+      inset-inline-end: 0;
+      padding: 0.15rem 0.45rem;
+      border-radius: 0.35rem;
+      background: var(--sl-color-accent-low);
+      color: var(--sl-color-text-accent);
+      font-size: var(--sl-text-xs);
+      white-space: nowrap;
+      pointer-events: none;
+    }
+
+    /* The non-numbered case (a formula inside a hover popup, the "Notation
+       used on this page" list, a `Diagram`, or a lab's interactive equation)
+       has no controls to flash against, so the box itself flashes instead —
+       the generic `[data-notation-formula][data-copied]::after` rule in
+       `global.css`, not reimplemented here. */
+
+    @media (prefers-reduced-motion: reduce) {
+      .notation-formula-number,
+      .notation-formula-copy {
+        transition: none;
+      }
+    }
+
+    @media (forced-colors: active) {
+      .notation-formula-number,
+      .notation-formula-copy {
+        opacity: 1;
+      }
+    }
+
     .notation-gloss-list {
       display: flex;
       flex-wrap: wrap;

package/src/components/notation/NotationGlossary.astro

@@ -19,6 +19,15 @@ const [notationEntries, lessonEntries, manifest] = await Promise.all([
   getCollection('docs', ({ id }) => isLessonSlug(id)),
   loadManifest(),
 ]);
+// 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).
+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);
 const notationLabelByKey = new Map(
@@ -83,6 +92,18 @@ const renderedEntries = await Promise.all(
     })),
 );
 
+// Every entry with a rigorous `formula` gets its own equation number, `G.<n>`
+// in page order — the glossary's own numbering, distinct from a lesson's
+// chapter-qualified `(2.1)` (`equations-validate.ts`), since a glossary
+// formula has no lesson/part to qualify it against.
+let equationCounter = 0;
+const equationNumberByKey = new Map<string, string>();
+for (const { entry } of renderedEntries) {
+  if (!entry.data.formula) continue;
+  equationCounter += 1;
+  equationNumberByKey.set(entry.data.key, `G.${equationCounter}`);
+}
+
 // Drives the hover explanation for `[[key]]` links inside the definition
 // bodies. Every entry is already shown in full on this page, so the layer
 // renders in panel-only mode: no visible list, just the shared panel.
@@ -138,17 +159,26 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
               <NotationMath class="glossary-symbol" latex={entry.data.latex} />
             </span>
             <div>
-              <h2>{labelOf(entry.data)}</h2>
+              <h2>
+                <a
+                  class="glossary-term-link"
+                  href={`#notation-${entry.data.key}`}
+                >
+                  {labelOf(entry.data)}
+                </a>
+                <a
+                  class="glossary-anchor"
+                  href={`#notation-${entry.data.key}`}
+                  aria-label={`Link to “${labelOf(entry.data)}”`}
+                >
+                  <span class="glossary-anchor-icon" aria-hidden="true">
+                    <svg viewBox="0 0 24 24" fill="currentColor">
+                      <path d={HEADING_LINK_ICON_PATH}></path>
+                    </svg>
+                  </span>
+                </a>
+              </h2>
               <code>{entry.data.key}</code>
-              <a
-                class="glossary-anchor"
-                href={`#notation-${entry.data.key}`}
-                data-glossary-anchor
-                aria-label={`Copy link to “${labelOf(entry.data)}”`}
-                title="Copy link to this entry"
-              >
-                <span aria-hidden="true">#</span>
-              </a>
             </div>
             <span class="glossary-status">{entry.data.editorialStatus}</span>
           </header>
@@ -193,6 +223,8 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
                 scope={formulaScopeByKey.get(entry.data.key) ?? []}
                 glosses={glossesByKey.get(entry.data.key)}
                 entryLabel={labelOf(entry.data)}
+                number={equationNumberByKey.get(entry.data.key)}
+                numberHref={`#notation-${entry.data.key}`}
               />
             </div>
           )}
@@ -264,34 +296,6 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
   definitions={panelDefinitions}
 />
 
-<script>
-  const RESET_MS = 1200;
-
-  for (const anchor of document.querySelectorAll<HTMLAnchorElement>(
-    '[data-glossary-anchor]',
-  )) {
-    anchor.addEventListener('click', () => {
-      const href = anchor.getAttribute('href');
-      if (!href || !navigator.clipboard) return;
-
-      // Keep the native hash navigation (scroll + history) and copy the
-      // absolute URL alongside it.
-      const url = new URL(href, window.location.href).href;
-      navigator.clipboard.writeText(url).then(
-        () => {
-          anchor.dataset.copied = 'true';
-          window.setTimeout(() => {
-            delete anchor.dataset.copied;
-          }, RESET_MS);
-        },
-        () => {
-          /* Clipboard blocked: the plain anchor link still works. */
-        },
-      );
-    });
-  }
-</script>
-
 <style>
   .glossary-index ul {
     display: grid;
@@ -326,6 +330,17 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     font-size: var(--sl-text-xl);
   }
 
+  .glossary-term-link {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  .glossary-term-link:hover,
+  .glossary-term-link:focus-visible {
+    color: var(--sl-color-text-accent);
+    text-decoration: underline;
+  }
+
   .glossary-symbol {
     color: var(--sl-color-accent-high);
     font-size: 1.2rem;
@@ -353,14 +368,22 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     }
   }
 
+  /* Mirrors the hover/focus-reveal treatment of a content heading's own
+     `.sl-anchor-link` (`rehype-heading-anchors.mjs`), reimplemented here
+     rather than reused because that class's CSS assumes a single inline
+     prose heading, not this entry's grid-based header. */
   .glossary-anchor {
-    position: relative;
-    margin-inline-start: 0.5rem;
-    padding-inline: 0.2rem;
+    display: inline-flex;
+    align-items: center;
+    margin-inline-start: 0.4rem;
     color: var(--sl-color-gray-3);
-    font-family: monospace;
-    text-decoration: none;
-    vertical-align: baseline;
+    vertical-align: middle;
+  }
+
+  .glossary-anchor-icon svg {
+    width: 0.85em;
+    height: 0.85em;
+    display: block;
   }
 
   .glossary-anchor:hover,
@@ -368,20 +391,28 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     color: var(--sl-color-text-accent);
   }
 
-  .glossary-anchor[data-copied]::after {
-    content: 'Link copied';
-    position: absolute;
-    inset-block-end: calc(100% + 0.35rem);
-    inset-inline-start: 50%;
-    translate: -50% 0;
-    padding: 0.15rem 0.45rem;
-    border-radius: 0.35rem;
-    background: var(--sl-color-accent-low);
-    color: var(--sl-color-text-accent);
-    font-family: var(--sl-font, sans-serif);
-    font-size: var(--sl-text-xs);
-    white-space: nowrap;
-    pointer-events: none;
+  @media (hover: hover) {
+    .glossary-anchor {
+      opacity: 0;
+    }
+
+    h2:hover .glossary-anchor,
+    h2:focus-within .glossary-anchor,
+    .glossary-anchor:focus-visible {
+      opacity: 1;
+    }
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .glossary-anchor {
+      transition: opacity 120ms ease-out, color 120ms ease-out;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .glossary-anchor {
+      opacity: 1;
+    }
   }
 
   .glossary-status {

package/src/components/notation/NotationLayer.astro

@@ -263,14 +263,6 @@ for (const gloss of glossItems) {
             </header>
             <p data-slot-summary hidden />
             <div data-slot-formula hidden />
-            <button
-              class="notation-popup-copy"
-              type="button"
-              data-popup-copy
-              hidden
-            >
-              Copy LaTeX
-            </button>
             <p class="notation-units" data-slot-units hidden />
             <a data-slot-link hidden>
               Open the full definition
@@ -405,18 +397,7 @@ for (const gloss of glossItems) {
       const units = fragment.querySelector<HTMLElement>('[data-slot-units]');
       const link =
         fragment.querySelector<HTMLAnchorElement>('[data-slot-link]');
-      const copyButton = fragment.querySelector<HTMLButtonElement>(
-        '[data-popup-copy]',
-      );
-      if (
-        !el ||
-        !symbolHost ||
-        !title ||
-        !summary ||
-        !formulaHost ||
-        !units ||
-        !copyButton
-      ) {
+      if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
         return null;
       }
 
@@ -443,34 +424,6 @@ for (const gloss of glossItems) {
       );
       formulaHost.hidden = sourceFormula === null;
 
-      // The formula's own `data-latex` carries the plain, authored LaTeX —
-      // not the `\explain{key}{…}`-wrapped source KaTeX actually rendered —
-      // so what a reader copies is what they'd write themselves, not an
-      // internal marker macro. See `render-notation-math.ts:renderNotationFormula`.
-      const formulaLatex = sourceFormula?.dataset.latex ?? '';
-      copyButton.hidden = formulaLatex.length === 0;
-      if (formulaLatex.length > 0) {
-        copyButton.addEventListener('click', (event) => {
-          // Otherwise this bubbles to the document click handler in
-          // `popup-stack.ts`, which treats any click inside a popup that
-          // isn't a trigger or a link as "close it" — that would remove the
-          // card before the "Copied!" flash below ever paints.
-          event.stopPropagation();
-          if (!navigator.clipboard) return;
-          navigator.clipboard.writeText(formulaLatex).then(
-            () => {
-              copyButton.dataset.copied = 'true';
-              window.setTimeout(() => {
-                delete copyButton.dataset.copied;
-              }, 1200);
-            },
-            () => {
-              /* Clipboard blocked: nothing more we can do here. */
-            },
-          );
-        });
-      }
-
       setOptionalText(
         units,
         entry
@@ -547,6 +500,84 @@ for (const gloss of glossItems) {
     );
     if (details) setupNotationDisclosure(details);
   }
+
+  // "Copy LaTeX" for a notation formula (a glossary entry's own numbered
+  // formula, or one named inline via `\explain{}` inside a popup/`Diagram`),
+  // two ways: its own button (only a numbered formula has one —
+  // `data-notation-formula-copy`, `NotationFormula.astro`), or a click
+  // anywhere else in the box that isn't the number link or an explained
+  // symbol — the same region `.notation-formula-math:hover` highlights
+  // (`NotationFormula.astro`), which includes the reserved gutter between
+  // the equation and its number, not just the rendered `.katex-html`. This
+  // listener lives here, not in `NotationFormula.astro` or
+  // `KeyedFloatEnhancer.astro`, because this component loads on every page —
+  // it's the Starlight `Footer` override — while `KeyedFloatEnhancer` is
+  // lesson-only and a formula can appear inside a hover popup mounted
+  // outside `.sl-markdown-content`.
+  document.addEventListener('click', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (!origin) return;
+
+    const ownButton = origin.closest<HTMLButtonElement>(
+      '[data-notation-formula-copy]',
+    );
+    const container = ownButton
+      ? null
+      : origin.closest<HTMLElement>('[data-notation-formula]');
+    if (!ownButton) {
+      if (origin.closest('[data-notation-key], .notation-formula-number')) {
+        return;
+      }
+      if (!container) return;
+    }
+
+    const feedbackTarget =
+      ownButton ??
+      container?.querySelector<HTMLElement>('[data-notation-formula-copy]') ??
+      container;
+    const latex =
+      ownButton?.dataset.latex ?? feedbackTarget?.dataset.latex ?? '';
+    if (!feedbackTarget || latex.length === 0 || !navigator.clipboard) return;
+
+    navigator.clipboard.writeText(latex).then(
+      () => {
+        feedbackTarget.dataset.copied = 'true';
+        window.setTimeout(() => {
+          delete feedbackTarget.dataset.copied;
+        }, 1200);
+      },
+      () => {
+        /* Clipboard blocked: nothing more we can do here. */
+      },
+    );
+  });
+
+  // A tooltip for the click gesture above, and only for the part of the
+  // equation it actually applies to — an explained symbol has its own hover
+  // card (created above) and needs no tooltip layered on top of it, and the
+  // copy button already carries a static `title`. `mouseover`/`mouseout` (not
+  // `mouseenter`/`mouseleave`) because they bubble, which this document-level
+  // delegation needs.
+  document.addEventListener('mouseover', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (!origin || origin.getAttribute('title') === 'Copy LaTeX') return;
+    if (
+      origin.closest(
+        '[data-notation-key], [data-notation-formula-copy], .notation-formula-number',
+      )
+    ) {
+      return;
+    }
+    if (!origin.closest('[data-notation-formula]')) return;
+    origin.setAttribute('title', 'Copy LaTeX');
+  });
+
+  document.addEventListener('mouseout', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (origin?.getAttribute('title') === 'Copy LaTeX') {
+      origin.removeAttribute('title');
+    }
+  });
 </script>
 
 <style>
@@ -722,6 +753,10 @@ for (const gloss of glossItems) {
       font-size: var(--sl-text-sm);
     }
 
+    /* Cursor, hover highlight, and "Copied!" flash for this plain-span
+       formula fallback (a definition with no `formulaScope`) come from the
+       generic `[data-notation-formula]` rules in `global.css` — shared with
+       every other producer of that attribute, not reimplemented here. */
     .notation-formula {
       overflow-x: auto;
       /* `overflow-x: auto` alone makes the block axis compute to `auto` too
@@ -823,39 +858,6 @@ for (const gloss of glossItems) {
       line-height: 1.5;
     }
 
-    .notation-popup-copy {
-      position: relative;
-      margin-block: 0.4rem 0.6rem;
-      padding: 0.2rem 0.55rem;
-      border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.35rem;
-      color: var(--sl-color-text-accent);
-      background: var(--sl-color-bg);
-      font: inherit;
-      font-size: var(--sl-text-xs);
-      cursor: pointer;
-    }
-
-    .notation-popup-copy:hover {
-      border-color: var(--sl-color-accent);
-      background: var(--sl-color-accent-low);
-    }
-
-    .notation-popup-copy[data-copied]::after {
-      content: 'Copied!';
-      position: absolute;
-      inset-block-end: calc(100% + 0.35rem);
-      inset-inline-start: 50%;
-      translate: -50% 0;
-      padding: 0.15rem 0.45rem;
-      border-radius: 0.35rem;
-      background: var(--sl-color-accent-low);
-      color: var(--sl-color-text-accent);
-      font-size: var(--sl-text-xs);
-      white-space: nowrap;
-      pointer-events: none;
-    }
-
     .notation-panel-body [data-slot-formula] {
       overflow-x: auto;
       /* See `.notation-formula` above: pairs with `overflow-x` to stop the