explico 0.3.0 → 0.5.0

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

@@ -1,29 +1,126 @@
+/**
+ * The numbering inputs a lesson page needs, read off one manifest.
+ *
+ * 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` / `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, 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>>,
+ *   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]
  *
- * `chapters` maps a lesson slug to its 1-based course ordinal. When the
- * current page has one, every display equation / `<Table>` / `<Figure>` is
- * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
- * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
- * which is what feeds `equations`/`tables`/`figures` above.
+ * `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>` / `<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`/`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.
+ *
+ * `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;
 /**