explico 0.8.0 → 0.11.0

package/src/components/starlight/LayoutHeader.astro

@@ -14,27 +14,53 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
     {
       attribute: string;
       storageKey: string;
+      legacyStorageKey: string;
+      widthStorageKey: string;
+      widthProperty: string;
+      resizedAttribute: string;
       peekSuppressedAttribute: string;
+      peekArmedAttribute: string;
       panelSelector: string;
+      /** The layout this panel's width belongs to; outside it, nothing to set. */
+      query: string;
+      /** Which way a drag widens the panel, before the page's own direction. */
+      grows: 1 | -1;
       shownLabel: string;
       hiddenLabel: string;
+      widthLabel: string;
     }
   > = {
     navigation: {
       attribute: 'data-navigation-hidden',
-      storageKey: 'credit-playground:layout:navigation-hidden',
+      storageKey: 'explico:layout:navigation-hidden',
+      legacyStorageKey: 'credit-playground:layout:navigation-hidden',
+      widthStorageKey: 'explico:layout:navigation-width',
+      widthProperty: '--sl-sidebar-width',
+      resizedAttribute: 'data-navigation-resized',
       peekSuppressedAttribute: 'data-navigation-peek-suppressed',
+      peekArmedAttribute: 'data-navigation-peek-armed',
       panelSelector: '.sidebar-pane',
+      query: '(min-width: 50rem)',
+      grows: 1,
       shownLabel: 'Hide navigation',
       hiddenLabel: 'Show navigation',
+      widthLabel: 'Navigation width',
     },
     contents: {
       attribute: 'data-page-sidebar-hidden',
-      storageKey: 'credit-playground:layout:contents-hidden',
+      storageKey: 'explico:layout:contents-hidden',
+      legacyStorageKey: 'credit-playground:layout:contents-hidden',
+      widthStorageKey: 'explico:layout:contents-width',
+      widthProperty: '--layout-contents-width',
+      resizedAttribute: 'data-contents-resized',
       peekSuppressedAttribute: 'data-page-sidebar-peek-suppressed',
+      peekArmedAttribute: 'data-page-sidebar-peek-armed',
       panelSelector: '.right-sidebar',
+      query: '(min-width: 72rem)',
+      grows: -1,
       shownLabel: 'Hide page contents',
       hiddenLabel: 'Show page contents',
+      widthLabel: 'Page contents width',
     },
   };
 
@@ -55,10 +81,11 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
    * Starlight's own formula already gave it.
    *
    * This doesn't close a loop back on itself: `.right-sidebar`'s own width
-   * is edge-anchored and shrink-to-fit against its own content, not
-   * against how much room `.main-pane` leaves it (that dependency is
-   * exactly what the edge anchor removed), so measuring it here doesn't
-   * need to react to anything this function itself changes.
+   * is edge-anchored and shrink-to-fit against its own content (or, once the
+   * reader has set one, exactly the width they set), not against how much
+   * room `.main-pane` leaves it — that dependency is exactly what the edge
+   * anchor removed — so measuring it here doesn't need to react to anything
+   * this function itself changes.
    */
   function updateTocReservation(): void {
     const panel = document.querySelector<HTMLElement>('.right-sidebar');
@@ -78,14 +105,22 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
   // PreferenceStore and nothing here changes.
   const preferences = createBrowserPreferenceStore();
 
-  function readPreference(storageKey: string): boolean {
-    return preferences.get(storageKey) === 'true';
+  function readPreference(region: LayoutRegion): boolean {
+    const settings = regions[region];
+    const stored =
+      preferences.get(settings.storageKey) ??
+      // Written under a name this engine has outgrown; honour it once so a
+      // returning reader keeps the layout they left.
+      preferences.get(settings.legacyStorageKey);
+    return stored === 'true';
   }
 
   function writePreference(storageKey: string, hidden: boolean): void {
     preferences.set(storageKey, String(hidden));
   }
 
+  const toggles = new Map<LayoutRegion, HTMLButtonElement>();
+
   function applyState(
     button: HTMLButtonElement,
     region: LayoutRegion,
@@ -100,14 +135,40 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
     button.title = label;
   }
 
+  function setHidden(region: LayoutRegion, hidden: boolean): void {
+    const settings = regions[region];
+    if (root.hasAttribute(settings.attribute) === hidden) return;
+    const button = toggles.get(region);
+    if (button) applyState(button, region, hidden);
+    else root.toggleAttribute(settings.attribute, hidden);
+    writePreference(settings.storageKey, hidden);
+  }
+
+  /**
+   * A panel collapsed by the pointer would otherwise peek straight back open,
+   * because the pointer that collapsed it is still inside the rail it left
+   * behind. Hold the peek off until the pointer actually leaves.
+   */
+  function suppressPeek(region: LayoutRegion): void {
+    const settings = regions[region];
+    root.setAttribute(settings.peekSuppressedAttribute, '');
+    const panel = document.querySelector(settings.panelSelector);
+    const clear = () => root.removeAttribute(settings.peekSuppressedAttribute);
+    panel?.addEventListener('pointerleave', clear, { once: true });
+    window.setTimeout(() => {
+      if (!panel?.matches(':hover')) clear();
+    }, 180);
+  }
+
   document
     .querySelectorAll<HTMLButtonElement>('[data-layout-toggle]')
     .forEach((button) => {
       const region = button.dataset.layoutToggle as LayoutRegion;
       const settings = regions[region];
       if (!settings) return;
+      toggles.set(region, button);
 
-      applyState(button, region, readPreference(settings.storageKey));
+      applyState(button, region, readPreference(region));
       button.removeAttribute('hidden');
       button.addEventListener('click', (event) => {
         const hidden = !root.hasAttribute(settings.attribute);
@@ -121,20 +182,238 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
         // A pointer click should leave a newly collapsed rail collapsed even
         // though the pointer was inside the full-width panel when clicked.
         if (hidden && event.detail > 0) {
-          root.setAttribute(settings.peekSuppressedAttribute, '');
           button.blur();
+          suppressPeek(region);
+        }
+      });
+    });
+
+  /**
+   * Hover intent for the peek.
+   *
+   * A collapsed panel peeks open when the pointer rests on its rail, and the
+   * rails sit on the two edges of the window — a pointer on its way to the
+   * scrollbar, the tab strip, or the other side of the article crosses one
+   * without meaning anything by it, and the panel would swing open behind it
+   * every time. Waiting out `--layout-peek-delay` before arming the peek
+   * makes crossing the rail cost nothing while resting on it still opens the
+   * panel about as fast as the eye registers that it moved.
+   *
+   * The CSS keeps `:hover` as the trigger and reads this attribute as the
+   * gate in front of it, so there is one description of what peeking looks
+   * like, not two. Nothing is lost without JavaScript: a panel is only ever
+   * collapsed because this same script collapsed it.
+   */
+  const PEEK_DELAY_FALLBACK = 40;
+
+  function peekDelay(): number {
+    const declared = getComputedStyle(root)
+      .getPropertyValue('--layout-peek-delay')
+      .trim();
+    const value = Number.parseFloat(declared);
+    if (!Number.isFinite(value) || value < 0) return PEEK_DELAY_FALLBACK;
+    // A bare number is read as milliseconds; `s` is the only other unit CSS
+    // gives a <time>.
+    return declared.endsWith('ms') || !declared.endsWith('s')
+      ? value
+      : value * 1000;
+  }
+
+  (Object.keys(regions) as LayoutRegion[]).forEach((region) => {
+    const settings = regions[region];
+    const panel = document.querySelector<HTMLElement>(settings.panelSelector);
+    if (!panel) return;
+    let timer: number | null = null;
+
+    panel.addEventListener('pointerenter', () => {
+      if (timer !== null) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        timer = null;
+        root.setAttribute(settings.peekArmedAttribute, '');
+      }, peekDelay());
+    });
+
+    panel.addEventListener('pointerleave', () => {
+      if (timer !== null) window.clearTimeout(timer);
+      timer = null;
+      root.removeAttribute(settings.peekArmedAttribute);
+    });
+  });
+
+  /**
+   * Reader-set panel widths.
+   *
+   * A panel's width is the reader's, not the theme's: `--sl-sidebar-width` is
+   * Starlight's own token, so setting it moves the header's title column, the
+   * article's inline start and the `.main-pane` formula together, with no
+   * second source of truth to keep in step. The "On this page" rail has no
+   * such token — it shrink-wraps its own content — so a reader-set width goes
+   * to `--layout-contents-width`, which `global.css` only honours once
+   * `data-contents-resized` says the reader has set one.
+   *
+   * Dragging a panel below three characters of width is how a reader collapses
+   * it by hand: there is no useful panel narrower than that, and treating it
+   * as "closed" beats leaving a sliver that can only be reopened by dragging
+   * a handle that has nowhere left to sit. `3ch` is measured in the panel's
+   * own font rather than assumed, so a course that changes `--sl-font` gets
+   * the threshold its own text implies.
+   */
+  const MAX_PANEL_WIDTH = 640;
+  const pageIsRtl = getComputedStyle(root).direction === 'rtl';
+
+  function threeCharacters(panel: HTMLElement): number {
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:absolute;visibility:hidden;width:3ch';
+    panel.appendChild(probe);
+    const width = probe.getBoundingClientRect().width;
+    probe.remove();
+    return width || 24;
+  }
+
+  function maxPanelWidth(): number {
+    return Math.min(window.innerWidth / 2, MAX_PANEL_WIDTH);
+  }
+
+  function restoreWidth(region: LayoutRegion, matches: boolean): void {
+    const settings = regions[region];
+    const stored = Number(preferences.get(settings.widthStorageKey));
+    if (matches && Number.isFinite(stored) && stored > 0) {
+      root.style.setProperty(settings.widthProperty, `${Math.round(stored)}px`);
+      root.setAttribute(settings.resizedAttribute, '');
+      return;
+    }
+    // Outside this panel's layout the token belongs to the theme again: a
+    // desktop width left on `:root` would follow the page down to a phone,
+    // where Starlight expects its own value.
+    root.style.removeProperty(settings.widthProperty);
+    root.removeAttribute(settings.resizedAttribute);
+  }
+
+  document
+    .querySelectorAll<HTMLElement>('[data-layout-resizer]')
+    .forEach((handle) => {
+      const region = handle.dataset.layoutResizer as LayoutRegion;
+      const settings = regions[region];
+      if (!settings) return;
+      const media = window.matchMedia(settings.query);
+      const grows = settings.grows * (pageIsRtl ? -1 : 1);
+      let floor = 24;
+
+      const panel = () =>
+        document.querySelector<HTMLElement>(settings.panelSelector);
+      const currentWidth = () => panel()?.getBoundingClientRect().width ?? 0;
+
+      const describe = (width: number) => {
+        handle.setAttribute('aria-valuemin', '0');
+        handle.setAttribute('aria-valuemax', String(Math.round(maxPanelWidth())));
+        handle.setAttribute('aria-valuenow', String(Math.round(width)));
+        handle.setAttribute(
+          'aria-valuetext',
+          width > 0 ? `${Math.round(width)} pixels` : 'collapsed',
+        );
+      };
+
+      const applyWidth = (width: number) => {
+        root.style.setProperty(settings.widthProperty, `${Math.round(width)}px`);
+        root.setAttribute(settings.resizedAttribute, '');
+        if (region === 'contents') updateTocReservation();
+      };
+
+      /**
+       * A width the reader passed through on the way somewhere else is not a
+       * width they chose, so nothing is written until the gesture ends. That
+       * also keeps the width a collapsing drag sweeps through — 40px, 30px,
+       * whatever the last frame above the threshold happened to be — from
+       * becoming the width the panel reopens at.
+       */
+      const persist = () => {
+        const current = Number.parseFloat(
+          root.style.getPropertyValue(settings.widthProperty),
+        );
+        if (Number.isFinite(current) && current > 0) {
+          preferences.set(settings.widthStorageKey, String(Math.round(current)));
+        }
+      };
 
-          const panel = document.querySelector(settings.panelSelector);
-          const clearSuppression = () =>
-            root.removeAttribute(settings.peekSuppressedAttribute);
-          panel?.addEventListener('pointerleave', clearSuppression, {
-            once: true,
-          });
-          window.setTimeout(() => {
-            if (!panel?.matches(':hover')) clearSuppression();
-          }, 180);
+      const resize = (width: number, reopenAt: number) => {
+        if (width < floor) {
+          setHidden(region, true);
+          // Collapsed, the panel's own width is the rail's; this is the width
+          // its control will bring back.
+          applyWidth(reopenAt);
+          describe(0);
+          return;
         }
+        setHidden(region, false);
+        const next = Math.round(
+          Math.min(Math.max(width, floor), maxPanelWidth()),
+        );
+        applyWidth(next);
+        describe(next);
+      };
+
+      const measureFloor = () => {
+        const element = panel();
+        floor = element ? threeCharacters(element) : 24;
+      };
+
+      handle.addEventListener('pointerdown', (event) => {
+        if (!media.matches) return;
+        const startX = event.clientX;
+        const startWidth = currentWidth();
+        measureFloor();
+        handle.setAttribute('data-resizing', '');
+        handle.setPointerCapture(event.pointerId);
+
+        const move = (moveEvent: PointerEvent) => {
+          resize(startWidth + (moveEvent.clientX - startX) * grows, startWidth);
+        };
+        const end = () => {
+          handle.removeAttribute('data-resizing');
+          persist();
+          // The pointer that dragged the panel away is still inside the rail
+          // it left behind, which would peek it straight back open.
+          if (root.hasAttribute(settings.attribute)) suppressPeek(region);
+          window.removeEventListener('pointermove', move);
+          window.removeEventListener('pointerup', end);
+          window.removeEventListener('pointercancel', end);
+        };
+        // Captured events still bubble on through the handle's ancestors, and
+        // listening up here keeps the drag alive across the moment a panel
+        // dragged past the threshold collapses and takes its handle off the
+        // layout — the reader can drag straight back out of it.
+        window.addEventListener('pointermove', move);
+        window.addEventListener('pointerup', end);
+        window.addEventListener('pointercancel', end);
+        event.preventDefault();
       });
+
+      handle.addEventListener('keydown', (event) => {
+        if (!media.matches) return;
+        const step = event.shiftKey ? 64 : 16;
+        measureFloor();
+        const from = currentWidth();
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+          const direction = event.key === 'ArrowRight' ? 1 : -1;
+          resize(from + direction * grows * step, from);
+        } else if (event.key === 'Home') {
+          resize(0, from);
+        } else if (event.key === 'End') {
+          resize(maxPanelWidth(), from);
+        } else {
+          return;
+        }
+        persist();
+        event.preventDefault();
+      });
+
+      const applyMedia = () => {
+        restoreWidth(region, media.matches);
+        handle.toggleAttribute('hidden', !media.matches);
+        if (media.matches) describe(currentWidth());
+      };
+      applyMedia();
+      media.addEventListener('change', applyMedia);
     });
 
   updateTocReservation();

package/src/components/starlight/LayoutPageSidebar.astro

@@ -1,6 +1,29 @@
 ---
-import { Icon } from '@astrojs/starlight/components';
 import DefaultPageSidebar from '@astrojs/starlight/components/PageSidebar.astro';
+import { isLessonSlug, lessonIdFromSlug } from '../../compiler/lesson-derivation';
+import { titledBlocksOf, tocWithTitledBlocks } from '../block-heading';
+
+// "On this page" lists the `<h2>` a knowledge check and a worked-example set
+// draw (docs/plans/titles-and-containers.md Part 6): a component renders
+// them, so Astro's heading list — Starlight's source for the list — never
+// had them. The manifest's `titledBlocks` says where each one stands; the
+// list is rebuilt with them in before Starlight's own component (desktop and
+// mobile alike) renders it. Each is listed by its title, as a section is;
+// `data-titled-blocks` tells the script below which entries they are, so
+// `global.css` draws the badge's icon before them.
+const route = Astro.locals.starlightRoute;
+const routeSlug = route.entry.id;
+let blockKinds: Record<string, string> | undefined;
+if (route.toc && isLessonSlug(routeSlug)) {
+  const blocks = await titledBlocksOf(lessonIdFromSlug(routeSlug));
+  if (blocks.length > 0) {
+    route.toc = {
+      ...route.toc,
+      items: tocWithTitledBlocks(route.toc, route.headings, blocks),
+    };
+    blockKinds = Object.fromEntries(blocks.map((block) => [block.anchor, block.kind]));
+  }
+}
 ---
 
 <div
@@ -16,18 +39,82 @@ import DefaultPageSidebar from '@astrojs/starlight/components/PageSidebar.astro'
     data-layout-toggle="contents"
     hidden
   >
-    <Icon
-      name="right-caret"
-      class="layout-edge-icon layout-edge-icon-hide"
-      size="1rem"
-    />
-    <Icon
-      name="left-caret"
-      class="layout-edge-icon layout-edge-icon-restore"
-      size="1rem"
-    />
+    <span class="layout-edge-glyph layout-edge-glyph-hide" aria-hidden="true"
+      >&gt;&gt;&gt;</span
+    >
+    <span class="layout-edge-glyph layout-edge-glyph-restore" aria-hidden="true"
+      >&lt;&lt;&lt;</span
+    >
   </button>
-  <div id="starlight__page-sidebar-content" class="layout-page-sidebar-content">
+  <div
+    class="layout-edge-resizer layout-contents-resizer"
+    role="separator"
+    aria-orientation="vertical"
+    aria-controls="starlight__page-sidebar-content"
+    aria-label="Page contents width"
+    tabindex="0"
+    data-layout-resizer="contents"
+    hidden
+  >
+  </div>
+  <div
+    id="starlight__page-sidebar-content"
+    class="layout-page-sidebar-content"
+    data-titled-blocks={blockKinds && JSON.stringify(blockKinds)}
+  >
     <DefaultPageSidebar />
+    <script>
+      // A knowledge check's or an example set's entry: `data-block-kind` on
+      // its link, which `global.css` gives the badge's icon.
+      (() => {
+        const rail = document.querySelector<HTMLElement>('#starlight__page-sidebar-content');
+        const kinds = JSON.parse(rail?.dataset.titledBlocks ?? '{}') as Record<string, string>;
+        for (const link of rail?.querySelectorAll<HTMLAnchorElement>('a[href^="#"]') ?? []) {
+          const kind = kinds[decodeURIComponent(link.hash.slice(1))];
+          if (kind) link.dataset.blockKind = kind;
+        }
+      })();
+    </script>
+    <script>
+      /**
+       * The same progress the navigation rail shows across the course, shown
+       * here across the page: the headings above the reader's position are
+       * marked, the one they are in is marked as current, and the rest stay
+       * plain.
+       *
+       * Starlight's own scroll-spy moves `aria-current="true"` from link to
+       * link as the reader scrolls, so this watches for that attribute
+       * instead of re-implementing the intersection logic, and re-marks from
+       * whichever link holds it.
+       */
+      (() => {
+        const rail = document.querySelector('#starlight__page-sidebar-content');
+        const toc = rail?.querySelector('starlight-toc');
+        if (!toc) return;
+
+        const mark = () => {
+          const links = [...toc.querySelectorAll('a')];
+          const current = links.findIndex(
+            (link) => link.getAttribute('aria-current') === 'true',
+          );
+          links.forEach((link, index) => {
+            const item = link.parentElement;
+            if (!item) return;
+            item.toggleAttribute(
+              'data-covered',
+              current > 0 && index < current,
+            );
+            item.toggleAttribute('data-current', index === current);
+          });
+        };
+
+        mark();
+        new MutationObserver(mark).observe(toc, {
+          attributes: true,
+          attributeFilter: ['aria-current'],
+          subtree: true,
+        });
+      })();
+    </script>
   </div>
 </div>

package/src/components/starlight/LayoutPageTitle.astro

@@ -0,0 +1,120 @@
+---
+/**
+ * The page title, preceded by the part it belongs to.
+ *
+ * A reader who arrives from a search result, a shared link, or a print export
+ * has no sidebar state to read their position from, and the sidebar itself
+ * names a part without linking it. One line above the title answers both: it
+ * says which part this chapter sits in, and it is the route to that part's own
+ * page — the surface that does not depend on a hover, a caret, or a rail being
+ * open at all.
+ *
+ * The trail stops at the part on purpose: the `<h1>` immediately below is the
+ * current page, and repeating it costs a screen reader the same words twice.
+ */
+import DefaultPageTitle from '@astrojs/starlight/components/PageTitle.astro';
+import { loadManifest } from '../../compiler/manifest';
+import { isLessonSlug } from '../../compiler/lesson-derivation';
+
+const route = Astro.locals.starlightRoute;
+const routeSlug = route.entry.id;
+const manifest = await loadManifest();
+
+// `<dir>/<name>` is a chapter. A part's own page is `<dir>/index.mdx`, whose
+// entry id the glob loader shortens to the directory itself — so a slug with
+// no `/` is a part page when it names a configured part, and an ordinary
+// top-level page (`glossary`, `curriculum-map`) when it does not.
+const partDir = isLessonSlug(routeSlug)
+  ? routeSlug.slice(0, routeSlug.indexOf('/'))
+  : routeSlug.replace(/\/index$/, '');
+const part = manifest.parts.find((entry) => entry.dir === partDir);
+const isPartPage = part !== undefined && !isLessonSlug(routeSlug);
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+// A part is only a link when there is a page behind its directory URL.
+const partHref =
+  part?.overview && !isPartPage ? `${base}${part.link}` : undefined;
+---
+
+{
+  part && (
+    <nav class="lesson-breadcrumb not-content" aria-label="Breadcrumb">
+      <ol>
+        <li>
+          <a href={route.siteTitleHref}>{route.siteTitle}</a>
+        </li>
+        <li>
+          {partHref ? (
+            <a href={partHref}>{part.label}</a>
+          ) : (
+            <span aria-current={isPartPage ? 'page' : undefined}>
+              {part.label}
+            </span>
+          )}
+        </li>
+      </ol>
+    </nav>
+  )
+}
+<DefaultPageTitle />
+
+<style>
+  .lesson-breadcrumb {
+    margin-block-start: 1rem;
+    /* The title's own `margin-top: 1rem` would otherwise open a second gap of
+       the same size between the trail and the heading it introduces. */
+    margin-block-end: -0.75rem;
+    font-size: var(--sl-text-xs);
+    line-height: 1.4;
+  }
+
+  .lesson-breadcrumb ol {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem 0.4rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .lesson-breadcrumb li {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    margin: 0;
+    padding: 0;
+    color: var(--sl-color-gray-3);
+  }
+
+  .lesson-breadcrumb li + li::before {
+    content: '\203A';
+    color: var(--sl-color-gray-4);
+  }
+
+  .lesson-breadcrumb a {
+    color: var(--sl-color-gray-3);
+    text-decoration: none;
+  }
+
+  .lesson-breadcrumb a:hover,
+  .lesson-breadcrumb a:focus-visible {
+    color: var(--sl-color-text-accent);
+    text-decoration: underline;
+    text-underline-offset: 0.2em;
+  }
+
+  [dir='rtl'] .lesson-breadcrumb li + li::before {
+    content: '\2039';
+  }
+
+  @media print {
+    .lesson-breadcrumb {
+      margin-block-end: 0;
+    }
+
+    .lesson-breadcrumb a {
+      text-decoration: none;
+    }
+  }
+</style>