explico 0.5.0 → 0.7.0

package/src/components/notation/NotationLayer.astro

@@ -42,6 +42,10 @@ 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';
@@ -55,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';
@@ -111,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>
@@ -183,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>
           ))}
@@ -216,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>
       )}
 
@@ -249,14 +263,6 @@ 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
@@ -270,6 +276,7 @@ for (const gloss of glossItems) {
 
 <script>
   import { createPopupStack, closestElement } from '../popup-stack';
+  import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
 
   const triggerSelector = '[data-notation-key]';
 
@@ -296,10 +303,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
@@ -324,20 +327,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]');
@@ -357,7 +372,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
@@ -382,18 +397,7 @@ for (const gloss of glossItems) {
       const units = fragment.querySelector<HTMLElement>('[data-slot-units]');
       const link =
         fragment.querySelector<HTMLAnchorElement>('[data-slot-link]');
-      const copyButton = fragment.querySelector<HTMLButtonElement>(
-        '[data-popup-copy]',
-      );
-      if (
-        !el ||
-        !symbolHost ||
-        !title ||
-        !summary ||
-        !formulaHost ||
-        !units ||
-        !copyButton
-      ) {
+      if (!el || !symbolHost || !title || !summary || !formulaHost || !units) {
         return null;
       }
 
@@ -420,34 +424,6 @@ for (const gloss of glossItems) {
       );
       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
@@ -465,21 +441,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
@@ -493,7 +454,6 @@ for (const gloss of glossItems) {
       triggerFrom,
       keyFor,
       createPopup,
-      pinControlFrom: controlFrom,
       onChange: (open, pinned) => {
         for (const trigger of highlightTargets) {
           trigger.classList.toggle(
@@ -501,16 +461,123 @@ 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);
   }
+
+  // "Copy LaTeX" for a notation formula (a glossary entry's own numbered
+  // formula, or one named inline via `\explain{}` inside a popup/`Diagram`),
+  // two ways: its own button (only a numbered formula has one —
+  // `data-notation-formula-copy`, `NotationFormula.astro`), or a click
+  // anywhere else in the box that isn't the number link or an explained
+  // symbol — the same region `.notation-formula-math:hover` highlights
+  // (`NotationFormula.astro`), which includes the reserved gutter between
+  // the equation and its number, not just the rendered `.katex-html`. This
+  // listener lives here, not in `NotationFormula.astro` or
+  // `KeyedFloatEnhancer.astro`, because this component loads on every page —
+  // it's the Starlight `Footer` override — while `KeyedFloatEnhancer` is
+  // lesson-only and a formula can appear inside a hover popup mounted
+  // outside `.sl-markdown-content`.
+  document.addEventListener('click', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (!origin) return;
+
+    const ownButton = origin.closest<HTMLButtonElement>(
+      '[data-notation-formula-copy]',
+    );
+    const container = ownButton
+      ? null
+      : origin.closest<HTMLElement>('[data-notation-formula]');
+    if (!ownButton) {
+      if (origin.closest('[data-notation-key], .notation-formula-number')) {
+        return;
+      }
+      if (!container) return;
+    }
+
+    const feedbackTarget =
+      ownButton ??
+      container?.querySelector<HTMLElement>('[data-notation-formula-copy]') ??
+      container;
+    const latex =
+      ownButton?.dataset.latex ?? feedbackTarget?.dataset.latex ?? '';
+    if (!feedbackTarget || latex.length === 0 || !navigator.clipboard) return;
+
+    navigator.clipboard.writeText(latex).then(
+      () => {
+        feedbackTarget.dataset.copied = 'true';
+        window.setTimeout(() => {
+          delete feedbackTarget.dataset.copied;
+        }, 1200);
+      },
+      () => {
+        /* Clipboard blocked: nothing more we can do here. */
+      },
+    );
+  });
+
+  // A tooltip for the click gesture above, and only for the part of the
+  // equation it actually applies to — an explained symbol has its own hover
+  // card (created above) and needs no tooltip layered on top of it, and the
+  // copy button already carries a static `title`. `mouseover`/`mouseout` (not
+  // `mouseenter`/`mouseleave`) because they bubble, which this document-level
+  // 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.closest(
+        '[data-notation-key], [data-notation-formula-copy], .notation-formula-number',
+      )
+    ) {
+      return;
+    }
+    if (!origin.closest('[data-notation-formula]')) return;
+    origin.setAttribute('title', 'Copy LaTeX');
+  });
+
+  document.addEventListener('mouseout', (event) => {
+    const origin = event.target instanceof Element ? event.target : null;
+    if (origin?.getAttribute('title') === 'Copy LaTeX') {
+      origin.removeAttribute('title');
+    }
+  });
 </script>
 
 <style>
@@ -526,9 +593,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 {
@@ -539,8 +610,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,
@@ -594,14 +709,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;
@@ -624,6 +753,10 @@ for (const gloss of glossItems) {
       font-size: var(--sl-text-sm);
     }
 
+    /* Cursor, hover highlight, and "Copied!" flash for this plain-span
+       formula fallback (a definition with no `formulaScope`) come from the
+       generic `[data-notation-formula]` rules in `global.css` — shared with
+       every other producer of that attribute, not reimplemented here. */
     .notation-formula {
       overflow-x: auto;
       /* `overflow-x: auto` alone makes the block axis compute to `auto` too
@@ -634,24 +767,6 @@ for (const gloss of glossItems) {
       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);
@@ -743,39 +858,6 @@ for (const gloss of glossItems) {
       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;
       /* See `.notation-formula` above: pairs with `overflow-x` to stop the