explico 0.8.0 → 0.11.0

package/src/components/starlight/LayoutSidebar.astro

@@ -1,6 +1,24 @@
 ---
-import { Icon } from '@astrojs/starlight/components';
 import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
+import { loadManifest } from '../../compiler/manifest';
+
+/**
+ * The header control that opens a part's own page. Starlight's sidebar group
+ * is a label and a list with no link of its own, and the label here already
+ * owns a click (it collapses the part), so the control is added beside the
+ * caret rather than taking either. It is an enhancement on top of the
+ * `Overview` row the compiler puts in the group's list: that row is in the
+ * HTML, so the part page is reachable, keyboard-operable and crawlable with
+ * this script disabled.
+ */
+const manifest = await loadManifest();
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const partLinks = manifest.parts
+  .filter((part) => part.overview !== undefined)
+  .map((part) => ({ label: part.label, href: `${base}${part.link}` }));
+// `<` keeps a label that happens to contain `</script>` from ending the
+// element early. It is still the same JSON to `JSON.parse`.
+const partLinkPayload = JSON.stringify(partLinks).replace(/</g, '\\u003c');
 ---
 
 <div class="layout-navigation-panel" data-layout-panel="navigation">
@@ -12,22 +30,127 @@ import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
     data-layout-toggle="navigation"
     hidden
   >
-    <Icon
-      name="left-caret"
-      class="layout-edge-icon layout-edge-icon-hide"
-      size="1rem"
-    />
-    <Icon
-      name="right-caret"
-      class="layout-edge-icon layout-edge-icon-restore"
-      size="1rem"
-    />
+    <span class="layout-edge-glyph layout-edge-glyph-hide" aria-hidden="true"
+      >&lt;&lt;&lt;</span
+    >
+    <span class="layout-edge-glyph layout-edge-glyph-restore" aria-hidden="true"
+      >&gt;&gt;&gt;</span
+    >
   </button>
+  <div
+    class="layout-edge-resizer layout-navigation-resizer"
+    role="separator"
+    aria-orientation="vertical"
+    aria-controls="starlight__navigation-content"
+    aria-label="Navigation width"
+    tabindex="0"
+    data-layout-resizer="navigation"
+    hidden
+  >
+  </div>
   <div
     id="starlight__navigation-content"
     class="layout-navigation-content layout-compact-sidebar"
   >
     <DefaultSidebar />
+    {
+      partLinks.length > 0 && (
+        <script
+          is:inline
+          type="application/json"
+          data-explico-part-links
+          set:html={partLinkPayload}
+        />
+      )
+    }
+    <script>
+      /**
+       * Give each part header a control that opens the part's own page. The
+       * labels come from the manifest, so a group is matched by the text
+       * Starlight rendered for it rather than by position — the Reference
+       * group and any part without an overview page simply never match.
+       *
+       * The link is a sibling of `<summary>`, drawn over the end of the header
+       * row, not a child of it: `<summary>` is itself an interactive control,
+       * and a link inside one is `nested-interactive` — announced
+       * inconsistently by screen readers, and a focus trap for some assistive
+       * technology. Out here it is an ordinary link that happens to sit in the
+       * header, and a click on it never reaches the summary's collapse.
+       */
+      (() => {
+        const payload = document.querySelector('[data-explico-part-links]');
+        if (!payload?.textContent) return;
+
+        let links: { label: string; href: string }[] = [];
+        try {
+          links = JSON.parse(payload.textContent);
+        } catch {
+          return;
+        }
+        const hrefByLabel = new Map(
+          links.map((link) => [link.label.trim(), link.href]),
+        );
+
+        const root = document.querySelector('#starlight__navigation-content');
+        for (const summary of root?.querySelectorAll('summary') ?? []) {
+          const group = summary.parentElement;
+          const label = summary
+            .querySelector('.group-label')
+            ?.textContent?.trim();
+          const href = label ? hrefByLabel.get(label) : undefined;
+          if (!group || !href || group.querySelector('.layout-part-open')) {
+            continue;
+          }
+
+          const link = document.createElement('a');
+          link.className = 'layout-part-open';
+          link.href = href;
+          link.title = 'Open part overview';
+          link.setAttribute('aria-label', `Open part overview: ${label}`);
+          link.textContent = '»';
+          // Immediately after the header it belongs to: the reading order is
+          // the part, then its page, then its chapters, and CSS lifts it back
+          // into the header row.
+          summary.insertAdjacentElement('afterend', link);
+          group.classList.add('layout-part-has-open');
+        }
+      })();
+    </script>
+    <script>
+      /**
+       * Mark every chapter the reader has already passed, so the rail beside
+       * the chapter list can show how far into the course this page is.
+       *
+       * The sidebar's document order *is* the reading order — the compiler
+       * built it from the merged track order — so "covered" is simply
+       * "earlier in this list than the current page". A part whose chapters
+       * are all covered is covered itself, which is what makes the rail read
+       * as one run rather than as a mark per group.
+       */
+      (() => {
+        const root = document.querySelector('#starlight__navigation-content');
+        const links = [...(root?.querySelectorAll('a') ?? [])].filter(
+          (link) => !link.classList.contains('layout-part-open'),
+        );
+        const current = links.findIndex(
+          (link) => link.getAttribute('aria-current') === 'page',
+        );
+        if (current < 1) return;
+
+        for (const link of links.slice(0, current)) {
+          link.parentElement?.setAttribute('data-covered', '');
+        }
+        for (const group of root?.querySelectorAll('details') ?? []) {
+          const chapters = [...group.querySelectorAll(':scope > ul > li')];
+          if (
+            chapters.length > 0 &&
+            chapters.every((item) => item.hasAttribute('data-covered'))
+          ) {
+            group.setAttribute('data-covered', '');
+          }
+        }
+      })();
+    </script>
     <script>
       import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
 
@@ -86,5 +209,100 @@ import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
         });
       })();
     </script>
+    <script>
+      /**
+       * A compact chapter shows its lessons as icons and hands the lesson's own
+       * title to a tooltip. That tooltip is a child of the navigation panel,
+       * which scrolls (`overflow-y: auto`, which forces `overflow-x` to match),
+       * so an absolutely positioned child cannot leave it: any title longer
+       * than the panel is wide ended at the panel's edge, unreadable.
+       *
+       * Nothing in CSS escapes an ancestor's scroll clipping while staying
+       * positioned against that ancestor, so the showing tooltip gets
+       * `position: fixed` (see `global.css`) and the anchor's own viewport
+       * coordinates from here. The tooltip stays the link's accessible name in
+       * the markup either way — this only moves where it is painted.
+       */
+      (() => {
+        if (!matchMedia('(min-width: 50rem)').matches) return;
+        const panel = document.querySelector<HTMLElement>(
+          '#starlight__navigation-content',
+        );
+        if (!panel) return;
+
+        const COMPACT_LINK =
+          'details[data-compact] > ul:not(.top-level) > li > a';
+        const GAP = 7;
+        const EDGE = 8;
+        let open: HTMLAnchorElement | null = null;
+
+        const labelOf = (link: HTMLAnchorElement) =>
+          link.querySelector<HTMLElement>(':scope > span');
+
+        const place = () => {
+          if (!open) return;
+          const label = labelOf(open);
+          if (!label) return;
+          const anchor = open.getBoundingClientRect();
+          label.style.setProperty(
+            '--layout-tooltip-y',
+            `${anchor.top + anchor.height / 2}px`,
+          );
+          // Measured while it is already fixed, so this is the width it will
+          // actually be drawn at, wrapping included.
+          const width = label.getBoundingClientRect().width;
+          const rtl = getComputedStyle(document.documentElement).direction === 'rtl';
+          const preferred = rtl
+            ? anchor.left - GAP - width
+            : anchor.right + GAP;
+          const furthest = Math.max(EDGE, window.innerWidth - width - EDGE);
+          label.style.setProperty(
+            '--layout-tooltip-x',
+            `${Math.min(Math.max(EDGE, preferred), furthest)}px`,
+          );
+        };
+
+        const hide = () => {
+          if (!open) return;
+          const label = labelOf(open);
+          label?.style.removeProperty('--layout-tooltip-x');
+          label?.style.removeProperty('--layout-tooltip-y');
+          open.removeAttribute('data-tooltip-open');
+          open = null;
+        };
+
+        const show = (link: HTMLAnchorElement) => {
+          if (open === link) return;
+          hide();
+          open = link;
+          link.setAttribute('data-tooltip-open', '');
+          place();
+        };
+
+        const linkFrom = (target: EventTarget | null) =>
+          target instanceof Element
+            ? target.closest<HTMLAnchorElement>(COMPACT_LINK)
+            : null;
+
+        panel.addEventListener('pointerover', (event) => {
+          const link = linkFrom(event.target);
+          if (link) show(link);
+          else hide();
+        });
+        panel.addEventListener('pointerleave', hide);
+        panel.addEventListener('focusin', (event) => {
+          const link = linkFrom(event.target);
+          if (link) show(link);
+          else hide();
+        });
+        panel.addEventListener('focusout', hide);
+        // A fixed tooltip no longer travels with the panel it points at.
+        window.addEventListener('scroll', place, {
+          passive: true,
+          capture: true,
+        });
+        window.addEventListener('resize', place, { passive: true });
+      })();
+    </script>
   </div>
 </div>

package/src/components/starlight/LessonExportActions.astro

@@ -100,15 +100,10 @@ const {
 </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;
-  };
+  import {
+    prepareDisclosures,
+    type PreparedDisclosures,
+  } from '../disclosure/print-as-shown';
 
   type SavedLink = {
     readonly element: HTMLAnchorElement;
@@ -124,7 +119,7 @@ const {
 
   type PreparedStaticExport = {
     readonly mode: StaticExportMode;
-    readonly details: readonly SavedDetails[];
+    readonly disclosures: PreparedDisclosures;
     readonly hidden: readonly SavedHidden[];
     readonly links: readonly SavedLink[];
   };
@@ -164,19 +159,25 @@ const {
       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 canonicalUrl(target, canonicalBaseUrl, siteBaseUrl);
+  }
 
-    return result;
+  // 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 {
@@ -187,35 +188,32 @@ const {
 
     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 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>(
-        'main :is(.assessment-panel, .short-note, .compact-example, .keyed-table__body tr:not(.keyed-table__more-row))[hidden]',
-      ),
+      document.querySelectorAll<HTMLElement>(hiddenSelector),
       (element): SavedHidden => {
         const saved = { element, hidden: element.hidden };
         element.hidden = false;
@@ -223,8 +221,6 @@ const {
       },
     );
 
-    const canonicalBaseUrl = printController.dataset.canonicalBaseUrl;
-    const siteBaseUrl = printController.dataset.siteBaseUrl ?? '/';
     const links =
       mode === 'print'
         ? Array.from(
@@ -248,7 +244,7 @@ const {
           })
         : [];
 
-    prepared = { mode, details, hidden, links };
+    prepared = { mode, disclosures, hidden, links };
     if (mode === 'print') root.dataset.explicoPrintReady = '';
   }
 
@@ -257,17 +253,7 @@ const {
     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);
-      }
-    }
+    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');
@@ -280,16 +266,7 @@ const {
     // 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,
-          );
-        }
-      }
+      saved.disclosures.releaseMarkers();
       delete root.dataset.explicoStaticExport;
       pendingMarkerCleanup = null;
     };
@@ -324,9 +301,13 @@ const {
   }
 
   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;

package/src/components/starlight/LessonFooter.astro

@@ -31,6 +31,7 @@ import {
   notationDefinitionsForRenderedPage,
   pageNotationDependencies,
 } from '../../reference/page-notation';
+import type { NotationSuspension } from '../../reference/types';
 
 // `lessonId` is no longer authored (Phase C2); derive it from the route.
 const routeSlug = Astro.locals.starlightRoute.entry.id;
@@ -42,13 +43,30 @@ const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
 const definitions: NotationLayerDefinition[] = [];
 let notationDefaultOpen = false;
+let numberAliases = false;
+let suspended: NotationSuspension[] = [];
 if (lessonId) {
   const manifest = await loadManifest();
-  notationDefaultOpen = manifest.disclosureDefaults.notation;
+  notationDefaultOpen = manifest.disclosure.notation.defaultOpen;
+  numberAliases = manifest.numbering.aliases;
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
   const routeData = Astro.locals.starlightRoute.entry.data as {
-    notation?: { local?: readonly { key?: unknown }[] };
+    notation?: {
+      local?: readonly { key?: unknown }[];
+      suspend?: readonly { operator?: unknown; reason?: unknown }[];
+    };
   };
+  // `notation.suspend` (rule N22), already checked by the schema and by
+  // `validate:content`; the Page notation panel tells the reader.
+  suspended = (routeData.notation?.suspend ?? []).flatMap((item) =>
+    typeof item.operator === 'string'
+      ? [
+          typeof item.reason === 'string'
+            ? { operator: item.operator, reason: item.reason }
+            : { operator: item.operator },
+        ]
+      : [],
+  );
   const authoredLocalKeys = (routeData.notation?.local ?? [])
     .map((entry) => entry.key)
     .filter((key): key is string => typeof key === 'string');
@@ -83,11 +101,15 @@ if (lessonId) {
 }
 ---
 
-<NotationLayer definitions={definitions} defaultOpen={notationDefaultOpen} />
+<NotationLayer
+  definitions={definitions}
+  defaultOpen={notationDefaultOpen}
+  suspended={suspended}
+/>
 <AnchorScrollEnhancer />
 {lessonId && <CitationLayer />}
 {lessonId && <AbbreviationLayer />}
-{lessonId && <KeyedFloatEnhancer />}
+{lessonId && <KeyedFloatEnhancer aliases={numberAliases} />}
 {lessonId && <FloatRefLayer />}
 {lessonId && <CollapsibleSections />}
 {lessonId && <TableOverflowExpander />}

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

@@ -16,14 +16,27 @@
 
 export const HEADINGS = 'h1, h2, h3, h4, h5, h6';
 
+/**
+ * Two markers for a block that is a section of its own, not a heading in the
+ * page's outline — a `<Memo>`, whose bar is a `######`
+ * (docs/plans/titles-and-containers.md Part 4), and a `<Fold>`, the same
+ * without the memo's marker, letter and frame:
+ * - `data-section-to-end` on its heading wrapper: its section is every
+ *   following sibling in its container, whatever headings its body holds;
+ * - `data-section-contained` on its container: the block never ends a
+ *   section around it — it is body content there, like a figure.
+ */
 export function sectionParts(heading: HTMLElement): Element[] {
   const wrapper = heading.closest('.sl-heading-wrapper') ?? heading;
   const rank = Number(heading.tagName[1]);
+  const toEnd = wrapper.hasAttribute('data-section-to-end');
   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;
+    if (!toEnd && !node.matches('[data-section-contained]')) {
+      const inner = node.matches(HEADINGS) ? node : node.querySelector(HEADINGS);
+      if (inner && Number(inner.tagName[1]) <= rank) break;
+    }
     parts.push(node);
     node = node.nextElementSibling;
   }