explico 0.2.0 → 0.4.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

@@ -1,7 +1,7 @@
 ---
 /**
  * Progressive enhancement for content-heading deep links (Step F3), the sibling
- * of `EquationEnhancer.astro`.
+ * 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
@@ -24,7 +24,7 @@
  * 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 `EquationEnhancer.astro`, which
+ * what actually plays the highlight — see `KeyedFloatEnhancer.astro`, which
  * this mirrors.
  *
  * Everything here is gated on `prefers-reduced-motion` and degrades to the
@@ -113,7 +113,7 @@
       const heading = headingForId(href.slice(1));
       if (!heading) return;
       // Only the already-on-this-anchor click needs handling here — see
-      // `EquationEnhancer.astro`. Every other click is left to the browser's
+      // `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();

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/LayoutSidebar.astro

@@ -23,7 +23,68 @@ import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
       size="1rem"
     />
   </button>
-  <div id="starlight__navigation-content" class="layout-navigation-content">
+  <div
+    id="starlight__navigation-content"
+    class="layout-navigation-content layout-compact-sidebar"
+  >
     <DefaultSidebar />
+    <script>
+      import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+
+      (() => {
+        if (!matchMedia('(min-width: 50rem)').matches) return;
+        const root = document.querySelector('#starlight__navigation-content');
+        const stateRoot = root?.querySelector('sl-sidebar-state-persist');
+        if (!stateRoot) return;
+
+        const groups = [
+          ...stateRoot.querySelectorAll(':scope > ul > li > details'),
+        ];
+        const storageKey = 'explico-sidebar-groups';
+        const preferences = createBrowserPreferenceStore();
+        let compact = groups.map(() => true);
+        try {
+          const saved = JSON.parse(preferences.get(storageKey) || 'null');
+          if (
+            saved?.hash === stateRoot.dataset.hash &&
+            Array.isArray(saved.compact)
+          ) {
+            compact = groups.map((_, index) => saved.compact[index] !== false);
+          }
+        } catch {}
+
+        const save = () => {
+          try {
+            preferences.set(
+              storageKey,
+              JSON.stringify({
+                hash: stateRoot.dataset.hash,
+                compact: groups.map((group) => group.hasAttribute('data-compact')),
+              }),
+            );
+          } catch {}
+        };
+
+        groups.forEach((group, index) => {
+          // The links remain rendered and operable in compact mode; only their
+          // labels collapse. Keep <details> open so this stays true for assistive
+          // technology as well as pointer users.
+          group.setAttribute('open', '');
+          group.toggleAttribute('data-compact', compact[index]);
+          const summary = group.querySelector(':scope > summary');
+          summary?.setAttribute('aria-expanded', String(!compact[index]));
+          summary?.addEventListener('click', (event) => {
+            event.preventDefault();
+            group.toggleAttribute('data-compact');
+            group.setAttribute('open', '');
+            summary.setAttribute(
+              'aria-expanded',
+              String(!group.hasAttribute('data-compact')),
+            );
+            save();
+          });
+        });
+      })();
+    </script>
   </div>
 </div>

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

@@ -9,6 +9,7 @@
  * D5); this component never rebuilds the registry.
  */
 import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+import { assertLocalNotationParity } from '../../compiler/astro';
 import { loadManifest } from '../../compiler/manifest';
 import {
   isLessonSlug,
@@ -18,7 +19,8 @@ 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.
@@ -33,6 +35,16 @@ const definitions: NotationLayerDefinition[] = [];
 if (lessonId) {
   const manifest = await loadManifest();
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  const routeData = Astro.locals.starlightRoute.entry.data as {
+    notation?: { local?: readonly { key?: unknown }[] };
+  };
+  const authoredLocalKeys = (routeData.notation?.local ?? [])
+    .map((entry) => entry.key)
+    .filter((key): key is string => typeof key === 'string');
+  const renderedLocalKeys = (lesson?.notation.definitions ?? [])
+    .filter((definition) => definition.scope === 'local')
+    .map((definition) => definition.key);
+  assertLocalNotationParity(lessonId, authoredLocalKeys, renderedLocalKeys);
   for (const definition of lesson?.notation.definitions ?? []) {
     definitions.push({
       key: definition.key,
@@ -57,6 +69,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,105 @@
+---
+/**
+ * A referenceable table (F-tables-figures) — the table equivalent of a
+ * keyed display equation. `remark-notation.mjs` numbers every `<Table>` on a
+ * lesson page `‹part›.‹n›` (the part is the sidebar group's ordinal, `n`
+ * sequential over every `<Table>` in that part — see
+ * `docs/authoring/structure.md`), 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>