explico 0.12.0 → 0.13.1

package/src/components/card-carry.ts

@@ -0,0 +1,406 @@
+/**
+ * Carrying the kept cards (rules K1–K8). With "Carry cards" on, a card the
+ * reader keeps — pinned, docked or moved — stays on screen as the page
+ * scrolls, and comes along to every page of the course.
+ *
+ * K1. Carrying is the reader's switch, "Carry cards", remembered across pages
+ * and visits. It is off until the reader turns it on, unless the course turns
+ * it on by default (`cards.carry` in the course settings, D8).
+ *
+ * K2–K4 hold a card at the window's edges: `heldAt` in
+ * `./card-placement.ts`, which the card manager (`./card-manager.ts`)
+ * applies.
+ *
+ * K5. Wherever the reader goes in the course — a link, the sidebar, search,
+ * Next and Previous, Back and Forward, a reload, a typed address — the kept
+ * cards come along. On the page a card was opened on (or last attached to,
+ * C8) it attaches to its trigger again, the same occurrence, at its place;
+ * on any other page it is rebuilt from that page, fetched
+ * (`./card-fetch.ts`, `CardSource.build`), and held at the edge it was at
+ * when the reader left, at the same place across the window. A figure's plot
+ * comes as it was drawn. A card's journey ends when it is closed; turning
+ * carrying off ends the journeys of the cards from other pages. Each tab
+ * keeps its own set (session storage), and every change also writes it as
+ * the course's last set (local storage): a tab with no set of its own — a new
+ * tab, a browser restarted without its tabs — takes the last set (D9). Card
+ * memory per page (`./card-memory.ts`) rests while carrying is on.
+ *
+ * K6 (D4). A symbol of a page's own (`notation.local`) travels under a key
+ * scoped to its page, `theta-star@projectiles/optimal-launch-angle`, so it
+ * never stands for another page's symbol of the same name. On any other
+ * page its card opens with "Defined in ‹page title› · means this only
+ * there", and its arrow to a symbol there whose entry has the same LaTeX is
+ * dashed and grey: the same letters, defined elsewhere. A shared symbol's
+ * arrow stays solid. A symbol inside a card cloned from another page opens
+ * this page's card only when both pages share its meaning
+ * (`NotationLayer.astro`).
+ *
+ * K7 (D15). While carrying is on, every kept card links back to where it
+ * was opened, beside its "Go to …": "Opened at § 2.1.1", or "Opened at
+ * (2.1.3)" when it was opened from inside a numbered equation. With
+ * carrying off a kept card stays by its trigger, so it has no such link,
+ * but where it was opened is still recorded, for a journey started later.
+ * Its arrow says where that is, as every
+ * card link's does (`./card-jump.ts`), and its tooltip says it in full:
+ * "Back to where you opened this card: Projectile Range, § 2.1.1 From launch
+ * to landing". The link is the section's (or the equation's) anchor, so it
+ * works in a new tab and without JavaScript; with it, the page scrolls to
+ * the trigger itself and flashes it, after loading when the card was opened
+ * on another page. A card opened from inside another goes back to where the
+ * outermost one was opened. Where a card was opened travels with it.
+ *
+ * K8. While carrying is on, a kept card shows, at the left of its header's
+ * buttons, whether its meaning holds on every page — a globe: shared
+ * notation, citations, abbreviations, numbered references — or only on its
+ * own page: a page and "this page", for one of that page's own symbols.
+ * Never the pin's icon. Its tooltip says which (`syncMark`).
+ *
+ * The stored set is plain JSON checked field by field on the way back
+ * (`decodeCarried`), like card memory's, so `tests/unit/card-carry.test.ts`
+ * checks it in Node.
+ */
+import {
+  createBrowserPreferenceStore,
+  createSessionPreferenceStore,
+} from '../session/PreferenceStore';
+import { decodeCard, keyOf, type RememberedCard } from './card-memory';
+import type { HoldEdge } from './card-placement';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** K1, remembered across pages and visits, for every course on this site. */
+const CARRY_KEY = 'explico:cards:carry';
+
+// The one seam for per-viewer UI preferences; this module never touches
+// browser storage itself.
+const preferences = createBrowserPreferenceStore();
+
+/** K1: whether the reader carries cards: their own choice, else the course's default. */
+export function readCarry(courseDefault: boolean): boolean {
+  const stored = preferences.get(CARRY_KEY);
+  if (stored === 'true') return true;
+  if (stored === 'false') return false;
+  return courseDefault;
+}
+
+export const writeCarry = (on: boolean): void => preferences.set(CARRY_KEY, String(on));
+
+/**
+ * What the course says about its cards, from the element `LessonFooter.astro`
+ * renders on every page: whether carrying starts on (K1), and its base path.
+ */
+export interface CardConfig {
+  readonly carry: boolean;
+  /** The course's base path, which keeps the carried sets of courses on one origin apart. */
+  readonly base: string;
+}
+
+export function readCardConfig(): CardConfig {
+  const config = document.querySelector<HTMLElement>('[data-explico-card-config]');
+  return { carry: config?.dataset.carry === 'true', base: config?.dataset.base || '/' };
+}
+
+// ---------------------------------------------------------------------------
+// K5: the carried set, pure.
+// ---------------------------------------------------------------------------
+
+/** K7: where a card was opened: the page, the place on it, and the trigger there. */
+export interface OpenedAt {
+  /** The page's path. */
+  readonly page: string;
+  /** The page's title, for the link's tooltip. */
+  readonly title: string;
+  /** The anchor the link goes to: the section's heading or the equation; `_top` before any. */
+  readonly anchor: string;
+  /**
+   * The link's short label: `§ 2.1.1`, `(2.1.3)`, `Example 1.2.1`, the
+   * section's title when it has no number, `the start` before the first
+   * section, `the notation list`.
+   */
+  readonly label: string;
+  /** The section's or the equation's own title, for the tooltip; may be empty. */
+  readonly name: string;
+  /** The trigger itself: its layer, its item, which occurrence on the page. */
+  readonly layer: string;
+  readonly item: string;
+  readonly occurrence: number;
+}
+
+/** K7: an opened-at record checked field by field; `null` for anything malformed. */
+export function decodeOpenedAt(value: unknown): OpenedAt | null {
+  if (!isRecord(value)) return null;
+  const { page, title, anchor, label, name, layer, item, occurrence } = value;
+  const strings = [title, anchor, label, name, layer, item];
+  if (typeof page !== 'string' || !page.startsWith('/')) return null;
+  if (!strings.every((field) => typeof field === 'string')) return null;
+  if (anchor === '' || label === '' || layer === '' || item === '') return null;
+  if (typeof occurrence !== 'number' || !Number.isInteger(occurrence) || occurrence < 0) return null;
+  return {
+    page,
+    title: title as string,
+    anchor: anchor as string,
+    label: label as string,
+    name: name as string,
+    layer: layer as string,
+    item: item as string,
+    occurrence,
+  };
+}
+
+/**
+ * How "Opened at" names a section heading (K7): by its number — "§ 2.1.1",
+ * "Knowledge check 2.1.1", "Example 2.1.1" — with its title as the name, or,
+ * where the course shows sections unnumbered, by its title in quotes, the way
+ * a reference to it prints (`remark-notation.mjs`).
+ */
+export function sectionPlace(
+  numbers: { readonly secNumber?: string; readonly checkNumber?: string; readonly exNumber?: string },
+  title: string,
+): { readonly label: string; readonly name: string } {
+  const { secNumber, checkNumber, exNumber } = numbers;
+  const label = secNumber
+    ? `§\u00a0${secNumber}`
+    : checkNumber
+      ? `Knowledge check\u00a0${checkNumber}`
+      : exNumber
+        ? `Example\u00a0${exNumber}`
+        : '';
+  return label ? { label, name: title } : { label: `\u201c${title}\u201d`, name: '' };
+}
+
+/**
+ * The short label and the tooltip of a card's "Opened at" link (K7): "Opened
+ * at § 2.1.1", and the page and the section's title in full. Before a page's
+ * first section, its anchor is the page's own heading (`_top`): "Opened at
+ * the start".
+ */
+export function openedAtText(at: OpenedAt): { readonly label: string; readonly title: string } {
+  const where =
+    at.anchor === '_top'
+      ? `the start of ${at.title}`
+      : `${at.title}, ${at.label}${at.name ? ` ${at.name}` : ''}`;
+  return { label: `Opened at ${at.label}`, title: `Back to where you opened this card: ${where}` };
+}
+
+/** A carried card: a remembered card (`./card-memory.ts`) that knows its page. */
+export interface CarriedCard extends RememberedCard {
+  /**
+   * The path of the page its trigger is on: where it was opened, or the page
+   * it was attached to last. Its occurrence counts there, and another page
+   * rebuilds it from there.
+   */
+  readonly page: string;
+  /** K2: the edge it is held at on another page. */
+  readonly edge: HoldEdge;
+  /** Its left edge against the article column's, where it goes across the window on another page (px). */
+  readonly dx: number;
+  /** A figure card's plot as it was drawn: an `<svg>`'s markup. */
+  readonly picture?: string;
+  /** K7: where it was opened. */
+  readonly openedAt?: OpenedAt;
+}
+
+export interface CarriedSet {
+  /** In the order they were first opened (C10, K3). */
+  readonly cards: readonly CarriedCard[];
+  /** S2: the docked card pointed at last, by its stored key. */
+  readonly pointed: string | null;
+}
+
+/** Bumped whenever the stored shape changes; a set of another version is dropped. */
+const VERSION = 1;
+
+export const EMPTY_SET: CarriedSet = { cards: [], pointed: null };
+
+/** A carried card's name in the set: its page and its key there. */
+export const carriedKeyOf = (card: Pick<CarriedCard, 'page' | 'layer' | 'item'>): string =>
+  `${card.page} ${keyOf(card)}`;
+
+export function encodeCarried(set: CarriedSet): string {
+  return JSON.stringify({ v: VERSION, cards: set.cards, pointed: set.pointed });
+}
+
+/** A picture longer than this is not carried: the card shows the page's own. */
+export const PICTURE_LIMIT = 200_000;
+
+function decodeCarriedCard(value: unknown): CarriedCard | null {
+  const card = decodeCard(value);
+  if (!card || !isRecord(value)) return null;
+  const { page, edge, dx, picture } = value;
+  const openedAt = decodeOpenedAt(value.openedAt);
+  if (typeof page !== 'string' || !page.startsWith('/')) return null;
+  if (edge !== 'top' && edge !== 'bottom') return null;
+  if (typeof dx !== 'number' || !Number.isFinite(dx)) return null;
+  return {
+    ...card,
+    page,
+    edge,
+    dx,
+    ...(typeof picture === 'string' && picture.length > 0 && picture.length <= PICTURE_LIMIT
+      ? { picture }
+      : {}),
+    ...(openedAt ? { openedAt } : {}),
+  };
+}
+
+/**
+ * The set a stored value holds, or `null` when it holds none: no value, other
+ * JSON, another version. An empty set is a set: a tab whose reader closed
+ * every card keeps it. Malformed cards are dropped one by one, and so is a
+ * card whose parent is not carried before it, on its page.
+ */
+export function decodeCarried(text: string | null): CarriedSet | null {
+  if (!text) return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(value) || value.v !== VERSION || !Array.isArray(value.cards)) return null;
+  const cards: CarriedCard[] = [];
+  const seen = new Set<string>();
+  for (const entry of value.cards) {
+    const card = decodeCarriedCard(entry);
+    if (!card || seen.has(carriedKeyOf(card))) continue;
+    if (card.parentKey !== null && !seen.has(`${card.page} ${card.parentKey}`)) continue;
+    seen.add(carriedKeyOf(card));
+    cards.push(card);
+  }
+  const pointed =
+    typeof value.pointed === 'string' && cards.some((card) => keyOf(card) === value.pointed)
+      ? value.pointed
+      : null;
+  return { cards, pointed };
+}
+
+// ---------------------------------------------------------------------------
+// The DOM layer.
+// ---------------------------------------------------------------------------
+
+// This tab's own set; the course's last set is in `preferences` (local).
+const tab = createSessionPreferenceStore();
+
+/** K7: an "Opened at" link followed to another page, which scrolls to the trigger there once it loads. */
+const JUMP_KEY = 'explico:cards:opened-at';
+
+export const stashOpenedAt = (at: OpenedAt): void => tab.set(JUMP_KEY, JSON.stringify(at));
+
+/** K7: the trigger an "Opened at" link brought the reader to this page for, once. */
+export function takeOpenedAt(): OpenedAt | null {
+  const text = tab.get(JUMP_KEY);
+  if (text === null) return null;
+  if (tab.remove) tab.remove(JUMP_KEY);
+  else tab.set(JUMP_KEY, '');
+  try {
+    return decodeOpenedAt(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** One set per course: the base keeps courses on one origin apart. */
+const setKey = (base: string) => `explico:cards:carried:${base}`;
+
+/**
+ * K5, D9: this tab's own set; a tab with none takes the course's last set,
+ * which is its own from then on.
+ */
+export function readCarried(base: string): CarriedSet {
+  const own = decodeCarried(tab.get(setKey(base)));
+  if (own) return own;
+  const last = decodeCarried(preferences.get(setKey(base))) ?? EMPTY_SET;
+  tab.set(setKey(base), encodeCarried(last));
+  return last;
+}
+
+/** K5: this tab's set, written as the course's last set too. Returns what was stored. */
+export function writeCarried(base: string, set: CarriedSet): string {
+  const text = encodeCarried(set);
+  tab.set(setKey(base), text);
+  preferences.set(setKey(base), text);
+  return text;
+}
+
+/** K5: with carrying off, nothing is carried, in this tab or the next. */
+export function forgetCarried(base: string): void {
+  for (const store of [tab, preferences]) {
+    if (store.remove) store.remove(setKey(base));
+    else store.set(setKey(base), '');
+  }
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** A card's picture: its first drawing that is not math. */
+function pictureIn(card: HTMLElement): SVGSVGElement | null {
+  for (const svg of card.querySelectorAll<SVGSVGElement>('[data-panel-content] svg')) {
+    if (!svg.closest('.katex') && !svg.parentElement?.closest('svg')) return svg;
+  }
+  return null;
+}
+
+/** K5: a figure card's plot as it is drawn now, to carry; `undefined` for any other card. */
+export function capturePicture(card: HTMLElement): string | undefined {
+  if (!card.hasAttribute('data-panel-picture')) return undefined;
+  const markup = pictureIn(card)?.outerHTML;
+  return markup && markup.length <= PICTURE_LIMIT ? markup : undefined;
+}
+
+let pictureSerial = 0;
+
+/**
+ * K5: put a carried plot back in a card rebuilt from its page, in place of
+ * the picture the page's build drew. Only an inert `<svg>` comes back: no
+ * script, no foreign content, no handler, no link off the drawing, and ids of
+ * its own, so it never collides with this page's.
+ */
+export function restorePicture(card: HTMLElement, markup: string): void {
+  // Parsed as HTML, as `outerHTML` wrote it: an `<svg>` there has no
+  // `xmlns`, and the HTML parser puts it in the SVG namespace. The parsed
+  // document is inert: nothing in it runs.
+  const parsed = new DOMParser().parseFromString(markup, 'text/html');
+  const svg = parsed.body.firstElementChild;
+  if (!svg || svg.namespaceURI !== SVG_NS || svg.localName !== 'svg') return;
+  if (parsed.body.childElementCount !== 1) return;
+  const banned = new Set(['script', 'foreignObject', 'iframe', 'object', 'embed', 'animate', 'set']);
+  const prefix = `carried-${++pictureSerial}-`;
+  const ids = new Map<string, string>();
+  for (const el of [svg, ...Array.from(svg.querySelectorAll('*'))]) {
+    if (banned.has(el.localName)) {
+      el.remove();
+      continue;
+    }
+    for (const attribute of Array.from(el.attributes)) {
+      const name = attribute.name.toLowerCase();
+      const isLink = name === 'href' || name === 'xlink:href';
+      if (name.startsWith('on') || (isLink && !attribute.value.startsWith('#'))) {
+        el.removeAttribute(attribute.name);
+      }
+    }
+    if (el.id) {
+      ids.set(el.id, `${prefix}${el.id}`);
+      el.id = `${prefix}${el.id}`;
+    }
+  }
+  if (ids.size > 0) {
+    for (const el of [svg, ...Array.from(svg.querySelectorAll('*'))]) {
+      for (const attribute of Array.from(el.attributes)) {
+        const value = attribute.value.replace(
+          /url\(#([^)]+)\)|^#(.+)$/g,
+          (whole, inUrl?: string, bare?: string) => {
+            const id = ids.get(inUrl ?? bare ?? '');
+            if (!id) return whole;
+            return inUrl ? `url(#${id})` : `#${id}`;
+          },
+        );
+        if (value !== attribute.value) el.setAttribute(attribute.name, value);
+      }
+    }
+  }
+  const node = document.importNode(svg, true);
+  const target = pictureIn(card);
+  if (target) target.replaceWith(node);
+  else card.querySelector('[data-panel-content]')?.append(node);
+}

package/src/components/card-drag.ts

@@ -21,7 +21,7 @@
  * where they go once dropped.
  */
 import { moveTo } from './card-placement';
-import { headerBottom, railLeftEdge, remToPx } from './card-side';
+import { headerBottom, sidebarsBetween } from './card-side';
 import type { Box, Point } from './card-travel';
 
 const clamp = (value: number, low: number, high: number) =>
@@ -207,35 +207,6 @@ export const movedAt = (spot: MovedSpot, columnLeft: number, lineTop: number): P
 // The DOM layer.
 // ---------------------------------------------------------------------------
 
-/**
- * The navigation's right edge: collapsed, its edge strip's, since the panel
- * itself widens over the article while it peeks. `null` without a visible
- * navigation (a phone, a page without one).
- */
-function navigationRightEdge(): number | null {
-  const pane = document.querySelector<HTMLElement>('.sidebar-pane');
-  if (!pane || pane.getClientRects().length === 0) return null;
-  if (getComputedStyle(pane).visibility === 'hidden') return null;
-  const rect = pane.getBoundingClientRect();
-  if (rect.width === 0) return null;
-  const root = document.documentElement;
-  if (root.hasAttribute('data-navigation-hidden')) {
-    const strip = getComputedStyle(root).getPropertyValue('--layout-edge-rail-width').trim();
-    const width = strip ? remToPx(strip) : Number.NaN;
-    if (Number.isFinite(width) && width > 0) return rect.left + width;
-  }
-  return rect.right;
-}
-
-/** D2: the room between the navigation and the rail, each `edge` px away, in viewport x. */
-export function sidebarsBetween(edge: number): Between {
-  const nav = navigationRightEdge();
-  return {
-    left: (nav ?? 0) + edge,
-    right: railLeftEdge() - edge,
-  };
-}
-
 /** D1, D2: where a dragged card may go: between the sidebars, below the header, inside the window. */
 export function dragBounds(edge: number): DragBounds {
   return {

package/src/components/card-fetch.ts

@@ -0,0 +1,87 @@
+/**
+ * Another page of the course, fetched and parsed once, for a card built from
+ * it: a cross-page reference's preview (`reference/FloatRefLayer.astro`), and
+ * every carried card rebuilt on a page other than the one it was opened on
+ * (rule K5, `./card-carry.ts`). Every card layer builds from the same cache.
+ */
+
+/**
+ * Parsed pages, keyed by path. A page is fetched once and reused for every
+ * later card on this page; a failed fetch drops its entry so a later card can
+ * retry.
+ */
+const pageCache = new Map<string, Promise<Document>>();
+
+/** A path as a page, whatever its trailing slash or `index.html`. */
+export const pagePath = (path: string): string =>
+  path.replace(/\/index\.html$/, '/').replace(/\/+$/, '') || '/';
+
+/** Whether `page` is the page the reader is on. */
+export const isThisPage = (page: string): boolean =>
+  pagePath(page) === pagePath(window.location.pathname);
+
+/** `page`, parsed; this page is its own document and is never fetched. */
+export function fetchDoc(page: string): Promise<Document> {
+  if (isThisPage(page)) return Promise.resolve(document);
+  let pending = pageCache.get(page);
+  if (!pending) {
+    pending = fetch(page, { credentials: 'same-origin' })
+      .then((response) => {
+        if (!response.ok) throw new Error(`${response.status} for ${page}`);
+        return response.text();
+      })
+      .then((html) => new DOMParser().parseFromString(html, 'text/html'))
+      .catch((error: unknown) => {
+        pageCache.delete(page);
+        throw error;
+      });
+    pageCache.set(page, pending);
+  }
+  return pending;
+}
+
+/**
+ * A card cloned from another page may hold math, which needs KaTeX's
+ * stylesheet. Every page that authors math already loads it; this only
+ * matters for a page without math of its own, so copy the `<link>` from the
+ * fetched document when this one has none.
+ */
+export function ensureKatexStylesheet(sourceDoc: Document): void {
+  const selector = 'link[rel="stylesheet"][href*="katex"]';
+  if (document.querySelector(selector)) return;
+  const link = sourceDoc.querySelector<HTMLLinkElement>(selector);
+  if (link) document.head.appendChild(document.importNode(link, true));
+}
+
+/** A page's title, as its own heading shows it. */
+export const pageTitleOf = (doc: Document): string | undefined =>
+  doc.getElementById('_top')?.textContent?.replace(/\s+/g, ' ').trim() || undefined;
+
+/** A link read off `page`, usable from any page: a fragment gets the page's path. */
+export const hrefFrom = (href: string, page: string): string =>
+  href.startsWith('#') ? `${page}${href}` : href;
+
+/** The route slug a page's own symbols are scoped by (`NotationLayer.astro`), or `''`. */
+export const notationPageOf = (doc: Document): string =>
+  [...doc.querySelectorAll<HTMLElement>('[data-notation-page]')]
+    .map((layer) => layer.dataset.notationPage ?? '')
+    .find(Boolean) ?? '';
+
+/**
+ * K6: `el`, a card built from `doc`, the page at `page`, is that page's, and
+ * a symbol in it means what it means there. Says so on the card
+ * (`data-card-foreign`), with the page it came from (`data-card-from`) and
+ * that page's notation slug (`data-card-from-slug`), and marks each symbol
+ * in it with its scope there (`data-notation-scope`).
+ */
+export function markForeign(el: HTMLElement, doc: Document, page: string): void {
+  el.setAttribute('data-card-foreign', '');
+  el.dataset.cardFrom = page;
+  el.dataset.cardFromSlug = notationPageOf(doc);
+  for (const symbol of el.querySelectorAll<HTMLElement>('[data-notation-key]')) {
+    const there = doc.querySelector<HTMLElement>(
+      `[data-notation-entry="${CSS.escape(symbol.dataset.notationKey ?? '')}"]`,
+    );
+    symbol.dataset.notationScope = there?.dataset.notationScope ?? 'shared';
+  }
+}