explico 0.1.1 → 0.3.0

package/src/components/starlight/AboutPanel.astro

@@ -0,0 +1,255 @@
+---
+/**
+ * The `[?]` "about this material" control, rendered top-right in the header next
+ * to the social icons (`LayoutSocialIcons.astro` composes both). It appears on
+ * every route — landing page and study-material pages alike.
+ *
+ * All of its data comes from the one compiler manifest (`manifest.about`): the
+ * engine identity from `explico`'s own `package.json`, the course's reader-facing
+ * `about` block, and the knowledge version resolved against
+ * `content/CHANGELOG.md`. This component never re-reads the filesystem.
+ *
+ * It is a plain `<details>` disclosure: the browser gives keyboard toggle and
+ * `aria-expanded` for free; the inline script only adds Escape-to-close and
+ * outside-click-to-close.
+ */
+import { loadManifest } from '../../compiler/manifest';
+
+const { about } = await loadManifest();
+const { engine, material, knowledge, authors, disclaimer, changelogHref } =
+  about;
+
+/** `mailto:` an email, pass through an http(s) URL, plain text otherwise. */
+function contactHref(contact: string): string | undefined {
+  if (/^https?:\/\//i.test(contact)) return contact;
+  if (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(contact)) return `mailto:${contact}`;
+  return undefined;
+}
+
+const authorLabel = authors.length > 1 ? 'Authors' : 'Author';
+const knowledgeLine = knowledge.date
+  ? `${knowledge.version} · ${knowledge.date}`
+  : knowledge.version;
+---
+
+<details class="about" data-about-panel>
+  <summary
+    class="about-toggle"
+    aria-label={`About ${material.name}`}
+    title={`About ${material.name}`}
+  >
+    <span aria-hidden="true">?</span>
+  </summary>
+  <div class="about-body">
+    <p class="about-name">{material.name}</p>
+    {material.summary && <p class="about-summary">{material.summary}</p>}
+
+    <dl class="about-facts">
+      <div>
+        <dt>Knowledge version</dt>
+        <dd>{knowledgeLine}</dd>
+      </div>
+      <div>
+        <dt>Engine</dt>
+        <dd>
+          {
+            engine.homepage ? (
+              <a href={engine.homepage}>
+                {engine.name} {engine.version}
+              </a>
+            ) : (
+              <span>
+                {engine.name} {engine.version}
+              </span>
+            )
+          }
+        </dd>
+      </div>
+      {
+        authors.length > 0 && (
+          <div>
+            <dt>{authorLabel}</dt>
+            <dd>
+              {authors.map((author, index) => {
+                const href = author.contact
+                  ? contactHref(author.contact)
+                  : undefined;
+                return (
+                  <>
+                    {index > 0 && ', '}
+                    {author.name}
+                    {author.contact && (
+                      <>
+                        {' '}
+                        (
+                        {href ? (
+                          <a href={href}>{author.contact}</a>
+                        ) : (
+                          author.contact
+                        )}
+                        )
+                      </>
+                    )}
+                  </>
+                );
+              })}
+            </dd>
+          </div>
+        )
+      }
+    </dl>
+
+    {disclaimer && <p class="about-disclaimer">{disclaimer}</p>}
+
+    {
+      changelogHref && (
+        <p class="about-links">
+          <a href={changelogHref}>What changed in this material</a>
+        </p>
+      )
+    }
+  </div>
+</details>
+
+<style>
+  @layer starlight.components {
+    .about {
+      position: relative;
+      display: inline-flex;
+    }
+
+    .about-toggle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.75rem;
+      height: 1.75rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 999px;
+      color: var(--sl-color-gray-1);
+      background: var(--sl-color-bg);
+      font-size: var(--sl-text-sm);
+      font-weight: 600;
+      line-height: 1;
+      cursor: pointer;
+      user-select: none;
+      list-style: none;
+    }
+
+    .about-toggle::-webkit-details-marker {
+      display: none;
+    }
+
+    .about-toggle:hover {
+      color: var(--sl-color-text);
+      border-color: var(--sl-color-gray-4);
+    }
+
+    .about[open] .about-toggle {
+      color: var(--sl-color-text);
+      border-color: var(--sl-color-accent);
+    }
+
+    .about-toggle:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    .about-body {
+      position: absolute;
+      inset-inline-end: 0;
+      top: calc(100% + 0.5rem);
+      z-index: 90;
+      width: min(21rem, calc(100vw - 1.5rem));
+      max-height: min(70vh, 34rem);
+      overflow-y: auto;
+      padding: 1rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-top: 0.25rem solid var(--sl-color-accent);
+      border-radius: 0.65rem;
+      color: var(--sl-color-text);
+      background: var(--sl-color-bg);
+      box-shadow: var(--sl-shadow-lg);
+      font-size: var(--sl-text-xs);
+      line-height: 1.5;
+    }
+
+    .about-name {
+      margin: 0;
+      font-size: var(--sl-text-sm);
+      font-weight: 600;
+    }
+
+    .about-summary {
+      margin: 0.35rem 0 0;
+      color: var(--sl-color-gray-2);
+    }
+
+    .about-facts {
+      margin: 0.75rem 0 0;
+      display: grid;
+      gap: 0.4rem;
+    }
+
+    .about-facts > div {
+      display: grid;
+      grid-template-columns: 8rem 1fr;
+      gap: 0.5rem;
+    }
+
+    .about-facts dt {
+      color: var(--sl-color-gray-3);
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+      font-size: 0.65rem;
+      line-height: 1.6;
+    }
+
+    .about-facts dd {
+      margin: 0;
+      overflow-wrap: anywhere;
+    }
+
+    .about-disclaimer {
+      margin: 0.85rem 0 0;
+      padding-top: 0.75rem;
+      border-top: 1px solid var(--sl-color-gray-6);
+      color: var(--sl-color-gray-2);
+    }
+
+    .about-links {
+      margin: 0.75rem 0 0;
+    }
+
+    .about-body a {
+      color: var(--sl-color-text-accent);
+    }
+  }
+</style>
+
+<script>
+  (() => {
+    const panels = Array.from(
+      document.querySelectorAll<HTMLDetailsElement>('details[data-about-panel]'),
+    );
+    if (panels.length === 0) return;
+
+    document.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape') return;
+      for (const details of panels) {
+        if (!details.open) continue;
+        details.open = false;
+        details.querySelector<HTMLElement>('summary')?.focus();
+      }
+    });
+
+    document.addEventListener('pointerdown', (event) => {
+      const target = event.target instanceof Node ? event.target : null;
+      for (const details of panels) {
+        if (details.open && (!target || !details.contains(target))) {
+          details.open = false;
+        }
+      }
+    });
+  })();
+</script>

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -0,0 +1,131 @@
+---
+/**
+ * Progressive enhancement for content-heading deep links (Step F3), the sibling
+ * of `KeyedFloatEnhancer.astro`.
+ *
+ * The no-JS baseline is complete: `rehype-heading-anchors` emits Starlight's
+ * `.sl-heading-wrapper` + `a.sl-anchor-link` markup, its bundled
+ * `anchor-links.css` does the hover/focus reveal, and `global.css` does the
+ * `:target` flash (with a `prefers-reduced-motion` fallback) and the
+ * sticky-header `scroll-margin`.
+ *
+ * This script only adds what CSS and anchors cannot:
+ *  - a smooth, header-aware scroll on an in-page jump;
+ *  - a brief highlight of the section body (the heading's following siblings up
+ *    to the next heading of equal or higher rank), so a deep link lands the
+ *    reader on the whole passage, not just the title;
+ *  - re-triggering the highlight when the same `#…` is activated again —
+ *    the one case a plain anchor click does nothing for, since the browser
+ *    won't navigate to a fragment that's already current;
+ *  - moving keyboard focus onto the heading so screen-reader users land on it.
+ *
+ * It deliberately does *not* intercept an ordinary click that changes the
+ * hash. `:target` is set only by a genuine same-document fragment
+ * navigation — never by `history.pushState` (a common trap: pushState
+ * updates the URL but leaves `:target`, and thus `heading-flash`, dark).
+ * Letting the click through and reacting to the `hashchange` it produces is
+ * what actually plays the highlight — see `KeyedFloatEnhancer.astro`, which
+ * this mirrors.
+ *
+ * Everything here is gated on `prefers-reduced-motion` and degrades to the
+ * native anchor behaviour if it throws.
+ */
+---
+
+<script>
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    const HEADINGS = 'h1, h2, h3, h4, h5, h6';
+    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const isContentHeading = (el: Element | null): el is HTMLElement =>
+      !!el && el.matches(HEADINGS) && root.contains(el);
+
+    const headingForId = (raw: string): HTMLElement | null => {
+      if (!raw) return null;
+      let id = raw;
+      try {
+        id = decodeURIComponent(raw);
+      } catch {
+        /* keep the raw value */
+      }
+      const el = document.getElementById(id);
+      return isContentHeading(el) ? el : null;
+    };
+
+    // Matches `global.css`'s `heading-flash` animation-duration; the buffer
+    // avoids clipping the CSS animation's own fade-out.
+    const FLASH_MS = 5200;
+
+    const flash = (el: Element | null) => {
+      if (!el || reduce.matches) return;
+      el.classList.remove('deep-link-section-flash');
+      void (el as HTMLElement).offsetWidth;
+      el.classList.add('deep-link-section-flash');
+      window.setTimeout(
+        () => el.classList.remove('deep-link-section-flash'),
+        FLASH_MS,
+      );
+    };
+
+    const sectionParts = (heading: HTMLElement): Element[] => {
+      const wrapper = heading.closest('.sl-heading-wrapper') ?? heading;
+      const rank = Number(heading.tagName[1]);
+      const parts: Element[] = [wrapper];
+      let node = wrapper.nextElementSibling;
+      while (node) {
+        const inner = node.matches(HEADINGS)
+          ? node
+          : node.querySelector(HEADINGS);
+        if (inner && Number(inner.tagName[1]) <= rank) break;
+        parts.push(node);
+        node = node.nextElementSibling;
+      }
+      return parts;
+    };
+
+    const activate = (heading: HTMLElement | null, doScroll: boolean) => {
+      if (!heading) return;
+      const parts = sectionParts(heading);
+      if (doScroll) {
+        parts[0].scrollIntoView({
+          behavior: reduce.matches ? 'auto' : 'smooth',
+          block: 'start',
+        });
+      }
+      for (const part of parts) flash(part);
+      heading.setAttribute('tabindex', '-1');
+      try {
+        heading.focus({ preventScroll: true });
+      } catch {
+        heading.focus();
+      }
+    };
+
+    root.addEventListener('click', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      const link = origin?.closest('a.sl-anchor-link');
+      if (!link) return;
+      const href = link.getAttribute('href') || '';
+      if (!href.startsWith('#')) return;
+      const heading = headingForId(href.slice(1));
+      if (!heading) return;
+      // Only the already-on-this-anchor click needs handling here — see
+      // `KeyedFloatEnhancer.astro`. Every other click is left to the browser's
+      // own fragment navigation, picked up below via `hashchange`.
+      if (location.hash === href) {
+        event.preventDefault();
+        activate(heading, true);
+      }
+    });
+
+    window.addEventListener('hashchange', () => {
+      activate(headingForId(location.hash.slice(1)), true);
+    });
+
+    const initial = headingForId(location.hash.slice(1));
+    if (initial) activate(initial, true);
+  })();
+</script>

package/src/components/starlight/KeyedFloatEnhancer.astro

@@ -0,0 +1,137 @@
+---
+/**
+ * Progressive enhancement for keyed floats — equations (Step D7), extended
+ * to `<Table>`/`<Figure>` (F-tables-figures). Generalizes the original
+ * equation-only `EquationEnhancer`: the scroll/focus/flash mechanics are
+ * unchanged, parameterized over `KINDS` below so a deep-link to `#eq-`,
+ * `#tab-`, or `#fig-` is handled the same way.
+ *
+ * The no-JS baseline is complete: `remark-notation` emits a real
+ * `id="eq-<key>"` / `id="tab-<key>"` / `id="fig-<key>"` container, a
+ * focusable number `<a>`, and a `[[…]]` reference renders a plain anchor;
+ * `global.css` does the `:target` deep-link highlight (with a
+ * `prefers-reduced-motion` fallback) and the sticky-header scroll offset via
+ * `scroll-margin`.
+ *
+ * This script only adds what CSS and anchors cannot:
+ *  - a smooth, header-aware scroll on an in-page jump;
+ *  - re-triggering the highlight when the same `#eq-…`/`#tab-…`/`#fig-…` is
+ *    activated again — the one case a plain anchor click does nothing for,
+ *    since the browser won't navigate to a fragment that's already current;
+ *  - moving keyboard focus onto the float so screen-reader users land on it;
+ *  - for an equation only, marking its number permanently visible
+ *    (`.eq-number-revealed`, styled in `global.css`) once the reader has
+ *    actually arrived at it, so it doesn't fade back down once the
+ *    `:target`/`:hover` state ends — a table/figure number isn't faded to
+ *    begin with (it's part of the always-visible caption), so it has
+ *    nothing to reveal.
+ *
+ * It deliberately does *not* intercept an ordinary click that changes the
+ * hash. `:target` is set only by a genuine same-document fragment
+ * navigation — never by `history.pushState` (a common trap: pushState
+ * updates the URL but leaves `:target`, and thus the flash, dark). Letting
+ * the click through and reacting to the `hashchange` it produces is what
+ * actually plays the highlight.
+ *
+ * Everything here is gated on `prefers-reduced-motion` and degrades to the
+ * native anchor behaviour if it throws.
+ */
+---
+
+<script>
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    interface Kind {
+      readonly prefix: string;
+      readonly triggerSelector: string;
+      readonly numberSelector: string;
+      readonly reveal: boolean;
+    }
+
+    const KINDS: readonly Kind[] = [
+      {
+        prefix: '#eq-',
+        triggerSelector: 'a.equation-ref, a.keyed-equation__number',
+        numberSelector: '.keyed-equation__number',
+        reveal: true,
+      },
+      {
+        prefix: '#tab-',
+        triggerSelector: 'a.table-ref, a.keyed-table__number',
+        numberSelector: '.keyed-table__number',
+        reveal: false,
+      },
+      {
+        prefix: '#fig-',
+        triggerSelector: 'a.figure-ref, a.keyed-figure__number',
+        numberSelector: '.keyed-figure__number',
+        reveal: false,
+      },
+    ];
+    const TRIGGER_SELECTOR = KINDS.map((kind) => kind.triggerSelector).join(', ');
+    const kindForHash = (hash: string) =>
+      KINDS.find((kind) => hash.startsWith(kind.prefix));
+
+    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const activate = (target: HTMLElement | null, doScroll: boolean, kind: Kind) => {
+      if (!target) return;
+      if (kind.reveal) {
+        target
+          .querySelector(kind.numberSelector)
+          ?.classList.add('eq-number-revealed');
+      }
+      if (!reduce.matches) {
+        // Restart the CSS `:target` animation even when the hash is unchanged.
+        target.style.animation = 'none';
+        void target.offsetWidth;
+        target.style.removeProperty('animation');
+      }
+      if (doScroll) {
+        target.scrollIntoView({
+          behavior: reduce.matches ? 'auto' : 'smooth',
+          block: 'start',
+        });
+      }
+      target.setAttribute('tabindex', '-1');
+      try {
+        target.focus({ preventScroll: true });
+      } catch {
+        target.focus();
+      }
+    };
+
+    root.addEventListener('click', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      const link = origin?.closest(TRIGGER_SELECTOR);
+      if (!link) return;
+      const href = link.getAttribute('href') || '';
+      const kind = kindForHash(href);
+      if (!kind) return; // cross-page or unrecognized: let the browser navigate
+      const target = document.getElementById(href.slice(1));
+      if (!target) return;
+      // Only the already-on-this-anchor click needs handling here — the
+      // browser has nothing new to navigate to, so it won't fire `hashchange`
+      // and nothing else will re-trigger the flash. Every other click is left
+      // alone: its native navigation sets `:target` and fires `hashchange`,
+      // which the listener below turns into the same `activate()`.
+      if (location.hash === href) {
+        event.preventDefault();
+        activate(target, true, kind);
+      }
+    });
+
+    window.addEventListener('hashchange', () => {
+      const kind = kindForHash(location.hash);
+      if (!kind) return;
+      activate(document.getElementById(location.hash.slice(1)), true, kind);
+    });
+
+    const initialKind = kindForHash(location.hash);
+    if (initialKind) {
+      activate(document.getElementById(location.hash.slice(1)), true, initialKind);
+    }
+  })();
+</script>

package/src/components/starlight/LayoutSocialIcons.astro

@@ -0,0 +1,12 @@
+---
+/**
+ * Starlight allows one `SocialIcons` override, so this composes the stock
+ * social-link row with the `[?]` About control (`AboutPanel.astro`). Both sit in
+ * the header's right cluster; the About panel is present on every route.
+ */
+import DefaultSocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
+import AboutPanel from './AboutPanel.astro';
+---
+
+<DefaultSocialIcons />
+<AboutPanel />

package/src/components/starlight/LessonFooter.astro

@@ -18,7 +18,9 @@ import NotationLayer, {
   type NotationLayerDefinition,
 } from '../notation/NotationLayer.astro';
 import CitationLayer from '../citation/CitationLayer.astro';
-import EquationEnhancer from './EquationEnhancer.astro';
+import KeyedFloatEnhancer from './KeyedFloatEnhancer.astro';
+import FloatRefLayer from '../reference/FloatRefLayer.astro';
+import HeadingAnchorEnhancer from './HeadingAnchorEnhancer.astro';
 
 // `lessonId` is no longer authored (Phase C2); derive it from the route.
 const routeSlug = Astro.locals.starlightRoute.entry.id;
@@ -39,6 +41,8 @@ if (lessonId) {
       label: definition.label,
       summary: definition.summary,
       formula: definition.formula,
+      formulaScope: definition.formulaScope,
+      glosses: definition.glosses,
       units: definition.units,
       seeAlso: definition.seeAlso,
       editorialStatus: definition.editorialStatus,
@@ -54,5 +58,7 @@ if (lessonId) {
 
 <NotationLayer definitions={definitions} />
 {lessonId && <CitationLayer />}
-{lessonId && <EquationEnhancer />}
+{lessonId && <KeyedFloatEnhancer />}
+{lessonId && <FloatRefLayer />}
+{lessonId && <HeadingAnchorEnhancer />}
 <DefaultFooter />

package/src/components/table/Table.astro

@@ -0,0 +1,104 @@
+---
+/**
+ * A referenceable table (F-tables-figures) — the table equivalent of a
+ * keyed display equation. `remark-notation.mjs` numbers every `<Table>` on a
+ * lesson page `‹chapter›.‹n›` (chapter = the lesson's course ordinal, `n`
+ * sequential over the lesson), keyed or not, and injects the resulting
+ * `number`/`anchorId` as props; this component only renders what it's given
+ * — it never computes its own number, same as `equationNode()`'s output for
+ * equations.
+ *
+ * An author sets `id` to make the table referenceable by name with
+ * `[[tab-<id>]]` (same page) or `[[lesson-slug#tab-<id>]]` (cross page); a
+ * table without `id` is still numbered and deep-linkable, just not
+ * referenceable by name — the same rule an unkeyed equation follows.
+ */
+export interface Props {
+  /** Stable key, e.g. `id="kinematics-summary"`. Omit for a positional-only table. */
+  id?: string;
+  /** Visible caption, shown below the table and in the hover-preview card. */
+  caption: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  number?: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+const { id, caption, number, anchorId } = Astro.props;
+
+if (typeof caption !== 'string' || !caption.trim()) {
+  throw new Error('Table requires a non-empty `caption` prop.');
+}
+if (!number || !anchorId) {
+  throw new Error(
+    'Table is missing its computed `number`/`anchorId` — this page must run remark-notation with a `tables` cross-page table configured (see astro.config.mjs).',
+  );
+}
+---
+
+<figure
+  class="keyed-table"
+  id={anchorId}
+  data-tab-number={number}
+  data-tab-key={id}
+>
+  <div class="keyed-table__body">
+    <slot />
+  </div>
+  <figcaption class="keyed-table__caption">
+    <a
+      class="keyed-table__number"
+      href={`#${anchorId}`}
+      aria-label={`Table ${number}`}>Table {number}</a
+    >
+    <span class="keyed-table__caption-text">{caption}</span>
+  </figcaption>
+</figure>
+
+<style>
+  .keyed-table {
+    margin-block: 1.5rem;
+    padding: 0;
+  }
+
+  .keyed-table__body {
+    overflow-x: auto;
+  }
+
+  .keyed-table__body :global(table) {
+    margin: 0;
+  }
+
+  .keyed-table__caption {
+    margin-block-start: 0.5rem;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+
+  .keyed-table__number {
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+  }
+
+  .keyed-table__number:hover,
+  .keyed-table__number:focus-visible {
+    text-decoration: underline;
+  }
+
+  .keyed-table__number:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  .keyed-table__caption-text::before {
+    content: ' — ';
+  }
+
+  @media print {
+    .keyed-table__number {
+      color: inherit;
+    }
+  }
+</style>