explico 0.4.0 → 0.5.0

package/dist/reference/remark-notation.d.mts

@@ -3,53 +3,88 @@
  *
  * Every number on a page comes from two places that MUST agree: the page's own
  * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
- * is resolved against (`equations` / `tables` / `figures`). Deriving all four
- * from the same manifest in one step is what stops a course config from
+ * is resolved against (`equations` / `tables` / `figures` / `diagrams` /
+ * `checks`).
+ * Deriving every input from the same manifest in one step stops a course config from
  * supplying one without the other — the omission that produced page-local
  * `(2.2)` and cross-page `(4.5)` for the same equation.
  *
- * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
- * the part's ordinal (the number before the dot) and, per kind of float, how
- * many of them the earlier lessons of that part already used.
+ * `numbering` maps a lesson slug to
+ * `{ part, equations, tables, figures, diagrams, checks }`: the part's ordinal
+ * (the number before the dot) and, per numbered kind, how many earlier lessons
+ * of that part already used.
  */
 export function numberingFromManifest(manifest: any): {
     equations?: undefined;
     tables?: undefined;
     figures?: undefined;
+    diagrams?: undefined;
+    checks?: undefined;
     numbering?: undefined;
 } | {
     equations: any;
     tables: any;
     figures: any;
+    diagrams: any;
+    checks: any;
     numbering: {
         [k: string]: any;
     };
 };
+/**
+ * The options object `remarkNotation` needs for one manifest, in one call.
+ *
+ * A consumer used to hand-assemble `definitions`, `equations`, `tables`,
+ * `figures`, and `chapters` separately — easy to do partially, which is how a
+ * page ends up numbered under the legacy `##`-section scheme while the
+ * manifest (and every cross-page reference to that page) uses the part
+ * scheme. This does not return that literal four-map-plus-chapters shape:
+ * `chapters` is the superseded per-lesson form (see `pageNumbering` below),
+ * and passing `manifest` through already makes `numberingFromManifest()`
+ * derive `numbering` plus every `equations`/`tables`/`figures`/`diagrams`/
+ * `checks` map from the same source in one step — strictly more correct than
+ * reconstructing `chapters` by hand.
+ *
+ * `overrides` is spread last, so a caller can add `strict`, `unknown`,
+ * `resolve`, `base`, or override anything above:
+ *
+ *   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })]
+ *
+ * @param {object} manifest - a compiled Explico manifest (`compileManifest()`).
+ * @param {object} [overrides] - additional/overriding `remarkNotation` options.
+ */
+export function createRemarkNotationOptions(manifest: object, overrides?: object): {
+    definitions: any;
+    manifest: object;
+};
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
+ *   strict?: boolean,
  *   base?: string,
  *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
  *   tables?: Record<string, Record<string, string>>,
  *   figures?: Record<string, Record<string, string>>,
- *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
+ *   diagrams?: Record<string, Record<string, string>>,
+ *   checks?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number, diagrams: number, checks: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
- * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * `manifest` is the preferred wiring: pass the compiled manifest and all
  * numbering inputs below are read off it together, so they cannot drift apart.
  * They stay available individually for hand-built trees, and an explicitly
  * supplied one still wins over the manifest.
  *
  * `numbering` maps a lesson slug to its **part** (the number before the dot)
  * and, per kind of float, how many the earlier lessons of that part already
- * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * used. Every display equation / `<Table>` / `<Figure>` / `<Diagram>` on the page is then
  * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
  * entry the legacy `##`-section scheme applies. It must agree with
- * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`/`diagrams`
  * above — supplying the tables without `numbering` numbers the same equation
  * twice, and `assertManifestNumberParity` turns that into a build error rather
  * than a page whose references disagree with their targets.
@@ -57,21 +92,34 @@ export function numberingFromManifest(manifest: any): {
  * `chapters` is the superseded per-lesson form (slug → the lesson's course
  * ordinal, no running offset). Still read when `numbering` has no entry, so a
  * config written against the old option keeps building.
+ *
+ * `strict` (default `false`) additionally fails the build when a catalogued
+ * lesson contains an equation/`<Table>`/`<Figure>` — keyed or not — but has no
+ * `numbering` placement or no cross-page number table entry, instead of
+ * silently rendering it under the legacy `##`-section scheme. Off by default
+ * for backward compatibility; `createRemarkNotationOptions(manifest, { strict:
+ * true })` is the recommended way to turn it on for a course whose manifest
+ * covers every catalogued lesson.
  */
 export default function remarkNotation(options?: {
     definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
     resolve?: (key: string, context: object) => object | undefined;
     unknown?: "error" | "warn" | "ignore";
+    strict?: boolean;
     base?: string;
     manifest?: object;
     equations?: Record<string, Record<string, string>>;
     tables?: Record<string, Record<string, string>>;
     figures?: Record<string, Record<string, string>>;
+    diagrams?: Record<string, Record<string, string>>;
+    checks?: Record<string, Record<string, string>>;
     numbering?: Record<string, {
         part: number;
         equations: number;
         tables: number;
         figures: number;
+        diagrams: number;
+        checks: number;
     }>;
     chapters?: Record<string, number>;
 }): (tree: any, file: any) => void;