explico 0.8.0 → 0.11.1

package/src/components/notation/NotationLayer.astro

@@ -42,16 +42,25 @@ export interface Props {
    * links to reveal an explanation on hover.
    */
   presentation?: 'full' | 'panel';
-  /** Author-chosen state for a reader with nothing saved yet. Default: `false` (closed) — see `docs/authoring` on `CourseConfig.disclosureDefaults`. */
+  /** Author-chosen state for a reader with nothing saved yet. Default: `false` (closed) — from the course's `disclosure.notation` (`CourseConfig.disclosure`). */
   defaultOpen?: boolean;
   /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
   rememberState?: boolean;
+  /**
+   * Decorations this page says are not operators (`notation.suspend`, rule
+   * N22), shown at the top of the list so a reader who knows `'` as the
+   * derivative is told it means something else here.
+   */
+  suspended?: readonly NotationSuspension[];
 }
 
+import HoverPanel from '../HoverPanel.astro';
 import NotationMath from './NotationMath.astro';
 import NotationFormula from './NotationFormula.astro';
 import { stripNotationMarkers } from './render-notation-math';
+import { operatorDisplayLatex } from '../../reference/math-glyphs.mjs';
 import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
+import type { NotationSuspension } from '../../reference/types';
 
 const {
   definitions,
@@ -61,6 +70,7 @@ const {
   presentation = 'full',
   defaultOpen = false,
   rememberState = true,
+  suspended = [],
 } = Astro.props;
 
 const panelOnly = presentation === 'panel';
@@ -121,7 +131,7 @@ for (const gloss of glossItems) {
     >
       <div class="notation-list-titlebar">
       <details
-        class="notation-list"
+        class="notation-list ex-tier-meta"
         id={id}
         hidden={panelOnly}
         data-remember-state={String(rememberState)}
@@ -130,6 +140,28 @@ for (const gloss of glossItems) {
         <summary>
           {label} <span class="notation-count">({items.length})</span>
         </summary>
+        {/* How the cards work, inside the panel: shown once the panel is
+            opened, not as three lines under every closed one. */}
+        {!panelOnly && (
+          <p class="notation-enhancement-help" data-notation-help hidden>
+            Point to a marked symbol or term, here or in the text, for a quick
+            explanation; a symbol inside an open card explains itself in a
+            card of its own. Click a symbol or term to keep its card open, and
+            click it again, use the card’s “×” or press Escape to close the
+            card.
+          </p>
+        )}
+        {!panelOnly && suspended.length > 0 && (
+          <ul class="notation-suspended" data-notation-suspended>
+            {suspended.map((item) => (
+              <li>
+                On this page,{' '}
+                <NotationMath latex={operatorDisplayLatex(item.operator)} /> is
+                not an operator.{item.reason ? ` ${item.reason}` : ''}
+              </li>
+            ))}
+          </ul>
+        )}
         <dl>
           {items.map((definition) => (
             <div
@@ -232,54 +264,44 @@ for (const gloss of glossItems) {
       )}
       </div>
 
-      {!panelOnly && (
-        <p class="notation-enhancement-help" data-notation-help hidden>
-          Point to a marked symbol for a quick explanation, or use the list
-          above — pointing at a symbol inside an open card explains that one
-          too, alongside it. Click a symbol to keep its card open; click the
-          card (or its “×”) to close it, or press Escape.
-        </p>
-      )}
-
-      <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"
+      <HoverPanel
+        id={`${id}-card`}
+        label="Notation"
+        class="notation-popup"
+        data-notation-popup
+      >
+        <div class="notation-panel-heading" slot="heading">
+          <span class="notation-panel-symbol" data-slot-symbol></span>
+          <h3 data-slot-title></h3>
+        </div>
+        <div class="notation-panel-body">
+          <p data-slot-summary hidden></p>
+          <div data-slot-formula hidden></div>
+          <p class="notation-units" data-slot-units hidden></p>
+          <a data-slot-link hidden
+            >Go to the full definition<span aria-hidden="true" data-jump-arrow> →</span></a
           >
-            <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>
+        </div>
+      </HoverPanel>
     </section>
   )
 }
 
 <script>
-  import { createPopupStack, closestElement } from '../popup-stack';
+  import {
+    cloneCardShell,
+    isKept,
+    registerCardSource,
+  } from '../card-manager';
+  import { wireJumpArrow } from '../card-jump';
   import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
 
   const triggerSelector = '[data-notation-key]';
 
+  function closestElement(node: EventTarget | null, selector: string) {
+    return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
+  }
+
   function setOptionalText(element: HTMLElement, value: string) {
     element.textContent = value;
     element.hidden = value.length === 0;
@@ -299,18 +321,19 @@ for (const gloss of glossItems) {
     if (entries.size === 0) return;
 
     const template = root.querySelector<HTMLTemplateElement>(
-      '[data-notation-popup-template]',
+      'template[data-card-template]',
     );
     if (!template) return;
 
     // 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.
+    // treatment. Symbols that appear *inside a card* (a card's own formula,
+    // D15, or an equation a reference card previews) are not in this list —
+    // there's no bound on how many of those can exist — but they still work
+    // as triggers: `symbolFrom` 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(
@@ -327,14 +350,19 @@ for (const gloss of glossItems) {
     for (const trigger of highlightTargets) {
       trigger.classList.add('notation-trigger');
     }
+    // C13: a `[[key]]` term's `title` is its no-JavaScript explanation; with
+    // the card here it would only be a second tooltip on top of it.
+    for (const term of externalTriggers) {
+      if (term.matches('a.notation-term')) term.removeAttribute('title');
+    }
     const help = root.querySelector<HTMLElement>('[data-notation-help]');
     if (help) help.hidden = false;
 
     // The visible list's own symbol glyphs are the only keyboard path to
-    // pinning a card from this list (the old "Pin explanation" button was
-    // the other one, and is gone) — make them a real, labelled, Enter/Space-
-    // operable control rather than a mouse-only `<span>`. `symbolTriggers`
-    // (defined above) is already scoped to entries inside this list.
+    // pinning a card from this list — make them a real, labelled,
+    // Enter/Space-operable control rather than a mouse-only `<span>`.
+    // `symbolTriggers` (defined above) is already scoped to entries inside
+    // this list.
     for (const trigger of symbolTriggers) {
       const key = trigger.dataset.notationKey ?? '';
       const entryLabel =
@@ -351,18 +379,9 @@ for (const gloss of glossItems) {
       });
     }
 
-    const keyFor = (element: HTMLElement | null) =>
-      element?.dataset.notationKey ?? element?.dataset.notationLink ?? null;
-
-    const staticLinkFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(node, '[data-notation-link]');
-      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.
+    // list, or — the D15 case — inside an open card. This has to be live: a
+    // card'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;
@@ -371,36 +390,27 @@ for (const gloss of glossItems) {
         : null;
     };
 
-    const triggerFrom = (node: EventTarget | null) =>
-      staticLinkFrom(node) ?? symbolFrom(node);
-
     const labelOf = (entry: HTMLElement, key: string) =>
       entry
         .querySelector<HTMLElement>('[data-notation-link]')
         ?.textContent?.trim() ?? key;
 
-    const createPopup = (key: string, _trigger: HTMLElement) => {
+    const buildCard = (key: string) => {
       const entry = entries.get(key);
       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]');
+      const el = cloneCardShell(template);
+      const symbolHost = el?.querySelector<HTMLElement>('[data-slot-symbol]');
+      const title = el?.querySelector<HTMLElement>('[data-slot-title]');
+      const summary = el?.querySelector<HTMLElement>('[data-slot-summary]');
+      const formulaHost = el?.querySelector<HTMLElement>('[data-slot-formula]');
+      const units = el?.querySelector<HTMLElement>('[data-slot-units]');
+      const link = el?.querySelector<HTMLAnchorElement>('[data-slot-link]');
       if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
         return null;
       }
 
+      el.dataset.popupKey = key;
       el.setAttribute('aria-label', `Notation: ${labelOf(entry, key)}`);
 
       const sourceSymbol = entry.querySelector<HTMLElement>('.notation-symbol');
@@ -431,30 +441,28 @@ for (const gloss of glossItems) {
           ?.textContent?.trim() ?? '',
       );
 
-      // A gloss has no card to open. Its own popup is the whole of it.
+      // A gloss has no entry to go to. Its own card is the whole of it.
       const href = entry.dataset.notationHref;
       if (link) {
         link.hidden = href === undefined;
-        if (href !== undefined) link.href = href;
+        if (href !== undefined) {
+          link.href = href;
+          wireJumpArrow(link);
+        }
       }
 
       return el;
     };
 
-    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,
-      createPopup,
-      onChange: (open, pinned) => {
+    // The card manager mounts every card in one layer on `<body>`, never in
+    // the article: an ancestor's stacking context once let the Starlight
+    // right sidebar eat a card's clicks.
+    registerCardSource({
+      layer: 'notation',
+      triggerFrom: symbolFrom,
+      itemFor: (trigger) => trigger.dataset.notationKey ?? null,
+      render: (key) => buildCard(key),
+      onChange: (open) => {
         for (const trigger of highlightTargets) {
           trigger.classList.toggle(
             'is-notation-active',
@@ -462,10 +470,8 @@ for (const gloss of glossItems) {
           );
         }
         for (const trigger of symbolTriggers) {
-          trigger.setAttribute(
-            'aria-pressed',
-            String(pinned.has(trigger.dataset.notationKey ?? '')),
-          );
+          const mode = open.get(trigger.dataset.notationKey ?? '');
+          trigger.setAttribute('aria-pressed', String(!!mode && isKept(mode)));
         }
       },
     });
@@ -560,7 +566,7 @@ for (const gloss of glossItems) {
   // 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 || origin.getAttribute('title')?.startsWith('Copy LaTeX')) return;
     if (
       origin.closest(
         '[data-notation-key], [data-notation-formula-copy], .notation-formula-number',
@@ -568,14 +574,20 @@ for (const gloss of glossItems) {
     ) {
       return;
     }
-    if (!origin.closest('[data-notation-formula]')) return;
-    origin.setAttribute('title', 'Copy LaTeX');
+    const formula = origin.closest<HTMLElement>('[data-notation-formula]');
+    if (!formula) return;
+    // "Copy LaTeX — ‹entry label›", the same title as the copy button.
+    origin.setAttribute('title', formula.dataset.copyTitle ?? 'Copy LaTeX');
+    origin.setAttribute('data-copy-hint', '');
   });
 
   document.addEventListener('mouseout', (event) => {
     const origin = event.target instanceof Element ? event.target : null;
-    if (origin?.getAttribute('title') === 'Copy LaTeX') {
+    // Only a title this script added — the copy button's own static
+    // `title` must survive the pointer leaving it (or crossing onto its icon).
+    if (origin?.hasAttribute('data-copy-hint')) {
       origin.removeAttribute('title');
+      origin.removeAttribute('data-copy-hint');
     }
   });
 </script>
@@ -594,20 +606,16 @@ for (const gloss of glossItems) {
     }
 
     /* Positioning context for `.notation-list-anchor`, mirroring
-       `Figure.astro`'s `.keyed-figure__titlebar` — the anchor link is a DOM
-       sibling of `<details>`, not nested inside `<summary>` (a focusable `<a>`
-       inside `<summary>` trips axe's `nested-interactive` check the same way
-       it would there). */
+       `Memo.astro`'s frame — the anchor link is a DOM sibling of `<details>`,
+       not nested inside `<summary>` (a focusable `<a>` inside `<summary>`
+       trips axe's `nested-interactive` check). */
     .notation-list-titlebar {
       position: relative;
     }
 
-    .notation-list {
-      border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.6rem;
-      background: var(--sl-color-gray-7);
-    }
-
+    /* `.notation-list` itself has no box styles: the panel is page
+       logistics, and the meta tier (`ex-tier-meta`, `surfaces.css`) draws
+       its surface, border and radius. */
     .notation-list > summary {
       padding: 0.8rem 1rem;
       padding-inline-end: 2.2rem;
@@ -671,6 +679,18 @@ for (const gloss of glossItems) {
       padding: 0 1rem 1rem;
     }
 
+    .notation-suspended {
+      margin: 0;
+      padding: 0 1rem 0.85rem;
+      list-style: none;
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-sm);
+    }
+
+    .notation-suspended li + li {
+      margin-top: 0.35rem;
+    }
+
     .notation-entry {
       display: grid;
       grid-template-columns: minmax(9rem, 0.65fr) minmax(12rem, 1.35fr);
@@ -768,61 +788,21 @@ for (const gloss of glossItems) {
     }
 
     .notation-enhancement-help {
-      margin: 0.55rem 0 0;
+      margin: 0 0 0.75rem;
+      padding: 0 1rem;
       font-size: var(--sl-text-xs);
     }
 
-    /* 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-block: 0.75rem;
-      padding-inline: 1rem 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);
-      /* Relative to the surrounding prose's own font-size, not a fixed
-         Starlight step — the card is mounted on `<body>`, alongside the
-         article rather than nested inside it, so `%` still resolves against
-         the same base the article's paragraphs use. */
+    /* Each open explanation is its own card, cloned from the `HoverPanel`
+       shell above and mounted by the card manager (`card-manager.ts`) on
+       `<body>`. Relative to the surrounding prose's own font-size, not a
+       fixed Starlight step: `%` resolves against the same base the article's
+       paragraphs use. `.notation-panel-body` and its descendants below style
+       the fields common to both this static list and a card's content. */
+    .notation-popup.hover-panel {
       font-size: 90%;
     }
 
-    .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]) {
@@ -901,6 +881,33 @@ for (const gloss of glossItems) {
     pointer-events: none;
   }
 
+  /* An accent's glyph box (`\hat`, `\dot`, `\vec`, …) is a full line tall and
+     painted over the letter it decorates, so it took every hover on that
+     letter: under an operator entry (rule N22) `\dot{x}` showed the dot's
+     card wherever the reader pointed. The glyph box lets the pointer through,
+     and a strip across the top of the decorated form — where KaTeX puts the
+     accent's ink, since the vlist's height is the accent's top — is the
+     accent's hit area instead. It sits inside the decorated form's trigger
+     and outside the letter's, so the letter shows its card and the accent
+     shows the operator's. Measured over 14 accents on short, tall and
+     subscripted letters; rendering is pixel-identical. */
+  :global(.katex-html .accent-body) {
+    pointer-events: none;
+  }
+
+  :global(.katex-html .accent > .vlist-t > .vlist-r > .vlist) {
+    position: relative;
+  }
+
+  :global(.katex-html .accent > .vlist-t > .vlist-r > .vlist::after) {
+    content: '';
+    position: absolute;
+    inset-inline: -0.1em;
+    top: 0;
+    height: 0.25em;
+    pointer-events: auto;
+  }
+
   :global(.katex-html [data-notation-key]) {
     cursor: help;
   }

package/src/components/notation/NotationMath.astro

@@ -1,6 +1,10 @@
 ---
 import { renderNotationMath } from './render-notation-math';
 import SafeMathNode from './SafeMathNode.astro';
+import {
+  decorationOfEntry,
+  operatorDisplayLatex,
+} from '../../reference/math-glyphs.mjs';
 
 interface Props {
   latex: string;
@@ -8,7 +12,12 @@ interface Props {
 }
 
 const { latex, class: className } = Astro.props;
-const nodes = renderNotationMath(latex);
+// An operator entry (`\dot{}`, rule N22) is shown over a placeholder square;
+// on its own the decoration is a speck.
+const operator = decorationOfEntry(latex);
+const nodes = renderNotationMath(
+  operator === undefined ? latex : operatorDisplayLatex(operator),
+);
 ---
 
 <span class:list={['notation-math', className]} data-notation-math>