explico 0.4.0 → 0.6.0

package/src/components/notation/NotationFormula.astro

@@ -15,8 +15,15 @@
  */
 import NotationMath from './NotationMath.astro';
 import SafeMathNode from './SafeMathNode.astro';
-import { renderNotationFormula } from './render-notation-math';
+import {
+  renderNotationFormula,
+  stripNotationMarkers,
+} from './render-notation-math';
 import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
+import {
+  notationKeysInMathNodes,
+  registerPageNotationDependencies,
+} from '../../reference/page-notation';
 
 export interface Props {
   formula: string;
@@ -36,12 +43,18 @@ const {
   entryLabel,
 } = Astro.props;
 const { nodes } = renderNotationFormula(formula, scope);
+registerPageNotationDependencies(
+  Astro.locals,
+  notationKeysInMathNodes(nodes),
+  `NotationFormula formula "${formula}"`,
+);
 ---
 
 <div class="notation-formula-block">
   <div
     class="notation-formula-math"
     data-notation-formula
+    data-latex={stripNotationMarkers(formula)}
     role="group"
     aria-label={entryLabel ? `${entryLabel} formula` : 'Formula'}
     tabindex="0"
@@ -88,6 +101,10 @@ const { nodes } = renderNotationFormula(formula, scope);
        container is the fix; this is its focus ring. */
     .notation-formula-math {
       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);
     }

package/src/components/notation/NotationLayer.astro

@@ -42,10 +42,15 @@ 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`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
 }
 
 import NotationMath from './NotationMath.astro';
 import NotationFormula from './NotationFormula.astro';
+import { stripNotationMarkers } from './render-notation-math';
 import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
 
 const {
@@ -54,6 +59,8 @@ const {
   label = 'Notation used on this page',
   glossaryHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`,
   presentation = 'full',
+  defaultOpen = false,
+  rememberState = true,
 } = Astro.props;
 
 const panelOnly = presentation === 'panel';
@@ -110,16 +117,16 @@ for (const gloss of glossItems) {
       class:list={['notation-layer', panelOnly && 'notation-layer--panel-only']}
       data-notation-layer
       data-notation-layer-id={id}
-      aria-labelledby={panelOnly ? undefined : `${id}-heading`}
-      aria-label={panelOnly ? 'Notation explanations' : undefined}
+      aria-label={panelOnly ? 'Notation explanations' : label}
     >
-      {!panelOnly && (
-        <h2 id={`${id}-heading`} class="notation-layer-heading">
-          Page notation
-        </h2>
-      )}
-
-      <details class="notation-list" hidden={panelOnly}>
+      <div class="notation-list-titlebar">
+      <details
+        class="notation-list"
+        id={id}
+        hidden={panelOnly}
+        data-remember-state={String(rememberState)}
+        open={defaultOpen}
+      >
         <summary>
           {label} <span class="notation-count">({items.length})</span>
         </summary>
@@ -169,7 +176,11 @@ for (const gloss of glossItems) {
                       entryLabel={definition.label}
                     />
                   ) : (
-                    <span class="notation-formula" data-notation-formula>
+                    <span
+                      class="notation-formula"
+                      data-notation-formula
+                      data-latex={stripNotationMarkers(definition.formula)}
+                    >
                       <NotationMath latex={definition.formula} />
                     </span>
                   ))}
@@ -178,16 +189,6 @@ for (const gloss of glossItems) {
                     <strong>Units:</strong> {definition.units}
                   </p>
                 )}
-                <button
-                  class="notation-pin"
-                  type="button"
-                  data-notation-control={definition.key}
-                  aria-expanded="false"
-                  aria-pressed="false"
-                  hidden
-                >
-                  Pin explanation
-                </button>
               </dd>
             </div>
           ))}
@@ -211,14 +212,32 @@ for (const gloss of glossItems) {
           </div>
         ))}
       </details>
+      {!panelOnly && (
+        <a
+          class="notation-list-anchor"
+          href={`#${id}`}
+          aria-label={`${label}, titled section`}
+        >
+          <svg
+            aria-hidden="true"
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="currentColor"
+            ><path
+              d="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"
+            ></path></svg
+          >
+        </a>
+      )}
+      </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, or select “Pin explanation”, to
-          keep a card open; click the card (or its “×”) to close it, or press
-          Escape.
+          too, alongside it. Click a symbol to keep its card open; click the
+          card (or its “×”) to close it, or press Escape.
         </p>
       )}
 
@@ -244,6 +263,14 @@ 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
@@ -257,6 +284,7 @@ for (const gloss of glossItems) {
 
 <script>
   import { createPopupStack, closestElement } from '../popup-stack';
+  import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
 
   const triggerSelector = '[data-notation-key]';
 
@@ -283,10 +311,6 @@ for (const gloss of glossItems) {
     );
     if (!template) return;
 
-    const controls = Array.from(
-      root.querySelectorAll<HTMLButtonElement>('[data-notation-control]'),
-    );
-
     // 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
@@ -311,20 +335,32 @@ for (const gloss of glossItems) {
     for (const trigger of highlightTargets) {
       trigger.classList.add('notation-trigger');
     }
-    for (const control of controls) control.hidden = false;
     const help = root.querySelector<HTMLElement>('[data-notation-help]');
     if (help) help.hidden = false;
 
-    const keyFor = (element: HTMLElement | null) =>
-      element?.dataset.notationKey ??
-      element?.dataset.notationControl ??
-      element?.dataset.notationLink ??
-      null;
+    // 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.
+    for (const trigger of symbolTriggers) {
+      const key = trigger.dataset.notationKey ?? '';
+      const entryLabel =
+        entries.get(key)?.querySelector<HTMLElement>('[data-notation-link]')
+          ?.textContent?.trim() ?? key;
+      trigger.setAttribute('role', 'button');
+      trigger.tabIndex = 0;
+      trigger.setAttribute('aria-pressed', 'false');
+      trigger.setAttribute('aria-label', `Pin the ${entryLabel} explanation`);
+      trigger.addEventListener('keydown', (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        trigger.click();
+      });
+    }
 
-    const controlFrom = (node: EventTarget | null) => {
-      const candidate = closestElement(node, '[data-notation-control]');
-      return candidate && root.contains(candidate) ? candidate : null;
-    };
+    const keyFor = (element: HTMLElement | null) =>
+      element?.dataset.notationKey ?? element?.dataset.notationLink ?? null;
 
     const staticLinkFrom = (node: EventTarget | null) => {
       const candidate = closestElement(node, '[data-notation-link]');
@@ -344,7 +380,7 @@ for (const gloss of glossItems) {
     };
 
     const triggerFrom = (node: EventTarget | null) =>
-      controlFrom(node) ?? staticLinkFrom(node) ?? symbolFrom(node);
+      staticLinkFrom(node) ?? symbolFrom(node);
 
     const labelOf = (entry: HTMLElement, key: string) =>
       entry
@@ -369,7 +405,18 @@ for (const gloss of glossItems) {
       const units = fragment.querySelector<HTMLElement>('[data-slot-units]');
       const link =
         fragment.querySelector<HTMLAnchorElement>('[data-slot-link]');
-      if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
+      const copyButton = fragment.querySelector<HTMLButtonElement>(
+        '[data-popup-copy]',
+      );
+      if (
+        !el ||
+        !symbolHost ||
+        !title ||
+        !summary ||
+        !formulaHost ||
+        !units ||
+        !copyButton
+      ) {
         return null;
       }
 
@@ -395,6 +442,35 @@ for (const gloss of glossItems) {
         ...(sourceFormula ? [sourceFormula.cloneNode(true)] : []),
       );
       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
@@ -412,21 +488,6 @@ for (const gloss of glossItems) {
       return el;
     };
 
-    const updateControls = (
-      open: ReadonlySet<string>,
-      pinned: ReadonlySet<string>,
-    ) => {
-      for (const control of controls) {
-        const key = control.dataset.notationControl ?? '';
-        const selected = pinned.has(key);
-        control.setAttribute('aria-pressed', String(selected));
-        control.setAttribute('aria-expanded', String(open.has(key)));
-        control.textContent = selected
-          ? 'Unpin explanation'
-          : 'Pin explanation';
-      }
-    };
-
     createPopupStack({
       // Popups are `position: fixed` and float above everything regardless
       // of DOM placement — *except* z-index only ever wins within its own
@@ -440,7 +501,6 @@ for (const gloss of glossItems) {
       triggerFrom,
       keyFor,
       createPopup,
-      pinControlFrom: controlFrom,
       onChange: (open, pinned) => {
         for (const trigger of highlightTargets) {
           trigger.classList.toggle(
@@ -448,15 +508,44 @@ for (const gloss of glossItems) {
             open.has(trigger.dataset.notationKey ?? ''),
           );
         }
-        updateControls(open, pinned);
+        for (const trigger of symbolTriggers) {
+          trigger.setAttribute(
+            'aria-pressed',
+            String(pinned.has(trigger.dataset.notationKey ?? '')),
+          );
+        }
       },
     });
   }
 
+  function setupNotationDisclosure(details: HTMLDetailsElement) {
+    if (details.dataset.disclosureWired === 'true') return;
+    details.dataset.disclosureWired = 'true';
+
+    // Same convention as `Figure.astro`: the SSR-rendered `open` attribute
+    // already carries the author's `defaultOpen` prop verbatim.
+    const defaultOpen = details.open;
+    if (details.dataset.rememberState === 'true') {
+      wirePersistedDetails(details, `notation:${details.id}`, defaultOpen);
+    }
+
+    // Deep-linking to `#page-notation` (the anchor link, or a shared URL)
+    // must reveal it even if a reader left it collapsed.
+    const openIfTargeted = () => {
+      if (location.hash === `#${details.id}`) details.open = true;
+    };
+    openIfTargeted();
+    window.addEventListener('hashchange', openIfTargeted);
+  }
+
   for (const root of document.querySelectorAll<HTMLElement>(
     '[data-notation-layer]',
   )) {
     setupNotationLayer(root);
+    const details = root.querySelector<HTMLDetailsElement>(
+      ':scope > .notation-list-titlebar > .notation-list[id]',
+    );
+    if (details) setupNotationDisclosure(details);
   }
 </script>
 
@@ -473,9 +562,13 @@ for (const gloss of glossItems) {
       margin: 0;
     }
 
-    .notation-layer-heading {
-      margin: 0 0 0.65rem;
-      font-size: var(--sl-text-lg);
+    /* 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). */
+    .notation-list-titlebar {
+      position: relative;
     }
 
     .notation-list {
@@ -486,8 +579,52 @@ for (const gloss of glossItems) {
 
     .notation-list > summary {
       padding: 0.8rem 1rem;
+      padding-inline-end: 2.2rem;
       cursor: pointer;
       font-weight: 600;
+      font-size: var(--sl-text-lg);
+    }
+
+    .notation-list-anchor {
+      position: absolute;
+      top: 0.9rem;
+      inset-inline-end: 1rem;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1em;
+      height: 1em;
+      font-size: var(--sl-text-lg);
+      color: var(--sl-color-gray-3);
+      text-decoration: none;
+      -webkit-user-select: none;
+      user-select: none;
+    }
+
+    .notation-list-anchor svg {
+      width: 0.7em;
+      height: 0.7em;
+    }
+
+    .notation-list-anchor:hover,
+    .notation-list-anchor:focus-visible {
+      color: var(--sl-color-text-accent);
+    }
+
+    .notation-list-anchor:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 0.15rem;
+    }
+
+    @media (hover: hover) {
+      .notation-list-anchor {
+        opacity: 0;
+      }
+
+      .notation-list-anchor:focus-visible,
+      .notation-list-titlebar:hover .notation-list-anchor {
+        opacity: 1;
+      }
     }
 
     .notation-count,
@@ -541,14 +678,28 @@ for (const gloss of glossItems) {
       cursor: help;
     }
 
+    /* Entries in the visible list are keyboard-operable (Enter/Space pins
+       the same card a click would) now that the list has no separate "Pin
+       explanation" button of its own — see the setup script below. */
+    .notation-entry .notation-symbol-trigger {
+      cursor: pointer;
+    }
+
     .notation-symbol-trigger:hover,
+    .notation-symbol-trigger:focus-visible,
     .notation-symbol-trigger.is-notation-active {
       background: var(--sl-color-accent-low);
       box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
     }
 
+    .notation-symbol-trigger:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 0.1em;
+    }
+
     @media (forced-colors: active) {
       .notation-symbol-trigger:hover,
+      .notation-symbol-trigger:focus-visible,
       .notation-symbol-trigger.is-notation-active {
         outline: 2px solid Highlight;
         color: HighlightText;
@@ -573,28 +724,14 @@ for (const gloss of glossItems) {
 
     .notation-formula {
       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-pin {
-      justify-self: start;
-      padding: 0.25rem 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-sm);
-      cursor: pointer;
-    }
-
-    .notation-pin:hover,
-    .notation-pin[aria-pressed='true'] {
-      border-color: var(--sl-color-accent);
-      background: var(--sl-color-accent-low);
-    }
-
     .notation-enhancement-help {
       margin: 0.55rem 0 0;
       font-size: var(--sl-text-xs);
@@ -612,15 +749,19 @@ for (const gloss of glossItems) {
       margin: 0;
       width: min(23rem, calc(100vw - 1.5rem));
       overflow: auto;
-      padding: 1rem;
-      padding-inline-end: 2.4rem;
+      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);
-      font-size: var(--sl-text-sm);
+      /* 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. */
+      font-size: 90%;
     }
 
     .notation-popup-close {
@@ -677,15 +818,51 @@ for (const gloss of glossItems) {
     }
 
     .notation-panel-body p {
-      margin-block: 0.65rem;
+      margin-block: 0.5rem;
       color: var(--sl-color-gray-2);
-      font-size: var(--sl-text-sm);
       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;
-      margin-block: 0.65rem;
+      /* See `.notation-formula` above: pairs with `overflow-x` to stop the
+         auto-both-axes quirk from giving the formula its own vertical
+         scrollbar. */
+      overflow-y: hidden;
+      margin-block: 0.5rem;
       color: var(--sl-color-text);
     }
 

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

@@ -1,7 +1,11 @@
 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 {
+  GlyphResolutionError,
+  resolveMathGlyphs,
+  stripNotationMarkers,
+} from '../../reference/math-glyphs.mjs';
 import type { GlyphScopeEntry } from '../../reference/gloss';
 
 interface HastText {
@@ -32,6 +36,19 @@ export type SafeMathNode =
       children: readonly SafeMathNode[];
     };
 
+/**
+ * A string that mixes prose and math, already split and rendered — text runs
+ * verbatim, a math run as the same safe, structured tree `SafeMathNode` is.
+ * Produced by `AssessmentSet.astro` from `manifest.assessmentContent`
+ * (`ContentSegment[]`, unrendered LaTeX) via {@link renderNotationMath}, and
+ * consumed by `AssessmentRunner`'s React-side recursive renderer
+ * (`RenderedContent.tsx`) — the React equivalent of `SafeMathNode.astro`,
+ * since a React island can't render an `.astro` component.
+ */
+export type MixedContentNode =
+  | { type: 'text'; value: string }
+  | { type: 'math'; nodes: readonly SafeMathNode[] };
+
 const allowedTags = new Set([
   'annotation',
   'math',
@@ -203,6 +220,14 @@ function sanitizeNode(node: HastNode): SafeMathNode {
   });
 }
 
+// Re-exported so existing imports of `stripNotationMarkers` from this module
+// (the notation popup card's "Copy LaTeX" button) keep working. The
+// implementation lives in `math-glyphs.mjs` because `remark-notation.mjs`
+// (a numbered display equation's own copy button, at build time) needs it
+// too, and importing it from here would make that a circular dependency —
+// this module already imports from `remark-notation.mjs`.
+export { stripNotationMarkers };
+
 /**
  * Render repository-authored LaTeX through the same build-time KaTeX adapter
  * as lesson math, then expose a constrained structured tree to Astro. No HTML
@@ -274,7 +299,19 @@ export function renderNotationFormula(
     const result = resolveMathGlyphs(formula, [...scope]);
     bound = result.latex;
     unresolved = result.unresolved.map(({ token }: { token: string }) => token);
-  } catch {
+  } catch (error) {
+    // N13 (a nonlinear function with no parenthesized argument) is a hard,
+    // no-exceptions rule like N9 — never degrade it to inert math, so both
+    // `Diagram` (which turns `degraded` into a build error anyway, but with
+    // a misleading "notation scope" message) and `NotationFormula` (which
+    // otherwise keeps a degraded formula's inert-but-correct fallback) fail
+    // loudly with the actual fix instead.
+    if (
+      error instanceof GlyphResolutionError &&
+      error.code === 'unparenthesized-function'
+    ) {
+      throw error;
+    }
     bound = formula;
     degraded = true;
   }