explico 0.5.0 → 0.7.0

package/src/components/diagram/Diagram.astro

@@ -70,12 +70,6 @@ export interface Props {
    * Set `false` only when horizontal overflow is deliberate. Default: `800`.
    */
   warnAboveWidth?: number | false;
-  /**
-   * Prose text alternative for the SVG. When omitted, the fallback is
-   * generated from the node labels and the edge chain — readable, but a
-   * hand-written sentence usually reads better for a screen-reader user.
-   */
-  description?: string;
 }
 
 const {
@@ -85,7 +79,6 @@ const {
   edges,
   scope = [],
   direction = 'TB',
-  description,
   number,
   anchorId,
   defaultOpen = true,
@@ -190,12 +183,6 @@ if (warnAboveWidth !== false && layout.width > warnAboveWidth) {
   );
 }
 
-/** A node's human label for the text fallback — never the internal id. */
-function fallbackLabel(nodeId: string): string {
-  const node = nodeById.get(nodeId);
-  return node?.text ?? node?.formula ?? nodeId;
-}
-
 function pathFrom(points: readonly { x: number; y: number }[]): string {
   if (points.length === 0) return '';
   const [first, ...rest] = points;
@@ -318,33 +305,6 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
             </div>
           </div>
         </div>
-
-        <details class="diagram-fallback">
-          <summary>Diagram description</summary>
-          {
-            description ? (
-              <p>{description}</p>
-            ) : (
-              <Fragment>
-                <ol>
-                  {rendered.map((node) => (
-                    <li>{fallbackLabel(node.id)}</li>
-                  ))}
-                </ol>
-                {edges.length > 0 && (
-                  <p class="diagram-fallback-flow">
-                    {edges.map((edge, index) => (
-                      <Fragment>
-                        {index > 0 && '; '}
-                        {fallbackLabel(edge.from)} → {fallbackLabel(edge.to)}
-                      </Fragment>
-                    ))}
-                  </p>
-                )}
-              </Fragment>
-            )
-          }
-        </details>
       </div>
     </details>
 
@@ -635,21 +595,6 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       fill: var(--sl-color-gray-4);
     }
 
-    .diagram-fallback {
-      margin-block-start: 0.5rem;
-      color: var(--sl-color-gray-3);
-      font-size: var(--sl-text-sm);
-    }
-
-    .diagram-fallback ol,
-    .diagram-fallback p {
-      margin: 0.35rem 0 0;
-    }
-
-    .diagram-fallback ol {
-      padding-inline-start: 1.25rem;
-    }
-
     @media print {
       .diagram-toolbar,
       .diagram__title-anchor,

package/src/components/memo/Memo.astro

@@ -239,8 +239,8 @@ if (!number || !anchorId) {
 <script>
   import { attachHoverPeek, closeHoverPeek } from '../disclosure/hover-preview';
   import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
+  import { animatedScrollIntoView } from '../scroll-animation';
 
-  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
   let memoPreviewSerial = 0;
 
   function cloneMemoBody(body: HTMLElement): HTMLElement {
@@ -442,10 +442,7 @@ if (!number || !anchorId) {
             history.pushState(null, '', `#${details.id}`);
           }
           requestAnimationFrame(() => {
-            details.scrollIntoView({
-              behavior: reduceMotion.matches ? 'auto' : 'smooth',
-              block: 'start',
-            });
+            animatedScrollIntoView(details, { block: 'start' });
           });
         });
       }

package/src/components/memo/ShortNote.astro

@@ -116,7 +116,7 @@ if (!anchorId) {
 </style>
 
 <script>
-  const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+  import { animatedScrollIntoView } from '../scroll-animation';
 
   document
     .querySelectorAll<HTMLElement>('.short-note:not([data-short-note-wired])')
@@ -185,10 +185,7 @@ if (!anchorId) {
           history.pushState(null, '', `#${note.id}`);
         }
         requestAnimationFrame(() => {
-          note.scrollIntoView({
-            behavior: reduceMotion.matches ? 'auto' : 'smooth',
-            block: 'nearest',
-          });
+          animatedScrollIntoView(note, { block: 'nearest' });
         });
       };
 

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 {