explico 0.13.1 → 0.14.0

package/src/components/starlight/sidebar-editions.ts

@@ -0,0 +1,245 @@
+/**
+ * A lesson's editions in the sidebar (`sidebarEditions` in the course
+ * settings): a lesson with a chapter and a deck is one row. The row opens the
+ * **lead** edition under the lesson's title, and the **other** edition is an
+ * icon at the row's end, the second tile of a joined pair in a compact part,
+ * or not listed. A lesson with one edition is one row in every state; only
+ * when that edition is not the lead does the row carry its glyph, so the
+ * exception is marked and nothing else is.
+ *
+ * The course sets the default; the reader's own choice, made with the two
+ * controls in the sidebar's foot, is a setting kept in their browser
+ * whatever they answered about reading memory (`explico-sidebar-editions`,
+ * `session/reading-memory.ts`). It is kept field by field: a field the
+ * reader never set keeps the course's default, so a course that changes its
+ * default moves the readers who did not choose.
+ *
+ * Pure: `LayoutSidebar.astro` does the DOM and the storage, and
+ * `tests/unit/sidebar-editions.test.ts` checks this in Node.
+ */
+import type {
+  NormalizedSidebarEditions,
+  SidebarEditionLead,
+  SidebarEditionOther,
+} from '../../compiler/course-config';
+
+/** A lesson's edition, as `data-edition` names it on its sidebar link: its chapter or its deck. */
+export type Edition = SidebarEditionLead;
+
+/** What the sidebar shows: the edition a lesson's row opens, and whether it lists the other. */
+export type EditionsState = NormalizedSidebarEditions;
+
+/** The reader's choice: a field they never set is left out. */
+export type EditionsChoice = Partial<EditionsState>;
+
+/** Where the reader's choice is kept: one key for every explico course on the site, like `explico-sidebar-groups`. */
+export const SIDEBAR_EDITIONS_KEY = 'explico-sidebar-editions';
+
+/** Told on `window` once the rows are rebuilt, so the marks and the progress rail follow them. */
+export const SIDEBAR_EDITIONS_EVENT = 'explico:sidebar-editions';
+
+/** The other edition's link: the icon at a row's end, or a pair's second tile. */
+export const EDITION_OTHER_CLASS = 'layout-edition-other';
+
+/** A chapter that is a lesson's only edition while slides lead: its row carries a sheet. */
+export const CHAPTER_LESSON_CLASS = 'explico-chapter-lesson';
+
+/**
+ * Marks a chapter's section of its part's deck: the link the script makes
+ * a chapter's other edition from the chapter link's `data-deck-href` (the
+ * compiler's, `buildSidebar`) when the chapter has no deck of its own. It
+ * is no page of its own, so the marks pass it by; the part's deck's own
+ * row carries the deck page's.
+ */
+export const DECK_SECTION_ATTRIBUTE = 'data-deck-section';
+
+/**
+ * A chapter's section of its part's deck, under the site's base: the
+ * compiler writes it without one (`/motion/slides/#slide-9`), as Starlight's
+ * own links are written.
+ */
+export function deckSectionHref(base: string, deckHref: string): string {
+  return `${base.replace(/\/+$/u, '')}${deckHref.startsWith('/') ? deckHref : `/${deckHref}`}`;
+}
+
+/**
+ * The compiler's classes for a deck's link, `DECK_ROW_CLASS` (a chapter's
+ * "Slides" row) and `DECK_LESSON_CLASS` (a slides-first lesson), from
+ * `compiler/lesson-derivation.ts`: spelt out here so the browser bundle does
+ * not load the compiler.
+ */
+const DECK_ROW_CLASS = 'explico-deck-row';
+const DECK_LESSON_CLASS = 'explico-deck-lesson';
+
+/** The glyph class a lesson's one edition takes when it is not the lead. */
+export const GLYPH_CLASS: Readonly<Record<Edition, string>> = {
+  chapter: CHAPTER_LESSON_CLASS,
+  slides: DECK_LESSON_CLASS,
+};
+
+/** Every class a lesson's link can carry for its place in a row, the compiler's included: a rebuild starts from none. */
+export const ROW_CLASSES: readonly string[] = [EDITION_OTHER_CLASS, CHAPTER_LESSON_CLASS, DECK_LESSON_CLASS, DECK_ROW_CLASS];
+
+/**
+ * The same for a part's link: its own class (`explico-part-overview`,
+ * `explico-part-deck`) stays, since it draws the part's glyph in every place.
+ */
+export const PART_ROW_CLASSES: readonly string[] = [EDITION_OTHER_CLASS, DECK_ROW_CLASS];
+
+/**
+ * A link's second line, inside its `<span>` after its name: shown where the
+ * span is a tooltip, hidden where it is a row's text (`global.css`). The
+ * link's `aria-description` says it to assistive technology.
+ */
+export const EDITION_DETAIL_CLASS = 'layout-edition-detail';
+
+const EDITIONS: readonly Edition[] = ['chapter', 'slides'];
+const OTHERS: readonly SidebarEditionOther[] = ['listed', 'hidden'];
+
+const isEdition = (value: unknown): value is Edition => EDITIONS.includes(value as Edition);
+const isOther = (value: unknown): value is SidebarEditionOther => OTHERS.includes(value as SidebarEditionOther);
+
+/** A stored choice, or the course's payload: each field it holds with a value it may have; anything else is left out. */
+export function decodeEditionsChoice(raw: string | null): EditionsChoice {
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object') return {};
+  const { lead, other } = parsed as { lead?: unknown; other?: unknown };
+  return { ...(isEdition(lead) ? { lead } : {}), ...(isOther(other) ? { other } : {}) };
+}
+
+/** The stored text of a choice: `{"lead":"slides"}`, `{"lead":"slides","other":"listed"}`. */
+export function encodeEditionsChoice(choice: EditionsChoice): string {
+  return JSON.stringify({
+    ...(choice.lead === undefined ? {} : { lead: choice.lead }),
+    ...(choice.other === undefined ? {} : { other: choice.other }),
+  });
+}
+
+/** What the sidebar shows: the reader's choice, field by field, over the course's default. */
+export function resolveEditions(course: EditionsState, choice: EditionsChoice): EditionsState {
+  return { lead: choice.lead ?? course.lead, other: choice.other ?? course.other };
+}
+
+/** The row a lesson takes. */
+export interface LessonRow {
+  /** The edition the row opens, under the lesson's title. */
+  readonly lead: Edition;
+  /** The edition at the row's end, or the pair's second tile: none while hidden, or with one edition. */
+  readonly other?: Edition;
+  /** The glyph before the title: the lesson's one edition, when it is not the lead. */
+  readonly glyph?: Edition;
+}
+
+/**
+ * The row of a lesson with `editions` (one or both), in `state`. `open` is
+ * the edition that is the page open now, if it is one of this lesson's: a
+ * hidden edition is listed while it is open, so the open page is never
+ * missing from the sidebar.
+ */
+export function lessonRow(editions: readonly Edition[], state: EditionsState, open?: Edition): LessonRow {
+  const has = new Set(editions);
+  if (has.size < 2) {
+    const only = editions[0] ?? state.lead;
+    return only === state.lead ? { lead: only } : { lead: only, glyph: only };
+  }
+  const other: Edition = state.lead === 'chapter' ? 'slides' : 'chapter';
+  return state.other === 'listed' || open === other ? { lead: state.lead, other } : { lead: state.lead };
+}
+
+/**
+ * A link's text: the lesson's title on the row's own link, and on the other
+ * edition's icon the title it stands for ("Slides: Projectile Range"), which
+ * is its accessible name and its tooltip.
+ */
+export function editionLabel(edition: Edition, title: string, role: 'lead' | 'other'): string {
+  if (role === 'lead') return title;
+  return `${edition === 'slides' ? 'Slides' : 'Chapter'}: ${title}`;
+}
+
+/**
+ * A part's two links (`buildSidebar`): its Overview and its deck, each
+ * naming which it is. The script makes them the part's one row, as a
+ * lesson's chapter and deck are one: Overview stands where a chapter stands.
+ */
+export const PART_EDITION_ATTRIBUTE = 'data-part-edition';
+
+/** One of a part's two links, as `data-part-edition` names it. */
+export type PartEdition = 'overview' | 'slides';
+
+/** The row a part takes: the link it opens, and the link at its end. */
+export interface PartRow {
+  readonly lead: PartEdition;
+  readonly other?: PartEdition;
+}
+
+/**
+ * The row of a part with a deck, in `state`: with an Overview, a lesson's
+ * row with Overview for its chapter; without one, the deck's own row,
+ * listed unless chapters lead with the other edition unlisted. `open` is
+ * the part's link that is the page open now: it is always listed.
+ */
+export function partRow(hasOverview: boolean, state: EditionsState, open?: PartEdition): PartRow | undefined {
+  if (!hasOverview) {
+    return state.lead === 'chapter' && state.other === 'hidden' && open !== 'slides' ? undefined : { lead: 'slides' };
+  }
+  const asPart = (edition: Edition): PartEdition => (edition === 'chapter' ? 'overview' : 'slides');
+  const row = lessonRow(['chapter', 'slides'], state, open === undefined ? undefined : open === 'overview' ? 'chapter' : 'slides');
+  return row.other === undefined ? { lead: asPart(row.lead) } : { lead: asPart(row.lead), other: asPart(row.other) };
+}
+
+/**
+ * A part's link's text: Overview's own label (`overviewLabel`, "Overview" by
+ * default) or "Slides for this part" leading the row, and the part's name
+ * after either at its end, which is the icon's name and its tooltip.
+ */
+export function partEditionLabel(edition: PartEdition, part: string, role: 'lead' | 'other', overviewLabel = 'Overview'): string {
+  if (edition === 'overview') return role === 'lead' ? overviewLabel : `Overview: ${part}`;
+  return role === 'lead' ? 'Slides for this part' : `Slides for this part: ${part}`;
+}
+
+/**
+ * The part's deck's second line: the chapters it covers (`1–2`, `1, 3`, as
+ * `data-chapters` writes them) and its slides. `Chapters 1–2 · 26 slides`,
+ * `Chapter 1 · 9 slides`.
+ */
+export function partDeckDetail(chapters: string, frames: number): string {
+  const slides = `${frames} ${frames === 1 ? 'slide' : 'slides'}`;
+  if (chapters.trim() === '') return slides;
+  return `${/[–,]/u.test(chapters) ? 'Chapters' : 'Chapter'} ${chapters} · ${slides}`;
+}
+
+/**
+ * A chapter's section's second line: its frames in the part's deck, as
+ * `data-deck-range` writes them. `Slides 17–26 of the part's slides`,
+ * `Slide 5 of the part's slides`.
+ */
+export function sectionDetail(range: string): string {
+  return `${range.includes('–') ? 'Slides' : 'Slide'} ${range} of the part's slides`;
+}
+
+/**
+ * Told on `window` by a deck's page when the chapter on screen changes
+ * (`deck-controller.ts`): `{ deck, chapter }`, the deck's slug and the
+ * chapter's lesson slug, empty on a frame of no chapter. The sidebar lights
+ * that chapter's section link and moves the rail to it.
+ */
+export const DECK_FRAME_EVENT = 'explico:deck-frame';
+
+/**
+ * The chapter on screen, on `<html>`, as {@link DECK_FRAME_EVENT} tells it:
+ * whichever of the deck's script and the sidebar's runs first, the sidebar
+ * reads the state from here.
+ */
+export const DECK_CHAPTER_ATTRIBUTE = 'data-deck-chapter';
+
+/** What {@link DECK_FRAME_EVENT} tells. */
+export interface DeckFrameDetail {
+  readonly deck: string;
+  readonly chapter: string;
+}

package/src/components/table/Table.astro

@@ -21,7 +21,8 @@
  * a table keeps that caption line and its header row (decision Q6).
  */
 import { courseDisclosure } from '../disclosure/course-disclosure';
-import { captionTitle } from '../float-name';
+import { deckFloat } from '../deck/deck-context';
+import { captionTitle } from '../../reference/float-name';
 
 export interface Props {
   /** Stable key, e.g. `id="kinematics-summary"`. Omit for a positional-only table. */
@@ -37,6 +38,9 @@ export interface Props {
 }
 
 const { id, caption, short, number, anchorId } = Astro.props;
+// On a deck, the deck's own table carries no number and a recalled one's
+// number links to its chapter (rule D8).
+const { onDeck, numberHref } = await deckFloat(Astro.locals, anchorId, import.meta.env.BASE_URL);
 // A table longer than this starts truncated (the course's
 // `disclosure.tables.truncateAfter`, default 6).
 const { truncateAfter } = (await courseDisclosure()).tables;
@@ -47,7 +51,7 @@ if (typeof caption !== 'string' || !caption.trim()) {
 if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
   throw new Error('Table `short` must be a non-empty string when given.');
 }
-if (!number || !anchorId) {
+if ((!number && !onDeck) || !anchorId) {
   throw new Error(
     `Table is missing its computed \`number\`/\`anchorId\`. remark-notation numbers a <Table> only on a lesson page, at its top level or in a <Memo>, <ShortNote> or <Fold>: elsewhere (a worked example) write a plain Markdown table, and on a page that is not a chapter (rule S10) link the chapter's table. At a lesson's top level, this page is not running remark-notation with the manifest's \`tables\` (see astro.config.mjs).`,
   );
@@ -63,11 +67,15 @@ if (!number || !anchorId) {
   data-truncate-after={truncateAfter}
 >
   <figcaption class="keyed-table__caption float-caption">
-    <a
-      class="keyed-table__number float-caption__number"
-      href={`#${anchorId}`}
-      aria-label={`Table ${number}`}>Table {number}</a
-    >
+    {
+      number && (
+        <a
+          class="keyed-table__number float-caption__number"
+          href={numberHref ?? `#${anchorId}`}
+          aria-label={`Table ${number}`}>Table {number}</a
+        >
+      )
+    }
     {short && <b class="float-caption__title">{captionTitle(short)}</b>}{short && ' '}<span
       class="keyed-table__caption-text float-caption__text">{caption}</span
     >

package/src/content-config.ts

@@ -1,6 +1,11 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import { defineCollection } from 'astro:content';
 import { glob } from 'astro/loaders';
-import { docsSchema } from '@astrojs/starlight/schema';
+import type { Loader } from 'astro/loaders';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
+import { slug as githubSlug } from 'github-slugger';
 import {
   abbreviationSchema,
   assessmentSchema,
@@ -10,6 +15,7 @@ import {
   sourceSchema,
   trackSchema,
 } from './compiler/content-schemas';
+import { isPartDeckSlug, partDeckDir } from './compiler/lesson-derivation';
 
 // The schemas live in `compiler/content-schemas.ts`, where the manifest walk
 // checks every record against them too (`validate:content` rejects what this
@@ -19,9 +25,46 @@ import {
 // `docsLoader()` is hard-wired to `<srcDir>/content/docs`, so the `docs`
 // collection uses a plain glob with the same extensions and `_`-prefix ignore.
 const CONTENT_DIR = './content';
+
+/**
+ * Astro's own id for a docs file (`generateIdDefault` in `astro/loaders`):
+ * the frontmatter `slug` if any, else each path segment slugged, the
+ * extension and a trailing `/index` dropped.
+ */
+function defaultDocsId(entry: string, data: Record<string, unknown>): string {
+  if (data.slug) return String(data.slug);
+  return entry
+    .replace(/\.(md|mdx)$/, '')
+    .split('/')
+    .map((segment) => githubSlug(segment))
+    .join('/')
+    .replace(/\/index$/, '');
+}
+
+/**
+ * A lesson's deck, `<lesson>.deck.mdx`, is served at `<lesson>/slides/`
+ * beside its chapter, and at the lesson's own URL when the lesson has no
+ * chapter (`deckRouteSlug` in `compiler/lesson-derivation.ts`, which the
+ * manifest uses for the same route). A part's deck, `<part>/index.deck.mdx`,
+ * is served at `<part>/slides/` (`partDeckRouteSlug`). Every other page
+ * keeps Astro's id.
+ */
+function docsId({ entry, base, data }: { entry: string; base: URL; data: Record<string, unknown> }): string {
+  const deck = /^(.*)\.deck\.(md|mdx)$/.exec(entry);
+  if (!deck || data.slug) return defaultDocsId(entry, data);
+  if (isPartDeckSlug(entry)) return `${defaultDocsId(`${partDeckDir(entry)}.mdx`, {})}/slides`;
+  const lesson = deck[1] ?? '';
+  const hasChapter = ['.mdx', '.md'].some((extension) =>
+    existsSync(fileURLToPath(new URL(`./${encodeURI(lesson)}${extension}`, base))),
+  );
+  const lessonId = defaultDocsId(`${lesson}.mdx`, {});
+  return hasChapter ? `${lessonId}/slides` : lessonId;
+}
+
 const docsGlob = glob({
   base: `${CONTENT_DIR}/docs`,
   pattern: '**/[^_]*.{md,mdx}',
+  generateId: docsId,
 });
 
 const docs = defineCollection({
@@ -29,6 +72,48 @@ const docs = defineCollection({
   schema: docsSchema({ extend: lessonFrontmatterSchema }),
 });
 
+const i18nGlob = glob({
+  base: `${CONTENT_DIR}/i18n`,
+  pattern: '**/[^_]*.{json,yml,yaml}',
+});
+
+/**
+ * Starlight reads its optional `i18n` collection even in a single-language
+ * course. Astro logs a warning when that collection is absent or empty, so
+ * supply an empty English entry until a course authors translations of its
+ * own. Avoid invoking `glob()` for a missing/empty directory: the loader would
+ * emit a second warning before Starlight reads the collection.
+ */
+const i18nLoader: Loader = {
+  name: 'explico-i18n-loader',
+  async load(context) {
+    const directory = new URL('content/i18n/', context.config.root);
+    let hasTranslations = false;
+    try {
+      const entries = await readdir(directory, { recursive: true });
+      hasTranslations = entries.some((entry) =>
+        /(^|[/\\])[^_/\\][^/\\]*\.(json|ya?ml)$/.test(entry),
+      );
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;
+    }
+
+    if (hasTranslations) {
+      await i18nGlob.load(context);
+      return;
+    }
+
+    context.store.clear();
+    const data = await context.parseData({ id: 'en', data: {} });
+    context.store.set({ id: 'en', data, digest: context.generateDigest(data) });
+  },
+};
+
+const i18n = defineCollection({
+  loader: i18nLoader,
+  schema: i18nSchema(),
+});
+
 const competencies = defineCollection({
   loader: glob({
     pattern: '**/*.json',
@@ -67,6 +152,7 @@ const abbreviations = defineCollection({
 
 export const collections = {
   docs,
+  i18n,
   competencies,
   assessments,
   tracks,

package/src/curriculum/competency-graph.ts

@@ -0,0 +1,95 @@
+/**
+ * The competency dependency graph, cut into one piece per part
+ * (`<CurriculumMap graph="per-part">`).
+ *
+ * The whole-course graph is one diagram, and a course with many competencies
+ * lays it out far wider than the lesson column (rule V8) — narrower boxes do
+ * not help, since the widest rank holds a dozen competencies. One diagram per
+ * part keeps each to the competencies a reader meets together.
+ */
+
+export interface GraphNode {
+  readonly id: string;
+  readonly text: string;
+}
+
+export interface GraphEdge {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface PartGraph {
+  /** The diagram's id, unique on the page: `competency-graph-<part dir>`. */
+  readonly id: string;
+  /** The part's overview title, its label when it has none; the untaught group's name. */
+  readonly title: string;
+  /** The competencies this group teaches, then one box per earlier competency they build on. */
+  readonly nodes: readonly GraphNode[];
+  /** An arrow from each prerequisite to a competency the group teaches. */
+  readonly edges: readonly GraphEdge[];
+}
+
+export interface PartInput {
+  readonly dir: string;
+  readonly label: string;
+  /** Lesson ids in chapter order. */
+  readonly lessons: readonly string[];
+  readonly overview?: { readonly title: string };
+}
+
+export interface CompetencyInput {
+  readonly id: string;
+  readonly title: string;
+  readonly prerequisites: readonly string[];
+}
+
+export const UNTAUGHT_GRAPH_ID = 'competency-graph-untaught';
+export const UNTAUGHT_TITLE = 'Competencies no lesson teaches';
+
+/**
+ * One graph per part, in `parts` order, then a last one for competencies no
+ * lesson teaches, so every competency is drawn once as a taught box. A
+ * competency belongs to the first part whose lessons teach it. A prerequisite
+ * taught in another part is drawn in this one as a box labelled
+ * `<part label>: <title>`, so the arrow into the competency still shows.
+ * A part that teaches no competency has no graph.
+ */
+export function competencyGraphsByPart(
+  parts: readonly PartInput[],
+  teachesByLesson: ReadonlyMap<string, readonly string[]>,
+  competencies: readonly CompetencyInput[],
+): PartGraph[] {
+  const partOf = new Map<string, PartInput>();
+  for (const part of parts) {
+    for (const lessonId of part.lessons) {
+      for (const id of teachesByLesson.get(lessonId) ?? []) {
+        if (!partOf.has(id)) partOf.set(id, part);
+      }
+    }
+  }
+  const titleOf = new Map(competencies.map((competency) => [competency.id, competency.title]));
+
+  const graphs: PartGraph[] = [];
+  for (const part of [...parts, undefined]) {
+    const taught = competencies.filter((competency) => partOf.get(competency.id) === part);
+    if (taught.length === 0) continue;
+    const earlier = [...new Set(taught.flatMap((competency) => competency.prerequisites))].filter(
+      (id) => partOf.get(id) !== part,
+    );
+    graphs.push({
+      id: part ? `competency-graph-${part.dir.replace(/[^A-Za-z0-9_-]/g, '-')}` : UNTAUGHT_GRAPH_ID,
+      title: part ? (part.overview?.title ?? part.label) : UNTAUGHT_TITLE,
+      nodes: [
+        ...taught.map((competency) => ({ id: competency.id, text: competency.title })),
+        ...earlier.map((id) => ({
+          id,
+          text: `${partOf.get(id)?.label ?? 'Not taught'}: ${titleOf.get(id) ?? id}`,
+        })),
+      ],
+      edges: taught.flatMap((competency) =>
+        competency.prerequisites.map((from) => ({ from, to: competency.id })),
+      ),
+    });
+  }
+  return graphs;
+}

package/src/reference/base-library.mjs

@@ -25,3 +25,22 @@ export const BASE_LIBRARY = Object.freeze(
 export function isBaseLibraryAtom(token) {
   return BASE_LIBRARY.has(token);
 }
+
+// An atom's LaTeX is its own glyph unless it is a command: `\pi` draws `π`.
+// `tests/notation/figure-symbols.test.ts` renders every atom and holds this
+// table to what KaTeX draws, so a new command atom cannot be forgotten here.
+const DRAWN_AS = Object.freeze({ '\\pi': 'π' });
+
+/** What KaTeX draws for each base-library atom: `d`, `e`, `i`, `π`. */
+export const BASE_LIBRARY_GLYPHS = Object.freeze(
+  new Set([...BASE_LIBRARY].map((atom) => DRAWN_AS[atom] ?? atom)),
+);
+
+/**
+ * True when `glyph`, as a rendered page shows it, is a base-library atom. The
+ * rendered-page check (`figure-symbols.ts`) reads glyphs, not LaTeX, and
+ * exempts the same library the math gates do.
+ */
+export function isBaseLibraryGlyph(glyph) {
+  return BASE_LIBRARY_GLYPHS.has(glyph);
+}