explico 0.8.0 → 0.11.1

package/src/components/card-drag.ts

@@ -0,0 +1,631 @@
+/**
+ * Dragging a card by its grip, and snapping it into the side column (rules
+ * D1–D7 of `docs/plans/hover-card-consistency.md`).
+ *
+ * The grip at the left of a card's header is the only handle, so the card's
+ * text stays selectable. A drag starts after a few pixels of movement and
+ * pins the card. Dropped in the snap zone — its left edge near the article's
+ * right edge — the card docks in the side column at the drop height;
+ * dropped near its anchored spot, it goes back next to its trigger; dropped
+ * anywhere else, it stays there as a Moved card, which keeps its place
+ * relative to the article column and its trigger's line and never covers a
+ * sidebar. The grip is also a button: arrow keys move the card, Home brings
+ * it back. Escape during a drag cancels it.
+ *
+ * The decisions are pure functions over plain numbers and boxes (`snaps`,
+ * `dropOutcome`, `keepBetween`, `movedSpot`, `movedAt`, `nudgeSpot`), so
+ * `tests/unit/card-drag.test.ts` checks them in Node. The DOM half follows
+ * the pointer (`installCardDrag`) and draws the docking area, the article's
+ * edge and the landing outline (`createDockPreview`). The card manager
+ * (`./card-manager.ts`) is the `DragHost`: it owns the cards' modes and
+ * where they go once dropped.
+ */
+import { moveTo } from './card-placement';
+import { headerBottom, railLeftEdge, remToPx } from './card-side';
+import type { Box, Point } from './card-travel';
+
+const clamp = (value: number, low: number, high: number) =>
+  Math.max(low, Math.min(value, high));
+
+// ---------------------------------------------------------------------------
+// The decisions, pure.
+// ---------------------------------------------------------------------------
+
+/** D1: whether the pointer has moved far enough from where it went down to start a drag. */
+export const pastThreshold = (from: Point, to: Point, threshold: number): boolean =>
+  Math.hypot(to.x - from.x, to.y - from.y) >= threshold;
+
+export interface SnapInput {
+  /**
+   * The card's left edge where the pointer takes it, before it is kept
+   * between the sidebars: a card held against the rail can still reach the
+   * zone when the article has to slide to make room.
+   */
+  readonly left: number;
+  /** The article's right text edge now, or `null` when the window has no side column (S7). */
+  readonly edge: number | null;
+  /** Whether the card is snapped already, during this drag (D4). */
+  readonly snapped: boolean;
+  /** Alt or Option held: no snapping (D4). */
+  readonly altKey: boolean;
+  /** D3: how near the article's edge the card's left edge snaps. */
+  readonly distance: number;
+  /** D4: how far it must go again to let go once snapped. */
+  readonly release: number;
+}
+
+/** D3, D4: whether the card is in the snap zone, with hysteresis. */
+export function snaps(input: SnapInput): boolean {
+  if (input.altKey || input.edge === null) return false;
+  const off = Math.abs(input.left - input.edge);
+  return off <= (input.snapped ? input.release : input.distance);
+}
+
+export type DropOutcome =
+  | { readonly kind: 'side'; readonly top: number }
+  | { readonly kind: 'home' }
+  | { readonly kind: 'moved'; readonly left: number; readonly top: number };
+
+export interface DropInput {
+  /** Where the card is dropped: its top-left corner. */
+  readonly at: Point;
+  /** Whether it is snapped into the side column (`snaps`). */
+  readonly snapped: boolean;
+  /** Its anchored spot next to its trigger, or `null` when it has none. */
+  readonly home: Point | null;
+  /** Alt or Option held: no snapping of either kind. */
+  readonly altKey: boolean;
+  /** D5: how near its anchored spot a drop goes back there. */
+  readonly homeDistance: number;
+}
+
+/**
+ * D3, D5, D2: a snapped card docks at the drop height; one dropped within
+ * reach of its anchored spot goes back next to its trigger; any other drop
+ * leaves it where it is, Moved.
+ */
+export function dropOutcome(input: DropInput): DropOutcome {
+  const { at, home } = input;
+  if (input.snapped) return { kind: 'side', top: at.y };
+  if (
+    !input.altKey &&
+    home &&
+    Math.hypot(at.x - home.x, at.y - home.y) <= input.homeDistance
+  ) {
+    return { kind: 'home' };
+  }
+  return { kind: 'moved', left: at.x, top: at.y };
+}
+
+/** The room between the sidebars a card is kept in, in viewport x. */
+export interface Between {
+  readonly left: number;
+  readonly right: number;
+}
+
+/** D2: a card's left edge, kept between the sidebars; a card wider than the room sits at its left. */
+export const keepBetween = (left: number, width: number, between: Between): number =>
+  clamp(left, between.left, Math.max(between.left, between.right - width));
+
+/** Where a card may go during a drag, in the viewport. */
+export interface DragBounds extends Between {
+  /** Below the sticky header. */
+  readonly top: number;
+  /** The window's bottom edge, less the window edge. */
+  readonly bottom: number;
+}
+
+/**
+ * D1, D2: the card's spot while the pointer drags it, from where the card and
+ * the pointer started. It is kept between the sidebars, and its grip row
+ * (`grab` px tall) stays below the header and inside the window, so the card
+ * can always be picked up again.
+ */
+export function dragSpot(
+  card: Point,
+  from: Point,
+  to: Point,
+  width: number,
+  bounds: DragBounds,
+  grab: number,
+): { readonly free: Point; readonly kept: Point } {
+  const free = { x: card.x + to.x - from.x, y: card.y + to.y - from.y };
+  return {
+    free,
+    kept: {
+      x: keepBetween(free.x, width, bounds),
+      y: clamp(free.y, bounds.top, Math.max(bounds.top, bounds.bottom - grab)),
+    },
+  };
+}
+
+/**
+ * D6: the card's spot after one arrow-key step. Like a drag, a step never
+ * takes it over a sidebar, nor its grip under the header or out of the
+ * window; a card already past an edge (scrolled under the header) is never
+ * pushed further out, nor pulled in by a step away from that edge.
+ */
+export function nudgeSpot(
+  card: Point,
+  by: Point,
+  width: number,
+  bounds: DragBounds,
+  grab: number,
+): Point {
+  const low = Math.min(card.y, bounds.top);
+  const high = Math.max(card.y, bounds.bottom - grab);
+  return {
+    x: keepBetween(card.x + by.x, width, bounds),
+    y: clamp(card.y + by.y, low, high),
+  };
+}
+
+/** D6: the step an arrow key moves a card, or `null` for any other key. */
+export function keyboardStep(
+  key: string,
+  large: boolean,
+  steps: { readonly small: number; readonly large: number },
+): Point | null {
+  const size = large ? steps.large : steps.small;
+  switch (key) {
+    case 'ArrowLeft':
+      return { x: -size, y: 0 };
+    case 'ArrowRight':
+      return { x: size, y: 0 };
+    case 'ArrowUp':
+      return { x: 0, y: -size };
+    case 'ArrowDown':
+      return { x: 0, y: size };
+    default:
+      return null;
+  }
+}
+
+/**
+ * D2: a Moved card's place — its left edge from the article column's left
+ * edge, its top from its trigger's line — so it scrolls with the page and
+ * follows its trigger when the text reflows.
+ */
+export interface MovedSpot {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** D2: a card at `at` (its top-left corner), stored against the article column and its trigger's line. */
+export const movedSpot = (at: Point, columnLeft: number, lineTop: number): MovedSpot => ({
+  x: at.x - columnLeft,
+  y: at.y - lineTop,
+});
+
+/** D2: where a Moved card goes, for the article column and its trigger's line where they are now. */
+export const movedAt = (spot: MovedSpot, columnLeft: number, lineTop: number): Point => ({
+  x: columnLeft + spot.x,
+  y: lineTop + spot.y,
+});
+
+// ---------------------------------------------------------------------------
+// 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 {
+    ...sidebarsBetween(edge),
+    top: Math.max(edge, headerBottom() + edge),
+    bottom: document.documentElement.clientHeight - edge,
+  };
+}
+
+export interface DockPreviewState {
+  /** D3: the docking area, tinted from a drag's first movement; `null` without a side column. */
+  readonly area: Between | null;
+  /** D3: the article's edge, dashed while the card is snapped. */
+  readonly edge: number | null;
+  /** D3: the dashed outline of where a snapped card lands. */
+  readonly landing: Box | null;
+}
+
+export interface DockPreview {
+  show(state: DockPreviewState): void;
+  hide(): void;
+}
+
+/** "Release to pin to the side" (D3). */
+const RELEASE_LABEL = 'Release to pin to the side';
+
+/**
+ * D3: the docking area's tint, the dashed line on the article's edge, the
+ * landing outline and its label. They are fixed to the window at the bottom
+ * of the card layer: over the article, under every card, and never in the
+ * way of a click.
+ */
+export function createDockPreview(layer: () => HTMLElement): DockPreview {
+  let root: HTMLElement | null = null;
+  let area: HTMLElement | null = null;
+  let edge: HTMLElement | null = null;
+  let outline: HTMLElement | null = null;
+  let label: HTMLElement | null = null;
+
+  const part = (name: string) => {
+    const el = document.createElement('div');
+    el.className = `explico-card-dock-${name}`;
+    el.hidden = true;
+    return el;
+  };
+
+  const mount = () => {
+    if (!root) {
+      root = document.createElement('div');
+      root.className = 'explico-card-dock';
+      root.dataset.cardDock = '';
+      root.setAttribute('aria-hidden', 'true');
+      area = part('area');
+      edge = part('edge');
+      outline = part('outline');
+      label = part('label');
+      label.textContent = RELEASE_LABEL;
+      root.append(area, edge, outline, label);
+    }
+    const host = layer();
+    if (root.parentElement !== host) host.prepend(root);
+    return root;
+  };
+
+  const top = () => Math.max(0, headerBottom());
+
+  return {
+    show(state) {
+      mount();
+      if (!area || !edge || !outline || !label) return;
+      area.hidden = !state.area;
+      if (state.area) {
+        area.style.left = `${Math.round(state.area.left)}px`;
+        area.style.width = `${Math.max(0, Math.round(state.area.right - state.area.left))}px`;
+        area.style.top = `${Math.round(top())}px`;
+      }
+      edge.hidden = state.edge === null;
+      if (state.edge !== null) {
+        edge.style.left = `${Math.round(state.edge)}px`;
+        edge.style.top = `${Math.round(top())}px`;
+      }
+      const landing = state.landing;
+      outline.hidden = !landing;
+      label.hidden = !landing;
+      root?.toggleAttribute('data-snapped', !!landing);
+      if (landing) {
+        outline.style.left = `${Math.round(landing.left)}px`;
+        outline.style.top = `${Math.round(landing.top)}px`;
+        outline.style.width = `${Math.round(landing.right - landing.left)}px`;
+        outline.style.height = `${Math.round(landing.bottom - landing.top)}px`;
+        // Under the outline, or over its top when it reaches the window's bottom.
+        const height = label.offsetHeight || 24;
+        const below = landing.bottom + 8;
+        const room = document.documentElement.clientHeight - 8;
+        label.style.left = `${Math.round((landing.left + landing.right) / 2)}px`;
+        label.style.top = `${Math.round(below + height <= room ? below : landing.top + 8)}px`;
+      }
+    },
+    hide() {
+      root?.remove();
+      root?.removeAttribute('data-snapped');
+      for (const el of [area, edge, outline, label]) if (el) el.hidden = true;
+    },
+  };
+}
+
+/** What a drag needs from the page, measured once when it starts. */
+export interface DragFrame {
+  /** Where the card may go (D1, D2). */
+  readonly bounds: DragBounds;
+  /** The article's right text edge now, or `null` when the window has no side column (D3, S7). */
+  readonly edge: number | null;
+  /** The docking area: 16 px right of the article to 16 px left of the rail (D3). */
+  readonly area: Between | null;
+  /** The card's anchored spot next to its trigger, its top-left corner (D5). */
+  readonly home: Point | null;
+}
+
+/** The card manager's side of a drag. Every card is the card element a grip sits in. */
+export interface DragHost {
+  /** The open card a grip belongs to, or `null`. */
+  cardOf(grip: HTMLElement): HTMLElement | null;
+  /** D1, D2: the drag starts — pin the card — and say where it may go; `null` refuses it. */
+  begin(card: HTMLElement): DragFrame | null;
+  /** D3: where a snapped card with its top at `top` lands, in the viewport. */
+  landing(card: HTMLElement, top: number): Box | null;
+  /** The card is dropped: dock it, send it home, or leave it where it is. */
+  drop(card: HTMLElement, outcome: DropOutcome): void;
+  /** D7: the drag was cancelled; the card is back where it started. */
+  cancel(card: HTMLElement): void;
+  /** D6: an arrow key on the grip. */
+  nudge(card: HTMLElement, by: Point): void;
+  /** D6: Home on the grip. */
+  home(card: HTMLElement): void;
+}
+
+export interface CardDragOptions {
+  /** D1: movement before a drag starts (px). */
+  readonly threshold: number;
+  /** D3, D4 (px). */
+  readonly snapDistance: number;
+  readonly snapRelease: number;
+  /** D5 (px). */
+  readonly snapHome: number;
+  /** D6 (px). */
+  readonly step: number;
+  readonly stepLarge: number;
+  /** The card layer, where the preview mounts. */
+  layer(): HTMLElement;
+}
+
+export interface CardDrag {
+  /** The card being dragged now, if any. */
+  readonly active: HTMLElement | null;
+  /** End a drag without a drop or a cancel: the card it moved is closing. */
+  abort(): void;
+}
+
+/** Set on `<html>` for the length of a drag: no text selection, a grabbing cursor. */
+const DRAGGING_ATTRIBUTE = 'data-card-dragging';
+
+interface Session {
+  readonly pointerId: number;
+  readonly grip: HTMLElement;
+  readonly card: HTMLElement;
+  /** The pointer where it went down. */
+  readonly from: Point;
+  /** The card's top-left corner then, in the viewport. */
+  readonly start: Point;
+  /** The card's inline position then, restored on cancel. */
+  readonly style: { readonly left: string; readonly top: string };
+  readonly width: number;
+  /** The grip row's height: what must stay inside the window. */
+  readonly grab: number;
+  frame: DragFrame | null;
+  pointer: Point;
+  altKey: boolean;
+  snapped: boolean;
+  at: Point;
+}
+
+/**
+ * D1–D7: follow the pointer from a card's grip (`[data-card-grip]`), and the
+ * grip's arrow keys and Home. One set of document listeners serves every
+ * card.
+ */
+export function installCardDrag(host: DragHost, options: CardDragOptions): CardDrag {
+  const preview = createDockPreview(options.layer);
+  let session: Session | null = null;
+
+  const gripOf = (node: EventTarget | null): HTMLElement | null =>
+    node instanceof Element ? node.closest<HTMLElement>('[data-card-grip]') : null;
+
+  const finish = () => {
+    const ending = session;
+    session = null;
+    preview.hide();
+    document.documentElement.removeAttribute(DRAGGING_ATTRIBUTE);
+    window.removeEventListener('scroll', onScroll, true);
+    if (!ending) return;
+    ending.card.removeAttribute('data-card-dragged');
+    if (ending.grip.hasPointerCapture?.(ending.pointerId)) {
+      ending.grip.releasePointerCapture(ending.pointerId);
+    }
+  };
+
+  /** Put the card where the pointer takes it, and show what a drop there would do. */
+  const follow = (current: Session) => {
+    const { frame } = current;
+    if (!frame) return;
+    const { free, kept } = dragSpot(
+      current.start,
+      current.from,
+      current.pointer,
+      current.width,
+      frame.bounds,
+      current.grab,
+    );
+    current.snapped = snaps({
+      left: free.x,
+      edge: frame.edge,
+      snapped: current.snapped,
+      altKey: current.altKey,
+      distance: options.snapDistance,
+      release: options.snapRelease,
+    });
+    current.at = kept;
+    moveTo(current.card, kept.x, kept.y);
+    preview.show({
+      area: frame.area,
+      edge: current.snapped ? frame.edge : null,
+      landing: current.snapped ? host.landing(current.card, kept.y) : null,
+    });
+  };
+
+  /** D1: past the threshold, the drag starts. */
+  const begin = (current: Session): boolean => {
+    const frame = host.begin(current.card);
+    if (!frame) {
+      finish();
+      return false;
+    }
+    current.frame = frame;
+    document.documentElement.setAttribute(DRAGGING_ATTRIBUTE, '');
+    current.card.setAttribute('data-card-dragged', '');
+    // A wheel turned mid-drag scrolls the page under the card: keep it at the pointer.
+    window.addEventListener('scroll', onScroll, { capture: true, passive: true });
+    return true;
+  };
+
+  /** D7: back where the drag started. */
+  const cancel = (current: Session) => {
+    const started = current.frame !== null;
+    current.card.style.left = current.style.left;
+    current.card.style.top = current.style.top;
+    finish();
+    if (started) host.cancel(current.card);
+  };
+
+  function onScroll() {
+    if (session?.frame) follow(session);
+  }
+
+  const onPointerDown = (event: PointerEvent) => {
+    const grip = gripOf(event.target);
+    if (!grip || event.button !== 0 || !event.isPrimary) return;
+    const card = host.cardOf(grip);
+    if (!card) return;
+    // No text selection, no focus ring from the mouse: the grip is a handle.
+    event.preventDefault();
+    if (session) cancel(session);
+    const rect = card.getBoundingClientRect();
+    const gripRect = grip.getBoundingClientRect();
+    const point = { x: event.clientX, y: event.clientY };
+    session = {
+      pointerId: event.pointerId,
+      grip,
+      card,
+      from: point,
+      start: { x: rect.left, y: rect.top },
+      style: { left: card.style.left, top: card.style.top },
+      width: rect.width,
+      grab: Math.max(gripRect.bottom - rect.top, 1),
+      frame: null,
+      pointer: point,
+      altKey: event.altKey,
+      snapped: false,
+      at: { x: rect.left, y: rect.top },
+    };
+    try {
+      grip.setPointerCapture(event.pointerId);
+    } catch {
+      // A pointer that is already gone: the drag simply never starts.
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent) => {
+    const current = session;
+    if (!current || event.pointerId !== current.pointerId) return;
+    current.pointer = { x: event.clientX, y: event.clientY };
+    current.altKey = event.altKey;
+    if (!current.frame) {
+      if (!pastThreshold(current.from, current.pointer, options.threshold)) return;
+      if (!begin(current)) return;
+    }
+    event.preventDefault();
+    follow(current);
+  };
+
+  const onPointerUp = (event: PointerEvent) => {
+    const current = session;
+    if (!current || event.pointerId !== current.pointerId) return;
+    if (!current.frame) {
+      finish(); // a click on the grip moves nothing
+      return;
+    }
+    current.pointer = { x: event.clientX, y: event.clientY };
+    current.altKey = event.altKey;
+    follow(current);
+    const outcome = dropOutcome({
+      at: current.at,
+      snapped: current.snapped,
+      home: current.frame.home,
+      altKey: current.altKey,
+      homeDistance: options.snapHome,
+    });
+    finish();
+    host.drop(current.card, outcome);
+  };
+
+  const onPointerCancel = (event: PointerEvent) => {
+    if (session && event.pointerId === session.pointerId) cancel(session);
+  };
+
+  const onLostCapture = (event: PointerEvent) => {
+    // After a drop the session is already gone; any other loss ends the drag.
+    if (session && event.pointerId === session.pointerId) cancel(session);
+  };
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    const current = session;
+    if (current) {
+      if (event.key === 'Escape') {
+        // D7: this press cancels the drag and closes nothing (C10 waits for the next).
+        event.preventDefault();
+        event.stopPropagation();
+        cancel(current);
+      } else if (event.key === 'Alt' && current.frame) {
+        current.altKey = true;
+        follow(current);
+      }
+      return;
+    }
+    const grip = gripOf(event.target);
+    if (!grip || event.ctrlKey || event.metaKey || event.altKey) return;
+    const card = host.cardOf(grip);
+    if (!card) return;
+    if (event.key === 'Home') {
+      event.preventDefault();
+      host.home(card);
+      return;
+    }
+    const by = keyboardStep(event.key, event.shiftKey, {
+      small: options.step,
+      large: options.stepLarge,
+    });
+    if (!by) return;
+    event.preventDefault();
+    host.nudge(card, by);
+  };
+
+  const onKeyUp = (event: KeyboardEvent) => {
+    if (event.key !== 'Alt' || !session?.frame) return;
+    session.altKey = false;
+    follow(session);
+  };
+
+  document.addEventListener('pointerdown', onPointerDown, true);
+  document.addEventListener('pointermove', onPointerMove, true);
+  document.addEventListener('pointerup', onPointerUp, true);
+  document.addEventListener('pointercancel', onPointerCancel, true);
+  document.addEventListener('lostpointercapture', onLostCapture, true);
+  // The window's capture phase runs before the card manager's Escape (C10).
+  window.addEventListener('keydown', onKeyDown, true);
+  window.addEventListener('keyup', onKeyUp, true);
+
+  return {
+    get active() {
+      return session?.frame ? session.card : null;
+    },
+    abort: finish,
+  };
+}

package/src/components/card-jump.ts

@@ -0,0 +1,45 @@
+/**
+ * The arrow that ends an explanation card's "Go to …" link, from where the
+ * link lands: ↑ or ↓ for a place on this page, above or below the middle of
+ * the reader's view; → for another page of the course; ↗ only for a link
+ * that leaves the site. ↗ used to end every one of them, although only a
+ * citation's source ever leaves the site.
+ *
+ * The float, notation, citation and abbreviation cards mark the arrow with
+ * `[data-jump-arrow]` inside the link and call `wireJumpArrow` once its
+ * `href` is set. The arrow is worked out again whenever the reader points at
+ * or focuses the link, since a kept card outlives the scroll position it was
+ * opened at.
+ */
+
+const trimPath = (path: string) => path.replace(/\/index\.html$/, '/').replace(/\/+$/, '');
+
+export function jumpArrow(href: string): '↑' | '↓' | '→' | '↗' {
+  let url: URL;
+  try {
+    url = new URL(href, window.location.href);
+  } catch {
+    return '→';
+  }
+  if (url.origin !== window.location.origin) return '↗';
+  if (trimPath(url.pathname) !== trimPath(window.location.pathname)) return '→';
+  const id = decodeURIComponent(url.hash.slice(1));
+  const target = id ? document.getElementById(id) : null;
+  if (!target) return '↓';
+  const rect = target.getBoundingClientRect();
+  return rect.top + rect.height / 2 < window.innerHeight / 2 ? '↑' : '↓';
+}
+
+/** Set `link`'s `[data-jump-arrow]` from its `href`, and keep it current. */
+export function wireJumpArrow(link: HTMLAnchorElement): void {
+  const arrow = link.querySelector<HTMLElement>('[data-jump-arrow]');
+  if (!arrow) return;
+  const update = () => {
+    arrow.textContent = ` ${jumpArrow(link.getAttribute('href') ?? '')}`;
+  };
+  update();
+  if (link.dataset.jumpArrowWired === 'true') return;
+  link.dataset.jumpArrowWired = 'true';
+  link.addEventListener('pointerenter', update);
+  link.addEventListener('focus', update);
+}