explico 0.3.0 → 0.5.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

@@ -46,6 +46,7 @@ export interface Props {
 
 import NotationMath from './NotationMath.astro';
 import NotationFormula from './NotationFormula.astro';
+import { stripNotationMarkers } from './render-notation-math';
 import type { GlyphScopeEntry, ResolvedGloss } from '../../reference/gloss';
 
 const {
@@ -169,7 +170,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>
                   ))}
@@ -244,6 +249,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
@@ -369,7 +382,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 +419,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
@@ -573,6 +626,10 @@ 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);
     }
@@ -612,15 +669,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 +738,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);
     }
 
@@ -711,6 +808,17 @@ for (const gloss of glossItems) {
     pointer-events: none;
   }
 
+  /* KaTeX draws a radical sign, an extensible arrow (`\xrightarrow`), and
+     other stretchy glyphs as an absolutely-positioned SVG layer that is
+     painted after — and on top of — the content it decorates. Without this,
+     a pointer over a symbol inside `\sqrt{…}` or under an arrow hits that
+     overlay instead of the notation marker beneath it. The radicand lives in
+     the sibling `.svg-align` layer, which stays interactive. */
+  :global(.katex-html .sqrt .vlist > span:not(.svg-align)),
+  :global(.katex-html .hide-tail) {
+    pointer-events: none;
+  }
+
   :global(.katex-html [data-notation-key]) {
     cursor: help;
   }

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;
   }

package/src/components/notation/safe-math-to-react.ts

@@ -0,0 +1,50 @@
+/**
+ * Adapt a `SafeMathNode.properties` object — HTML attribute names and a raw
+ * CSS-text `style` string, exactly what `SafeMathNode.astro` spreads onto a
+ * dynamic element — into React's prop shape, for the React-side renderer
+ * (`RenderedContent.tsx`) `SafeMathNode.astro` doesn't need: React requires
+ * `className` (not `class`) and an object for `style` (not a CSS-text
+ * string) — "The `style` prop expects a mapping from style properties to
+ * values, not a string" is a hard React error, not a warning, so this isn't
+ * optional. Split into its own `.ts` module (rather than living inline in
+ * the `.tsx` component) so the parsing logic is unit-testable without a DOM.
+ */
+
+/** kebab-case CSS property -> camelCase, e.g. `margin-right` -> `marginRight`. */
+export function camelCaseCssProperty(name: string): string {
+  return name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+/**
+ * Parse a CSS-text `style` string into a React style object. `safeStyle`'s
+ * own grammar in `render-notation-math.ts`
+ * (`/^(?:[a-z-]+:[ A-Za-z0-9+.,()\-/%]*;)*$/`) guarantees every declaration
+ * is `key: value;` with no nested colons/semicolons — a straight split is
+ * exact for that input; this is not a general CSS parser.
+ */
+export function parseStyle(style: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const declaration of style.split(';')) {
+    if (declaration.trim() === '') continue;
+    const [property, value] = declaration.split(':');
+    if (property === undefined || value === undefined) continue;
+    result[camelCaseCssProperty(property.trim())] = value.trim();
+  }
+  return result;
+}
+
+/**
+ * `class` -> `className`, a `style` string -> a style object, everything
+ * else (`aria-hidden`, `data-notation-key`, the MathML attribute names)
+ * passed through unchanged — they're spelled the same in HTML and React.
+ */
+export function toReactProps(
+  properties: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const { class: className, style, ...rest } = properties;
+  return {
+    ...rest,
+    ...(className !== undefined ? { className } : {}),
+    ...(style !== undefined ? { style: parseStyle(style) } : {}),
+  };
+}