explico 0.4.0 → 0.6.0

package/src/components/starlight/LessonExportActions.astro

@@ -0,0 +1,436 @@
+---
+interface Props {
+  standaloneDownload?: {
+    readonly href: string;
+    readonly filename: string;
+  };
+  print: boolean;
+  canonicalBaseUrl?: string;
+  siteBaseUrl: string;
+}
+
+const {
+  standaloneDownload,
+  print,
+  canonicalBaseUrl,
+  siteBaseUrl,
+} = Astro.props;
+---
+
+<nav
+  class="lesson-export-actions not-content"
+  aria-label="Lesson exports"
+  data-explico-export-chrome="lesson-actions"
+  data-explico-print-controller={print ? '' : undefined}
+  data-canonical-base-url={canonicalBaseUrl}
+  data-site-base-url={siteBaseUrl}
+>
+  {
+    standaloneDownload && (
+      <a
+        href={standaloneDownload.href}
+        download={standaloneDownload.filename}
+        aria-label="Download this lesson as standalone HTML"
+        title="Download this lesson as standalone HTML"
+      >
+        <svg viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M12 3v12m0 0 4-4m-4 4-4-4M5 19h14" />
+        </svg>
+      </a>
+    )
+  }
+  {
+    print && (
+      <button
+        type="button"
+        data-explico-print-action
+        aria-label="Print or save this lesson as PDF"
+        title="Print or save this lesson as PDF"
+      >
+        <svg viewBox="0 0 24 24" aria-hidden="true">
+          <path d="M7 9V3h10v6M7 17H5a2 2 0 0 1-2-2v-4a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v4a2 2 0 0 1-2 2h-2M7 14h10v7H7z" />
+        </svg>
+      </button>
+    )
+  }
+</nav>
+
+<style>
+  .lesson-export-actions {
+    display: inline-flex;
+  }
+
+  .lesson-export-actions a,
+  .lesson-export-actions button {
+    align-items: center;
+    background: transparent;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    color: var(--sl-color-gray-1);
+    cursor: pointer;
+    display: inline-flex;
+    font: inherit;
+    height: 1.75rem;
+    justify-content: center;
+    padding: 0;
+    text-decoration: none;
+    width: 1.75rem;
+  }
+
+  .lesson-export-actions svg {
+    fill: none;
+    height: 1rem;
+    stroke: currentColor;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    stroke-width: 1.75;
+    width: 1rem;
+  }
+
+  .lesson-export-actions :is(a, button):hover,
+  .lesson-export-actions :is(a, button):focus-visible {
+    border-color: var(--sl-color-accent);
+    color: var(--sl-color-text-accent);
+  }
+
+  .lesson-export-actions :is(a, button):focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 2px;
+  }
+</style>
+
+<script>
+  type SavedDetails = {
+    readonly element: HTMLDetailsElement;
+    readonly open: boolean;
+    readonly state: string | undefined;
+    readonly style: string | null;
+    readonly body: HTMLElement | null;
+    readonly bodyStyle: string | null;
+    readonly temporaryMarker: string | null;
+  };
+
+  type SavedLink = {
+    readonly element: HTMLAnchorElement;
+    readonly href: string | null;
+  };
+
+  type SavedHidden = {
+    readonly element: HTMLElement;
+    readonly hidden: boolean;
+  };
+
+  type StaticExportMode = 'print' | 'markdown';
+
+  type PreparedStaticExport = {
+    readonly mode: StaticExportMode;
+    readonly details: readonly SavedDetails[];
+    readonly hidden: readonly SavedHidden[];
+    readonly links: readonly SavedLink[];
+  };
+
+  const root = document.documentElement;
+  let prepared: PreparedStaticExport | null = null;
+  let pendingMarkerCleanup: (() => void) | null = null;
+
+  function controller(): HTMLElement | null {
+    return document.querySelector<HTMLElement>('[data-explico-print-controller]');
+  }
+
+  function canonicalPrintHref(
+    link: HTMLAnchorElement,
+    canonicalBaseUrl: string | undefined,
+    siteBaseUrl: string,
+  ): string | undefined {
+    const rawHref = link.getAttribute('href');
+    if (!rawHref || rawHref.startsWith('#') || link.hasAttribute('download')) {
+      return undefined;
+    }
+
+    let target: URL;
+    try {
+      target = new URL(rawHref, location.href);
+    } catch {
+      return undefined;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') return undefined;
+
+    const current = new URL(location.href);
+    if (
+      target.origin === current.origin &&
+      target.pathname === current.pathname &&
+      target.search === current.search
+    ) {
+      return undefined;
+    }
+
+    let result = target.href;
+    if (canonicalBaseUrl && target.origin === current.origin) {
+      const normalizedSiteBase = `/${siteBaseUrl.replace(/^\/+|\/+$/gu, '')}/`;
+      const relativePath = target.pathname.startsWith(normalizedSiteBase)
+        ? target.pathname.slice(normalizedSiteBase.length)
+        : target.pathname.replace(/^\/+/, '');
+      result = new URL(
+        `${relativePath}${target.search}${target.hash}`,
+        canonicalBaseUrl,
+      ).href;
+    }
+
+    return result;
+  }
+
+  function prepareStaticExport(mode: StaticExportMode): void {
+    if (prepared) return;
+    const printController = controller();
+    if (!printController) return;
+    pendingMarkerCleanup?.();
+
+    root.dataset.explicoStaticExport = mode;
+
+    const details = Array.from(
+      document.querySelectorAll<HTMLDetailsElement>('main details'),
+      (element): SavedDetails => {
+        const body = element.querySelector<HTMLElement>(
+          ':scope > .sl-section-body, :scope > .diagram__body',
+        );
+        const saved = {
+          element,
+          open: element.open,
+          state: element.dataset.state,
+          style: element.getAttribute('style'),
+          body,
+          bodyStyle: body?.getAttribute('style') ?? null,
+          temporaryMarker: element.getAttribute('data-explico-temporary-open'),
+        };
+        element.dataset.explicoTemporaryOpen = mode;
+        element.open = true;
+        if (element.dataset.state !== undefined) element.dataset.state = 'open';
+        body?.style.removeProperty('max-height');
+        body?.style.removeProperty('overflow');
+        body?.style.removeProperty('transition');
+        return saved;
+      },
+    );
+
+    const hidden = Array.from(
+      document.querySelectorAll<HTMLElement>(
+        'main :is(.assessment-panel, .short-note, .compact-example, .keyed-table__body tr:not(.keyed-table__more-row))[hidden]',
+      ),
+      (element): SavedHidden => {
+        const saved = { element, hidden: element.hidden };
+        element.hidden = false;
+        return saved;
+      },
+    );
+
+    const canonicalBaseUrl = printController.dataset.canonicalBaseUrl;
+    const siteBaseUrl = printController.dataset.siteBaseUrl ?? '/';
+    const links =
+      mode === 'print'
+        ? Array.from(
+            document.querySelectorAll<HTMLAnchorElement>('main a[href]'),
+          ).flatMap((element): SavedLink[] => {
+            const printHref = canonicalPrintHref(
+              element,
+              canonicalBaseUrl,
+              siteBaseUrl,
+            );
+            if (!printHref) return [];
+            const saved = {
+              element,
+              href: element.getAttribute('href'),
+            };
+            // PDF viewers retain anchors as clickable annotations. Point the
+            // anchor itself at the deployed lesson while printing; no visible
+            // URL suffix is needed in the document text.
+            element.setAttribute('href', printHref);
+            return [saved];
+          })
+        : [];
+
+    prepared = { mode, details, hidden, links };
+    if (mode === 'print') root.dataset.explicoPrintReady = '';
+  }
+
+  function restoreStaticExport(): void {
+    const saved = prepared;
+    if (!saved) return;
+    prepared = null;
+
+    for (const state of saved.details) {
+      state.element.open = state.open;
+      if (state.state === undefined) delete state.element.dataset.state;
+      else state.element.dataset.state = state.state;
+      if (state.style === null) state.element.removeAttribute('style');
+      else state.element.setAttribute('style', state.style);
+      if (state.body) {
+        if (state.bodyStyle === null) state.body.removeAttribute('style');
+        else state.body.setAttribute('style', state.bodyStyle);
+      }
+    }
+    for (const state of saved.hidden) state.element.hidden = state.hidden;
+    for (const state of saved.links) {
+      if (state.href === null) state.element.removeAttribute('href');
+      else state.element.setAttribute('href', state.href);
+    }
+    delete root.dataset.explicoPrintReady;
+
+    // Native `toggle` is queued after changing `.open`. Keep the temporary
+    // marker through that task so disclosure persistence ignores both the
+    // prepare and restore mutations.
+    const cleanupMarkers = () => {
+      if (pendingMarkerCleanup !== cleanupMarkers) return;
+      for (const state of saved.details) {
+        if (state.temporaryMarker === null) {
+          state.element.removeAttribute('data-explico-temporary-open');
+        } else {
+          state.element.setAttribute(
+            'data-explico-temporary-open',
+            state.temporaryMarker,
+          );
+        }
+      }
+      delete root.dataset.explicoStaticExport;
+      pendingMarkerCleanup = null;
+    };
+    pendingMarkerCleanup = cleanupMarkers;
+    window.setTimeout(cleanupMarkers, 0);
+  }
+
+  function afterNextPaint(): Promise<void> {
+    return new Promise((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  }
+
+  function waitForIslandHydration(island: HTMLElement): Promise<void> {
+    if (!island.hasAttribute('ssr')) return Promise.resolve();
+
+    return new Promise((resolve) => {
+      let timeout = 0;
+      const finish = () => {
+        window.clearTimeout(timeout);
+        island.removeEventListener('astro:hydrate', finish);
+        island.removeEventListener('astro:hydration-error', finish);
+        resolve();
+      };
+      island.addEventListener('astro:hydrate', finish, { once: true });
+      island.addEventListener('astro:hydration-error', finish, { once: true });
+      timeout = window.setTimeout(finish, 10_000);
+      requestAnimationFrame(() => {
+        if (!island.hasAttribute('ssr')) finish();
+      });
+    });
+  }
+
+  async function hydrateVisibleIslandsForPrint(): Promise<void> {
+    const islands = Array.from(
+      document.querySelectorAll<HTMLElement>('main astro-island[ssr][client="visible"]'),
+    );
+    if (islands.length === 0) return;
+
+    const scrollX = window.scrollX;
+    const scrollY = window.scrollY;
+    const scrollBehavior = root.style.scrollBehavior;
+    root.style.scrollBehavior = 'auto';
+    try {
+      // `client:visible` deliberately does not hydrate an off-screen plot.
+      // Visit each island briefly so its normal Astro directive runs before
+      // the browser snapshots the document for printing.
+      for (const island of islands) {
+        if (!island.isConnected || !island.hasAttribute('ssr')) continue;
+        const hydrated = waitForIslandHydration(island);
+        // Astro's `client:visible` directive observes an island's children,
+        // while the custom-element wrapper itself may have no layout box.
+        (island.firstElementChild ?? island).scrollIntoView({
+          block: 'center',
+          inline: 'nearest',
+        });
+        await hydrated;
+      }
+    } finally {
+      window.scrollTo({ left: scrollX, top: scrollY, behavior: 'auto' });
+      root.style.scrollBehavior = scrollBehavior;
+    }
+  }
+
+  async function waitForPrintVisuals(): Promise<void> {
+    await hydrateVisibleIslandsForPrint();
+    await document.fonts?.ready;
+    await Promise.all(
+      Array.from(document.querySelectorAll<HTMLImageElement>('main img'), (image) => {
+        if (!image.complete) {
+          return new Promise<void>((resolve) => {
+            image.addEventListener('load', () => resolve(), { once: true });
+            image.addEventListener('error', () => resolve(), { once: true });
+          });
+        }
+        return typeof image.decode === 'function'
+          ? image.decode().catch(() => undefined)
+          : Promise.resolve();
+      }),
+    );
+    // React chart effects and SVG layout settle after island hydration.
+    await afterNextPaint();
+  }
+
+  function wirePrintActions(): void {
+    document
+      .querySelectorAll<HTMLButtonElement>(
+        '[data-explico-print-action]:not([data-explico-print-wired])',
+      )
+      .forEach((button) => {
+        button.dataset.explicoPrintWired = '';
+        button.addEventListener('click', async () => {
+          button.disabled = true;
+          button.setAttribute('aria-busy', 'true');
+          window.dispatchEvent(
+            new CustomEvent('explico:prepare-static-export', {
+              detail: { mode: 'print' },
+            }),
+          );
+          try {
+            await waitForPrintVisuals();
+            window.print();
+          } finally {
+            button.disabled = false;
+            button.removeAttribute('aria-busy');
+          }
+        });
+      });
+  }
+
+  wirePrintActions();
+  document.addEventListener('astro:page-load', wirePrintActions);
+
+  if (!root.hasAttribute('data-explico-print-controller-wired')) {
+    root.dataset.explicoPrintControllerWired = '';
+    const printMedia = window.matchMedia('print');
+    window.addEventListener('explico:prepare-static-export', (event) => {
+      const mode = (event as CustomEvent<{ mode?: unknown }>).detail?.mode;
+      prepareStaticExport(mode === 'markdown' ? 'markdown' : 'print');
+    });
+    window.addEventListener('explico:restore-static-export', restoreStaticExport);
+    const requestPrintPreparation = () => {
+      window.dispatchEvent(
+        new CustomEvent('explico:prepare-static-export', {
+          detail: { mode: 'print' },
+        }),
+      );
+    };
+    const requestPrintRestore = () => {
+      window.dispatchEvent(
+        new CustomEvent('explico:restore-static-export', {
+          detail: { mode: 'print' },
+        }),
+      );
+    };
+    window.addEventListener('beforeprint', requestPrintPreparation);
+    window.addEventListener('afterprint', requestPrintRestore);
+    printMedia.addEventListener('change', (event) => {
+      if (event.matches) requestPrintPreparation();
+      else requestPrintRestore();
+    });
+    if (printMedia.matches) requestPrintPreparation();
+  }
+</script>

package/src/components/starlight/LessonFooter.astro

@@ -19,9 +19,17 @@ import NotationLayer, {
   type NotationLayerDefinition,
 } from '../notation/NotationLayer.astro';
 import CitationLayer from '../citation/CitationLayer.astro';
+import AbbreviationLayer from '../abbreviation/AbbreviationLayer.astro';
 import KeyedFloatEnhancer from './KeyedFloatEnhancer.astro';
 import FloatRefLayer from '../reference/FloatRefLayer.astro';
 import HeadingAnchorEnhancer from './HeadingAnchorEnhancer.astro';
+import CollapsibleSections from './CollapsibleSections.astro';
+import TableOverflowExpander from '../table/TableOverflowExpander.astro';
+import DiagramEnhancer from './DiagramEnhancer.astro';
+import {
+  notationDefinitionsForRenderedPage,
+  pageNotationDependencies,
+} from '../../reference/page-notation';
 
 // `lessonId` is no longer authored (Phase C2); derive it from the route.
 const routeSlug = Astro.locals.starlightRoute.entry.id;
@@ -32,8 +40,10 @@ const lessonId = isLessonSlug(routeSlug)
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
 const definitions: NotationLayerDefinition[] = [];
+let notationDefaultOpen = false;
 if (lessonId) {
   const manifest = await loadManifest();
+  notationDefaultOpen = manifest.disclosureDefaults.notation;
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
   const routeData = Astro.locals.starlightRoute.entry.data as {
     notation?: { local?: readonly { key?: unknown }[] };
@@ -45,7 +55,12 @@ if (lessonId) {
     .filter((definition) => definition.scope === 'local')
     .map((definition) => definition.key);
   assertLocalNotationParity(lessonId, authoredLocalKeys, renderedLocalKeys);
-  for (const definition of lesson?.notation.definitions ?? []) {
+  const renderedDefinitions = notationDefinitionsForRenderedPage(
+    manifest,
+    lessonId,
+    pageNotationDependencies(Astro.locals),
+  );
+  for (const definition of renderedDefinitions) {
     definitions.push({
       key: definition.key,
       notation: definition.notation,
@@ -67,9 +82,21 @@ if (lessonId) {
 }
 ---
 
-<NotationLayer definitions={definitions} />
+<NotationLayer definitions={definitions} defaultOpen={notationDefaultOpen} />
 {lessonId && <CitationLayer />}
+{lessonId && <AbbreviationLayer />}
 {lessonId && <KeyedFloatEnhancer />}
 {lessonId && <FloatRefLayer />}
+{lessonId && <CollapsibleSections />}
+{lessonId && <TableOverflowExpander />}
+<DiagramEnhancer />
 {lessonId && <HeadingAnchorEnhancer />}
-<DefaultFooter />
+<div class="explico-site-footer" data-explico-export-chrome="site-footer">
+  <DefaultFooter />
+</div>
+
+<style>
+  .explico-site-footer {
+    display: contents;
+  }
+</style>

package/src/components/starlight/section-parts.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared boundary-finding for a heading's "section": its `.sl-heading-wrapper`
+ * (see `rehype-heading-anchors.mjs`) plus every following sibling up to (not
+ * including) the next heading of equal or higher rank.
+ *
+ * Extracted so `HeadingAnchorEnhancer.astro` (deep-link flash) and
+ * `CollapsibleSections.astro` (Part 3 of
+ * `docs/plans/collapsible-disclosure.md`) share one algorithm instead of two
+ * copies drifting apart. Works unchanged when a section's body already
+ * contains a nested, already-wrapped `<details class="sl-section-collapsible">`
+ * for a deeper heading: `querySelector` finds the nested heading regardless of
+ * depth, so `CollapsibleSections.astro` can process headings deepest-rank
+ * first and have each parent's walk see its already-wrapped children as
+ * ordinary siblings.
+ */
+
+export const HEADINGS = 'h1, h2, h3, h4, h5, h6';
+
+export function 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;
+}