explico 0.1.0 → 0.2.0

package/src/components/hover-panel.ts

@@ -21,6 +21,8 @@ export interface HoverPanelState {
 export interface HoverPanelConfig {
   /** The `<aside data-hover-panel>` element. */
   panel: HTMLElement;
+  /** Exclusivity group (see the `activeSurface` note below `HoverPanelState`). */
+  groupId: string;
   /**
    * Element used only to locate the enclosing article column for the
    * horizontal clamp. Defaults to the panel itself.
@@ -49,6 +51,36 @@ function closestElement(node: EventTarget | null, selector: string) {
   return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
 }
 
+/**
+ * The notation layer and the citation layer each own their explanations —
+ * the notation layer through its own popup stack (`./popup-stack.ts`), the
+ * citation layer through this module's `createHoverPanel`. Neither knows the
+ * other exists, so a pinned citation and an open notation popup — or the
+ * reverse — can each be individually correct and still land on top of each
+ * other, or on top of the equation the other one is explaining. Rather than
+ * teach every positioning calculation about every other surface that might
+ * exist, the two are mutually exclusive *groups*: opening the first popup in
+ * one group closes whatever the other group had open. Within a group,
+ * surfaces manage their own overlap (the citation panel is a singleton; the
+ * notation stack positions its own popups against each other). A pin is not
+ * exempt — the reader's attention already moved to the other group.
+ */
+let activeSurface: {
+  readonly groupId: string;
+  readonly close: () => void;
+} | null = null;
+
+export function claimActiveSurface(groupId: string, close: () => void): void {
+  if (activeSurface && activeSurface.groupId !== groupId) {
+    activeSurface.close();
+  }
+  activeSurface = { groupId, close };
+}
+
+export function releaseActiveSurface(groupId: string): void {
+  if (activeSurface?.groupId === groupId) activeSurface = null;
+}
+
 export function createHoverPanel(config: HoverPanelConfig) {
   const { panel } = config;
   if (panel.dataset.hoverPanelReady === 'true') return;
@@ -145,6 +177,8 @@ export function createHoverPanel(config: HoverPanelConfig) {
     if (!key) return;
     if (config.render(anchor, key) === false) return;
 
+    claimActiveSurface(config.groupId, forceClose);
+
     activeKey = key;
     activeAnchor = anchor;
     config.onShow?.(key, anchor);
@@ -161,9 +195,23 @@ export function createHoverPanel(config: HoverPanelConfig) {
     activeAnchor = null;
     panel.hidden = true;
     config.onClose?.();
+    releaseActiveSurface(config.groupId);
     sync();
   };
 
+  // A plain `close()` deliberately leaves `pinned` set — a stray pointerout or
+  // focusout elsewhere on the page must not kill a pin the reader placed on
+  // purpose, and `restorePinnedOrClose` below relies on `pinned` surviving a
+  // transient close to bring the panel back. Being displaced by a DIFFERENT
+  // panel taking over (`claimActivePanel`) is not transient, though: without
+  // clearing the pin here, the very next stray blur anywhere on the page finds
+  // `pinned` still truthy and restores this panel — undoing the takeover a
+  // frame later and fighting the other panel for the screen.
+  const forceClose = () => {
+    pinned = null;
+    close();
+  };
+
   const restorePinnedOrClose = () => {
     window.requestAnimationFrame(() => {
       const focused = config.triggerFrom(document.activeElement);
@@ -235,11 +283,29 @@ export function createHoverPanel(config: HoverPanelConfig) {
     }
 
     const trigger = config.triggerFrom(event.target);
-    if (!trigger || trigger.closest('a')) return;
-    const key = config.keyFor(trigger);
-    if (!key) return;
-    event.preventDefault();
-    togglePin(key, trigger);
+    if (trigger && !trigger.closest('a')) {
+      const key = config.keyFor(trigger);
+      if (key) {
+        event.preventDefault();
+        togglePin(key, trigger);
+        return;
+      }
+    }
+    if (trigger) return; // a real link trigger: let it navigate.
+
+    // Anywhere else inside the panel collapses it, same as the corner "×" —
+    // its own body is never a trigger, so a click there can only mean "I'm
+    // done with this." A real link (e.g. "Open source link") is excluded so
+    // it still navigates instead of being swallowed.
+    if (
+      !panel.hidden &&
+      event.target instanceof Node &&
+      panel.contains(event.target) &&
+      !closestElement(event.target, 'a')
+    ) {
+      pinned = null;
+      close();
+    }
   });
 
   document.addEventListener('pointerdown', (event) => {

package/src/components/notation/NotationFormula.astro

@@ -0,0 +1,154 @@
+---
+/**
+ * A notation entry's rigorous `formula`, rendered with every glyph bound to a
+ * key so the reader can point at any symbol in it and get an explanation
+ * (D15).
+ *
+ * The formula resolves against the **entry-scoped** table from
+ * `reference/gloss.ts` — the entry, its `glosses:`, and any card the formula
+ * names with `\explain{key}{latex}` — not the registry-wide table a card's
+ * body math uses.
+ *
+ * The gloss list under the formula is not decoration: a gloss has no card of
+ * its own, so this list is where its name lives with JavaScript off. The hover
+ * panel is enhancement layered over content that already reads.
+ */
+import NotationMath from './NotationMath.astro';
+import SafeMathNode from './SafeMathNode.astro';
+import { renderNotationFormula } from './render-notation-math';
+import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
+
+export interface Props {
+  formula: string;
+  scope: readonly GlyphScopeEntry[];
+  glosses?: readonly ResolvedGloss[];
+  /** Heading for the gloss list; omitted renders the list unlabelled. */
+  glossLabel?: string;
+  /** The owning entry's display label, used to name the scrollable region. */
+  entryLabel?: string;
+}
+
+const {
+  formula,
+  scope,
+  glosses = [],
+  glossLabel = 'Symbols',
+  entryLabel,
+} = Astro.props;
+const { nodes } = renderNotationFormula(formula, scope);
+---
+
+<div class="notation-formula-block">
+  <div
+    class="notation-formula-math"
+    data-notation-formula
+    role="group"
+    aria-label={entryLabel ? `${entryLabel} formula` : 'Formula'}
+    tabindex="0"
+  >
+    <span class="notation-math">
+      {nodes.map((node) => <SafeMathNode node={node} />)}
+    </span>
+  </div>
+
+  {
+    glosses.length > 0 && (
+      <dl class="notation-gloss-list" data-notation-gloss-list>
+        {glossLabel && <dt class="notation-gloss-label">{glossLabel}</dt>}
+        {glosses.map((gloss) => (
+          <dd class="notation-gloss" data-notation-gloss={gloss.key}>
+            <span
+              class="notation-gloss-symbol"
+              data-notation-symbol-trigger
+              data-notation-key={gloss.key}
+            >
+              <NotationMath class="notation-symbol" latex={gloss.notation} />
+            </span>
+            <span class="notation-gloss-name">{gloss.label}</span>
+            {gloss.units && (
+              <span class="notation-gloss-units">({gloss.units})</span>
+            )}
+          </dd>
+        ))}
+      </dl>
+    )
+  }
+</div>
+
+<style>
+  @layer starlight.components {
+    .notation-formula-block {
+      display: grid;
+      gap: 0.5rem;
+    }
+
+    /* 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 {
+      overflow-x: auto;
+      padding-block: 0.15rem;
+      color: var(--sl-color-text);
+    }
+
+    .notation-formula-math:focus-visible {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    .notation-gloss-list {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: baseline;
+      gap: 0.25rem 1rem;
+      margin: 0;
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-sm);
+    }
+
+    .notation-gloss-label {
+      margin: 0;
+      color: var(--sl-color-gray-3);
+      font-weight: 600;
+    }
+
+    .notation-gloss {
+      display: flex;
+      align-items: baseline;
+      gap: 0.35rem;
+      margin: 0;
+    }
+
+    .notation-gloss-symbol {
+      border-radius: 0.16em;
+      color: var(--sl-color-accent-high);
+      cursor: help;
+    }
+
+    .notation-gloss-symbol:hover,
+    .notation-gloss-symbol:global(.is-notation-active) {
+      background: var(--sl-color-accent-low);
+      box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
+    }
+
+    .notation-gloss-name::before {
+      content: '— ';
+      color: var(--sl-color-gray-3);
+    }
+
+    .notation-gloss-units {
+      color: var(--sl-color-gray-3);
+    }
+
+    @media (forced-colors: active) {
+      .notation-gloss-symbol:hover,
+      .notation-gloss-symbol:global(.is-notation-active) {
+        outline: 2px solid Highlight;
+        color: HighlightText;
+        background: Highlight;
+        box-shadow: none;
+      }
+    }
+  }
+</style>

package/src/components/notation/NotationGlossary.astro

@@ -1,10 +1,13 @@
 ---
 import { getCollection, render } from 'astro:content';
 import NotationMath from './NotationMath.astro';
+import NotationFormula from './NotationFormula.astro';
 import NotationLayer, {
   type NotationLayerDefinition,
 } from './NotationLayer.astro';
 import { resolveLabel } from '../../reference/label';
+import { formulaGlyphScope, resolveGlosses } from '../../reference/gloss';
+import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
 import {
   isLessonSlug,
   lessonIdFromSlug,
@@ -38,6 +41,35 @@ for (const backlink of manifest.notation.backlinks) {
   lessonsByNotationKey.set(backlink.key, current);
 }
 
+// The two-tier vocabulary (D15). Every card is a node here; its glosses are
+// not — they are symbol-and-name entries owned by the card whose `formula`
+// needs them, kept out of the registry so a definitional letter never becomes
+// a curriculum edge.
+const cardsByKey = new Map<string, GlyphScopeEntry>(
+  notationEntries.map((entry) => [
+    entry.data.key,
+    { key: entry.data.key, notation: entry.data.latex },
+  ]),
+);
+const glossesByKey = new Map<string, ResolvedGloss[]>(
+  notationEntries.map((entry) => [
+    entry.data.key,
+    resolveGlosses(entry.data.key, entry.data.glosses),
+  ]),
+);
+const formulaScopeByKey = new Map<string, GlyphScopeEntry[]>(
+  notationEntries.map((entry) => [
+    entry.data.key,
+    formulaGlyphScope({
+      key: entry.data.key,
+      notation: entry.data.latex,
+      formula: entry.data.formula,
+      glosses: glossesByKey.get(entry.data.key) ?? [],
+      cardsByKey,
+    }),
+  ]),
+);
+
 const renderedEntries = await Promise.all(
   notationEntries
     .sort(
@@ -60,6 +92,9 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     notation: entry.data.latex,
     label: labelOf(entry.data),
     summary: entry.data.meaning,
+    formula: entry.data.formula,
+    formulaScope: formulaScopeByKey.get(entry.data.key),
+    glosses: glossesByKey.get(entry.data.key),
     units: entry.data.units,
     seeAlso: entry.data.seeAlso,
     editorialStatus: entry.data.editorialStatus,
@@ -149,6 +184,19 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
             )}
           </dl>
 
+          <p class="glossary-meaning">{entry.data.meaning}</p>
+
+          {entry.data.formula && (
+            <div class="glossary-formula">
+              <NotationFormula
+                formula={entry.data.formula}
+                scope={formulaScopeByKey.get(entry.data.key) ?? []}
+                glosses={glossesByKey.get(entry.data.key)}
+                entryLabel={labelOf(entry.data)}
+              />
+            </div>
+          )}
+
           <div class="glossary-definition">
             <Content />
           </div>
@@ -364,6 +412,18 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     margin: 0;
   }
 
+  .glossary-meaning {
+    margin-block: 0 1rem;
+  }
+
+  .glossary-formula {
+    margin-block: 1rem;
+    padding: 0.85rem 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    background: var(--sl-color-bg);
+  }
+
   .see-also {
     display: flex;
     flex-wrap: wrap;