@pretextbook/pretext-html 0.16.1 → 0.18.0

package/dist/subtree.d.ts

@@ -0,0 +1,79 @@
+import { Element, Root } from 'xast';
+export interface SubtreeOptions {
+    /**
+     * The `xml:id` of the element to preview. An element that is not itself a
+     * division selects the division enclosing it. Takes precedence over
+     * `file`/`line`.
+     */
+    id?: string;
+    /**
+     * The 1-based source line the author is at, selecting the innermost
+     * division containing it. A line outside every division (in the prolog or
+     * `<docinfo>`, say) selects the nearest division after it, else before it.
+     */
+    line?: number;
+    /**
+     * Which file `line` is in — an absolute path, as given to `sourcePath` and
+     * resolved the same way. Defaults to the file being rendered, which is the
+     * right answer for a single-file document; a line in an xi:included file
+     * needs its own path, since each file's lines start at 1.
+     */
+    file?: string;
+    /**
+     * Chunk level, with PreTeXt's meaning: the depth at which divisions become
+     * pages of their own (1 for chapters of a book or sections of an article,
+     * 2 one deeper, and so on). The preview is the page that would hold the
+     * selection in a build chunked at that level:
+     *
+     *  - a selection deeper than `level` previews its ancestor at `level`,
+     *    whole, since that whole ancestor is one page there;
+     *  - a selection at `level` previews that division, whole;
+     *  - a selection shallower than `level` — a chapter's introduction, say —
+     *    previews that division as a summary page: its own content, then
+     *    links to the divisions nested in it, since those are pages of their
+     *    own and only summarized on the shallower page.
+     *
+     * Omitted, every division is a page of its own: the innermost division
+     * around the selection is previewed, as a summary page whenever it
+     * contains divisions. Only leaf divisions then render in full, and a
+     * cursor at the top of a book shows the book's front matter and a table
+     * of its chapters, not the book.
+     */
+    level?: number;
+    /**
+     * Render the whole document instead when it has no more than this many
+     * elements. Small documents preview whole as fast as any division of them
+     * would, and showing all of one is the better preview; this is the knob
+     * for "never show the entire document unless it is small". Counted on the
+     * xi:include-merged document, which {@link measureDocument} reports.
+     */
+    wholeDocumentUpTo?: number;
+}
+/** The division {@link selectDivision} chose. */
+export interface SelectedDivision {
+    element: Element;
+    /** Its `xml:id` — authored, or injected (see {@link ensureXmlId}). */
+    id: string;
+    /** Whether its child divisions should be collapsed (see `level`). */
+    collapse: boolean;
+}
+/**
+ * Pick the division to preview (see the module comment). Returns undefined
+ * when the document has no division to pick — an `id` that names nothing,
+ * a file with no divisions — which the caller should treat as "render the
+ * whole document".
+ */
+export declare function selectDivision(tree: Root, options: SubtreeOptions, 
+/** The file the tree's root was parsed from; what `file` defaults to. */
+defaultFile: string): SelectedDivision | undefined;
+/**
+ * The element's `xml:id`, injecting one when it has none — the very id
+ * pretext-assembly.xsl would stamp on it anyway (`parent-id + "-" +
+ * position`), so the rendered page's ids, and with them the source map and
+ * in-place patching, are the same as without the injection. Needed because
+ * both upstream's `subtree` parameter and the skeleton address a division
+ * by `xml:id`, and most divisions in a single-file document carry none.
+ */
+export declare function ensureXmlId(tree: Root, element: Element): string;
+/** Number of elements in the tree — what the assembly passes' cost tracks. */
+export declare function countElements(tree: Root | Element): number;

package/dist/target.d.ts

@@ -2,7 +2,7 @@
  * Which PreTeXt conversion a render drives.
  *
  * The two share almost everything — the same assembly passes, the same
- * publication file, the same portable/CDN resource handling — and differ in
+ * publication file, the same CDN resource handling — and differ in
  * the stylesheet they enter through:
  *
  *   "html"   - assets/preview-html.xsl, wrapping pretext-html.xsl.

package/dist/xinclude.d.ts

@@ -1,10 +1,34 @@
 import { Element, Root } from 'xast';
+import { SourceCache } from './source-cache.js';
+/**
+ * How a file the document refers to is read: by absolute, normalized path
+ * (as `path.resolve` spells it on the platform — posix in the browser build),
+ * returning its text, or `undefined` for a file that does not exist.
+ *
+ * Lets a host that holds its project in memory — a browser editor, an
+ * extension with unsaved buffers — supply files without a filesystem.
+ * Returning `undefined` falls through to the host platform's own read (the
+ * disk under Node, an absolute URL in the browser), so a reader can also just
+ * overlay a few files on top of what is there.
+ */
+export type SourceReader = (file: string) => Promise<string | undefined> | string | undefined;
+/** Options shared by everything that resolves includes. */
+export interface ResolveOptions {
+    /** See {@link SourceReader}. */
+    readSource?: SourceReader;
+    /** Reuse parses of unchanged files across calls (see source-cache.ts). */
+    cache?: SourceCache;
+}
+/**
+ * Read a file through the caller's reader first, then the platform's.
+ */
+export declare function readWith(options: ResolveOptions | undefined, file: string): Promise<string | undefined>;
 /**
  * Return `sourceContent` with every xi:include replaced by the contents of
  * the referenced files. `sourcePath` anchors relative hrefs; `projectDir`
  * bounds which files may be included.
  */
-export declare function resolveXIncludes(sourceContent: string, sourcePath: string, projectDir: string): Promise<string>;
+export declare function resolveXIncludes(sourceContent: string, sourcePath: string, projectDir: string, options?: ResolveOptions): Promise<string>;
 /** Result of resolveXIncludesToTree. */
 export interface ResolvedTree {
     /**
@@ -16,18 +40,31 @@ export interface ResolvedTree {
     tree: Root;
     /** The merged document serialized, as resolveXIncludes would return it. */
     content: string;
+    /**
+     * Every file the document spans — the source itself first, then each
+     * xi:included file in the order first reached. What a host should watch
+     * for changes that affect this document.
+     */
+    files: string[];
+    /**
+     * Total length of those files' contents: the size of the merged document,
+     * near enough, without serializing it.
+     */
+    bytes: number;
 }
 /**
  * Like resolveXIncludes, but also return the merged tree with per-file
  * position attribution, for source-map computation.
  */
-export declare function resolveXIncludesToTree(sourceContent: string, sourcePath: string, projectDir: string): Promise<ResolvedTree>;
+export declare function resolveXIncludesToTree(sourceContent: string, sourcePath: string, projectDir: string, options?: ResolveOptions): Promise<ResolvedTree>;
 /**
  * File a spliced-in element was parsed from, tagged by expandInclude.
  * Undefined for nodes of the file being resolved (callers track that file
  * themselves). Stored on the unist `data` field, which serializers ignore.
  */
 export declare function includedFileOf(element: Element): string | undefined;
+/** Record that `element` was parsed from `file` (see includedFileOf). */
+export declare function tagIncludedFile(element: Element, file: string): void;
 /**
  * Extract the `<docinfo>` element from a complete PreTeXt source file as an XML
  * string, resolving xi:includes along the way. Handles the two shapes authors
@@ -42,4 +79,4 @@ export declare function includedFileOf(element: Element): string | undefined;
  * macros beats a failed render). `mainPath` anchors relative hrefs;
  * `projectDir` bounds which files may be read.
  */
-export declare function extractDocinfo(mainContent: string, mainPath: string, projectDir: string): Promise<string | undefined>;
+export declare function extractDocinfo(mainContent: string, mainPath: string, projectDir: string, options?: ResolveOptions): Promise<string | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Convert PreTeXt documents to HTML in pure JavaScript using the official PreTeXt XSLT stylesheets via libxslt-wasm. No Python or PreTeXt installation required.",
   "author": "Oscar Levin",
   "license": "MIT",