explico 0.7.0 → 0.11.0

package/src/components/block-heading.ts

@@ -0,0 +1,146 @@
+/**
+ * The heading a knowledge check and a worked-example set draw for themselves
+ * (docs/plans/titles-and-containers.md Part 6, Q11). The author writes only
+ * the topic; the engine draws the *kind* before it — an icon and, by
+ * default, its word — and the number, which shows and hides by the section
+ * rules. `BlockHeading.astro` renders it; `LayoutPageSidebar.astro` lists it
+ * in "On this page" through {@link tocWithTitledBlocks}.
+ */
+import {
+  BLOCK_LABELS_DEFAULT,
+  type BlockLabels,
+} from '../compiler/course-config';
+import {
+  loadManifest,
+  type Manifest,
+  type ManifestTitledBlock,
+} from '../compiler/manifest';
+
+export type BlockKind = ManifestTitledBlock['kind'];
+
+export const BLOCK_KINDS: Readonly<
+  Record<BlockKind, { readonly word: string; readonly numberAttribute: string }>
+> = {
+  // `data-check-number` / `data-ex-number` beside the heading's `id` is what
+  // a number-form fragment (`#ex-1.1.1`) resolves against
+  // (`KeyedFloatEnhancer.astro`), and what the chain icon's "Link copied ·
+  // Example 1.1.1" reads (`HeadingAnchorEnhancer.astro`).
+  check: { word: 'Knowledge check', numberAttribute: 'data-check-number' },
+  example: { word: 'Example', numberAttribute: 'data-ex-number' },
+};
+
+export interface BlockHeadingSettings {
+  /** The course's badge form (`blockLabels`). */
+  readonly labels: BlockLabels;
+  /** Whether numbers show at all (`numbering.sections.show`). */
+  readonly showNumbers: boolean;
+}
+
+// Read once per build, like `courseDisclosure()`: every check, every example
+// set and every page's "On this page" asks, and the manifest does not change
+// under a running build (a content edit in dev restarts Astro).
+let cached: Promise<Manifest> | undefined;
+const manifestOnce = (): Promise<Manifest> => (cached ??= loadManifest());
+
+/** The course's badge form and number visibility. */
+export async function blockHeadingSettings(): Promise<BlockHeadingSettings> {
+  const manifest = await manifestOnce();
+  return {
+    labels: manifest.blockLabels ?? BLOCK_LABELS_DEFAULT,
+    showNumbers: manifest.numbering?.sections?.show !== false,
+  };
+}
+
+/** A lesson's titled blocks (`manifest.lessons[].titledBlocks`), by its id. */
+export async function titledBlocksOf(
+  lessonId: string,
+): Promise<readonly ManifestTitledBlock[]> {
+  const lesson = (await manifestOnce()).lessons.find((entry) => entry.id === lessonId);
+  return lesson?.titledBlocks ?? [];
+}
+
+/** A heading as Astro and Starlight list it (`MarkdownHeading`). */
+export interface OutlineHeading {
+  readonly depth: number;
+  readonly slug: string;
+  readonly text: string;
+}
+
+/** One "On this page" entry (Starlight's `TocItem`). */
+export interface TocItem extends OutlineHeading {
+  children: TocItem[];
+}
+
+/**
+ * A page's headings with its titled blocks' `<h2>`s put in: each right after
+ * the top-level heading it follows (`after`), or ahead of every heading when
+ * it follows none. Blocks after one heading keep their document order; one
+ * whose heading the page does not list goes at the end. The entry is the
+ * author's title alone, as a section's is — the badge, like a section's
+ * number, is the engine's; `LayoutPageSidebar.astro` draws the badge's icon
+ * before it.
+ */
+export function withTitledBlocks(
+  headings: readonly OutlineHeading[],
+  blocks: readonly ManifestTitledBlock[],
+): OutlineHeading[] {
+  const asHeading = (block: ManifestTitledBlock): OutlineHeading => ({
+    depth: 2,
+    slug: block.anchor,
+    text: block.title,
+  });
+  const leading: OutlineHeading[] = [];
+  const byAfter = new Map<string, OutlineHeading[]>();
+  for (const block of blocks) {
+    if (block.after === undefined) {
+      leading.push(asHeading(block));
+    } else {
+      const list = byAfter.get(block.after) ?? [];
+      list.push(asHeading(block));
+      byAfter.set(block.after, list);
+    }
+  }
+  const out = [...leading];
+  for (const heading of headings) {
+    out.push(heading);
+    out.push(...(byAfter.get(heading.slug) ?? []));
+    byAfter.delete(heading.slug);
+  }
+  for (const rest of byAfter.values()) out.push(...rest);
+  return out;
+}
+
+/**
+ * Starlight's "On this page" tree rebuilt with the titled blocks in it: the
+ * same nesting `generateToC` does (`@astrojs/starlight/utils/generateToC.ts`)
+ * — its first item, the page-title "Overview", kept as it was, and every
+ * heading in the level range nested under the last shallower one. A
+ * component draws these `<h2>`s, so Astro's heading list never had them
+ * (audit §8.7). Returns `items` unchanged when the first item is not the
+ * overview Starlight puts there.
+ */
+export function tocWithTitledBlocks(
+  toc: {
+    readonly minHeadingLevel: number;
+    readonly maxHeadingLevel: number;
+    readonly items: readonly TocItem[];
+  },
+  headings: readonly OutlineHeading[],
+  blocks: readonly ManifestTitledBlock[],
+): TocItem[] {
+  const [overview] = toc.items;
+  if (blocks.length === 0 || overview?.slug !== '_top') return [...toc.items];
+  const items: TocItem[] = [{ ...overview, children: [] }];
+  const inject = (list: TocItem[], item: TocItem): void => {
+    const last = list.at(-1);
+    if (!last || last.depth >= item.depth) list.push(item);
+    else inject(last.children, item);
+  };
+  for (const heading of withTitledBlocks(headings, blocks)) {
+    if (heading.depth < toc.minHeadingLevel || heading.depth > toc.maxHeadingLevel) {
+      continue;
+    }
+    inject(items, { ...heading, children: [] });
+  }
+  return items;
+}

package/src/components/card-arrow.ts

@@ -0,0 +1,243 @@
+/**
+ * The arrow from a kept card to an occurrence of its item (rule S5 of
+ * `docs/plans/hover-card-consistency.md`).
+ *
+ * A pinned or docked card can sit far from the place the reader is pointing
+ * at: another occurrence of its symbol, or — for a card in the side column —
+ * its own trigger. The arrow leaves the card's edge on the side facing that
+ * occurrence, arcs over the occurrence's line and ends on it with an
+ * arrowhead. It stays while the occurrence or the card is hovered or focused,
+ * and fades a while after both are left.
+ *
+ * `arrowShape` is the geometry, pure, over plain boxes, so
+ * `tests/unit/card-arrow.test.ts` can check it in Node. The overlay is one
+ * SVG at the bottom of the card layer (`./card-placement.ts`): above the
+ * article, below every card, in page coordinates, so it scrolls with both.
+ */
+import type { Box, Point } from './card-travel';
+
+const clamp = (value: number, low: number, high: number) =>
+  Math.max(low, Math.min(value, high));
+
+/** The arrowhead's length and half its width (px). */
+const HEAD_LENGTH = 8;
+const HEAD_HALF_WIDTH = 4.5;
+
+export interface ArrowShape {
+  /** Where the line leaves the card. */
+  readonly start: Point;
+  /** The two control points of the line's cubic curve. */
+  readonly controls: readonly [Point, Point];
+  /** Where the line meets the arrowhead. */
+  readonly neck: Point;
+  /** The arrowhead's point: on the occurrence's top edge. */
+  readonly tip: Point;
+  /** The line, as an SVG path. */
+  readonly path: string;
+  /** The arrowhead, as SVG polygon points. */
+  readonly head: string;
+}
+
+const format = (value: number) => String(Math.round(value * 10) / 10);
+
+/**
+ * S5: from `card`'s edge to the top of `target`, the occurrence's box on its
+ * first line. The line leaves the card on the side facing the occurrence, and
+ * its last stretch comes straight down onto the occurrence, so the arc passes
+ * over the occurrence's line instead of through it.
+ */
+export function arrowShape(card: Box, target: Box): ArrowShape {
+  const tip = { x: (target.left + target.right) / 2, y: target.top - 1 };
+  const leftward = tip.x < (card.left + card.right) / 2;
+  // Leave level with the occurrence's line where the card allows it, clear
+  // of its rounded corners. A side card's top is 14 px above its line (S2),
+  // so this starts at or above the line's top, never through its text.
+  const inset = Math.min(12, (card.bottom - card.top) / 2);
+  const start = {
+    x: leftward ? card.left : card.right,
+    y: clamp(tip.y, card.top + inset, card.bottom - inset),
+  };
+  const reach = Math.abs(start.x - tip.x);
+  const lift = clamp(reach * 0.2, 20, 48);
+  const out = leftward ? -1 : 1;
+  const controls: [Point, Point] = [
+    {
+      x: start.x + out * Math.max(24, reach * 0.4),
+      // An occurrence level with or above the start: arc over it. One below:
+      // leave level, then come down onto it.
+      y: tip.y <= start.y ? tip.y - lift : start.y,
+    },
+    { x: tip.x, y: tip.y - lift },
+  ];
+  const neck = { x: tip.x, y: tip.y - HEAD_LENGTH + 1 };
+  const [c1, c2] = controls;
+  return {
+    start,
+    controls,
+    neck,
+    tip,
+    path:
+      `M ${format(start.x)} ${format(start.y)} ` +
+      `C ${format(c1.x)} ${format(c1.y)} ${format(c2.x)} ${format(c2.y)} ` +
+      `${format(neck.x)} ${format(neck.y)}`,
+    head: [
+      [tip.x, tip.y],
+      [tip.x - HEAD_HALF_WIDTH, tip.y - HEAD_LENGTH],
+      [tip.x + HEAD_HALF_WIDTH, tip.y - HEAD_LENGTH],
+    ]
+      .map(([x, y]) => `${format(x)},${format(y)}`)
+      .join(' '),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The overlay.
+// ---------------------------------------------------------------------------
+
+export interface ArrowOverlay {
+  /** Draw the arrow from `card` to `target`, replacing any other. */
+  show(card: HTMLElement, target: HTMLElement): void;
+  /** Draw it again after the card or the occurrence moved. */
+  redraw(): void;
+  /**
+   * The pointer or focus reached `node`: on the card or the occurrence, the
+   * arrow stays; anywhere else, it fades a while later.
+   */
+  follow(node: EventTarget | null): void;
+  /** The pointer or focus left both: fade a while later, unless one is hovered or focused by then. */
+  release(): void;
+  /** Take the arrow away now. */
+  hide(): void;
+  /** The card the arrow runs from, if one is shown. */
+  readonly card: HTMLElement | null;
+}
+
+export interface ArrowOverlayOptions {
+  /** The card layer; the arrow mounts at its bottom. */
+  layer(): HTMLElement;
+  /** S5: how long the arrow stays after the card and the occurrence are left (ms). */
+  readonly holdMs: number;
+  /** How long it takes to fade out (ms); not at all under reduced motion. */
+  readonly fadeMs: number;
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+const reducedMotion = () => window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+const hovered = (el: Element) => el.matches(':hover');
+
+const focused = (el: Element) =>
+  el.matches(':focus-visible') || el.querySelector(':focus-visible') !== null;
+
+export function createArrowOverlay(options: ArrowOverlayOptions): ArrowOverlay {
+  let svg: SVGSVGElement | null = null;
+  let line: SVGPathElement | null = null;
+  let head: SVGPolygonElement | null = null;
+  let from: HTMLElement | null = null;
+  let to: HTMLElement | null = null;
+  let holdTimer: ReturnType<typeof setTimeout> | null = null;
+  let fadeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearTimers = () => {
+    if (holdTimer !== null) clearTimeout(holdTimer);
+    if (fadeTimer !== null) clearTimeout(fadeTimer);
+    holdTimer = null;
+    fadeTimer = null;
+  };
+
+  const mount = () => {
+    if (!svg) {
+      svg = document.createElementNS(SVG_NS, 'svg');
+      svg.classList.add('explico-card-arrow');
+      svg.setAttribute('aria-hidden', 'true');
+      // A zero-size box at the layer's origin: the drawing overflows it in
+      // page coordinates, and never takes a click.
+      svg.style.cssText =
+        'position:absolute;left:0;top:0;width:1px;height:1px;overflow:visible;pointer-events:none;z-index:0';
+      line = document.createElementNS(SVG_NS, 'path');
+      line.classList.add('explico-card-arrow-line');
+      head = document.createElementNS(SVG_NS, 'polygon');
+      head.classList.add('explico-card-arrow-head');
+      svg.append(line, head);
+    }
+    const layer = options.layer();
+    if (svg.parentElement !== layer || layer.firstChild !== svg) layer.prepend(svg);
+    return svg;
+  };
+
+  const hide = () => {
+    clearTimers();
+    from = null;
+    to = null;
+    svg?.remove();
+    svg?.classList.remove('is-fading');
+  };
+
+  const draw = () => {
+    if (!from || !to) return;
+    const box = to.getClientRects()[0];
+    if (!from.isConnected || !to.isConnected || !box) {
+      hide();
+      return;
+    }
+    const layer = options.layer();
+    const origin = layer.getBoundingClientRect();
+    const shift = (rect: Box): Box => ({
+      left: rect.left - origin.left,
+      top: rect.top - origin.top,
+      right: rect.right - origin.left,
+      bottom: rect.bottom - origin.top,
+    });
+    const shape = arrowShape(shift(from.getBoundingClientRect()), shift(box));
+    mount();
+    line?.setAttribute('d', shape.path);
+    head?.setAttribute('points', shape.head);
+    if (svg) svg.dataset.cardArrow = from.dataset.cardKey ?? '';
+  };
+
+  const fade = () => {
+    holdTimer = null;
+    if (!from || !to) return;
+    // Still on the card or the occurrence: keep it until they are left again.
+    if (hovered(from) || hovered(to) || focused(from) || focused(to)) return;
+    if (reducedMotion() || !svg) {
+      hide();
+      return;
+    }
+    svg.classList.add('is-fading');
+    fadeTimer = setTimeout(hide, options.fadeMs);
+  };
+
+  const hold = () => {
+    clearTimers();
+    svg?.classList.remove('is-fading');
+  };
+
+  const release = () => {
+    if (!from || holdTimer !== null) return;
+    if (fadeTimer !== null) return; // already on its way out
+    holdTimer = setTimeout(fade, options.holdMs);
+  };
+
+  return {
+    show(card, target) {
+      hold();
+      from = card;
+      to = target;
+      draw();
+    },
+    redraw: draw,
+    follow(node) {
+      if (!from || !to) return;
+      const on = node instanceof Node && (from.contains(node) || to.contains(node));
+      if (on) hold();
+      else release();
+    },
+    release,
+    hide,
+    get card() {
+      return from;
+    },
+  };
+}