explico 0.11.1 → 0.13.0

package/src/components/starlight/KeyedFloatEnhancer.astro

@@ -64,10 +64,13 @@ const { aliases = false } = Astro.props;
 
 <script>
   import { animatedScrollIntoView } from '../scroll-animation';
+  import { startFloatToolbar } from '../float-toolbar';
 
   (() => {
-    const root = document.querySelector('.sl-markdown-content');
+    const root = document.querySelector<HTMLElement>('.sl-markdown-content');
     if (!root) return;
+    // The number's toolbar: Pin, Dock, Copy link; and Copy LaTeX's place.
+    startFloatToolbar(root);
 
     // `#sec-1.1.2` → the element printing that number, if this page has one.
     const ALIAS = /^#(sec|eq|tab|fig|dia|check|ex)-(\d+(?:\.\d+)+)$/;
@@ -94,27 +97,27 @@ const { aliases = false } = Astro.props;
     const KINDS: readonly Kind[] = [
       {
         prefix: '#eq-',
-        triggerSelector: 'a.equation-ref, a.keyed-equation__number',
+        triggerSelector: 'a.equation-ref, a.keyed-equation__number, a.float-toolbar__link',
         numberSelector: '.keyed-equation__number',
         reveal: true,
       },
-      // A float's caption line links to it twice: its number, and the chain
-      // icon beside it (which also copies the link, `HeadingAnchorEnhancer`).
+      // A float is linked by its number, and by its number's toolbar's Copy
+      // link, which also copies the link (`float-toolbar.ts`).
       {
         prefix: '#tab-',
-        triggerSelector: 'a.table-ref, a.keyed-table__number, a.float-caption__anchor',
+        triggerSelector: 'a.table-ref, a.keyed-table__number, a.float-toolbar__link',
         numberSelector: '.keyed-table__number',
         reveal: false,
       },
       {
         prefix: '#fig-',
-        triggerSelector: 'a.figure-ref, a.keyed-figure__number, a.float-caption__anchor',
+        triggerSelector: 'a.figure-ref, a.keyed-figure__number, a.float-toolbar__link',
         numberSelector: '.keyed-figure__number',
         reveal: false,
       },
       {
         prefix: '#dia-',
-        triggerSelector: 'a.diagram-ref, a.diagram__number, a.float-caption__anchor',
+        triggerSelector: 'a.diagram-ref, a.diagram__number, a.float-toolbar__link',
         numberSelector: '.diagram__number',
         reveal: false,
       },
@@ -183,7 +186,7 @@ const { aliases = false } = Astro.props;
     root.addEventListener('click', (event) => {
       const origin = event.target instanceof Element ? event.target : null;
       if (!origin) return;
-      if (origin.closest('a.keyed-equation__number, [data-notation-key]')) {
+      if (origin.closest('a.keyed-equation__number, [data-notation-key], .float-toolbar')) {
         return;
       }
 
@@ -228,7 +231,7 @@ const { aliases = false } = Astro.props;
       if (!origin || origin.getAttribute('title')?.startsWith('Copy LaTeX')) return;
       if (
         origin.closest(
-          '[data-notation-key], [data-eq-copy], a.keyed-equation__number',
+          '[data-notation-key], [data-eq-copy], a.keyed-equation__number, .float-toolbar',
         )
       ) {
         return;
@@ -260,7 +263,22 @@ const { aliases = false } = Astro.props;
     // `ResizeObserver` catches every case that changes that: first layout, a
     // viewport change, and a collapsed section opening (no layout box while
     // closed, so no overflow either).
+    // Which edge an overflowing equation is cut at: `data-overflow` is
+    // `end`, `start`, or `start end`, and `global.css` fades that edge, so a
+    // reader on a phone sees the formula goes on (there is no scrollbar).
+    const updateEquationEdges = (display: HTMLElement) => {
+      const scroll = Math.abs(display.scrollLeft);
+      const edges = [
+        scroll > 1 ? 'start' : '',
+        scroll + display.clientWidth < display.scrollWidth - 1 ? 'end' : '',
+      ]
+        .filter(Boolean)
+        .join(' ');
+      if (edges) display.setAttribute('data-overflow', edges);
+      else display.removeAttribute('data-overflow');
+    };
     const updateEquationScroll = (display: HTMLElement) => {
+      updateEquationEdges(display);
       if (display.scrollWidth > display.clientWidth + 1) {
         const number = display
           .closest<HTMLElement>('.keyed-equation')
@@ -282,6 +300,7 @@ const { aliases = false } = Astro.props;
     });
     for (const display of root.querySelectorAll<HTMLElement>('.katex-display')) {
       equationResize.observe(display);
+      display.addEventListener('scroll', () => updateEquationEdges(display), { passive: true });
     }
 
     window.addEventListener('hashchange', (event) => {

package/src/components/starlight/LayoutPageSidebar.astro

@@ -1,7 +1,13 @@
 ---
 import DefaultPageSidebar from '@astrojs/starlight/components/PageSidebar.astro';
 import { isLessonSlug, lessonIdFromSlug } from '../../compiler/lesson-derivation';
-import { titledBlocksOf, tocWithTitledBlocks } from '../block-heading';
+import {
+  mathHeadingTextsOf,
+  titledBlocksOf,
+  tocWithHeadingTexts,
+  tocWithTitledBlocks,
+  withHeadingTexts,
+} 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
@@ -11,17 +17,25 @@ import { titledBlocksOf, tocWithTitledBlocks } from '../block-heading';
 // 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.
+//
+// A heading with inline math is listed by the manifest's text for it: Astro
+// lists a heading by all the text in it, which for a formula is its MathML,
+// its LaTeX and its glyphs run together.
 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));
+  const lessonId = lessonIdFromSlug(routeSlug);
+  const texts = await mathHeadingTextsOf(lessonId);
+  const blocks = await titledBlocksOf(lessonId);
   if (blocks.length > 0) {
     route.toc = {
       ...route.toc,
-      items: tocWithTitledBlocks(route.toc, route.headings, blocks),
+      items: tocWithTitledBlocks(route.toc, withHeadingTexts(route.headings, texts), blocks),
     };
     blockKinds = Object.fromEntries(blocks.map((block) => [block.anchor, block.kind]));
+  } else if (texts.size > 0) {
+    route.toc = { ...route.toc, items: tocWithHeadingTexts(route.toc.items, texts) };
   }
 }
 ---

package/src/components/starlight/LayoutSocialIcons.astro

@@ -1,38 +1,88 @@
 ---
 /**
  * Starlight allows one `SocialIcons` override, so this composes the stock
- * social-link row with lesson export and `[?]` About controls. They sit in the
- * header's right cluster; the About panel is present on every route.
+ * social-link row with page export and `[?]` About controls. They sit in the
+ * header's right cluster; the About panel is present on every route, the
+ * export actions on every page the manifest knows (each chapter, the landing
+ * page, a part's page, the glossary, … — not the 404 route). On a touch
+ * screen the reader's text size follows (`TextSizeControl.astro`); in the
+ * phone menu it sits beside the theme switch.
+ *
+ * The Download menu lists the scopes that contain the page (D1, D4): "This
+ * chapter" on a chapter, "This part" on a chapter or its part's page, and
+ * "Whole course" on every page. Each scope downloads as standalone HTML (a
+ * part and the course as one file each); with `latex`, as PDF and LaTeX
+ * source (a part and the course as a book); with `markdown`, as Markdown. A page that is not a chapter has no download of its own (D8):
+ * its content is in its part's and the course's files.
  */
 import DefaultSocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
 import { loadManifest } from '../../compiler/manifest';
+import { docsSlugsForRoute } from '../../compiler/lesson-derivation';
 import {
-  isLessonSlug,
-  lessonIdFromSlug,
-} from '../../compiler/lesson-derivation';
+  courseFileStem,
+  exportPageSlugs,
+  standaloneFilename,
+} from '../../compiler/exports/export-pages';
 import AboutPanel from './AboutPanel.astro';
-import LessonExportActions from './LessonExportActions.astro';
+import LessonExportActions, {
+  type DownloadCell,
+  type DownloadRow,
+} from './LessonExportActions.astro';
+import TextSizeControl from './TextSizeControl.astro';
 
-const routeSlug = Astro.locals.starlightRoute.entry.id;
-const lessonId = isLessonSlug(routeSlug)
-  ? lessonIdFromSlug(routeSlug)
-  : undefined;
-let standaloneDownload:
-  | { readonly href: string; readonly filename: string }
-  | undefined;
-let printEnabled = false;
-let canonicalBaseUrl: string | undefined;
-if (lessonId) {
-  const manifest = await loadManifest();
-  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
-  printEnabled = lesson !== undefined && manifest.lessonExports.print;
-  canonicalBaseUrl = manifest.lessonExports.canonicalBaseUrl;
-  if (lesson && manifest.lessonExports.standaloneHtml) {
-    const base = import.meta.env.BASE_URL.replace(/\/$/, '');
-    standaloneDownload = {
-      href: `${base}/downloads/${lesson.slug}.html`,
-      filename: `${lesson.slug.split('/').at(-1) ?? 'lesson'}.html`,
-    };
+const manifest = await loadManifest();
+const routeSlugs = docsSlugsForRoute(Astro.locals.starlightRoute.entry.id);
+const pageSlug = exportPageSlugs(manifest).find((slug) =>
+  routeSlugs.includes(slug),
+);
+const exports = manifest.lessonExports;
+const printEnabled = pageSlug !== undefined && exports.print;
+const lesson = manifest.lessons.find((entry) => entry.slug === pageSlug);
+const part = lesson
+  ? manifest.parts.find((entry) => entry.ordinal === lesson.part)
+  : manifest.parts.find((entry) => `${entry.dir}/index` === pageSlug);
+
+const downloads: DownloadRow[] = [];
+if (lesson) {
+  const name = lesson.slug.split('/').at(-1) ?? lesson.slug;
+  const cells: DownloadCell[] = [];
+  if (exports.standaloneHtml) {
+    cells.push({ format: 'html', path: `${lesson.slug}.html`, filename: standaloneFilename(lesson.slug) });
+  }
+  if (exports.latex) {
+    cells.push(
+      { format: 'pdf', path: `${lesson.slug}.pdf`, filename: `${name}.pdf` },
+      { format: 'latex', path: `${lesson.slug}-latex.zip`, filename: `${name}-latex.zip` },
+    );
+  }
+  if (exports.markdown) {
+    cells.push({ format: 'markdown', path: `${lesson.slug}-markdown.zip`, filename: `${name}-markdown.zip` });
+  }
+  if (cells.length > 0) {
+    downloads.push({ scope: 'chapter', label: 'This chapter', title: lesson.title, cells });
+  }
+}
+if (pageSlug !== undefined) {
+  /** A part's or the course's downloads: `stem` names the files a reader saves. */
+  const wholeCells = (path: string, stem: string): DownloadCell[] => [
+    ...(exports.standaloneHtml ? [{ format: 'html' as const, path: `${path}.html`, filename: `${stem}.html` }] : []),
+    ...(exports.latex
+      ? [
+          { format: 'pdf' as const, path: `${path}.pdf`, filename: `${stem}.pdf` },
+          { format: 'latex' as const, path: `${path}-latex.zip`, filename: `${stem}-latex.zip` },
+        ]
+      : []),
+    ...(exports.markdown
+      ? [{ format: 'markdown' as const, path: `${path}-markdown.zip`, filename: `${stem}-markdown.zip` }]
+      : []),
+  ];
+  const partCells = part && part.lessons.length > 0 ? wholeCells(`part/${part.dir}`, part.dir) : [];
+  if (part && partCells.length > 0) {
+    downloads.push({ scope: 'part', label: 'This part', title: part.label, cells: partCells });
+  }
+  const courseCells = wholeCells('course', courseFileStem(manifest));
+  if (courseCells.length > 0) {
+    downloads.push({ scope: 'course', label: 'Whole course', title: manifest.about.material.name, cells: courseCells });
   }
 }
 ---
@@ -40,12 +90,12 @@ if (lessonId) {
 <DefaultSocialIcons />
 <AboutPanel />
 {
-  (standaloneDownload || printEnabled) && (
+  (downloads.length > 0 || printEnabled) && (
     <LessonExportActions
-      standaloneDownload={standaloneDownload}
+      downloads={downloads}
       print={printEnabled}
-      canonicalBaseUrl={canonicalBaseUrl}
       siteBaseUrl={import.meta.env.BASE_URL}
     />
   )
 }
+<TextSizeControl />