explico 0.13.1 → 0.15.0

package/src/compiler/course-config.ts

@@ -386,6 +386,258 @@ export function normalizeCards(config: CourseConfig): NormalizedCards {
   return { carry };
 }
 
+/**
+ * The marks the sidebar puts beside a chapter or part page for one reader
+ * (`sidebarMarks` in the course settings, `page-marks.ts`): a quiet ring
+ * while they have not opened it, an accent dot when its content changed
+ * since they last did. Every field is optional; {@link normalizeSidebarMarks}
+ * fills in the defaults.
+ */
+export interface CourseSidebarMarks {
+  /** Mark a page the reader has not opened yet. Default `true`. */
+  readonly unopened?: boolean;
+  /** Mark a page whose content changed since the reader last opened it. Default `true`. */
+  readonly changed?: boolean;
+}
+
+/** {@link CourseSidebarMarks} with every default applied. */
+export interface NormalizedSidebarMarks {
+  readonly unopened: boolean;
+  readonly changed: boolean;
+}
+
+export const SIDEBAR_MARKS_DEFAULTS: NormalizedSidebarMarks = { unopened: true, changed: true };
+
+/** Validate `CourseConfig.sidebarMarks` and apply its defaults. Throws on a bad value. */
+export function normalizeSidebarMarks(config: CourseConfig): NormalizedSidebarMarks {
+  const marks = config.sidebarMarks ?? {};
+  const read = (field: keyof NormalizedSidebarMarks): boolean => {
+    const value: unknown = marks[field] ?? SIDEBAR_MARKS_DEFAULTS[field];
+    if (typeof value !== 'boolean') {
+      throw new Error(
+        `CourseConfig sidebarMarks.${field} must be true or false; received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value;
+  };
+  return { unopened: read('unopened'), changed: read('changed') };
+}
+
+/**
+ * Which edition of a lesson its sidebar row opens, for a reader who has not
+ * chosen (`sidebarEditions` in the course settings, `sidebar-editions.ts`). A
+ * lesson with a chapter and a deck is one row: the row opens the **lead**
+ * edition, and the **other** is an icon at the row's end, or not listed. A
+ * reader switches both in the sidebar's foot. The plain `string` fields
+ * arrive as JSON; {@link normalizeSidebarEditions} rejects any value it does
+ * not list.
+ */
+export interface CourseSidebarEditions {
+  /** The edition a lesson's row opens: `chapter` (default) or `slides`. */
+  readonly lead?: string;
+  /** Whether the row also lists the other edition: `listed` (default) or `hidden`. */
+  readonly other?: string;
+}
+
+export type SidebarEditionLead = 'chapter' | 'slides';
+export type SidebarEditionOther = 'listed' | 'hidden';
+
+/** {@link CourseSidebarEditions} with every default applied. */
+export interface NormalizedSidebarEditions {
+  readonly lead: SidebarEditionLead;
+  readonly other: SidebarEditionOther;
+}
+
+/** The engine's defaults (decision D10): the chapter leads, the slides are listed. */
+export const SIDEBAR_EDITIONS_DEFAULTS: NormalizedSidebarEditions = { lead: 'chapter', other: 'listed' };
+
+/** Validate `CourseConfig.sidebarEditions` and apply its defaults. Throws on a bad value. */
+export function normalizeSidebarEditions(config: CourseConfig): NormalizedSidebarEditions {
+  const editions = config.sidebarEditions ?? {};
+  const choice = <T extends string>(field: keyof NormalizedSidebarEditions, allowed: readonly T[]): T => {
+    const value: unknown = editions[field] ?? SIDEBAR_EDITIONS_DEFAULTS[field];
+    if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) {
+      throw new Error(
+        `CourseConfig sidebarEditions.${field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  return {
+    lead: choice<SidebarEditionLead>('lead', ['chapter', 'slides']),
+    other: choice<SidebarEditionOther>('other', ['listed', 'hidden']),
+  };
+}
+
+/**
+ * A course's decks: the slide edition of a lesson (`<lesson>.deck.mdx`,
+ * `docs/authoring/deck.md`). Every field is optional; {@link normalizeDeck}
+ * fills in the defaults. The plain `string` fields arrive as JSON, and
+ * {@link normalizeDeck} rejects any value it does not list.
+ */
+export interface CourseDeck {
+  /**
+   * The canvas every deck of the course is laid out on: `16:9` (default),
+   * `16:10` or `4:3`. One setting for the course, because the frame-fit check,
+   * the captured figures and the PDF's page all read it.
+   */
+  readonly aspectRatio?: string;
+  /**
+   * The line on a frame that names the symbols it shows: `first-use`
+   * (default, the symbols the deck has not shown before), `every-frame`
+   * (every symbol on the frame), or `off`.
+   */
+  readonly legend?: string;
+  /**
+   * Who sees a frame's speaker notes: `reader` (default — under each frame in
+   * the scroll view, in the presenter window and in the handout), `presenter`
+   * (the presenter window and the handout only), or `off` (nowhere; the
+   * handout PDF is not built).
+   */
+  readonly notes?: string;
+  /** End each deck on a frame of what its lesson's competencies say a student can now do. Default `true`. */
+  readonly outcomesFrame?: boolean;
+  /** Offer the slides-with-notes PDF beside the slides PDF. Default `true`. */
+  readonly handoutPdf?: boolean;
+}
+
+export type DeckAspectRatio = '16:9' | '16:10' | '4:3';
+export type DeckLegend = 'first-use' | 'every-frame' | 'off';
+export type DeckNotes = 'reader' | 'presenter' | 'off';
+
+/**
+ * The logical canvas a frame is laid out on, in CSS pixels: the width of the
+ * page's reading column, so a figure, a table or a lab lays out on a frame at
+ * the size it was made for, and the frame is scaled to the screen. Every
+ * ratio is 450 px tall, so the type scale and a frame's capacity in lines are
+ * the same in all three. Printed, the canvas is scaled by 1.6 onto a page
+ * 7.5 in tall (13.333 × 7.5 in for 16:9).
+ */
+export const DECK_CANVAS: Readonly<Record<DeckAspectRatio, { readonly width: number; readonly height: number }>> = {
+  '16:9': { width: 800, height: 450 },
+  '16:10': { width: 720, height: 450 },
+  '4:3': { width: 600, height: 450 },
+};
+
+/** {@link CourseDeck} with every default applied, as the manifest publishes it. */
+export interface NormalizedDeck {
+  readonly aspectRatio: DeckAspectRatio;
+  readonly legend: DeckLegend;
+  readonly notes: DeckNotes;
+  readonly outcomesFrame: boolean;
+  readonly handoutPdf: boolean;
+  readonly canvas: { readonly width: number; readonly height: number };
+}
+
+export const DECK_DEFAULTS: Omit<NormalizedDeck, 'canvas'> = {
+  aspectRatio: '16:9',
+  legend: 'first-use',
+  notes: 'reader',
+  outcomesFrame: true,
+  handoutPdf: true,
+};
+
+/** Validate `CourseConfig.deck` and apply its defaults. Throws on a bad value. */
+export function normalizeDeck(config: CourseConfig): NormalizedDeck {
+  const deck = config.deck ?? {};
+  const choice = <T extends string>(field: keyof CourseDeck, allowed: readonly T[]): T => {
+    const value: unknown = deck[field] ?? DECK_DEFAULTS[field as keyof typeof DECK_DEFAULTS];
+    if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) {
+      throw new Error(
+        `CourseConfig deck.${field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  const flag = (field: 'outcomesFrame' | 'handoutPdf'): boolean => {
+    const value: unknown = deck[field] ?? DECK_DEFAULTS[field];
+    if (typeof value !== 'boolean') {
+      throw new Error(`CourseConfig deck.${field} must be true or false; received ${JSON.stringify(value)}.`);
+    }
+    return value;
+  };
+  const aspectRatio = choice<DeckAspectRatio>('aspectRatio', ['16:9', '16:10', '4:3']);
+  return {
+    aspectRatio,
+    legend: choice<DeckLegend>('legend', ['first-use', 'every-frame', 'off']),
+    notes: choice<DeckNotes>('notes', ['reader', 'presenter', 'off']),
+    outcomesFrame: flag('outcomesFrame'),
+    handoutPdf: flag('handoutPdf'),
+    canvas: DECK_CANVAS[aspectRatio],
+  };
+}
+
+/**
+ * Whether the course asks each reader if it may remember their reading in
+ * their browser (`readingMemory` in the course settings,
+ * `session/reading-memory.ts`): which chapters they opened (the sidebar's
+ * marks) and the cards they keep or carry, across visits. `ask` (default)
+ * shows the question until the reader answers; `off` never asks and never
+ * keeps reading memory, so the marks are off and cards last as long as the tab.
+ */
+export type ReadingMemorySetting = 'ask' | 'off';
+
+/** Validate `CourseConfig.readingMemory`. Throws on a bad value. */
+export function normalizeReadingMemory(config: CourseConfig): ReadingMemorySetting {
+  const value: unknown = config.readingMemory ?? 'ask';
+  if (value !== 'ask' && value !== 'off') {
+    throw new Error(`CourseConfig readingMemory must be "ask" or "off"; received ${JSON.stringify(value)}.`);
+  }
+  return value;
+}
+
+/**
+ * How the page tells its zones apart, and how a deck's slides sit on it
+ * (`appearance` in the course settings; `zones.css` and `deck.css` hold the
+ * colours). `zones`: `tonal` (the default) gives both sidebars one step of the
+ * neutral grey and the header a step further; `accent-header` makes the
+ * header a deep band of the course accent; `paper` lays the reading column
+ * on the sidebars' colour as a sheet; `none` keeps Starlight's colours.
+ * `slides`: `lifted` (the default) gives each slide an edge and a drop
+ * shadow, and in the dark theme a sheet a step lighter than the page; `edge`
+ * the edge and shadow on the page's own colour; `sorter` lays the deck on a
+ * tinted well. Every field is optional; {@link normalizeAppearance} fills in
+ * the defaults.
+ */
+export interface CourseAppearance {
+  /** `tonal` (default), `accent-header`, `paper` or `none`. */
+  readonly zones?: string;
+  /** `lifted` (default), `edge` or `sorter`. */
+  readonly slides?: string;
+}
+
+export type AppearanceZones = 'tonal' | 'accent-header' | 'paper' | 'none';
+export type AppearanceSlides = 'lifted' | 'edge' | 'sorter';
+
+/** {@link CourseAppearance} with every default applied. */
+export interface NormalizedAppearance {
+  readonly zones: AppearanceZones;
+  readonly slides: AppearanceSlides;
+}
+
+export const APPEARANCE_DEFAULTS: NormalizedAppearance = { zones: 'tonal', slides: 'lifted' };
+
+const APPEARANCE_ZONES: readonly AppearanceZones[] = ['tonal', 'accent-header', 'paper', 'none'];
+const APPEARANCE_SLIDES: readonly AppearanceSlides[] = ['lifted', 'edge', 'sorter'];
+
+/** Validate `CourseConfig.appearance` and apply its defaults. Throws on a bad value. */
+export function normalizeAppearance(config: CourseConfig): NormalizedAppearance {
+  const appearance = config.appearance ?? {};
+  const choice = <T extends string>(field: keyof NormalizedAppearance, allowed: readonly T[]): T => {
+    const value: unknown = appearance[field] ?? APPEARANCE_DEFAULTS[field];
+    if (!allowed.includes(value as T)) {
+      throw new Error(
+        `CourseConfig appearance.${field} must be one of ${allowed.map((v) => `"${v}"`).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  return { zones: choice('zones', APPEARANCE_ZONES), slides: choice('slides', APPEARANCE_SLIDES) };
+}
+
 /**
  * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
  * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
@@ -488,6 +740,21 @@ export interface CourseConfig {
   readonly numbering?: CourseNumbering;
   /** How explanation cards start for a reader: "Carry cards" on or off. */
   readonly cards?: CourseCards;
+  /** The sidebar's marks for a page the reader has not opened, or that changed since. */
+  readonly sidebarMarks?: CourseSidebarMarks;
+  /** Which edition a lesson's sidebar row opens, and whether it lists the other. */
+  readonly sidebarEditions?: CourseSidebarEditions;
+  /** How the course's decks look and what they show (`docs/authoring/deck.md`). */
+  readonly deck?: CourseDeck;
+  /**
+   * Ask each reader whether the course may remember their reading in their
+   * browser (`ask`, the default), or never keep it (`off`). A plain `string`
+   * because the settings arrive as JSON; {@link normalizeReadingMemory}
+   * rejects any other value.
+   */
+  readonly readingMemory?: string;
+  /** How the page tells header, sidebars and article apart, and how slides sit on it. */
+  readonly appearance?: CourseAppearance;
   /**
    * How a check's and an example set's heading names its kind: `icon-word`
    * (default) or `icon` ({@link BlockLabels}). A plain `string` because the