explico 0.7.0 → 0.11.0

package/src/components/card-side.ts

@@ -0,0 +1,336 @@
+/**
+ * The side column (rules S1–S10 of `docs/plans/hover-card-consistency.md`).
+ *
+ * A kept card can sit to the right of the article, level with its trigger's
+ * line, instead of next to the trigger. The room comes from sliding the
+ * article left — only while side cards are open, only as far as they need,
+ * and at most to the navigation's edge — never from covering the "On this
+ * page" rail. When even a fully left-aligned article leaves too little room,
+ * there is no side column (S7).
+ *
+ * The geometry is pure (`sideColumn`, `layoutColumn`) over numbers measured
+ * with the article at rest, so `tests/unit/card-side.test.ts` checks it in
+ * Node against the measured playground. The DOM half measures the page
+ * (`measureSide`), slides the article (`slideArticle`) and runs the "Keep
+ * the article left" toggle (S9). The card manager (`./card-manager.ts`)
+ * decides when any of it happens.
+ */
+import { createBrowserPreferenceStore } from '../session/PreferenceStore';
+
+/** Rounding slack for comparing measured, fractional pixel positions. */
+const EPSILON = 0.5;
+
+const clamp = (value: number, low: number, high: number) =>
+  Math.max(low, Math.min(value, high));
+
+// ---------------------------------------------------------------------------
+// The geometry, pure.
+// ---------------------------------------------------------------------------
+
+/** What the side column needs from the page, measured with the article at rest (not slid). */
+export interface SideMeasure {
+  /** The article's right text edge, at rest. */
+  readonly restRight: number;
+  /**
+   * How far the article can slide left: its start margin at rest. Slid that
+   * far, it starts at the navigation's edge plus the content padding.
+   */
+  readonly maxSlide: number;
+  /** The rail's left edge, open or collapsed to its strip; the window's right edge without one. */
+  readonly railLeft: number;
+}
+
+export interface SideOptions {
+  /** S1: from the article's text edge to a side card, and from a side card to the rail. */
+  readonly gap: number;
+  /** S1: the narrowest and the widest a side card gets. */
+  readonly minWidth: number;
+  readonly maxWidth: number;
+}
+
+export interface SideColumn extends SideMeasure {
+  /** S1: the room between the fully left-aligned article and the rail, both gaps taken off. */
+  readonly room: number;
+  /** S1: a side card's width: all the room, up to the widest. */
+  readonly width: number;
+  /** S3: how far the article slides from rest to fit a side card: only as far as it needs. */
+  readonly slide: number;
+}
+
+/** S1, S3, S7: the side column, or `null` when even a fully left-aligned article leaves too little room. */
+export function sideColumn(measure: SideMeasure, options: SideOptions): SideColumn | null {
+  const maxSlide = Math.max(0, measure.maxSlide);
+  const room =
+    measure.railLeft - options.gap - (measure.restRight - maxSlide) - options.gap;
+  if (room < options.minWidth - EPSILON) return null;
+  const width = Math.min(options.maxWidth, room);
+  const slide = clamp(
+    measure.restRight + options.gap + width + options.gap - measure.railLeft,
+    0,
+    maxSlide,
+  );
+  return { ...measure, maxSlide, room, width, slide };
+}
+
+/** The side column's left edge with the article slid `slide` px left of rest. */
+export const columnLeft = (measure: SideMeasure, slide: number, gap: number): number =>
+  measure.restRight - slide + gap;
+
+/** The room between the article and the rail, both gaps taken off, with the article slid `slide` px. */
+export const roomAt = (measure: SideMeasure, slide: number, gap: number): number =>
+  measure.railLeft - gap - columnLeft(measure, slide, gap);
+
+/** A vertical stretch of the column, in page coordinates. */
+export interface Span {
+  readonly top: number;
+  readonly bottom: number;
+}
+
+export interface ColumnEntry {
+  readonly key: string;
+  /** Level with its trigger's line (S2); `null` when the trigger has no box, and the card stays at `top`. */
+  readonly ideal: number | null;
+  /** Where the card is now. */
+  readonly top: number;
+  readonly height: number;
+}
+
+export interface ColumnLayoutOptions {
+  /** The card being pointed at: it gets its ideal spot before the others (S2). */
+  readonly first?: string | null;
+  /** The gap between two cards stacked in the column. */
+  readonly gap: number;
+  /** No card goes above this: the sticky header at the top of the page. */
+  readonly minTop: number;
+  /** Other cards in the column's way, which do not move. */
+  readonly obstacles?: readonly Span[];
+}
+
+/**
+ * S2: every side card level with its trigger's line. Overlaps resolve top
+ * down — the lower card moves down. The card being pointed at takes its
+ * ideal spot first; a card whose line is above it then moves up out of its
+ * way, the mirror of the rule, so the column keeps the order of the lines.
+ * Returns each card's top.
+ */
+export function layoutColumn(
+  entries: readonly ColumnEntry[],
+  options: ColumnLayoutOptions,
+): Map<string, number> {
+  const { gap, minTop } = options;
+  const taken: Span[] = [...(options.obstacles ?? [])];
+  const tops = new Map<string, number>();
+
+  const clashes = (top: number, height: number, span: Span) =>
+    top < span.bottom + gap - EPSILON && top + height + gap > span.top + EPSILON;
+  /** The first top at or below `want` that keeps `gap` from everything taken. */
+  const fitDown = (want: number, height: number) => {
+    let top = want;
+    for (let moved = true; moved; ) {
+      moved = false;
+      for (const span of taken) {
+        if (clashes(top, height, span)) {
+          top = span.bottom + gap;
+          moved = true;
+        }
+      }
+    }
+    return top;
+  };
+  /** The first top at or above `want` that keeps `gap` from everything taken, if one is below `minTop`. */
+  const fitUp = (want: number, height: number) => {
+    let top = want;
+    for (let moved = true; moved && top >= minTop - EPSILON; ) {
+      moved = false;
+      for (const span of taken) {
+        if (clashes(top, height, span)) {
+          top = span.top - gap - height;
+          moved = true;
+        }
+      }
+    }
+    return top >= minTop - EPSILON ? top : null;
+  };
+  const put = (entry: ColumnEntry, top: number) => {
+    tops.set(entry.key, top);
+    taken.push({ top, bottom: top + entry.height });
+  };
+  const want = (entry: ColumnEntry) => Math.max(entry.ideal ?? entry.top, minTop);
+
+  // A card whose trigger has no box has no line to follow: it stays.
+  for (const entry of entries) if (entry.ideal === null) put(entry, entry.top);
+  const lined = entries.filter((entry) => entry.ideal !== null);
+  const first = lined.find((entry) => entry.key === options.first);
+  const rest = lined.filter((entry) => entry !== first).sort((a, b) => want(a) - want(b));
+  if (first) {
+    put(first, fitDown(want(first), first.height));
+    // Above the pointed card, nearest first: up out of its way, or, with no
+    // room left above, down past it.
+    for (const entry of rest.filter((e) => want(e) < want(first)).reverse()) {
+      put(entry, fitUp(want(entry), entry.height) ?? fitDown(want(entry), entry.height));
+    }
+  }
+  for (const entry of rest.filter((e) => !first || want(e) >= want(first))) {
+    put(entry, fitDown(want(entry), entry.height));
+  }
+  return tops;
+}
+
+// ---------------------------------------------------------------------------
+// The DOM layer.
+// ---------------------------------------------------------------------------
+
+/** Set on `<html>` while the article is slid; `global.css` reads it with the start margin below. */
+const SLID_ATTRIBUTE = 'data-article-slid';
+/** The article's start margin while slid, which `global.css` hands to `--sl-content-margin-inline`. */
+const START_PROPERTY = '--explico-article-start';
+/** S9, remembered across pages and visits. */
+const KEEP_LEFT_KEY = 'explico:layout:keep-article-left';
+/** S7: below this there is never a side column, the same breakpoint Starlight drops the rail at. */
+const SIDE_QUERY = '(min-width: 72rem)';
+
+const root = () => document.documentElement;
+
+/** The article's text column on this page: the main pane's, never a card's or an overlay's copy. */
+const articleOf = () => document.querySelector<HTMLElement>('.main-pane .sl-markdown-content');
+
+/** The boxes that move when the article slides: the title's and the article's containers. */
+export const articleContainers = (): HTMLElement[] => [
+  ...document.querySelectorAll<HTMLElement>('.main-pane .sl-container'),
+];
+
+/** The article's left text edge where it is now, or `null` when the page has none. */
+export function articleLeft(): number | null {
+  const rect = articleOf()?.getBoundingClientRect();
+  return rect && rect.width > 0 ? rect.left : null;
+}
+
+/** The top of the first line a trigger sits on, or `null` when it has no box. */
+export function lineTopOf(trigger: HTMLElement): number | null {
+  if (!trigger.isConnected) return null;
+  const rect = trigger.getClientRects()[0];
+  return rect ? rect.top : null;
+}
+
+/** The sticky header's bottom edge. */
+export function headerBottom(): number {
+  return document.querySelector<HTMLElement>('.header')?.getBoundingClientRect().bottom ?? 0;
+}
+
+/** A CSS length in `rem` (the constants' `18rem`, `23rem`) as pixels. */
+export function remToPx(length: string): number {
+  const size = Number.parseFloat(getComputedStyle(root()).fontSize) || 16;
+  return Number.parseFloat(length) * (length.trim().endsWith('rem') ? size : 1);
+}
+
+/**
+ * The rail's left edge. Collapsed, it is the strip's edge: the rail itself
+ * widens over the article while it peeks, which is no reason to move a card.
+ */
+export function railLeftEdge(): number {
+  const windowRight = root().clientWidth;
+  const rail = document.querySelector<HTMLElement>('.right-sidebar');
+  if (!rail || rail.getClientRects().length === 0) return windowRight;
+  if (root().hasAttribute('data-page-sidebar-hidden')) {
+    const strip = document
+      .querySelector<HTMLElement>('.right-sidebar-container')
+      ?.getBoundingClientRect();
+    if (strip && strip.width > 0) return strip.left;
+  }
+  const rect = rail.getBoundingClientRect();
+  return rect.width > 0 ? rect.left : windowRight;
+}
+
+/**
+ * S1, S3, S7: the article and the rail, measured with the article at rest.
+ * `null` when the layout can never have a side column: below 72rem, a
+ * right-to-left page, or a page without an article.
+ */
+export function measureSide(): SideMeasure | null {
+  if (!window.matchMedia(SIDE_QUERY).matches) return null;
+  if (getComputedStyle(root()).direction === 'rtl') return null;
+  const article = articleOf();
+  const container = article?.closest<HTMLElement>('.sl-container');
+  if (!article || !container) return null;
+  // Measure at rest: lift the slide for the length of two reads. Nothing is
+  // painted in between.
+  const slid = root().hasAttribute(SLID_ATTRIBUTE);
+  if (slid) root().removeAttribute(SLID_ATTRIBUTE);
+  const rect = article.getBoundingClientRect();
+  const margin = Number.parseFloat(getComputedStyle(container).marginInlineStart) || 0;
+  if (slid) root().setAttribute(SLID_ATTRIBUTE, '');
+  if (rect.width === 0) return null;
+  return { restRight: rect.right, maxSlide: Math.max(0, margin), railLeft: railLeftEdge() };
+}
+
+/**
+ * S3: slide the article `slide` px left of where it rests, through its start
+ * margin (`--sl-content-margin-inline` on `.main-pane`, in `global.css`);
+ * `.main-pane`'s width and the rail stay put. `0` gives the margin back to
+ * Starlight, which then follows resizes on its own again.
+ */
+export function slideArticle(slide: number, maxSlide: number): void {
+  if (slide < EPSILON) {
+    root().removeAttribute(SLID_ATTRIBUTE);
+    root().style.removeProperty(START_PROPERTY);
+    return;
+  }
+  root().style.setProperty(START_PROPERTY, `${Math.max(0, maxSlide - slide)}px`);
+  root().setAttribute(SLID_ATTRIBUTE, '');
+}
+
+// The one seam for per-viewer UI preferences; this module never touches
+// browser storage itself.
+const preferences = createBrowserPreferenceStore();
+
+/** S9: whether the reader asked to keep the article left. Off by default. */
+export const readKeepLeft = (): boolean => preferences.get(KEEP_LEFT_KEY) === 'true';
+
+export const writeKeepLeft = (on: boolean): void => preferences.set(KEEP_LEFT_KEY, String(on));
+
+export interface KeepLeftToggle {
+  /** Show the toggle at the top of the side column (`left`, in viewport x), or hide it. */
+  update(state: { readonly visible: boolean; readonly on: boolean; readonly left: number }): void;
+}
+
+/**
+ * S9: "Keep the article left", a small toggle at the top of the side column,
+ * fixed just under the site header. It mounts right after the card layer,
+ * so it sits over the cards scrolling past and under the header.
+ */
+export function createKeepLeftToggle(
+  after: () => HTMLElement,
+  onToggle: (on: boolean) => void,
+): KeepLeftToggle {
+  let button: HTMLButtonElement | null = null;
+
+  const build = () => {
+    const el = document.createElement('button');
+    el.type = 'button';
+    el.className = 'explico-keep-left';
+    el.dataset.keepArticleLeft = '';
+    el.title = 'Keep the article on the left after the last side card closes';
+    el.setAttribute('aria-pressed', 'false');
+    const knob = document.createElement('span');
+    knob.className = 'explico-keep-left-switch';
+    knob.setAttribute('aria-hidden', 'true');
+    const label = document.createElement('span');
+    label.textContent = 'Keep the article left';
+    el.append(knob, label);
+    el.addEventListener('click', () => onToggle(el.getAttribute('aria-pressed') !== 'true'));
+    return el;
+  };
+
+  return {
+    update({ visible, on, left }) {
+      if (!visible && !button) return;
+      if (!button?.isConnected) {
+        button = build();
+        after().after(button);
+      }
+      button.hidden = !visible;
+      button.setAttribute('aria-pressed', String(on));
+      if (visible) button.style.left = `${Math.round(left)}px`;
+    },
+  };
+}

package/src/components/card-travel.ts

@@ -0,0 +1,197 @@
+/**
+ * The travel zone (rule C2 of `docs/plans/hover-card-consistency.md`).
+ *
+ * A card opens next to its trigger, but rarely touching it: a symbol inside
+ * a display equation gets its card below the whole equation. After the
+ * pointer leaves the trigger toward its card, the card stays open while the
+ * pointer is inside the triangle from the leave point to the card's near
+ * edge. Outside the triangle it closes after a short grace. Other triggers
+ * inside the triangle are held back, so a symbol grazed on the way does not
+ * take over; resting on one switches to it.
+ *
+ * The geometry is pure and works on plain boxes in viewport coordinates, so
+ * `tests/unit/card-travel.test.ts` can check it in Node. `startTrip` adds the
+ * timers. The card manager (`./card-manager.ts`) and the collapsed-content
+ * peeks (`./disclosure/hover-preview.ts`, `CollapsibleSections.astro`) share
+ * it; each measures its own card and trigger.
+ */
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** A box in viewport coordinates, as `getBoundingClientRect()` reports it. */
+export interface Box {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/**
+ * The card's two corners on the side facing the trigger: the top corners if
+ * the card is below it, the bottom corners if above, else the facing
+ * vertical edge.
+ */
+export function nearEdge(card: Box, trigger: Box): [Point, Point] {
+  if (card.top >= trigger.bottom - 1) {
+    return [
+      { x: card.left, y: card.top },
+      { x: card.right, y: card.top },
+    ];
+  }
+  if (card.bottom <= trigger.top + 1) {
+    return [
+      { x: card.left, y: card.bottom },
+      { x: card.right, y: card.bottom },
+    ];
+  }
+  if (card.left >= trigger.right - 1) {
+    return [
+      { x: card.left, y: card.top },
+      { x: card.left, y: card.bottom },
+    ];
+  }
+  return [
+    { x: card.right, y: card.top },
+    { x: card.right, y: card.bottom },
+  ];
+}
+
+const cross = (p: Point, a: Point, b: Point) =>
+  (p.x - b.x) * (a.y - b.y) - (a.x - b.x) * (p.y - b.y);
+
+/** Whether `p` lies inside triangle `abc` or on its edge. */
+export function pointInTriangle(p: Point, a: Point, b: Point, c: Point): boolean {
+  const d1 = cross(p, a, b);
+  const d2 = cross(p, b, c);
+  const d3 = cross(p, c, a);
+  const negative = d1 < 0 || d2 < 0 || d3 < 0;
+  const positive = d1 > 0 || d2 > 0 || d3 > 0;
+  return !(negative && positive);
+}
+
+/** Whether `p` lies inside `box` or on its edge. */
+export function pointInBox(box: Box, p: Point): boolean {
+  return p.x >= box.left && p.x <= box.right && p.y >= box.top && p.y <= box.bottom;
+}
+
+/** The triangle a trip keeps open: the leave point and the card's near edge. */
+export function travelZone(apex: Point, card: Box, trigger: Box): [Point, Point, Point] {
+  const [near1, near2] = nearEdge(card, trigger);
+  return [apex, near1, near2];
+}
+
+export interface TripOptions {
+  /** How long the pointer may stay outside the zone before `onExit`. */
+  readonly graceMs: number;
+  /** How long the pointer must rest inside the zone before `onRest`. */
+  readonly restMs: number;
+  /** The longest one trip may last before `onExit`. */
+  readonly tripMaxMs: number;
+  /** The card, measured live; `null` once it is gone. */
+  cardBox(): Box | null;
+  /** The trigger the pointer left, measured live; `null` once it is gone. */
+  triggerBox(): Box | null;
+  /** The trip ran out: the pointer stayed outside the zone, or took too long. */
+  onExit(): void;
+  /** The pointer reached the card. */
+  onLand?(): void;
+  /** The pointer rested inside the zone, at `point`, for `restMs`. */
+  onRest?(point: Point): void;
+}
+
+export interface Trip {
+  /**
+   * Feed a pointer position. Ends the trip once it lands on the card. Coming
+   * back to the trigger is the caller's to notice, from the trigger's own
+   * `pointerover`: a KaTeX glyph's box overlaps its neighbours, so the point
+   * where the pointer left it often still lies inside that box.
+   */
+  move(point: Point): void;
+  /** Whether `point` is inside the zone (a trigger there is held back). */
+  holds(point: Point): boolean;
+  /** Stop the timers without calling anything. */
+  end(): void;
+  readonly active: boolean;
+}
+
+/**
+ * Start a trip from `apex`, the point where the pointer left the trigger.
+ * Pointer moves are fed in by the caller (`move`), so one document-level
+ * `pointermove` listener can serve every trip.
+ */
+export function startTrip(apex: Point, options: TripOptions): Trip {
+  let active = true;
+  let exitTimer: ReturnType<typeof setTimeout> | null = null;
+  let restTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clear = () => {
+    if (exitTimer !== null) clearTimeout(exitTimer);
+    if (restTimer !== null) clearTimeout(restTimer);
+    clearTimeout(maxTimer);
+    exitTimer = null;
+    restTimer = null;
+  };
+  const end = () => {
+    if (!active) return;
+    active = false;
+    clear();
+  };
+  const exit = () => {
+    if (!active) return;
+    end();
+    options.onExit();
+  };
+  const maxTimer = setTimeout(exit, options.tripMaxMs);
+
+  const zone = () => {
+    const card = options.cardBox();
+    const trigger = options.triggerBox();
+    return card && trigger ? { card, trigger, corners: travelZone(apex, card, trigger) } : null;
+  };
+
+  const holds = (point: Point) => {
+    if (!active) return false;
+    const measured = zone();
+    return !!measured && pointInTriangle(point, ...measured.corners);
+  };
+
+  const move = (point: Point) => {
+    if (!active) return;
+    const measured = zone();
+    if (!measured) {
+      end();
+      return;
+    }
+    if (pointInBox(measured.card, point)) {
+      end();
+      options.onLand?.();
+      return;
+    }
+    if (restTimer !== null) clearTimeout(restTimer);
+    restTimer = null;
+    if (pointInTriangle(point, ...measured.corners)) {
+      if (exitTimer !== null) clearTimeout(exitTimer);
+      exitTimer = null;
+      restTimer = setTimeout(() => {
+        restTimer = null;
+        if (active) options.onRest?.(point);
+      }, options.restMs);
+    } else if (exitTimer === null) {
+      exitTimer = setTimeout(exit, options.graceMs);
+    }
+  };
+
+  move(apex);
+
+  return {
+    move,
+    holds,
+    end,
+    get active() {
+      return active;
+    },
+  };
+}