explico 0.12.0 → 0.13.1

package/src/components/starlight/LessonFooter.astro

@@ -7,8 +7,10 @@
  *
  * A page that is not a chapter (rule S10: the landing page, a part's overview
  * page) gets the card layers too — notation, citation, abbreviation and float
- * reference — from its own manifest bundle. The layers that serve a chapter's
- * numbered floats and outline stay on chapters.
+ * reference — from its own manifest bundle. Every layer registers on every
+ * course page, with nothing of its own to show or not, so a card carried in
+ * from another page can be built there (rule K5, `card-carry.ts`). The layers
+ * that serve a chapter's numbered floats and outline stay on chapters.
  *
  * The resolved notation bundle comes from the one compiler manifest (Phase
  * D5); this component never rebuilds the registry.
@@ -19,6 +21,7 @@ import { loadManifest } from '../../compiler/manifest';
 import {
   isLessonSlug,
   lessonIdFromSlug,
+  docsSlugsForRoute,
 } from '../../compiler/lesson-derivation';
 import NotationLayer, {
   type NotationLayerDefinition,
@@ -32,7 +35,9 @@ import AnchorScrollEnhancer from './AnchorScrollEnhancer.astro';
 import CollapsibleSections from './CollapsibleSections.astro';
 import TableOverflowExpander from '../table/TableOverflowExpander.astro';
 import DiagramEnhancer from './DiagramEnhancer.astro';
+import PrintController from './PrintController.astro';
 import {
+  derivedNotationForPage,
   notationDefinitionsForRenderedPage,
   pageNotationDependencies,
 } from '../../reference/page-notation';
@@ -45,13 +50,9 @@ const lessonId = isLessonSlug(routeSlug)
   : undefined;
 const manifest = await loadManifest();
 // A chapter, or a non-chapter page the manifest knows (not the 404 route).
-// The glob loader shortens `<dir>/index.mdx` to the id `<dir>`, and may give
-// the landing page an empty one, so match the page's docs slug either way.
-const routeSlugs = new Set(
-  routeSlug === '' ? ['index'] : [routeSlug, `${routeSlug}/index`],
-);
+const routeSlugs = docsSlugsForRoute(routeSlug);
 const pageId =
-  lessonId ?? manifest.pages.find((page) => routeSlugs.has(page.slug))?.id;
+  lessonId ?? manifest.pages.find((page) => routeSlugs.includes(page.slug))?.id;
 
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
@@ -109,8 +110,8 @@ if (pageId) {
       formulaScope: definition.formulaScope,
       glosses: definition.glosses,
       units: definition.units,
+      range: definition.range,
       seeAlso: definition.seeAlso,
-      editorialStatus: definition.editorialStatus,
       scope: definition.scope,
       href:
         definition.scope === 'shared'
@@ -118,13 +119,42 @@ if (pageId) {
           : `#notation-${definition.key}`,
     });
   }
+  // Rule N23: a derived card goes to its index entry's full definition.
+  for (const derived of derivedNotationForPage(
+    manifest,
+    pageId,
+    lessonId ? Astro.locals : undefined,
+  )) {
+    const index = definitions.find((definition) => definition.key === derived.index);
+    definitions.push({
+      key: derived.key,
+      notation: derived.notation,
+      label: derived.label,
+      summary: derived.summary,
+      formula: derived.formula,
+      formulaScope: derived.formulaScope,
+      glosses: derived.glosses,
+      units: derived.units,
+      scope: 'derived',
+      ...(index?.href === undefined ? {} : { href: index.href }),
+    });
+  }
 }
 ---
 
+{/* What the course says about its cards (`card-carry.ts`): carrying (K1),
+    and the base its carried set is stored under (K5). */}
+<div
+  hidden
+  data-explico-card-config
+  data-carry={String(manifest.cards.carry)}
+  data-base={import.meta.env.BASE_URL}
+></div>
 <NotationLayer
   definitions={definitions}
   defaultOpen={notationDefaultOpen}
   suspended={suspended}
+  page={routeSlug}
 />
 <AnchorScrollEnhancer />
 {pageId && <CitationLayer />}
@@ -135,6 +165,14 @@ if (pageId) {
 {lessonId && <TableOverflowExpander />}
 <DiagramEnhancer />
 {lessonId && <HeadingAnchorEnhancer />}
+{
+  pageId && manifest.lessonExports.print && (
+    <PrintController
+      canonicalBaseUrl={manifest.lessonExports.canonicalBaseUrl}
+      siteBaseUrl={import.meta.env.BASE_URL}
+    />
+  )
+}
 <div class="explico-site-footer" data-explico-export-chrome="site-footer">
   <DefaultFooter />
 </div>

package/src/components/starlight/PrintController.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * The page's print controller (`print-controller.ts`): what the Print
+ * button, Ctrl+P and Cmd+P run, and the site's URLs it moves links onto
+ * when printing. It sits in the page's footer, inside `<main>`, because a
+ * downloaded page keeps only `<main>` and must print the same way.
+ */
+interface Props {
+  canonicalBaseUrl?: string;
+  siteBaseUrl: string;
+}
+
+const { canonicalBaseUrl, siteBaseUrl } = Astro.props;
+---
+
+<div
+  hidden
+  data-explico-print-controller
+  data-canonical-base-url={canonicalBaseUrl}
+  data-site-base-url={siteBaseUrl}
+>
+</div>
+
+<script>
+  import { installPrintController } from './print-controller';
+
+  installPrintController();
+</script>

package/src/components/starlight/TextSizeControl.astro

@@ -0,0 +1,137 @@
+---
+/**
+ * The reader's text size on a touch screen: 100%, 90%, 80% or 70% of the
+ * site's own. A PC has the browser's zoom for this; a phone's text-size
+ * settings are buried in its browser's menus, so the page offers its own.
+ * It sits beside the theme switch (in the phone menu, and in the header
+ * of a tablet held wide) and shows only where there is no hover.
+ *
+ * The choice scales the root font size (`data-text-size` on `<html>`,
+ * `global.css`), so the text, the math, the spacing and the cards all
+ * follow. It is remembered per reader and copied onto the root before the
+ * page first paints by the inline script below, so the page never jumps
+ * from one size to another. `LayoutSocialIcons.astro` renders this in the
+ * header and in the phone menu; both copies stay in step.
+ */
+import { Icon } from '@astrojs/starlight/components';
+import { inlineRootAttributeScript } from '../../session/PreferenceStore';
+
+const TEXT_SIZE_KEY = 'explico:display:text-size';
+const SIZES = ['100', '90', '80', '70'] as const;
+const boot = inlineRootAttributeScript(TEXT_SIZE_KEY, 'data-text-size', SIZES.slice(1));
+---
+
+<script is:inline set:html={boot} />
+<label class="explico-text-size" data-text-size-control>
+  <span class="sr-only">Text size</span>
+  <span class="label-icon" aria-hidden="true">Aa</span>
+  <select autocomplete="off" data-text-size-select>
+    {SIZES.map((size) => <option value={size} selected={size === '100'}>{size}%</option>)}
+  </select>
+  <Icon name="down-caret" class="caret" />
+</label>
+
+<script>
+  import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+
+  const KEY = 'explico:display:text-size';
+  const SIZES = new Set(['100', '90', '80', '70']);
+  const preferences = createBrowserPreferenceStore();
+  const root = document.documentElement;
+  const selects = () =>
+    Array.from(document.querySelectorAll<HTMLSelectElement>('[data-text-size-select]'));
+
+  const current = (): string => {
+    const value = root.getAttribute('data-text-size') ?? '100';
+    return SIZES.has(value) ? value : '100';
+  };
+
+  const show = (value: string) => {
+    for (const select of selects()) select.value = value;
+  };
+
+  const choose = (value: string) => {
+    if (!SIZES.has(value)) return;
+    if (value === '100') {
+      root.removeAttribute('data-text-size');
+      preferences.remove?.(KEY);
+    } else {
+      root.setAttribute('data-text-size', value);
+      preferences.set(KEY, value);
+    }
+    show(value);
+  };
+
+  show(current());
+  for (const select of selects()) {
+    select.addEventListener('change', () => choose(select.value));
+  }
+  // A page restored from the back/forward cache keeps its old selects' values.
+  window.addEventListener('pageshow', () => show(current()));
+</script>
+
+<style>
+  @layer starlight.components {
+    /* Starlight's own select (`ThemeSelect`), with "Aa" for its icon. */
+    .explico-text-size {
+      --sl-label-icon-size: 0.875rem;
+      --sl-caret-size: 1.25rem;
+      --sl-inline-padding: 0.5rem;
+      --sl-select-width: 5.5em;
+      position: relative;
+      display: none;
+      align-items: center;
+      gap: 0.25rem;
+      color: var(--sl-color-gray-2);
+    }
+
+    @media (hover: none) {
+      .explico-text-size {
+        display: flex;
+      }
+    }
+
+    .explico-text-size:hover {
+      color: var(--sl-color-white);
+    }
+
+    .label-icon,
+    .explico-text-size :global(.caret) {
+      position: absolute;
+      top: 50%;
+      transform: translateY(-50%);
+      pointer-events: none;
+    }
+
+    .label-icon {
+      inset-inline-start: 0;
+      font-size: var(--sl-label-icon-size);
+      font-weight: 600;
+      letter-spacing: -0.02em;
+    }
+
+    .explico-text-size :global(.caret) {
+      inset-inline-end: 0;
+      font-size: var(--sl-caret-size);
+    }
+
+    /* As tall as the icon buttons beside it, so the row keeps its height. */
+    select {
+      border: 0;
+      padding-block: 0.25rem;
+      padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.5rem)
+        calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
+      margin-inline: calc(var(--sl-inline-padding) * -1);
+      width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
+      background-color: transparent;
+      color: inherit;
+      cursor: pointer;
+      appearance: none;
+    }
+
+    option {
+      background-color: var(--sl-color-bg-nav);
+      color: var(--sl-color-gray-1);
+    }
+  }
+</style>

package/src/components/starlight/print-controller.ts

@@ -0,0 +1,380 @@
+/**
+ * The page's print controller, shared by the header's Print button and the
+ * page itself. The button, Ctrl+P and Cmd+P prepare the page as shown
+ * (`../disclosure/print-as-shown`), move its links onto the deployed site,
+ * load every lab that will be on paper and then open the print dialog; the
+ * browser's own File → Print gets the same preparation without loading
+ * labs. The figure capture fires `explico:prepare-static-export` in
+ * `markdown` mode, which opens everything.
+ *
+ * `PrintController.astro` installs it from the page's footer, inside
+ * `<main>`, with the `[data-explico-print-controller]` element that holds
+ * the site's URLs: a downloaded page keeps only `<main>`, so it prints the
+ * same way.
+ */
+import {
+  prepareDisclosures,
+  type PreparedDisclosures,
+} from '../disclosure/print-as-shown';
+
+type SavedLink = {
+  readonly element: HTMLAnchorElement;
+  readonly href: string | null;
+};
+
+type SavedHidden = {
+  readonly element: HTMLElement;
+  readonly hidden: HTMLElement['hidden'];
+};
+
+type StaticExportMode = 'print' | 'markdown';
+
+type PreparedStaticExport = {
+  readonly mode: StaticExportMode;
+  readonly disclosures: PreparedDisclosures;
+  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;
+  }
+
+  return canonicalUrl(target, canonicalBaseUrl, siteBaseUrl);
+}
+
+// A same-site URL moved onto the deployed site, so a printed or saved
+// lesson's links don't point at whatever host the reader printed from.
+function canonicalUrl(
+  target: URL,
+  canonicalBaseUrl: string | undefined,
+  siteBaseUrl: string,
+): string {
+  if (!canonicalBaseUrl || target.origin !== location.origin) return target.href;
+  const normalizedSiteBase = `/${siteBaseUrl.replace(/^\/+|\/+$/gu, '')}/`;
+  const relativePath = target.pathname.startsWith(normalizedSiteBase)
+    ? target.pathname.slice(normalizedSiteBase.length)
+    : target.pathname.replace(/^\/+/, '');
+  return new URL(
+    `${relativePath}${target.search}${target.hash}`,
+    canonicalBaseUrl,
+  ).href;
+}
+
+function prepareStaticExport(mode: StaticExportMode): void {
+  if (prepared) return;
+  const printController = controller();
+  if (!printController) return;
+  pendingMarkerCleanup?.();
+
+  root.dataset.explicoStaticExport = mode;
+
+  const canonicalBaseUrl = printController.dataset.canonicalBaseUrl;
+  const siteBaseUrl = printController.dataset.siteBaseUrl ?? '/';
+
+  // Print follows the screen (see `../disclosure/print-as-shown`); a
+  // Markdown export needs every word whatever the reader collapsed.
+  const disclosures = prepareDisclosures(
+    mode === 'print' ? 'as-shown' : 'expanded',
+    {
+      noteHref: (anchorId) => {
+        const page = new URL(location.href);
+        page.hash = anchorId ? `#${anchorId}` : '';
+        return canonicalUrl(page, canonicalBaseUrl, siteBaseUrl);
+      },
+    },
+  );
+
+  // Rows beyond a long table's fold and an open example set's inactive
+  // tabs are hidden only to save screen space, so they are exposed for
+  // print too. A closed short note or question is a reader's disclosure:
+  // print leaves it closed (with its note), only Markdown export opens it.
+  const hiddenSelector =
+    mode === 'print'
+      ? 'main :is(.compact-example, .keyed-table__body tr:not(.keyed-table__more-row))[hidden]'
+      : 'main :is(.assessment-panel, .short-note, .compact-example, .keyed-table__body tr:not(.keyed-table__more-row))[hidden]';
+  const hidden = Array.from(
+    document.querySelectorAll<HTMLElement>(hiddenSelector),
+    (element): SavedHidden => {
+      const saved = { element, hidden: element.hidden };
+      element.hidden = false;
+      return saved;
+    },
+  );
+
+  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, disclosures, hidden, links };
+  if (mode === 'print') root.dataset.explicoPrintReady = '';
+}
+
+function restoreStaticExport(): void {
+  const saved = prepared;
+  if (!saved) return;
+  prepared = null;
+
+  saved.disclosures.restore();
+  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;
+    saved.disclosures.releaseMarkers();
+    delete root.dataset.explicoStaticExport;
+    pendingMarkerCleanup = null;
+  };
+  pendingMarkerCleanup = cleanupMarkers;
+  window.setTimeout(cleanupMarkers, 0);
+}
+
+function afterNextPaint(): Promise<void> {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+  });
+}
+
+/** `promise`, or nothing after `ms` — a slow resource never holds the dialog back. */
+function atMost(promise: Promise<unknown>, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = window.setTimeout(resolve, ms);
+    void promise.then(
+      () => {
+        window.clearTimeout(timer);
+        resolve();
+      },
+      () => {
+        window.clearTimeout(timer);
+        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> {
+  // Only islands that will be on paper: one inside a disclosure the reader
+  // left closed (print follows the screen) never gets a layout box, so it
+  // can never become visible, and waiting on it would stall the dialog for
+  // `waitForIslandHydration`'s full timeout. A lab's tools never print.
+  const islands = Array.from(
+    document.querySelectorAll<HTMLElement>('main astro-island[ssr][client="visible"]'),
+  ).filter((island) => !island.closest('details:not([open]), [hidden], [data-print-omit]'));
+  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;
+  // A lazy image the reader never scrolled to would never load, and the
+  // wait below would never end: load it now, and give up after a while.
+  const images = Array.from(document.querySelectorAll<HTMLImageElement>('main img'));
+  for (const image of images) {
+    if (image.loading === 'lazy') image.loading = 'eager';
+  }
+  await atMost(
+    Promise.all(
+      images.map((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();
+      }),
+    ),
+    5_000,
+  );
+  // React chart effects and SVG layout settle after island hydration.
+  await afterNextPaint();
+}
+
+let printing = false;
+
+/** Prepare the page, load what will be on paper, then open the print dialog. */
+export async function printPage(button?: HTMLButtonElement): Promise<void> {
+  if (printing) return;
+  printing = true;
+  if (button) {
+    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 {
+    printing = false;
+    if (button) {
+      button.disabled = false;
+      button.removeAttribute('aria-busy');
+    }
+  }
+}
+
+/**
+ * Wire the page once: the prepare and restore events, the browser's own
+ * print, and Ctrl+P / Cmd+P, which run the Print button's steps.
+ */
+export function installPrintController(): void {
+  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();
+
+    // Ctrl+P / Cmd+P run the Print button's steps: the browser's own dialog
+    // cannot wait for an off-screen lab to load.
+    window.addEventListener(
+      'keydown',
+      (event) => {
+        if (
+          !(event.ctrlKey || event.metaKey) ||
+          event.altKey ||
+          event.shiftKey ||
+          event.key.toLowerCase() !== 'p'
+        ) {
+          return;
+        }
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        void printPage(
+          document.querySelector<HTMLButtonElement>('[data-explico-print-action]') ?? undefined,
+        );
+      },
+      { capture: true },
+    );
+  }
+}