@pretextbook/pretext-html 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -9,6 +9,10 @@ export type { RenderTarget } from './target.js';
 export { injectRevealBridge, isRevealView, revealBridgeScript, } from './reveal.js';
 export type { RevealView, RevealViewOptions } from './reveal.js';
 export { openBornHiddenKnowls } from './knowls.js';
+export { buildSkeleton, divisionLevel, replaceDivision } from './skeleton.js';
+export type { Skeleton } from './skeleton.js';
+export { OFF_PAGE_MESSAGE, rewriteXrefLinks } from './xrefs.js';
+export type { RewriteXrefLinkOptions } from './xrefs.js';
 export { rewriteAssetUrls } from './assets.js';
 export type { AssetKind, AssetUrlResolver } from './assets.js';
 export { describeAsset, missingAssetPlaceholder, missingAssetSvg, } from './missing-asset.js';

package/dist/index.js

@@ -1,32 +1,37 @@
-import { P as r, d as i, a, f as t, b as n, i as o, c as l, o as d, p, r as c, m, s as E, e as g, x as v } from "./cli-Bcn4t3B1.js";
-import { injectRevealBridge as B, isRevealView as S, revealBridgeScript as f } from "./reveal.js";
-import { describeAsset as R, missingAssetPlaceholder as w, missingAssetSvg as h, rewriteAssetUrls as x } from "./assets.js";
-import { PREVIEW_THEME_MESSAGE as b, injectThemeBridge as u, isPreviewTheme as M, previewThemeMessage as _, themeBridgeScript as j } from "./theme.js";
+import { O as r, P as i, b as a, d as t, a as n, c as o, f as l, e as d, i as p, g as E, o as c, p as m, r as v, h as S, j as g, m as A, s as f, k as B, x as P } from "./cli-BONFCRgl.js";
+import { injectRevealBridge as R, isRevealView as h, revealBridgeScript as _ } from "./reveal.js";
+import { describeAsset as u, missingAssetPlaceholder as x, missingAssetSvg as M, rewriteAssetUrls as T } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as G, injectThemeBridge as k, isPreviewTheme as H, previewThemeMessage as L, themeBridgeScript as O } from "./theme.js";
 export {
-  r as PREVIEW_BANNER_STORAGE_KEY,
-  b as PREVIEW_THEME_MESSAGE,
-  i as defaultXslDir,
-  R as describeAsset,
-  a as detectRenderTarget,
-  t as findSourceMapEntry,
-  n as forcePortablePublication,
-  o as injectPreviewBanner,
-  B as injectRevealBridge,
-  u as injectThemeBridge,
-  l as isJspiAvailable,
-  M as isPreviewTheme,
-  S as isRevealView,
-  w as missingAssetPlaceholder,
-  h as missingAssetSvg,
-  d as openBornHiddenKnowls,
-  p as previewBannerScript,
-  _ as previewThemeMessage,
-  c as renderHtml,
-  f as revealBridgeScript,
-  x as rewriteAssetUrls,
-  m as runCli,
-  E as setAssetsBase,
-  g as setMountReader,
-  j as themeBridgeScript,
-  v as xpathStringLiteral
+  r as OFF_PAGE_MESSAGE,
+  i as PREVIEW_BANNER_STORAGE_KEY,
+  G as PREVIEW_THEME_MESSAGE,
+  a as buildSkeleton,
+  t as defaultXslDir,
+  u as describeAsset,
+  n as detectRenderTarget,
+  o as divisionLevel,
+  l as findSourceMapEntry,
+  d as forcePortablePublication,
+  p as injectPreviewBanner,
+  R as injectRevealBridge,
+  k as injectThemeBridge,
+  E as isJspiAvailable,
+  H as isPreviewTheme,
+  h as isRevealView,
+  x as missingAssetPlaceholder,
+  M as missingAssetSvg,
+  c as openBornHiddenKnowls,
+  m as previewBannerScript,
+  L as previewThemeMessage,
+  v as renderHtml,
+  S as replaceDivision,
+  _ as revealBridgeScript,
+  T as rewriteAssetUrls,
+  g as rewriteXrefLinks,
+  A as runCli,
+  f as setAssetsBase,
+  B as setMountReader,
+  O as themeBridgeScript,
+  P as xpathStringLiteral
 };

package/dist/renderer.d.ts

@@ -134,6 +134,59 @@ export interface RenderOptions {
      * the book's chapters. Only used in fragment mode.
      */
     docinfoSourcePath?: string;
+    /**
+     * Path to the complete document (typically the project's main.ptx) that the
+     * fragment being rendered belongs to. Renders the fragment **in place** in
+     * that document instead of standalone, which is what makes its numbering and
+     * its cross-references match the built book.
+     *
+     * A fragment rendered on its own restarts numbering at 1 and cannot see any
+     * `<xref>` target outside itself, so previewing section 3.2 shows "Theorem
+     * 1.1" where the book says "Theorem 3.2.1", and references leaving the
+     * section render as PreTeXt's `[cross-reference to target(s) ... missing]`
+     * placeholder. With this set, the document is pruned to a skeleton — every
+     * division, the previewed fragment verbatim, and the divisions holding the
+     * targets it references — and rendered with upstream's `subtree` parameter,
+     * which emits only the previewed division. See skeleton.ts for why that
+     * numbers identically to rendering the whole document, and for the cost.
+     *
+     * The fragment supplies its own content, so unsaved editor text is what gets
+     * rendered; the document on disk supplies only the structure around it. That
+     * matching is by `@xml:id`: a fragment whose root element has none, or whose
+     * id is not in the document, silently falls back to the standalone wrapper.
+     *
+     * Supersedes `docinfoSourcePath`, since the skeleton carries the document's
+     * real `<docinfo>`. Only used in fragment mode; ignored for whole documents.
+     * Optional when `contextSourceContent` is given — see there — but still
+     * used as the virtual base for xi:include resolution and source-map paths
+     * even then, so pass it whenever a real path is available.
+     */
+    contextSourcePath?: string;
+    /**
+     * The complete document's source text, used instead of reading
+     * `contextSourcePath` from disk. Lets a browser host that already holds the
+     * whole project in memory place a fragment in its document — with
+     * correct numbering and resolved `<xref>`s — without a filesystem or
+     * network round trip, and lets the skeleton see *unsaved* sibling
+     * divisions that a read from disk never would.
+     *
+     * `contextSourcePath` becomes optional when this is given, defaulting to
+     * `sourcePath` as the virtual base for resolving the document's own
+     * xi:includes; pass `contextSourcePath` too when a real one is available,
+     * for more useful source-map/error paths. Exactly parallel to
+     * `sourceContent` vs. `sourcePath`.
+     */
+    contextSourceContent?: string;
+    /**
+     * Tooltip for links whose target is not on the previewed page — the table of
+     * contents, and cross-references reaching outside the fragment. Those cannot
+     * navigate in a single-page preview, so they are stripped of their `@href`
+     * and given this as an explanation (see xrefs.ts). Defaults to
+     * {@link OFF_PAGE_MESSAGE}.
+     *
+     * Whole-document previews link only within the page, so nothing is affected.
+     */
+    offPageMessage?: string;
     /**
      * Also compute a source map: one entry per element, in document order,
      * mapping the element's @unique-id (its HTML id, when the page emits one)

package/dist/skeleton.d.ts

@@ -0,0 +1,41 @@
+import { Element, Root } from 'xast';
+/** A pruned document, ready to render as a fragment preview. */
+export interface Skeleton {
+    /** The pruned document, serialized. */
+    content: string;
+    /** `@xml:id` of the division to render; pass as the `subtree` param. */
+    divisionId: string;
+    /** That division's numbering level; pass as the `subtree-level` param. */
+    level: number;
+}
+/**
+ * A division's numbering level, mirroring `mode="level"` in
+ * pretext-numbers.xsl. `ancestors` runs from the document element down to (and
+ * including) the division itself.
+ *
+ * `hasParts` is upstream's `$b-has-parts` (`boolean($root/book/part)`), which
+ * pushes a book's chapters down a level.
+ */
+export declare function divisionLevel(ancestors: Element[], hasParts: boolean): number;
+/**
+ * Swap the division carrying `id` for `replacement`, in place. Returns false
+ * when the tree holds no such division.
+ *
+ * This is what lets a preview show *unsaved* work: the document on disk
+ * supplies the structure around the fragment, while the fragment itself comes
+ * from the editor's buffer.
+ */
+export declare function replaceDivision(tree: Root, id: string, replacement: Element): boolean;
+/**
+ * Build a skeleton of `tree` that preserves the numbering of the division
+ * carrying `divisionId` and resolves the cross-references it makes.
+ *
+ * Prunes `tree` in place and serializes the result, so the caller can go on to
+ * use the same tree — computing a source map from it, for instance, which is
+ * what the renderer does.
+ *
+ * Returns undefined when the tree holds no such division — an unsaved file
+ * whose `@xml:id` is not yet in the main document, say — which the caller
+ * should treat as "fall back to the standalone fragment wrapper".
+ */
+export declare function buildSkeleton(tree: Root, divisionId: string): Skeleton | undefined;

package/dist/xrefs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Reconcile a subtree render's links with the single page it actually
+ * produced.
+ *
+ * A fragment preview is rendered with upstream's `subtree` parameter: the
+ * whole document is assembled — so numbering is right and every `<xref>`
+ * finds its target — but only one division is emitted. The links, though, are
+ * written for the multi-page build that assembling implies. PreTeXt hands back
+ * `sec-two.html#thm-b` for a theorem in another section, `sec-one.html#thm-a`
+ * for one on this very page, and a bare `sec-three.html` for each table of
+ * contents entry. None of those files exist: there is one page, in memory.
+ *
+ * Two fixes, from one question — is the target on this page?
+ *
+ *   - **On the page.** Rewrite to a bare `#id`. The link then does exactly
+ *     what the built book's would: scroll to the target. Answering by looking
+ *     for the `id` in the rendered HTML, rather than by reasoning about
+ *     PreTeXt's filename scheme, means this cannot drift when that scheme
+ *     changes, and it costs one pass over the page.
+ *
+ *   - **Not on the page.** Drop the `@href` and explain in a tooltip. A link
+ *     that silently does nothing is worse than an obvious non-link, and the
+ *     reader has no other way to learn that the preview is showing one section
+ *     of something larger. The element, its classes and its text are all left
+ *     alone, so the page still reads like the built one — the same tactic, and
+ *     the same `aria-disabled` spelling, as the inert print-preview button in
+ *     preview-html.xsl (see PRINTOUT_LINK_OVERRIDE in scripts/refresh-xsl.mjs).
+ *
+ * Applied to the rendered HTML rather than in the stylesheet because the
+ * question cannot be answered during the transform: whether a target lands on
+ * the page is a fact about the finished output, and upstream computes every
+ * URL through `mode="url"` from a dozen call sites. One pass over the result
+ * is one rule that cannot fall out of step with them.
+ */
+/** Default tooltip on a link whose target is not on the previewed page. */
+export declare const OFF_PAGE_MESSAGE = "This live preview shows a single division, so links into the rest of the document do not work here.";
+export interface RewriteXrefLinkOptions {
+    /**
+     * Tooltip for a link whose target is not on this page. Defaults to
+     * {@link OFF_PAGE_MESSAGE}. When the link already carries a tooltip — an
+     * `<xref>` is given one naming its target, like "Theorem 2.1: Beta" — the
+     * two are joined rather than the original being thrown away.
+     */
+    offPageMessage?: string;
+}
+/**
+ * Point every link in `html` at something real: same-page targets become
+ * `#id`, and links leaving the page become inert with an explanatory tooltip.
+ *
+ * Safe to run on any rendered page. A whole-document preview emits only
+ * same-page anchors and absolute URLs, so nothing matches and the HTML comes
+ * back unchanged.
+ */
+export declare function rewriteXrefLinks(html: string, options?: RewriteXrefLinkOptions): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.8.0",
+  "version": "0.10.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",