explico 0.8.0 → 0.11.0

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -10,6 +10,24 @@
  * sticky-header `scroll-margin`.
  *
  * This script only adds what CSS and anchors cannot:
+ *  - the chain icon copies the section's link: one click puts the page URL
+ *    with the heading's named anchor (never its number) on the clipboard and
+ *    says so beside the icon — "Link copied · § 1.1.2 · Velocity over time",
+ *    the number read off the heading's `data-sec-number`
+ *    (docs/plans/titles-and-containers.md, Q2/Q3). On a narrow screen, where
+ *    headings show no number, this is where the number surfaces. The link is
+ *    a named one (docs/plans/figures-and-short-captions.md, decision 9.3):
+ *    beside the URL (`text/plain`), the clipboard holds an `<a>` reading
+ *    "§ 1.1.2 Velocity over time" (`text/html`) where the browser has
+ *    `ClipboardItem`, so a paste into a document keeps the name. The click
+ *    still navigates, so the hash and the highlight below follow as before;
+ *    a clipboard that is missing or refuses leaves exactly that navigation.
+ *    On hover the icon says "Copy link", a title this script sets, since
+ *    only with it does a click copy. A float's chain icon in its caption
+ *    line (`a[data-copy-link]`, `FloatCaption.astro`) copies the same way,
+ *    named by its number and short caption — "Link copied · Figure 2.2.1 ·
+ *    Projectile trajectory explorer", pasted as "Figure 2.2.1, Projectile
+ *    trajectory explorer"; its landing is `KeyedFloatEnhancer`'s;
  *  - a smooth, header-aware scroll on an in-page jump;
  *  - a brief highlight of the section body (the heading's following siblings up
  *    to the next heading of equal or higher rank), so a deep link lands the
@@ -38,6 +56,7 @@
 <script>
   import { HEADINGS, sectionParts } from './section-parts';
   import { animatedScrollIntoView } from '../scroll-animation';
+  import { floatOf } from '../float-name';
 
   (() => {
     const root = document.querySelector('.sl-markdown-content');
@@ -90,14 +109,187 @@
       }
     };
 
+    // The link a reader can share: the page's canonical URL when it declares
+    // one (Starlight does once the site has a `site` URL), else this page
+    // without its query — and the heading's named anchor, never a number.
+    const shareableUrl = (id: string): string => {
+      const canonical = document.querySelector<HTMLLinkElement>(
+        'link[rel="canonical"]',
+      )?.href;
+      const url = new URL(canonical || location.href);
+      if (!canonical) url.search = '';
+      url.hash = id;
+      return url.href;
+    };
+
+    // Screen readers hear the confirmation from one polite live region; the
+    // bubble beside the icon is for the eye only.
+    const status = document.createElement('div');
+    status.className = 'sr-only';
+    status.setAttribute('role', 'status');
+    document.body.append(status);
+
+    const COPIED_MS = 1800;
+    let bubble: HTMLElement | null = null;
+    let bubbleTimer = 0;
+
+    // What a link is called: its kind and number ("§ 1.1.2", "Figure 2.2.1")
+    // and its title — a heading's text, a check's or example set's topic, a
+    // float's short caption. Either can be missing.
+    interface LinkName {
+      readonly label: string;
+      readonly title: string;
+    }
+
+    const headingName = (heading: HTMLElement): LinkName => {
+      const { secNumber, checkNumber, exNumber, memoNumber } = heading.dataset;
+      const label = secNumber
+        ? `§ ${secNumber}`
+        : checkNumber
+          ? `Knowledge check ${checkNumber}`
+          : exNumber
+            ? `Example ${exNumber}`
+            : memoNumber
+              ? `Memo ${memoNumber}`
+              : '';
+      // A memo goes by its short caption where it has one, as its marker's
+      // tooltip does; a check's or example set's heading also draws its kind
+      // and number, so only its topic counts.
+      const short = memoNumber
+        ? heading.closest<HTMLElement>('[data-memo-short]')?.dataset.memoShort
+        : undefined;
+      const titled = heading.querySelector('.block-heading__title') ?? heading;
+      return {
+        label,
+        title: short || (titled.textContent?.replace(/\s+/g, ' ').trim() ?? ''),
+      };
+    };
+
+    const floatName = (link: HTMLElement): LinkName => {
+      const root = link.closest('figure');
+      return {
+        label: link.dataset.copyLink ?? '',
+        title: (root && floatOf(root)?.short) || '',
+      };
+    };
+
+    const confirmation = ({ label, title }: LinkName): string =>
+      ['Link copied', label, title].filter(Boolean).join(' · ');
+
+    // "§ 1.1.2 Velocity over time", "Figure 2.2.1, Projectile trajectory
+    // explorer": the text a pasted link reads.
+    const linkText = ({ label, title }: LinkName): string =>
+      !title ? label : !label ? title : label.startsWith('§') ? `${label} ${title}` : `${label}, ${title}`;
+
+    // `below`: the viewport y the bubble hangs from — under the icon, or
+    // under a heading's whole title when that wraps lower.
+    const confirmCopied = (link: HTMLElement, message: string, below: number) => {
+      status.textContent = message;
+
+      bubble?.remove();
+      window.clearTimeout(bubbleTimer);
+      const shown = document.createElement('span');
+      shown.className = 'sl-anchor-copied';
+      shown.setAttribute('aria-hidden', 'true');
+      shown.textContent = message;
+      document.body.append(shown);
+      // Under the title — a long one wraps below its icon — with its end edge
+      // on the icon's, and never past either side of the text column: a short
+      // heading's icon sits near the start.
+      const icon = link.getBoundingClientRect();
+      const column = root.getBoundingClientRect();
+      const width = shown.offsetWidth;
+      const left = Math.max(
+        column.left,
+        Math.min(icon.right - width, column.right - width),
+      );
+      // Page coordinates, so the bubble travels with the heading while the
+      // click's own navigation scrolls it into place.
+      shown.style.left = `${Math.round(left + window.scrollX)}px`;
+      shown.style.top = `${Math.round(below + window.scrollY + 4)}px`;
+      bubble = shown;
+      bubbleTimer = window.setTimeout(() => {
+        shown.remove();
+        if (bubble === shown) bubble = null;
+      }, COPIED_MS);
+    };
+
+    // The URL as plain text, and — where the browser can hold two flavours —
+    // a named link beside it, for a paste into a document.
+    const copyLink = (id: string, name: LinkName, confirm: () => void) => {
+      const clipboard = navigator.clipboard;
+      if (!clipboard?.writeText) return;
+      const url = shareableUrl(id);
+      const text = linkText(name);
+      let written: Promise<void>;
+      if (text && typeof ClipboardItem === 'function' && typeof clipboard.write === 'function') {
+        const named = document.createElement('a');
+        named.href = url;
+        named.textContent = text;
+        written = clipboard.write([
+          new ClipboardItem({
+            'text/plain': new Blob([url], { type: 'text/plain' }),
+            'text/html': new Blob([named.outerHTML], { type: 'text/html' }),
+          }),
+        ]);
+      } else {
+        written = clipboard.writeText(url);
+      }
+      written.then(confirm, () => {
+        /* Refused: the navigation still happens, as it always has. */
+      });
+    };
+
+    // A heading's chain icon says on hover that a click copies, as a float's
+    // does in its own markup (`FloatCaption.astro`). The markup cannot say it
+    // here: without this script, or without a clipboard, the icon only
+    // navigates. So the title goes on exactly the icons the click handler
+    // below copies from — every heading's, including the ones
+    // `BlockHeading.astro` and `Memo.astro` draw.
+    if (typeof navigator.clipboard?.writeText === 'function') {
+      for (const link of root.querySelectorAll<HTMLElement>('a.sl-anchor-link')) {
+        const href = link.getAttribute('href') || '';
+        if (href.startsWith('#') && headingForId(href.slice(1))) {
+          link.title = 'Copy link';
+        }
+      }
+    }
+
     root.addEventListener('click', (event) => {
       const origin = event.target instanceof Element ? event.target : null;
-      const link = origin?.closest('a.sl-anchor-link');
+
+      // A float's chain icon: copy, confirm, and let the click navigate.
+      const floatLink = origin?.closest<HTMLElement>('a[data-copy-link]');
+      const floatHref = floatLink?.getAttribute('href') || '';
+      if (floatLink && floatHref.startsWith('#')) {
+        const name = floatName(floatLink);
+        copyLink(floatHref.slice(1), name, () =>
+          confirmCopied(
+            floatLink,
+            confirmation(name),
+            floatLink.getBoundingClientRect().bottom,
+          ),
+        );
+        return;
+      }
+
+      const link = origin?.closest<HTMLElement>('a.sl-anchor-link');
       if (!link) return;
       const href = link.getAttribute('href') || '';
       if (!href.startsWith('#')) return;
       const heading = headingForId(href.slice(1));
       if (!heading) return;
+      const name = headingName(heading);
+      copyLink(heading.id, name, () =>
+        confirmCopied(
+          link,
+          confirmation(name),
+          Math.max(
+            link.getBoundingClientRect().bottom,
+            heading.getBoundingClientRect().bottom,
+          ),
+        ),
+      );
       // Only the already-on-this-anchor click needs handling here — see
       // `KeyedFloatEnhancer.astro`. Every other click is left to the browser's
       // own fragment navigation, picked up below via `hashchange`.

package/src/components/starlight/KeyedFloatEnhancer.astro

@@ -20,6 +20,7 @@
  *    activated again — the one case a plain anchor click does nothing for,
  *    since the browser won't navigate to a fragment that's already current;
  *  - moving keyboard focus onto the float so screen-reader users land on it;
+ *  - making a display equation that overflows its column keyboard-scrollable;
  *  - for an equation only, marking its number permanently visible
  *    (`.eq-number-revealed`, styled in `global.css`) once the reader has
  *    actually arrived at it, so it doesn't fade back down once the
@@ -36,9 +37,31 @@
  *
  * Everything here is gated on `prefers-reduced-motion` and degrades to the
  * native anchor behaviour if it throws.
+ *
+ * **Number aliases** (docs/plans/titles-and-containers.md, Q4). With the
+ * course's `numbering.aliases` on (the `aliases` prop, from the manifest), a
+ * fragment a reader types in number form — `#sec-1.1.2`, `#fig-2.2.1`,
+ * `#eq-2.2.4`, `#tab-…`, `#dia-…`, `#check-…`, `#ex-…` — is rewritten to the named
+ * anchor of the element that prints that number here. The map is the page
+ * itself: every numbered element already carries `data-‹kind›-number` beside
+ * its `id`, so an alias resolves exactly when the reader can see its number
+ * on this page, and never disagrees with it. Inbound only: nothing the site
+ * shows or copies is a number form, and an alias is only as stable as the
+ * content version the About panel names. This script runs before
+ * `CollapsibleSections` and `HeadingAnchorEnhancer` (see `LessonFooter`), so
+ * on arrival the rewrite is in place before either reads the hash — an alias
+ * lands exactly like a named deep link.
  */
+interface Props {
+  /** `manifest.numbering.aliases`: resolve number-form fragments. */
+  aliases?: boolean;
+}
+
+const { aliases = false } = Astro.props;
 ---
 
+{aliases && <div hidden data-explico-number-aliases />}
+
 <script>
   import { animatedScrollIntoView } from '../scroll-animation';
 
@@ -46,6 +69,21 @@
     const root = document.querySelector('.sl-markdown-content');
     if (!root) return;
 
+    // `#sec-1.1.2` → the element printing that number, if this page has one.
+    const ALIAS = /^#(sec|eq|tab|fig|dia|check|ex)-(\d+(?:\.\d+)+)$/;
+    const aliasesOn = document.querySelector('[data-explico-number-aliases]') !== null;
+    const aliasTarget = (hash: string): HTMLElement | null => {
+      const match = aliasesOn ? ALIAS.exec(hash) : null;
+      if (!match) return null;
+      return root.querySelector<HTMLElement>(
+        `[id][data-${match[1]}-number="${match[2]}"]`,
+      );
+    };
+    // On arrival: rewrite without an event, so every enhancer's own
+    // first-hash handling sees the named anchor.
+    const arrived = aliasTarget(location.hash);
+    if (arrived) history.replaceState(history.state, '', `#${arrived.id}`);
+
     interface Kind {
       readonly prefix: string;
       readonly triggerSelector: string;
@@ -60,21 +98,23 @@
         numberSelector: '.keyed-equation__number',
         reveal: true,
       },
+      // A float's caption line links to it twice: its number, and the chain
+      // icon beside it (which also copies the link, `HeadingAnchorEnhancer`).
       {
         prefix: '#tab-',
-        triggerSelector: 'a.table-ref, a.keyed-table__number',
+        triggerSelector: 'a.table-ref, a.keyed-table__number, a.float-caption__anchor',
         numberSelector: '.keyed-table__number',
         reveal: false,
       },
       {
         prefix: '#fig-',
-        triggerSelector: 'a.figure-ref, a.keyed-figure__number',
+        triggerSelector: 'a.figure-ref, a.keyed-figure__number, a.float-caption__anchor',
         numberSelector: '.keyed-figure__number',
         reveal: false,
       },
       {
         prefix: '#dia-',
-        triggerSelector: 'a.diagram-ref, a.diagram__title-anchor',
+        triggerSelector: 'a.diagram-ref, a.diagram__number, a.float-caption__anchor',
         numberSelector: '.diagram__number',
         reveal: false,
       },
@@ -178,12 +218,14 @@
 
     // A tooltip for the gesture above, and only for the part of the equation
     // it actually applies to — an explained symbol has its own hover card
-    // (`NotationLayer.astro`) and needs no tooltip layered on top of it.
+    // (`NotationLayer.astro`) and needs no tooltip layered on top of it. It
+    // names the equation by its `\caption{}` short caption when it has one —
+    // "Copy LaTeX — Range formula", the same title as its copy button.
     // `mouseover`/`mouseout` (not `mouseenter`/`mouseleave`) because they
     // bubble, which delegation on `root` needs.
     root.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-eq-copy], a.keyed-equation__number',
@@ -191,18 +233,67 @@
       ) {
         return;
       }
-      if (!origin.closest('.keyed-equation, .inline-equation')) return;
-      origin.setAttribute('title', 'Copy LaTeX');
+      const equation = origin.closest<HTMLElement>('.keyed-equation, .inline-equation');
+      if (!equation) return;
+      const short = equation.dataset.eqShort;
+      origin.setAttribute('title', short ? `Copy LaTeX — ${short}` : 'Copy LaTeX');
+      origin.setAttribute('data-copy-hint', '');
     });
 
     root.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');
       }
     });
 
-    window.addEventListener('hashchange', () => {
+    // A display equation wider than the column scrolls sideways
+    // (`.katex-display { overflow-x: auto }` in `global.css`) — on a phone,
+    // with a numbered equation's controls beside it, that is common. A
+    // scrollable region must be keyboard-reachable (WCAG 2.1.1, axe's
+    // `scrollable-region-focusable`), so, the same way
+    // `TableOverflowExpander.astro` and `DiagramEnhancer.astro` treat their
+    // scrollers, it gets a `tabindex` and a name only while it overflows. A
+    // `ResizeObserver` catches every case that changes that: first layout, a
+    // viewport change, and a collapsed section opening (no layout box while
+    // closed, so no overflow either).
+    const updateEquationScroll = (display: HTMLElement) => {
+      if (display.scrollWidth > display.clientWidth + 1) {
+        const number = display
+          .closest<HTMLElement>('.keyed-equation')
+          ?.dataset.eqNumber;
+        display.tabIndex = 0;
+        display.setAttribute('role', 'group');
+        display.setAttribute(
+          'aria-label',
+          number ? `Scrollable equation (${number})` : 'Scrollable equation',
+        );
+      } else {
+        display.removeAttribute('tabindex');
+        display.removeAttribute('role');
+        display.removeAttribute('aria-label');
+      }
+    };
+    const equationResize = new ResizeObserver((entries) => {
+      for (const entry of entries) updateEquationScroll(entry.target as HTMLElement);
+    });
+    for (const display of root.querySelectorAll<HTMLElement>('.katex-display')) {
+      equationResize.observe(display);
+    }
+
+    window.addEventListener('hashchange', (event) => {
+      // A number form typed into the address bar of a loaded page: navigate
+      // on to the named anchor. The listeners registered after this one
+      // (sections, headings) see only that second navigation, not this one.
+      const aliased = aliasTarget(location.hash);
+      if (aliased) {
+        event.stopImmediatePropagation();
+        location.replace(`#${aliased.id}`);
+        return;
+      }
       const kind = kindForHash(location.hash);
       if (!kind) return;
       activate(document.getElementById(location.hash.slice(1)), true, kind);