explico 0.8.0 → 0.11.1

package/src/styles/surfaces.css

@@ -0,0 +1,182 @@
+/* Style primitives and semantic tiers (docs/plans/titles-and-containers.md
+   Part 2). Every container the engine draws is one of four tiers, and every
+   tier is composed from the same three primitives:
+
+     surface  none · tint-neutral · tint-accent
+     edge     none · border · rule-left
+     depth    flat · raised
+
+     plain   none         + none      + flat    references, tables, equations,
+                                                figures, sections by default
+     meta    tint-neutral + border    + flat    notation panel, part rail,
+                                                About panel, Starlight <Card>
+     accent  tint-accent  + border    + raised  knowledge checks, worked
+                                                examples, `[card]` sections
+     aside   (tint-accent)+ rule-left + flat    memo (tinted), opened short
+                                                note, Starlight asides
+
+   What a tier means: grey (meta) is logistics or generated; no card (plain)
+   is what a book would print in its main flow; an accent card is enrichment
+   the author marked. `plain` has no class — it is the absence of one.
+
+   There is no top rule anywhere in the system, and elevation never scales
+   with heading depth: hierarchy stays in type size and numbers. Radius and
+   shadow are tokens, never author-selectable; an author reaches a tier only
+   through a heading's `[card]` / `[card=meta]` marker. Imported by
+   `global.css`, so a course's `customCss` needs no second entry.
+
+   Dark is Starlight's base theme (`:root`), light its override. */
+
+:root {
+  --ex-surface-none: transparent;
+  /* Starlight defines `--sl-color-gray-7` for its light theme only: a dark
+     page reading it got no background at all. Each theme names its own. */
+  --ex-surface-tint-neutral: var(--sl-color-gray-6);
+  --ex-surface-tint-accent: color-mix(in srgb, var(--sl-color-bg) 92%, var(--sl-color-accent) 8%);
+
+  --ex-edge-color: var(--sl-color-gray-5);
+  --ex-edge-border: 1px solid var(--ex-edge-color);
+  --ex-edge-rule-width: 3px;
+  --ex-edge-rule-color: var(--sl-color-accent);
+
+  --ex-depth-flat: none;
+  --ex-depth-raised: 0 1px 2px rgba(0, 0, 0, 0.4), 0 4px 14px rgba(0, 0, 0, 0.35);
+
+  /* One radius per boxed tier; an aside is a rule, not a box, and has none. */
+  --ex-radius-meta: 0.5rem;
+  --ex-radius-accent: 0.5rem;
+
+  /* Inner spacing shared by the boxed tiers and the aside tier. A box's
+     sides hold a section's chevron, so they stay a little wider than its
+     top and bottom. */
+  --ex-pad-box: clamp(1rem, 2.5vw, 1.25rem);
+  --ex-pad-box-block: 1rem;
+  --ex-pad-aside: 0.75rem 1rem;
+
+  /* Starlight asides (`:::caution`, `:::danger`) keep a warning / danger hue:
+     a caution in the course accent stops reading as one. */
+  --ex-aside-caution: var(--sl-color-orange);
+  --ex-aside-caution-surface: color-mix(in srgb, var(--sl-color-bg) 88%, var(--sl-color-orange) 12%);
+  --ex-aside-caution-text: var(--sl-color-orange-high);
+  --ex-aside-danger: var(--sl-color-red);
+  --ex-aside-danger-surface: color-mix(in srgb, var(--sl-color-bg) 88%, var(--sl-color-red) 12%);
+  --ex-aside-danger-text: var(--sl-color-red-high);
+}
+
+:root[data-theme='light'] {
+  --ex-surface-tint-neutral: var(--sl-color-gray-7);
+  --ex-surface-tint-accent: color-mix(in srgb, var(--sl-color-bg) 93%, var(--sl-color-accent) 7%);
+  --ex-edge-color: var(--sl-color-gray-5);
+  --ex-depth-raised: 0 1px 2px rgba(30, 42, 35, 0.08), 0 4px 14px rgba(30, 42, 35, 0.07);
+  --ex-aside-caution-surface: color-mix(in srgb, var(--sl-color-bg) 90%, var(--sl-color-orange) 10%);
+  --ex-aside-danger-surface: color-mix(in srgb, var(--sl-color-bg) 92%, var(--sl-color-red) 8%);
+}
+
+.ex-tier-meta {
+  background: var(--ex-surface-tint-neutral);
+  border: var(--ex-edge-border);
+  border-radius: var(--ex-radius-meta);
+  box-shadow: var(--ex-depth-flat);
+}
+
+.ex-tier-accent {
+  background: var(--ex-surface-tint-accent);
+  border: var(--ex-edge-border);
+  border-radius: var(--ex-radius-accent);
+  box-shadow: var(--ex-depth-raised);
+}
+
+/* The aside tier's surface is per use: a memo is tinted, an opened short note
+   is not. `--ex-aside-surface` and `--ex-aside-rule` are the two knobs. */
+.ex-tier-aside {
+  background: var(--ex-aside-surface, var(--ex-surface-none));
+  border: 0;
+  border-inline-start: var(--ex-edge-rule-width) solid var(--ex-aside-rule, var(--ex-edge-rule-color));
+  border-radius: 0;
+  box-shadow: var(--ex-depth-flat);
+}
+
+.ex-tier-aside--tinted {
+  --ex-aside-surface: var(--ex-surface-tint-accent);
+}
+
+/* A `[card]` / `[card=meta]` section (`CollapsibleSections.astro` wraps the
+   heading and its body). Its padding holds the collapse chevron: the gutter
+   the chevron centres in is the card's own inner edge, not the page's. */
+.sl-markdown-content .ex-section-card {
+  --ex-section-gutter: var(--ex-pad-box);
+  margin-block: 1.5rem;
+  padding: var(--ex-pad-box-block) var(--ex-pad-box);
+}
+
+.sl-markdown-content .ex-section-card > :first-child {
+  margin-block-start: 0;
+}
+
+.sl-markdown-content .ex-section-card > :last-child {
+  margin-block-end: 0;
+}
+
+/* Starlight asides (Q10): the aside tier's shape — left rule, tint, explico
+   spacing — with Starlight's own icon per type kept. `note` and `tip` take the
+   course accent; `caution` and `danger` keep their hue on the rule, tint and
+   title. `.starlight-aside` rules live in `@layer starlight.content`; these
+   are unlayered, so they win. */
+.starlight-aside {
+  --ex-aside-surface: var(--ex-surface-tint-accent);
+  --sl-color-asides-text-accent: var(--sl-color-text-accent);
+  --sl-color-asides-border: var(--ex-edge-rule-color);
+  padding: var(--ex-pad-aside);
+  background: var(--ex-aside-surface);
+  border: 0;
+  border-inline-start: var(--ex-edge-rule-width) solid var(--sl-color-asides-border);
+  border-radius: 0;
+  color: var(--sl-color-text);
+}
+
+.starlight-aside--caution {
+  --ex-aside-surface: var(--ex-aside-caution-surface);
+  --sl-color-asides-text-accent: var(--ex-aside-caution-text);
+  --sl-color-asides-border: var(--ex-aside-caution);
+}
+
+.starlight-aside--danger {
+  --ex-aside-surface: var(--ex-aside-danger-surface);
+  --sl-color-asides-text-accent: var(--ex-aside-danger-text);
+  --sl-color-asides-border: var(--ex-aside-danger);
+}
+
+.starlight-aside__title {
+  font-weight: 600;
+}
+
+/* `:::note{icon=""}` / `<Aside icon="">` — the author dropped the icon
+   (`remark-asides.mjs` wraps the aside in this marker; Starlight itself
+   reads an empty icon as "use the default"). */
+.ex-aside-no-icon > .starlight-aside .starlight-aside__icon {
+  display: none;
+}
+
+/* Starlight `<Card>` (Q10): the meta tier. Starlight's own card is a black
+   box with a coloured icon chip; the chip stays, the box becomes meta.
+   `article.card` is the element `Card.astro` renders, so a course's own
+   `.card` class elsewhere is left alone. */
+.sl-markdown-content article.card {
+  background: var(--ex-surface-tint-neutral);
+  border: var(--ex-edge-border);
+  border-radius: var(--ex-radius-meta);
+  box-shadow: var(--ex-depth-flat);
+}
+
+@media (forced-colors: active) {
+  .ex-tier-meta,
+  .ex-tier-accent,
+  .sl-markdown-content article.card {
+    border-color: CanvasText;
+  }
+
+  .ex-tier-aside,
+  .starlight-aside {
+    border-inline-start-color: CanvasText;
+  }
+}

package/src/components/hover-panel.ts

@@ -1,339 +0,0 @@
-/**
- * Interaction engine for the shared hover/pin panel (see `HoverPanel.astro`).
- *
- * One copy of the positioning, pin, Escape, outside-close, and
- * article-column-clamp logic that the notation layer and the citation layer
- * both need. Each layer supplies the domain-specific seams — how to find a
- * trigger, how to key it, how to fill the panel — and keeps its own markup.
- *
- * The panel is `position: fixed`. Placement clears the whole display equation
- * a marker sits inside (never just the glyph), decides the side against the
- * space left by the sticky site header, and keeps the box within the article
- * column so it never lands under a navigation rail.
- */
-
-export interface HoverPanelState {
-  activeKey: string | null;
-  pinnedKey: string | null;
-  visible: boolean;
-}
-
-export interface HoverPanelConfig {
-  /** The `<aside data-hover-panel>` element. */
-  panel: HTMLElement;
-  /** Exclusivity group (see the `activeSurface` note below `HoverPanelState`). */
-  groupId: string;
-  /**
-   * Element used only to locate the enclosing article column for the
-   * horizontal clamp. Defaults to the panel itself.
-   */
-  root?: HTMLElement;
-  /** Interactive element (marker, list row, control) for an event target. */
-  triggerFrom: (node: EventTarget | null) => HTMLElement | null;
-  /** Stable key identifying the content a trigger points at. */
-  keyFor: (trigger: HTMLElement) => string | null;
-  /**
-   * Fill the panel for `trigger`/`key`. Return `false` to abort the open
-   * (unknown key); the panel stays hidden.
-   */
-  render: (trigger: HTMLElement, key: string) => boolean | void;
-  /** A pin toggle for an event target (a list button, an in-panel button). */
-  pinControlFrom?: (node: EventTarget | null) => HTMLElement | null;
-  /** Called after the panel is shown for `key`. */
-  onShow?: (key: string, trigger: HTMLElement) => void;
-  /** Called after the panel is hidden. */
-  onClose?: () => void;
-  /** Called after every open, close, or pin change. */
-  onSync?: (state: HoverPanelState) => void;
-}
-
-function closestElement(node: EventTarget | null, selector: string) {
-  return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
-}
-
-/**
- * The notation layer and the citation layer each own their explanations —
- * the notation layer through its own popup stack (`./popup-stack.ts`), the
- * citation layer through this module's `createHoverPanel`. Neither knows the
- * other exists, so a pinned citation and an open notation popup — or the
- * reverse — can each be individually correct and still land on top of each
- * other, or on top of the equation the other one is explaining. Rather than
- * teach every positioning calculation about every other surface that might
- * exist, the two are mutually exclusive *groups*: opening the first popup in
- * one group closes whatever the other group had open. Within a group,
- * surfaces manage their own overlap (the citation panel is a singleton; the
- * notation stack positions its own popups against each other). A pin is not
- * exempt — the reader's attention already moved to the other group.
- */
-let activeSurface: {
-  readonly groupId: string;
-  readonly close: () => void;
-} | null = null;
-
-export function claimActiveSurface(groupId: string, close: () => void): void {
-  if (activeSurface && activeSurface.groupId !== groupId) {
-    activeSurface.close();
-  }
-  activeSurface = { groupId, close };
-}
-
-export function releaseActiveSurface(groupId: string): void {
-  if (activeSurface?.groupId === groupId) activeSurface = null;
-}
-
-export function createHoverPanel(config: HoverPanelConfig) {
-  const { panel } = config;
-  if (panel.dataset.hoverPanelReady === 'true') return;
-  panel.dataset.hoverPanelReady = 'true';
-
-  const anchorRoot = config.root ?? panel;
-
-  let activeKey: string | null = null;
-  let activeAnchor: HTMLElement | null = null;
-  let pinned: { key: string; anchor: HTMLElement } | null = null;
-
-  const sync = () => {
-    config.onSync?.({
-      activeKey,
-      pinnedKey: pinned?.key ?? null,
-      visible: panel.hidden === false,
-    });
-  };
-
-  const pinControlFrom = (node: EventTarget | null) =>
-    config.pinControlFrom?.(node) ?? null;
-
-  const interactiveFrom = (node: EventTarget | null) =>
-    pinControlFrom(node) ?? config.triggerFrom(node);
-
-  const position = () => {
-    if (panel.hidden || !activeAnchor) return;
-
-    const edge = 12;
-    const gap = 10;
-    const displayEquation = activeAnchor.closest<HTMLElement>('.katex-display');
-    const safeRegion = displayEquation ?? activeAnchor;
-    const regionRect = safeRegion.getBoundingClientRect();
-    const anchorRect = activeAnchor.getBoundingClientRect();
-
-    // The usable band is bounded by the sticky header, not the raw viewport
-    // edge. Decide the side against that real space so a clamp against the
-    // header can never push the panel back down over the equation.
-    const headerBottom =
-      document.querySelector<HTMLElement>('.header')?.getBoundingClientRect()
-        .bottom ?? 0;
-    const verticalStart = Math.max(edge, headerBottom + edge);
-    const verticalEnd = window.innerHeight - edge;
-    const spaceAbove = regionRect.top - gap - verticalStart;
-    const spaceBelow = verticalEnd - regionRect.bottom - gap;
-
-    // Measure the panel in the roomier band, then keep it on whichever side
-    // actually clears the safe region; shrink only when neither side fits.
-    panel.style.maxHeight = `${Math.max(spaceAbove, spaceBelow, 0)}px`;
-    let panelRect = panel.getBoundingClientRect();
-    const placeBelow =
-      spaceBelow >= panelRect.height || spaceBelow >= spaceAbove;
-    panel.style.maxHeight = `${Math.max(placeBelow ? spaceBelow : spaceAbove, 0)}px`;
-    panelRect = panel.getBoundingClientRect();
-
-    let top = placeBelow
-      ? regionRect.bottom + gap
-      : regionRect.top - gap - panelRect.height;
-    let left = anchorRect.left + anchorRect.width / 2 - panelRect.width / 2;
-
-    const article =
-      anchorRoot
-        .closest<HTMLElement>('.main-pane')
-        ?.querySelector<HTMLElement>('.sl-markdown-content') ??
-      document.querySelector<HTMLElement>('.sl-markdown-content');
-    const articleRect = article?.getBoundingClientRect();
-    const horizontalStart = Math.max(edge, articleRect?.left ?? edge);
-    const horizontalEnd = Math.min(
-      window.innerWidth - edge,
-      articleRect?.right ?? window.innerWidth - edge,
-    );
-
-    top = Math.max(
-      verticalStart,
-      Math.min(top, verticalEnd - panelRect.height),
-    );
-    left =
-      horizontalEnd - horizontalStart >= panelRect.width
-        ? Math.max(
-            horizontalStart,
-            Math.min(left, horizontalEnd - panelRect.width),
-          )
-        : Math.max(
-            edge,
-            Math.min(left, window.innerWidth - panelRect.width - edge),
-          );
-
-    panel.style.top = `${Math.round(top)}px`;
-    panel.style.left = `${Math.round(left)}px`;
-  };
-
-  const show = (anchor: HTMLElement) => {
-    const key = config.keyFor(anchor);
-    if (!key) return;
-    if (config.render(anchor, key) === false) return;
-
-    claimActiveSurface(config.groupId, forceClose);
-
-    activeKey = key;
-    activeAnchor = anchor;
-    config.onShow?.(key, anchor);
-
-    panel.style.visibility = 'hidden';
-    panel.hidden = false;
-    position();
-    panel.style.visibility = 'visible';
-    sync();
-  };
-
-  const close = () => {
-    activeKey = null;
-    activeAnchor = null;
-    panel.hidden = true;
-    config.onClose?.();
-    releaseActiveSurface(config.groupId);
-    sync();
-  };
-
-  // A plain `close()` deliberately leaves `pinned` set — a stray pointerout or
-  // focusout elsewhere on the page must not kill a pin the reader placed on
-  // purpose, and `restorePinnedOrClose` below relies on `pinned` surviving a
-  // transient close to bring the panel back. Being displaced by a DIFFERENT
-  // panel taking over (`claimActivePanel`) is not transient, though: without
-  // clearing the pin here, the very next stray blur anywhere on the page finds
-  // `pinned` still truthy and restores this panel — undoing the takeover a
-  // frame later and fighting the other panel for the screen.
-  const forceClose = () => {
-    pinned = null;
-    close();
-  };
-
-  const restorePinnedOrClose = () => {
-    window.requestAnimationFrame(() => {
-      const focused = config.triggerFrom(document.activeElement);
-      if (focused && config.keyFor(focused) === activeKey) return;
-      if (pinned) {
-        show(pinned.anchor);
-        return;
-      }
-      if (
-        activeAnchor?.matches(':hover') ||
-        panel.matches(':hover') ||
-        panel.contains(document.activeElement)
-      ) {
-        return;
-      }
-      close();
-    });
-  };
-
-  const togglePin = (key: string, anchor: HTMLElement) => {
-    if (pinned?.key === key && pinned.anchor === anchor) {
-      pinned = null;
-      close();
-      return;
-    }
-    pinned = { key, anchor };
-    show(anchor);
-  };
-
-  document.addEventListener('pointerover', (event) => {
-    if (event.pointerType === 'touch' || pinned) return;
-    const anchor = config.triggerFrom(event.target);
-    const key = anchor ? config.keyFor(anchor) : null;
-    if (anchor && key && anchor !== config.triggerFrom(event.relatedTarget)) {
-      show(anchor);
-    }
-  });
-
-  document.addEventListener('pointerout', (event) => {
-    if (event.pointerType === 'touch') return;
-    const anchor = config.triggerFrom(event.target);
-    if (!anchor || anchor === config.triggerFrom(event.relatedTarget)) return;
-    if (
-      event.relatedTarget instanceof Node &&
-      panel.contains(event.relatedTarget)
-    ) {
-      return;
-    }
-    restorePinnedOrClose();
-  });
-
-  document.addEventListener('focusin', (event) => {
-    const anchor = config.triggerFrom(event.target);
-    const key = anchor ? config.keyFor(anchor) : null;
-    if (anchor && key) show(anchor);
-  });
-  document.addEventListener('focusout', restorePinnedOrClose);
-
-  document.addEventListener('click', (event) => {
-    const control = pinControlFrom(event.target);
-    if (control) {
-      const ownKey = config.keyFor(control);
-      if (ownKey) {
-        togglePin(ownKey, control);
-      } else if (activeKey && activeAnchor) {
-        togglePin(activeKey, activeAnchor);
-      }
-      return;
-    }
-
-    const trigger = config.triggerFrom(event.target);
-    if (trigger && !trigger.closest('a')) {
-      const key = config.keyFor(trigger);
-      if (key) {
-        event.preventDefault();
-        togglePin(key, trigger);
-        return;
-      }
-    }
-    if (trigger) return; // a real link trigger: let it navigate.
-
-    // Anywhere else inside the panel collapses it, same as the corner "×" —
-    // its own body is never a trigger, so a click there can only mean "I'm
-    // done with this." A real link (e.g. "Open source link") is excluded so
-    // it still navigates instead of being swallowed.
-    if (
-      !panel.hidden &&
-      event.target instanceof Node &&
-      panel.contains(event.target) &&
-      !closestElement(event.target, 'a')
-    ) {
-      pinned = null;
-      close();
-    }
-  });
-
-  document.addEventListener('pointerdown', (event) => {
-    if (!pinned) return;
-    if (
-      interactiveFrom(event.target) ||
-      (event.target instanceof Node && panel.contains(event.target))
-    ) {
-      return;
-    }
-    pinned = null;
-    close();
-  });
-
-  document.addEventListener('keydown', (event) => {
-    if (event.key !== 'Escape' || (!activeKey && !pinned)) return;
-    pinned = null;
-    close();
-  });
-
-  panel.addEventListener('pointerleave', restorePinnedOrClose);
-  window.addEventListener('resize', position, { passive: true });
-  window.addEventListener('scroll', position, {
-    passive: true,
-    capture: true,
-  });
-
-  sync();
-}
-
-export { closestElement };