explico 0.11.1 → 0.13.0

package/dist/compiler/exports/static-tree.d.ts

@@ -0,0 +1,253 @@
+import { HtmlElement, HtmlNode } from './html-tree.js';
+import 'parse5';
+
+/**
+ * explico's static reading tree: a built page reduced to what a reader reads,
+ * with explico's meaning kept — a float with its number and captions, a
+ * cross-reference by its target, a check by its anchor. Print exporters (the
+ * LaTeX source now, Markdown later) serialize this tree; none of them
+ * re-walks `content/` or recomputes a number.
+ *
+ * It is read off Astro's static output, where every disclosure's body, every
+ * table row and every formula's TeX already sit in the markup, whatever the
+ * reader would see collapsed. What the static page does not hold — a lab's
+ * drawing, a check's answers — comes from the capture pass and the manifest.
+ *
+ * Math keeps the author's `\explain{key}{…}` and `\slot{key}{…}` markers (the
+ * KaTeX annotation, not the stripped `data-latex`): a printer that understands
+ * them (explico's LaTeX class) needs no stripping, and one that doesn't strips
+ * them itself.
+ */
+type RefKind = 'equation' | 'figure' | 'table' | 'diagram' | 'section' | 'example' | 'check' | 'memo' | 'anchor' | 'page';
+/** A link target inside the course: a page route (base-relative, no slashes at the ends) and an anchor. */
+interface CourseTarget {
+    readonly route: string;
+    readonly anchor: string;
+}
+type Inline = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'emphasis';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'strong';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'superscript';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'subscript';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'code';
+    readonly value: string;
+} | {
+    readonly kind: 'math';
+    readonly tex: string;
+} | {
+    readonly kind: 'break';
+} | {
+    readonly kind: 'link';
+    readonly href: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'ref';
+    readonly refKind: RefKind;
+    readonly target: CourseTarget;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'term';
+    readonly key: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'cite';
+    readonly number: string;
+    readonly anchor: string;
+    readonly sourceId?: string;
+    readonly locator?: string;
+} | {
+    readonly kind: 'memoMark';
+    readonly anchor: string;
+    readonly label: string;
+} | {
+    readonly kind: 'noteMark';
+    readonly anchor: string;
+    readonly children: readonly Inline[];
+};
+interface TableCell {
+    readonly header: boolean;
+    readonly colspan: number;
+    readonly rowspan: number;
+    readonly align?: 'left' | 'center' | 'right';
+    readonly children: readonly Inline[];
+}
+interface DiagramNodeShape {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly radius: number;
+    readonly text?: string;
+    readonly tex?: string;
+}
+interface DiagramGeometry {
+    readonly width: number;
+    readonly height: number;
+    readonly nodes: readonly DiagramNodeShape[];
+    /** Each edge as its polyline, start to end; the arrowhead sits at the end. */
+    readonly edges: readonly (readonly (readonly [number, number])[])[];
+}
+/** What a figure shows: an image file, or something only a browser can draw. */
+type FigurePicture = {
+    readonly kind: 'image';
+    readonly src: string;
+    readonly alt: string;
+} | {
+    readonly kind: 'diagram';
+    readonly geometry: DiagramGeometry;
+} | {
+    readonly kind: 'capture';
+};
+interface FloatBase {
+    /** The float's anchor id on its page (`fig-…`, `tab-…`, `dia-…`). */
+    readonly anchor: string;
+    readonly number: string;
+    readonly key?: string;
+    readonly short?: string;
+    /** The long caption. */
+    readonly caption: readonly Inline[];
+}
+type Block = {
+    readonly kind: 'heading';
+    readonly level: number;
+    readonly anchor?: string;
+    readonly number?: string;
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'paragraph';
+    readonly children: readonly Inline[];
+} | {
+    readonly kind: 'list';
+    readonly ordered: boolean;
+    readonly start?: number;
+    readonly items: readonly (readonly Block[])[];
+} | {
+    readonly kind: 'equation';
+    readonly anchor: string;
+    readonly number: string;
+    readonly key?: string;
+    readonly tex: string;
+} | {
+    readonly kind: 'displayMath';
+    readonly tex: string;
+} | (FloatBase & {
+    readonly kind: 'figure';
+    /** The live clause a lab writes after its caption; empty in the static page. */
+    readonly live: readonly Inline[];
+    readonly picture: FigurePicture;
+    /** The lab's own accessible label, when it gives one. */
+    readonly alt?: string;
+}) | (FloatBase & {
+    readonly kind: 'table';
+    readonly head: readonly (readonly TableCell[])[];
+    readonly body: readonly (readonly TableCell[])[];
+}) | (FloatBase & {
+    readonly kind: 'diagram';
+    readonly geometry: DiagramGeometry;
+}) | {
+    readonly kind: 'memo';
+    readonly anchor: string;
+    readonly label: string;
+    readonly short?: string;
+    readonly title: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'note';
+    readonly anchor: string;
+    readonly title: string;
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'aside';
+    readonly variant: string;
+    readonly title: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'fold';
+    readonly title?: readonly Inline[];
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'examples';
+    readonly anchor: string;
+    readonly number: string;
+    readonly title: readonly Inline[];
+    readonly items: readonly {
+        readonly title: readonly Inline[];
+        readonly children: readonly Block[];
+    }[];
+} | {
+    readonly kind: 'check';
+    readonly anchor: string;
+    readonly number: string;
+    readonly assessmentId: string;
+    readonly title: readonly Inline[];
+} | {
+    readonly kind: 'quote';
+    readonly children: readonly Block[];
+} | {
+    readonly kind: 'image';
+    readonly src: string;
+    readonly alt: string;
+} | {
+    readonly kind: 'code';
+    readonly value: string;
+} | {
+    readonly kind: 'rule';
+} | {
+    readonly kind: 'references';
+    readonly items: readonly {
+        readonly number: string;
+        readonly anchor: string;
+        readonly children: readonly Inline[];
+    }[];
+};
+interface NotationEntry {
+    readonly key: string;
+    readonly anchor: string;
+    readonly symbolTex?: string;
+    readonly label: readonly Inline[];
+    readonly summary: readonly Inline[];
+    readonly units?: readonly Inline[];
+    readonly formulaTex?: string;
+}
+interface StaticPage {
+    /** The page's docs slug, e.g. `projectiles/optimal-launch-angle`. */
+    readonly slug: string;
+    /** Base-relative route of the page, e.g. `projectiles/optimal-launch-angle`. */
+    readonly route: string;
+    readonly title: string;
+    readonly blocks: readonly Block[];
+    /** "Notation used on this page", in the page's order. */
+    readonly notation: readonly NotationEntry[];
+    /** The notation list's page-specific remarks ("On this page, ′ is not an operator …"). */
+    readonly notationRemarks: readonly (readonly Inline[])[];
+}
+interface ReadContext {
+    readonly route: string;
+    readonly base: string;
+}
+/** All text below `node`, as a reader sees it: no screen-reader-only or hidden helpers. */
+declare function readableText(node: HtmlNode): string;
+/** Resolve a link to a course target, or `undefined` when it leaves the course. */
+declare function courseTarget(href: string, context: ReadContext): CourseTarget | undefined;
+/** Node boxes and edge polylines of a built `<Diagram>`'s SVG. */
+declare function readDiagramGeometry(figure: HtmlElement): DiagramGeometry | undefined;
+/**
+ * Inline content from an HTML fragment of a page — a lab's live caption
+ * clause, which only exists once the lab has run.
+ */
+declare function readInlineFragment(html: string, route: string, base?: string): Inline[];
+/** Read the static reading tree of one built page. */
+declare function readStaticPage(html: string, slug: string, route: string): StaticPage;
+
+export { type Block, type CourseTarget, type DiagramGeometry, type DiagramNodeShape, type FigurePicture, type Inline, type NotationEntry, type RefKind, type StaticPage, type TableCell, courseTarget, readDiagramGeometry, readInlineFragment, readStaticPage, readableText };