explico 0.13.1 → 0.15.0

package/src/compiler/lesson-derivation.ts

@@ -26,19 +26,92 @@
 
 import { citedIds, withoutLinkCitations } from '../reference/citation-format.mjs';
 
-/** `foundations/discount-factors` → `foundations.discount-factors`. */
+/**
+ * `foundations/discount-factors` → `foundations.discount-factors`. A deck
+ * file's slug (`foundations/discount-factors.deck.mdx`) gives its lesson's id;
+ * a deck's route (`foundations/discount-factors/slides`) gives the deck's page
+ * id, `foundations.discount-factors.slides` ({@link deckPageId}).
+ */
 export function lessonIdFromSlug(slug: string): string {
-  return slug.replace(/\.(md|mdx)$/, '').replace(/\//g, '.');
+  return slug.replace(/\.(md|mdx)$/, '').replace(/\.deck$/, '').replace(/\//g, '.');
 }
 
 /**
- * A docs entry is a lesson when it lives in a section directory. The three
+ * A docs entry is a chapter when it lives in a section directory. The three
  * top-level pages (`index`, `curriculum-map`, `glossary`) are not lessons; a
- * future `<section>/index` page would not be one either.
+ * future `<section>/index` page would not be one either, and neither is a
+ * lesson's deck file (`<lesson>.deck.mdx`, {@link isDeckSlug}), which is an
+ * edition of a lesson rather than a lesson.
  */
 export function isLessonSlug(slug: string): boolean {
   const clean = slug.replace(/\.(md|mdx)$/, '');
-  return clean.includes('/') && !clean.endsWith('/index');
+  return clean.includes('/') && !clean.endsWith('/index') && !isDeckSlug(clean);
+}
+
+/**
+ * The last segment of a deck's route when the deck stands beside its chapter:
+ * `projectiles/projectile-range` is the chapter, `projectiles/projectile-range/slides`
+ * the deck.
+ */
+export const DECK_ROUTE_SEGMENT = 'slides';
+
+/**
+ * A deck file — a lesson's slide edition, `content/docs/<part>/<lesson>.deck.mdx`
+ * beside the chapter `<lesson>.mdx` or alone for a lesson that is only slides,
+ * or a part's deck ({@link isPartDeckSlug}). True for the docs slug with or
+ * without its extension; a caller that needs the lesson asks
+ * {@link isPartDeckSlug} first.
+ */
+export function isDeckSlug(slug: string): boolean {
+  return /\.deck(?:\.mdx?)?$/.test(slug);
+}
+
+/** The lesson a lesson's deck file belongs to: `motion/range.deck.mdx` → `motion/range`. */
+export function deckLessonSlug(slug: string): string {
+  return slug.replace(/\.(md|mdx)$/, '').replace(/\.deck$/, '');
+}
+
+/**
+ * A part's deck, `content/docs/<part>/index.deck.mdx` beside the part's page
+ * `index.mdx`: the slides of the part, served at `/<part>/slides/`
+ * ({@link partDeckRouteSlug}), whose `##` sections may each name the chapter
+ * they cover (`docs/authoring/deck.md`). It is no lesson's edition.
+ */
+export function isPartDeckSlug(slug: string): boolean {
+  return /^[^/]+\/index\.deck(?:\.mdx?)?$/.test(slug);
+}
+
+/** The part a part's deck belongs to: `motion/index.deck.mdx` → `motion`. */
+export function partDeckDir(slug: string): string {
+  return slug.replace(/\/index\.deck(?:\.mdx?)?$/, '');
+}
+
+/** Where a part's deck is served: `<part>/slides`, as a chapter's deck is `<lesson>/slides`. */
+export function partDeckRouteSlug(partDir: string): string {
+  return `${partDir}/${DECK_ROUTE_SEGMENT}`;
+}
+
+/** The page id of a part's deck, the id of its route: `<part>.slides`. */
+export function partDeckPageId(partDir: string): string {
+  return `${partDir}.${DECK_ROUTE_SEGMENT}`;
+}
+
+/**
+ * Where a lesson's deck is served: `<lesson>/slides` beside its chapter, or
+ * the lesson's own route when the lesson has no chapter (a slides-first
+ * lesson, whose deck is its only edition).
+ */
+export function deckRouteSlug(lessonSlug: string, hasChapter: boolean): string {
+  return hasChapter ? `${lessonSlug}/${DECK_ROUTE_SEGMENT}` : lessonSlug;
+}
+
+/**
+ * The page id a deck's notation bundle, gates and diagnostics use — the id of
+ * its route ({@link lessonIdFromSlug}): `<lessonId>.slides` beside a chapter,
+ * the lesson's own id for a slides-first lesson.
+ */
+export function deckPageId(lessonId: string, hasChapter: boolean): string {
+  return hasChapter ? `${lessonId}.${DECK_ROUTE_SEGMENT}` : lessonId;
 }
 
 /**
@@ -153,7 +226,8 @@ export interface SidebarSection {
 /**
  * One sidebar entry: a lesson slug, or an explicit link. `attrs` is Starlight's
  * own passthrough onto the rendered `<a>` — the engine uses it to mark a part's
- * overview row so CSS can give it its own icon.
+ * overview row so CSS can give it its own icon, and to name each edition of a
+ * lesson for the sidebar's script ({@link buildSidebar}).
  */
 export type SidebarItem =
   | string
@@ -161,6 +235,15 @@ export type SidebarItem =
       readonly label: string;
       readonly link: string;
       readonly attrs?: Readonly<Record<string, string>>;
+    }
+  | {
+      /**
+       * A docs entry by its id (Starlight's `slug` item), with its own label,
+       * or the entry's title without one.
+       */
+      readonly slug: string;
+      readonly label?: string;
+      readonly attrs?: Readonly<Record<string, string>>;
     };
 
 export interface SidebarGroup {
@@ -171,49 +254,190 @@ export interface SidebarGroup {
 /** Marks the overview row so `global.css` can give it its own icon. */
 export const PART_OVERVIEW_CLASS = 'explico-part-overview';
 
+/**
+ * Marks a deck's row, listed under its chapter, so `deck.css` can set it
+ * apart. That is the sidebar without its script; with it, the deck is its
+ * chapter row's trailing icon, or leads the row (`sidebar-editions.ts`).
+ */
+export const DECK_ROW_CLASS = 'explico-deck-row';
+
+/**
+ * Marks a slides-first lesson's row, whose deck is the lesson, so `deck.css`
+ * gives it the deck's glyph where a chapter has none (a row) or a sheet (a
+ * compact tile). It is a lesson of the reading order, unlike {@link DECK_ROW_CLASS}.
+ */
+export const DECK_LESSON_CLASS = 'explico-deck-lesson';
+
+/**
+ * Marks a part's deck, listed right after the part's Overview (with
+ * {@link DECK_ROW_CLASS}, so Next and Previous step past it as past any
+ * deck): the part's own, as Overview is, with the part's deck glyph. The
+ * sidebar's script makes the two one row, the part's, as a lesson's chapter
+ * and deck are one (`sidebar-editions.ts`).
+ */
+export const PART_DECK_CLASS = 'explico-part-deck';
+
+/**
+ * Numbers as a reader reads a run of them: `1–2`, `1, 3`, `2–4, 6`. A run of
+ * two or more is its ends with an en dash.
+ */
+export function numberList(numbers: readonly number[]): string {
+  const sorted = [...new Set(numbers)].sort((left, right) => left - right);
+  const runs: string[] = [];
+  for (let start = 0; start < sorted.length; ) {
+    let end = start;
+    while (end + 1 < sorted.length && sorted[end + 1] === sorted[end]! + 1) end += 1;
+    runs.push(end === start ? String(sorted[start]) : `${sorted[start]}–${sorted[end]}`);
+    start = end + 1;
+  }
+  return runs.join(', ');
+}
+
+/**
+ * The lesson a sidebar item lists, by its slug: an item served at its
+ * lesson's own URL (its `data-lesson` is its `slug`), a chapter or a
+ * slides-first lesson's deck. A part's overview, a chapter's slides row
+ * (served under the chapter) and a link list no lesson. A bare slug is a
+ * lesson too.
+ */
+export function sidebarLessonSlug(item: SidebarItem): string | undefined {
+  if (typeof item === 'string') return item;
+  if (!('slug' in item)) return undefined;
+  return item.attrs?.['data-lesson'] === item.slug ? item.slug : undefined;
+}
+
 /**
  * The Starlight `sidebar` config: one group per section, lessons ordered by the
  * merged track order (ties broken by slug), then the static Reference group.
  * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
  * `floatIndex`: the course has a top-level "Figures and tables" page
  * (`figures-and-tables.mdx`, `FloatIndex.astro`), listed in Reference.
+ *
+ * Each edition of a lesson is an item of its own, its chapter first, and
+ * names its edition, lesson and title (`data-edition`, `data-lesson`,
+ * `data-title` on the link): the HTML lists both, and the sidebar's script
+ * (`LayoutSidebar.astro`, `sidebar-editions.ts`) makes the two one row.
+ *
+ * A part's deck is an item of the part right after its Overview. Both name
+ * their part and which of its two editions they are (`data-part`,
+ * `data-part-edition`), and the deck its part's label and the ordinals of
+ * the chapters it covers (`data-title`, `data-chapters`: `1–2`), so the
+ * script makes them the part's one row. A chapter it covers that has no deck
+ * of its own carries the address of its section in the part's deck
+ * (`data-deck-href`, `/<part>/slides/#slide-N`, without the site's base),
+ * which the script makes the chapter's other edition: a lesson's own deck
+ * wins over its part's. The frames the deck and each section hold are
+ * `buildDecks`'s, added once it has run ({@link withPartDeckFrames}).
  */
 export function buildSidebar(
   tracks: readonly TrackLike[],
   lessonSlugs: readonly string[],
   parts: readonly SidebarSection[],
-  { floatIndex = false }: { readonly floatIndex?: boolean } = {},
+  {
+    floatIndex = false,
+    decks = new Map(),
+    slidesFirst = new Set(),
+    partDecks = new Map(),
+    titleOf = () => undefined,
+  }: {
+    readonly floatIndex?: boolean;
+    /** A deck beside its chapter: chapter slug → the deck's route, listed under the chapter. */
+    readonly decks?: ReadonlyMap<string, string>;
+    /** The lessons whose only edition is a deck, by slug: listed with the deck's glyph. */
+    readonly slidesFirst?: ReadonlySet<string>;
+    /**
+     * A part's deck, by the part's directory: its route, and the frame each
+     * chapter it covers opens on (its section's divider), by chapter slug.
+     */
+    readonly partDecks?: ReadonlyMap<
+      string,
+      { readonly route: string; readonly covers: ReadonlyMap<string, number> }
+    >;
+    /** A lesson's title, by its slug: `data-title` on each of its items, left out when unknown. */
+    readonly titleOf?: (slug: string) => string | undefined;
+  } = {},
 ): SidebarGroup[] {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index]),
   );
   const positionOf = (slug: string) =>
     rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
+  const edition = (lesson: string, name: 'chapter' | 'slides'): Record<string, string> => {
+    const title = titleOf(lesson);
+    return {
+      'data-edition': name,
+      'data-lesson': lesson,
+      ...(title === undefined ? {} : { 'data-title': title }),
+    };
+  };
 
   const groups: SidebarGroup[] = parts.map(
     ({ dir, label, overviewLabel, overviewLink }) => {
-      const chapters = lessonSlugs
+      const partDeck = partDecks.get(dir);
+      const ordered = lessonSlugs
         .filter((slug) => slug.startsWith(`${dir}/`))
         .sort(
           (left, right) =>
             positionOf(left) - positionOf(right) || left.localeCompare(right),
         );
+      const chapters: SidebarItem[] = ordered.flatMap((slug): SidebarItem[] => {
+        if (slidesFirst.has(slug)) {
+          return [{ slug, attrs: { class: DECK_LESSON_CLASS, ...edition(slug, 'slides') } }];
+        }
+        const deck = decks.get(slug);
+        // A chapter with no deck of its own: its section of the part's deck.
+        const frame = deck === undefined ? partDeck?.covers.get(slug) : undefined;
+        const chapter = {
+          slug,
+          attrs: {
+            ...edition(slug, 'chapter'),
+            ...(frame === undefined || partDeck === undefined
+              ? {}
+              : { 'data-deck-href': `/${partDeck.route}/#slide-${frame}` }),
+          },
+        };
+        return deck === undefined
+          ? [chapter]
+          : [chapter, { slug: deck, label: 'Slides', attrs: { class: DECK_ROW_CLASS, ...edition(slug, 'slides') } }];
+      });
       // The overview leads the group: it is the part's own page, so it reads
       // as the chapter list's heading rather than an appendix to it, and in
-      // compact mode it is the first icon instead of the last.
-      return {
-        label,
-        items: overviewLink
+      // compact mode it is the first icon instead of the last. The part's
+      // deck follows it, as the part's own too.
+      const own: SidebarItem[] = [
+        ...(overviewLink
           ? [
               {
                 label: overviewLabel ?? 'Overview',
                 link: overviewLink,
-                attrs: { class: PART_OVERVIEW_CLASS },
+                attrs: { class: PART_OVERVIEW_CLASS, 'data-part': dir, 'data-part-edition': 'overview' },
               },
-              ...chapters,
             ]
-          : chapters,
-      };
+          : []),
+        ...(partDeck === undefined
+          ? []
+          : [
+              {
+                slug: partDeck.route,
+                label: 'Slides',
+                attrs: {
+                  class: `${DECK_ROW_CLASS} ${PART_DECK_CLASS}`,
+                  'data-edition': 'slides',
+                  'data-part': dir,
+                  'data-part-edition': 'slides',
+                  'data-title': label,
+                  // A chapter's ordinal is its place in the part, as `lessons[].chapter` numbers it.
+                  'data-chapters': numberList(
+                    [...partDeck.covers.keys()].flatMap((slug) => {
+                      const at = ordered.indexOf(slug);
+                      return at === -1 ? [] : [at + 1];
+                    }),
+                  ),
+                },
+              },
+            ]),
+      ];
+      return { label, items: [...own, ...chapters] };
     },
   );
 
@@ -228,3 +452,45 @@ export function buildSidebar(
 
   return groups;
 }
+
+/** A part's deck as {@link withPartDeckFrames} reads it: its part and its frames, each with the chapter it covers. */
+export interface PartDeckFrames {
+  readonly part?: string;
+  readonly frames: readonly { readonly number: number; readonly chapter?: string }[];
+}
+
+/**
+ * The sidebar with each part's deck's frames, as `buildDecks` numbers them:
+ * the deck's count on its item (`data-frames`), and on each chapter that
+ * links into its section the frames that section holds (`data-deck-range`,
+ * `2–16`, or `5` for one), its first to its last when it runs over several
+ * sections. `buildDecks` runs after the sidebar is built, since the chapters
+ * it numbers are ordered by the sidebar.
+ */
+export function withPartDeckFrames(
+  groups: readonly SidebarGroup[],
+  decks: readonly PartDeckFrames[],
+): SidebarGroup[] {
+  const byPart = new Map(decks.flatMap((deck) => (deck.part === undefined ? [] : [[deck.part, deck] as const])));
+  const rangeOf = (chapter: string): string | undefined => {
+    const numbers = decks.flatMap((deck) =>
+      deck.part === undefined ? [] : deck.frames.filter((frame) => frame.chapter === chapter).map((frame) => frame.number),
+    );
+    if (numbers.length === 0) return undefined;
+    const first = Math.min(...numbers);
+    const last = Math.max(...numbers);
+    return first === last ? String(first) : `${first}–${last}`;
+  };
+  return groups.map((group) => ({
+    ...group,
+    items: group.items.map((item): SidebarItem => {
+      if (typeof item === 'string' || item.attrs === undefined) return item;
+      const attrs = item.attrs;
+      const deck = attrs['data-part-edition'] === 'slides' ? byPart.get(attrs['data-part'] ?? '') : undefined;
+      if (deck) return { ...item, attrs: { ...attrs, 'data-frames': String(deck.frames.length) } };
+      const lesson = attrs['data-lesson'];
+      const range = attrs['data-deck-href'] === undefined || lesson === undefined ? undefined : rangeOf(lesson);
+      return range === undefined ? item : { ...item, attrs: { ...attrs, 'data-deck-range': range } };
+    }),
+  }));
+}