explico 0.1.1 → 0.2.0

package/src/components/notation/NotationLayer.astro

@@ -11,8 +11,16 @@ export interface NotationLayerDefinition {
   key: string;
   notation: string;
   label: string;
-  summary: string;
+  /** A card's `meaning`. Absent on a gloss, which is a symbol and a name. */
+  summary?: string;
   formula?: string;
+  /**
+   * Entry-scoped glyph table for `formula` (D15). Without it the formula
+   * renders inert, as it did before the two-tier vocabulary.
+   */
+  formulaScope?: readonly GlyphScopeEntry[];
+  /** Symbols the formula names that have no card of their own. */
+  glosses?: readonly ResolvedGloss[];
   units?: string;
   seeAlso?: readonly string[];
   alignment?: NotationAlignment;
@@ -37,7 +45,8 @@ export interface Props {
 }
 
 import NotationMath from './NotationMath.astro';
-import HoverPanel from '../HoverPanel.astro';
+import NotationFormula from './NotationFormula.astro';
+import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
 
 const {
   definitions,
@@ -78,7 +87,21 @@ const items = definitions.map((definition) => {
   return { ...definition, scope, href };
 });
 
-const panelId = `${id}-panel`;
+// Glosses (D15) have no card and no anchor, so they need a data source for the
+// panel. Their names are already visible under the formula they belong to
+// (`NotationFormula` renders that list, and it is the no-JS baseline), so these
+// blocks are hidden and exist only for the enhancement to read.
+const glossItems = items.flatMap((definition) => definition.glosses ?? []);
+
+for (const gloss of glossItems) {
+  if (!keyPattern.test(gloss.key)) {
+    throw new Error(`Unsafe notation gloss key: ${gloss.key}`);
+  }
+  if (seen.has(gloss.key)) {
+    throw new Error(`Duplicate notation key in NotationLayer: ${gloss.key}`);
+  }
+  seen.add(gloss.key);
+}
 ---
 
 {
@@ -134,12 +157,22 @@ const panelId = `${id}-panel`;
                   )}
               </dt>
               <dd>
-                <p data-notation-summary>{definition.summary}</p>
-                {definition.formula && (
-                  <span class="notation-formula" data-notation-formula>
-                    <NotationMath latex={definition.formula} />
-                  </span>
+                {definition.summary && (
+                  <p data-notation-summary>{definition.summary}</p>
                 )}
+                {definition.formula &&
+                  (definition.formulaScope ? (
+                    <NotationFormula
+                      formula={definition.formula}
+                      scope={definition.formulaScope}
+                      glosses={definition.glosses}
+                      entryLabel={definition.label}
+                    />
+                  ) : (
+                    <span class="notation-formula" data-notation-formula>
+                      <NotationMath latex={definition.formula} />
+                    </span>
+                  ))}
                 {definition.units && (
                   <p class="notation-units" data-notation-units>
                     <strong>Units:</strong> {definition.units}
@@ -149,7 +182,6 @@ const panelId = `${id}-panel`;
                   class="notation-pin"
                   type="button"
                   data-notation-control={definition.key}
-                  aria-controls={panelId}
                   aria-expanded="false"
                   aria-pressed="false"
                   hidden
@@ -160,34 +192,71 @@ const panelId = `${id}-panel`;
             </div>
           ))}
         </dl>
+
+        {glossItems.map((gloss) => (
+          <div
+            class="notation-gloss-source"
+            data-notation-entry={gloss.key}
+            hidden
+          >
+            <span class="notation-symbol-trigger" data-notation-key={gloss.key}>
+              <NotationMath class="notation-symbol" latex={gloss.notation} />
+            </span>
+            <span data-notation-link={gloss.key}>{gloss.label}</span>
+            {gloss.units && (
+              <span data-notation-units>
+                <strong>Units:</strong> {gloss.units}
+              </span>
+            )}
+          </div>
+        ))}
       </details>
 
       {!panelOnly && (
         <p class="notation-enhancement-help" data-notation-help hidden>
           Point to a marked symbol for a quick explanation, or use the list
-          above. Select “Pin explanation” to keep one open; press Escape to
-          close it.
+          above — pointing at a symbol inside an open card explains that one
+          too, alongside it. Click a symbol, or select “Pin explanation”, to
+          keep a card open; click the card (or its “×”) to close it, or press
+          Escape.
         </p>
       )}
 
-      <HoverPanel id={panelId} label="Notation explanation" data-notation-panel>
-        <div class="notation-panel-body">
-          <header class="notation-panel-heading">
-            <span class="notation-panel-symbol" data-panel-symbol />
-            <h3 data-panel-title />
-          </header>
-          <p data-panel-summary />
-          <div data-panel-formula hidden />
-          <p data-panel-units hidden />
-          <a data-panel-link>Open the full definition</a>
-        </div>
-      </HoverPanel>
+      <template data-notation-popup-template>
+        <aside
+          class="notation-popup"
+          role="region"
+          aria-atomic="true"
+          tabindex="-1"
+        >
+          <button
+            class="notation-popup-close"
+            type="button"
+            data-popup-close
+            aria-label="Close"
+          >
+            <span aria-hidden="true">&times;</span>
+          </button>
+          <div class="notation-panel-body">
+            <header class="notation-panel-heading">
+              <span class="notation-panel-symbol" data-slot-symbol />
+              <h3 data-slot-title />
+            </header>
+            <p data-slot-summary hidden />
+            <div data-slot-formula hidden />
+            <p class="notation-units" data-slot-units hidden />
+            <a data-slot-link hidden>
+              Open the full definition
+            </a>
+          </div>
+        </aside>
+      </template>
     </section>
   )
 }
 
 <script>
-  import { createHoverPanel, closestElement } from '../hover-panel';
+  import { createPopupStack, closestElement } from '../popup-stack';
 
   const triggerSelector = '[data-notation-key]';
 
@@ -209,34 +278,24 @@ const panelId = `${id}-panel`;
     entries.delete('');
     if (entries.size === 0) return;
 
-    const panel = root.querySelector<HTMLElement>('[data-notation-panel]');
-    const panelSymbol = root.querySelector<HTMLElement>('[data-panel-symbol]');
-    const panelTitle = root.querySelector<HTMLElement>('[data-panel-title]');
-    const panelSummary = root.querySelector<HTMLElement>(
-      '[data-panel-summary]',
+    const template = root.querySelector<HTMLTemplateElement>(
+      '[data-notation-popup-template]',
     );
-    const panelFormula = root.querySelector<HTMLElement>(
-      '[data-panel-formula]',
-    );
-    const panelUnits = root.querySelector<HTMLElement>('[data-panel-units]');
-    const panelLink =
-      root.querySelector<HTMLAnchorElement>('[data-panel-link]');
-    if (
-      !panel ||
-      !panelSymbol ||
-      !panelTitle ||
-      !panelSummary ||
-      !panelFormula ||
-      !panelUnits ||
-      !panelLink
-    ) {
-      return;
-    }
+    if (!template) return;
 
     const controls = Array.from(
       root.querySelectorAll<HTMLButtonElement>('[data-notation-control]'),
     );
-    const triggers = Array.from(
+
+    // Static triggers, computed once: markers embedded in prose or an
+    // equation, and the symbol glyphs in the "Notation used on this page"
+    // list. These get the always-on `.notation-trigger` cursor/hover
+    // treatment. Symbols that appear *inside a popup* (a card's own formula,
+    // D15) are not in this list — there's no bound on how many of those can
+    // exist — but they still work as triggers: `triggerFrom` below finds
+    // them live, and the shared `[data-notation-key]:hover` rule (declared
+    // `:global`, further down) already paints them the same way.
+    const externalTriggers = Array.from(
       document.querySelectorAll<HTMLElement>(triggerSelector),
     ).filter(
       (element) =>
@@ -244,17 +303,10 @@ const panelId = `${id}-panel`;
         !element.closest('.katex-mathml') &&
         entries.has(element.dataset.notationKey ?? ''),
     );
-    const triggerSet = new Set(triggers);
-
-    // Symbol glyphs rendered inside the page-notation list. They live within
-    // `root`, so the external-marker filter above deliberately excludes them;
-    // wire them as their own trigger set so pointing at a listed symbol opens
-    // the same explanation as pointing at one embedded in prose or an equation.
     const symbolTriggers = Array.from(
       root.querySelectorAll<HTMLElement>('[data-notation-symbol-trigger]'),
     ).filter((element) => entries.has(element.dataset.notationKey ?? ''));
-    const symbolTriggerSet = new Set(symbolTriggers);
-    const highlightTargets = [...triggers, ...symbolTriggers];
+    const highlightTargets = [...externalTriggers, ...symbolTriggers];
 
     for (const trigger of highlightTargets) {
       trigger.classList.add('notation-trigger');
@@ -269,16 +321,6 @@ const panelId = `${id}-panel`;
       element?.dataset.notationLink ??
       null;
 
-    const externalTriggerFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(node, triggerSelector);
-      return candidate && triggerSet.has(candidate) ? candidate : null;
-    };
-
-    const symbolTriggerFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(node, '[data-notation-symbol-trigger]');
-      return candidate && symbolTriggerSet.has(candidate) ? candidate : null;
-    };
-
     const controlFrom = (node: EventTarget | null) => {
       const candidate = closestElement(node, '[data-notation-control]');
       return candidate && root.contains(candidate) ? candidate : null;
@@ -289,81 +331,125 @@ const panelId = `${id}-panel`;
       return candidate && root.contains(candidate) ? candidate : null;
     };
 
+    // A symbol trigger, wherever it lives: prose, the equation, the visible
+    // list, or — the D15 case this exists for — inside an already-open
+    // popup's own formula. Unlike the static sets above, this has to be
+    // live: a popup's content doesn't exist until the reader opens it.
+    const symbolFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(node, triggerSelector);
+      if (!candidate || candidate.closest('.katex-mathml')) return null;
+      return entries.has(candidate.dataset.notationKey ?? '')
+        ? candidate
+        : null;
+    };
+
     const triggerFrom = (node: EventTarget | null) =>
-      controlFrom(node) ??
-      staticLinkFrom(node) ??
-      externalTriggerFrom(node) ??
-      symbolTriggerFrom(node);
+      controlFrom(node) ?? staticLinkFrom(node) ?? symbolFrom(node);
+
+    const labelOf = (entry: HTMLElement, key: string) =>
+      entry
+        .querySelector<HTMLElement>('[data-notation-link]')
+        ?.textContent?.trim() ?? key;
 
-    const render = (_anchor: HTMLElement, key: string) => {
+    const createPopup = (key: string, _trigger: HTMLElement) => {
       const entry = entries.get(key);
-      if (!entry) return false;
+      if (!entry) return null;
+
+      const fragment = template.content.cloneNode(true) as DocumentFragment;
+      const el = fragment.querySelector<HTMLElement>('.notation-popup');
+      const symbolHost =
+        fragment.querySelector<HTMLElement>('[data-slot-symbol]');
+      const title = fragment.querySelector<HTMLElement>('[data-slot-title]');
+      const summary = fragment.querySelector<HTMLElement>(
+        '[data-slot-summary]',
+      );
+      const formulaHost = fragment.querySelector<HTMLElement>(
+        '[data-slot-formula]',
+      );
+      const units = fragment.querySelector<HTMLElement>('[data-slot-units]');
+      const link =
+        fragment.querySelector<HTMLAnchorElement>('[data-slot-link]');
+      if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
+        return null;
+      }
+
+      el.setAttribute('aria-label', `Notation: ${labelOf(entry, key)}`);
 
       const sourceSymbol = entry.querySelector<HTMLElement>('.notation-symbol');
-      panelSymbol.replaceChildren(
+      symbolHost.replaceChildren(
         ...(sourceSymbol
           ? [sourceSymbol.cloneNode(true)]
           : [document.createTextNode(entry.dataset.notationEntry ?? key)]),
       );
-      panelTitle.textContent =
-        entry
-          .querySelector<HTMLAnchorElement>('[data-notation-link]')
-          ?.textContent?.trim() ?? key;
-      panelSummary.textContent =
+      title.textContent = labelOf(entry, key);
+      setOptionalText(
+        summary,
         entry
           .querySelector<HTMLElement>('[data-notation-summary]')
-          ?.textContent?.trim() ?? '';
+          ?.textContent?.trim() ?? '',
+      );
       const sourceFormula = entry.querySelector<HTMLElement>(
         '[data-notation-formula]',
       );
-      panelFormula.replaceChildren(
+      formulaHost.replaceChildren(
         ...(sourceFormula ? [sourceFormula.cloneNode(true)] : []),
       );
-      panelFormula.hidden = sourceFormula === null;
+      formulaHost.hidden = sourceFormula === null;
       setOptionalText(
-        panelUnits,
+        units,
         entry
           .querySelector<HTMLElement>('[data-notation-units]')
           ?.textContent?.trim() ?? '',
       );
-      panelLink.href = entry.dataset.notationHref ?? `#notation-${key}`;
-      return true;
+
+      // A gloss has no card to open. Its own popup is the whole of it.
+      const href = entry.dataset.notationHref;
+      if (link) {
+        link.hidden = href === undefined;
+        if (href !== undefined) link.href = href;
+      }
+
+      return el;
     };
 
-    const updateControls = (pinnedKey: string | null, visible: boolean) => {
+    const updateControls = (
+      open: ReadonlySet<string>,
+      pinned: ReadonlySet<string>,
+    ) => {
       for (const control of controls) {
-        const selected = control.dataset.notationControl === pinnedKey;
+        const key = control.dataset.notationControl ?? '';
+        const selected = pinned.has(key);
         control.setAttribute('aria-pressed', String(selected));
-        control.setAttribute('aria-expanded', String(selected && visible));
+        control.setAttribute('aria-expanded', String(open.has(key)));
         control.textContent = selected
           ? 'Unpin explanation'
           : 'Pin explanation';
       }
     };
 
-    createHoverPanel({
-      panel,
-      root,
+    createPopupStack({
+      // Popups are `position: fixed` and float above everything regardless
+      // of DOM placement — *except* z-index only ever wins within its own
+      // stacking context. Nesting them under the article risked landing
+      // inside a stacking context an ancestor happens to establish (found
+      // live: the Starlight right sidebar then ate their clicks even though
+      // its own z-index is far lower). Mounting on `<body>` sidesteps that
+      // entirely.
+      container: document.body,
+      groupId: 'notation',
       triggerFrom,
       keyFor,
-      render,
+      createPopup,
       pinControlFrom: controlFrom,
-      onShow: (key) => {
+      onChange: (open, pinned) => {
         for (const trigger of highlightTargets) {
           trigger.classList.toggle(
             'is-notation-active',
-            trigger.dataset.notationKey === key,
+            open.has(trigger.dataset.notationKey ?? ''),
           );
         }
-        panel.dataset.activeNotationKey = key;
-      },
-      onClose: () => {
-        delete panel.dataset.activeNotationKey;
-        for (const trigger of highlightTargets) {
-          trigger.classList.remove('is-notation-active');
-        }
+        updateControls(open, pinned);
       },
-      onSync: ({ pinnedKey, visible }) => updateControls(pinnedKey, visible),
     });
   }
 
@@ -514,8 +600,67 @@ const panelId = `${id}-panel`;
       font-size: var(--sl-text-xs);
     }
 
-    /* The fixed-position shell is `HoverPanel`; these rules style only the
-       notation-owned fields slotted into it. */
+    /* Each open explanation is its own floating card — see `popup-stack.ts`.
+       They're mounted on `<body>`, not here (a stacking-context trap found
+       live: an ancestor of this section could otherwise cap how high a
+       popup's own z-index reaches). `.notation-panel-body` and its
+       descendants below style the fields common to both this static list
+       and a popup's cloned content. */
+    .notation-popup {
+      position: fixed;
+      z-index: 100;
+      margin: 0;
+      width: min(23rem, calc(100vw - 1.5rem));
+      overflow: auto;
+      padding: 1rem;
+      padding-inline-end: 2.4rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-top: 0.25rem solid var(--sl-color-accent);
+      border-radius: 0.65rem;
+      color: var(--sl-color-text);
+      background: var(--sl-color-bg);
+      box-shadow: var(--sl-shadow-lg);
+      font-size: var(--sl-text-sm);
+    }
+
+    .notation-popup-close {
+      position: absolute;
+      top: 0.5rem;
+      right: 0.5rem;
+      width: 1.6rem;
+      height: 1.6rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0;
+      border: 0;
+      border-radius: 0.35rem;
+      color: var(--sl-color-gray-3);
+      background: transparent;
+      font-size: 1.15rem;
+      line-height: 1;
+      cursor: pointer;
+    }
+
+    .notation-popup-close:hover {
+      color: var(--sl-color-text);
+      background: var(--sl-color-gray-6);
+    }
+
+    /* Symbols inside a card's formula are click/hover-through triggers for
+       another card — the D15 case this whole file exists for. */
+    .notation-panel-body [data-slot-formula] :global([data-notation-key]) {
+      border-radius: 0.16em;
+      cursor: pointer;
+    }
+
+    .notation-panel-body
+      [data-slot-formula]
+      :global([data-notation-key]:hover) {
+      background: var(--sl-color-accent-low);
+      box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
+    }
+
     .notation-panel-heading {
       display: flex;
       align-items: baseline;
@@ -538,7 +683,7 @@ const panelId = `${id}-panel`;
       line-height: 1.5;
     }
 
-    .notation-panel-body [data-panel-formula] {
+    .notation-panel-body [data-slot-formula] {
       overflow-x: auto;
       margin-block: 0.65rem;
       color: var(--sl-color-text);

package/src/components/notation/render-notation-math.ts

@@ -1,5 +1,8 @@
 import rehypeKatex from 'rehype-katex';
 import { createNotationKatexOptions } from '../../reference/katex-options.mjs';
+import { NOTATION_KEY_PATTERN } from '../../reference/remark-notation.mjs';
+import { resolveMathGlyphs } from '../../reference/math-glyphs.mjs';
+import type { GlyphScopeEntry } from '../../reference/gloss';
 
 interface HastText {
   type: 'text';
@@ -122,6 +125,20 @@ function safeProperties(
       continue;
     }
 
+    // The one marker attribute this renderer emits, and the only one KaTeX's
+    // trust callback lets through: `\explain{key}{latex}` expands to
+    // `\htmlData{notation-key=key}{latex}` so a resolved `formula` carries
+    // live, hoverable glyphs. Re-validate the key here rather than trusting
+    // the upstream check — this is the boundary that decides what reaches the
+    // page, and it must stay exactly as narrow as `trustNotationMarker`.
+    if (name === 'dataNotationKey') {
+      if (typeof value !== 'string' || !NOTATION_KEY_PATTERN.test(value)) {
+        throw new Error('Unsafe KaTeX notation key.');
+      }
+      properties['data-notation-key'] = value;
+      continue;
+    }
+
     if (name === 'encoding' && value === 'application/x-tex') {
       properties.encoding = value;
       continue;
@@ -221,3 +238,41 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
   transform(root as unknown as Parameters<typeof transform>[0], file);
   return Object.freeze(root.children.map(sanitizeNode));
 }
+
+/**
+ * Render a notation entry's `formula` with its glyphs bound to keys, so every
+ * symbol in a rigorous definition is itself explainable (D15).
+ *
+ * `scope` is the entry-scoped table from `reference/gloss.ts` — the entry, its
+ * glosses, and the cards its formula names — not the registry-wide table a
+ * card's body math uses. Resolution is best-effort by design: an unresolved
+ * glyph renders inert rather than breaking the page, and is reported instead
+ * by the `formula` completeness gate (Tier 3) and by the CI test that holds
+ * the corpus at zero. A scope error degrades all the way to today's behaviour,
+ * an inert but correct equation.
+ */
+export function renderNotationFormula(
+  formula: string,
+  scope: readonly GlyphScopeEntry[],
+): {
+  readonly nodes: readonly SafeMathNode[];
+  readonly unresolved: readonly string[];
+} {
+  let bound = formula;
+  let unresolved: string[] = [];
+  try {
+    const result = resolveMathGlyphs(formula, [...scope]);
+    bound = result.latex;
+    unresolved = result.unresolved.map(({ token }: { token: string }) => token);
+  } catch {
+    bound = formula;
+  }
+
+  try {
+    return { nodes: renderNotationMath(bound), unresolved };
+  } catch {
+    // A marker that KaTeX or the sanitizer rejects must not cost the reader
+    // the equation itself.
+    return { nodes: renderNotationMath(formula), unresolved };
+  }
+}