@pretextbook/pretext-html 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export { PREVIEW_THEME_MESSAGE, isPreviewTheme, previewThemeMessage, themeBridge
 export type { PreviewTheme, PreviewThemeMessage } from './theme.js';
 export { PREVIEW_BANNER_STORAGE_KEY, injectPreviewBanner, previewBannerScript, } from './banner.js';
 export type { PreviewBannerOptions } from './banner.js';
+export { PRINT_PREVIEW_GLOBAL, injectPrintPreview, listPrintouts, printPreviewBridgeScript, rootPrintoutId, } from './printout.js';
+export type { PrintoutInfo } from './printout.js';
 export { main as runCli } from './cli.js';
 export { setAssetsBase } from './host.js';
 export { setMountReader } from './mounts.js';

package/dist/index.js

@@ -1,37 +1,43 @@
-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";
+import { O as i, P as s, b as t, d as a, a as n, c as o, f as l, e as d, i as p, g as E, o as c, p as P, r as v, h as m, j as S, m as g, s as A, k as B, x as f } from "./cli-CMAunrD_.js";
+import { injectRevealBridge as R, isRevealView as _, revealBridgeScript as u } from "./reveal.js";
+import { describeAsset as x, missingAssetPlaceholder as T, missingAssetSvg as b, rewriteAssetUrls as M } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as G, injectThemeBridge as I, isPreviewTheme as L, previewThemeMessage as O, themeBridgeScript as V } from "./theme.js";
+import { PRINT_PREVIEW_GLOBAL as H, injectPrintPreview as N, listPrintouts as W, printPreviewBridgeScript as D, rootPrintoutId as F } from "./printout.js";
 export {
-  r as OFF_PAGE_MESSAGE,
-  i as PREVIEW_BANNER_STORAGE_KEY,
+  i as OFF_PAGE_MESSAGE,
+  s as PREVIEW_BANNER_STORAGE_KEY,
   G as PREVIEW_THEME_MESSAGE,
-  a as buildSkeleton,
-  t as defaultXslDir,
-  u as describeAsset,
+  H as PRINT_PREVIEW_GLOBAL,
+  t as buildSkeleton,
+  a as defaultXslDir,
+  x as describeAsset,
   n as detectRenderTarget,
   o as divisionLevel,
   l as findSourceMapEntry,
   d as forcePortablePublication,
   p as injectPreviewBanner,
+  N as injectPrintPreview,
   R as injectRevealBridge,
-  k as injectThemeBridge,
+  I as injectThemeBridge,
   E as isJspiAvailable,
-  H as isPreviewTheme,
-  h as isRevealView,
-  x as missingAssetPlaceholder,
-  M as missingAssetSvg,
+  L as isPreviewTheme,
+  _ as isRevealView,
+  W as listPrintouts,
+  T as missingAssetPlaceholder,
+  b as missingAssetSvg,
   c as openBornHiddenKnowls,
-  m as previewBannerScript,
-  L as previewThemeMessage,
+  P as previewBannerScript,
+  O as previewThemeMessage,
+  D as printPreviewBridgeScript,
   v as renderHtml,
-  S as replaceDivision,
-  _ as revealBridgeScript,
-  T as rewriteAssetUrls,
-  g as rewriteXrefLinks,
-  A as runCli,
-  f as setAssetsBase,
+  m as replaceDivision,
+  u as revealBridgeScript,
+  M as rewriteAssetUrls,
+  S as rewriteXrefLinks,
+  F as rootPrintoutId,
+  g as runCli,
+  A as setAssetsBase,
   B as setMountReader,
-  O as themeBridgeScript,
-  P as xpathStringLiteral
+  V as themeBridgeScript,
+  f as xpathStringLiteral
 };

package/dist/printout.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Print-preview layout for the printouts on a rendered page.
+ *
+ * A worksheet or handout is written to be printed and handed out, and PreTeXt
+ * lays one out very differently on paper than on screen: paginated to the
+ * chosen paper size, headers and footers on each sheet, solutions dropped, and
+ * — the part that is impossible to judge from the ordinary view — every
+ * `<workspace>` grown to the height the author asked for, so the blank space a
+ * student writes in is actually shown. An author editing a worksheet wants to
+ * see *that*, not the web version of it.
+ *
+ * ## How the built page does it, and why the preview cannot
+ *
+ * All of it is client-side, in pretext-core.js, and the entire entry point is a
+ * URL query parameter: `?printpreview=<html-id>`. On DOMContentLoaded the
+ * script swaps the theme stylesheet for `print-worksheet.css`, moves the named
+ * printout to be the page's only content, flattens its knowls, and paginates
+ * it. Upstream's print icon on a printout heading is nothing more than a link
+ * to that URL.
+ *
+ * A preview has no such URL. It is rendered in memory and handed to a host — a
+ * VS Code webview, an iframe on pretext.plus — so there is no page to reload
+ * and no query string of ours to put the parameter in; the link is disabled in
+ * the preview wrapper for exactly that reason (see PRINTOUT_LINK_OVERRIDE in
+ * scripts/refresh-xsl.mjs). What this module does is supply the parameter
+ * without the navigation: {@link injectPrintPreview} adds a small script that
+ * makes `new URLSearchParams(window.location.search)` — the one and only place
+ * pretext-core.js looks — report a `printpreview` parameter that is not in the
+ * URL at all.
+ *
+ * Rewriting the URL itself would be the obvious alternative and does not work
+ * here: `history.replaceState` throws in a document whose origin cannot own a
+ * new URL (a `vscode-webview://` page, an `about:blank` document written into
+ * in place), and on a host like pretext.plus it would corrupt the app's own
+ * address. Patching the reader is inert by comparison — it adds a parameter to
+ * one particular string and touches nothing else.
+ *
+ * ## Switching in and out
+ *
+ * By re-delivering the page, not by talking to a live one, exactly as the
+ * slideshow view toggle does (see reveal.ts). pretext-core.js runs the whole
+ * transformation once, from a DOMContentLoaded handler, and it is thoroughly
+ * destructive — sections are removed from the DOM, knowls are flattened,
+ * `<details>` become `<div>`s. There is no undo. Since the embedder already
+ * holds the rendered HTML, leaving print preview means re-injecting the *off*
+ * state into that pristine HTML and delivering it again; a fresh document
+ * (whether from a reload or an in-place `document.write`) fires
+ * DOMContentLoaded again and the page comes up in the other mode. No re-render.
+ *
+ * Injecting the off state matters as much as injecting the on state: a
+ * `document.write` rebuild reuses the same `Window`, so a patch installed by an
+ * earlier delivery is still in place. The script therefore keeps the wanted id
+ * in a window property it re-reads on every call, and the off state clears it.
+ */
+/** A printout on a rendered page: a division the reader can lay out for print. */
+export interface PrintoutInfo {
+    /**
+     * The printout element's HTML id — what `?printpreview=` names, and what
+     * {@link injectPrintPreview} takes.
+     */
+    id: string;
+    /** Localized division type: "Worksheet", "Handout", "Project", … */
+    type: string;
+    /** The printout's number as printed ("2.3"), or "" when it has none. */
+    number: string;
+    /** The printout's title as plain text, or "" when it is untitled. */
+    title: string;
+    /**
+     * The three above composed into one line — "Worksheet 2.3: Counting" — for
+     * an embedder that just wants to put the page's printouts in a menu.
+     */
+    label: string;
+}
+/**
+ * The printouts on a rendered page, in document order.
+ *
+ * Empty for a page with none, which is the signal an embedder wants: with no
+ * printouts there is nothing to offer, and — because PreTeXt only emits the
+ * paper-size and print-options controls on a page that has one — no print
+ * preview to be had either.
+ */
+export declare function listPrintouts(html: string): PrintoutInfo[];
+/**
+ * The printout to open in print preview when a document is *itself* a printout
+ * — the case of previewing `worksheet-3.ptx`, whose root element is the
+ * `<worksheet>`. Nothing else in the file competes for the reader's attention,
+ * so the paper layout is what they came to see.
+ *
+ * `rootElement` is the document's root element name **before** any fragment
+ * wrapping: a lone worksheet is rendered inside a synthesized `<article>`, and
+ * by the time the page exists that is all the HTML can say. The printout is the
+ * page's first, since the wrapper holds nothing else.
+ *
+ * Undefined for a document that merely contains printouts — a chapter with
+ * three worksheets in it should open as the chapter.
+ */
+export declare function rootPrintoutId(printouts: PrintoutInfo[], rootElement: string | undefined): string | undefined;
+/**
+ * Window property holding the id the patched reader should report. Read on
+ * every call rather than captured, so re-injecting into a document that shares
+ * a `Window` with an earlier one (an in-place `document.write` rebuild) changes
+ * the answer instead of piling a second patch on the first.
+ */
+export declare const PRINT_PREVIEW_GLOBAL = "__ptxPrintPreview";
+/**
+ * The inline `<script>` (as a string) that makes pretext-core.js see a
+ * `printpreview` query parameter, or — with no id — stop seeing one.
+ *
+ * Written in ES5-ish, self-contained JS because it is embedded verbatim in the
+ * output page (no bundler runs over it) and re-executes on every in-place
+ * `document.write` rebuild.
+ *
+ * The wrapper is deliberately narrow: it adds the parameter only when the
+ * caller passed the location's own search string, which is what pretext-core.js
+ * does and what nothing else has reason to do. Everything else — a
+ * `URLSearchParams` built from a form, from another URL, from an object — is
+ * constructed and returned untouched. Returning a real `URLSearchParams` from
+ * the constructor (rather than subclassing) keeps `instanceof` honest and works
+ * whether or not the caller says `new`.
+ */
+export declare function printPreviewBridgeScript(printoutId?: string): string;
+/**
+ * Deliver a rendered page in the print-preview layout for one of its printouts,
+ * or — with no id — in the ordinary layout.
+ *
+ * Inject into `<head>`, ahead of pretext-core.js: the patch has to be in place
+ * before that script's DOMContentLoaded handler *runs*, and being earlier in
+ * the document is the simplest way to be sure of it.
+ *
+ * An id that is not a printout on this page is treated as no id at all. That is
+ * not merely defensive: pretext-core.js swaps in the print stylesheet *before*
+ * it looks the element up, so a stale id — one left over from the previously
+ * previewed file, say — would leave the reader on a print-styled page with no
+ * printout on it.
+ *
+ * Returns the page with the bridge removed (never with a half-applied one) when
+ * there is no `<head>` to inject into, which would mean the page is not a
+ * PreTeXt render at all.
+ */
+export declare function injectPrintPreview(html: string, printoutId?: string): string;

package/dist/printout.js

@@ -0,0 +1,122 @@
+const p = /<a\b[^>]*\bdata-printout="[^"]*"[^>]*>/gi;
+function s(t, e) {
+  const n = new RegExp(`\\b${e}="([^"]*)"`, "i").exec(t);
+  return n ? u(n[1]) : void 0;
+}
+function u(t) {
+  return t.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;|&#39;/g, "'").replace(/&#x27;/gi, "'").replace(/&amp;/g, "&");
+}
+function l(t, e, n) {
+  const i = [t, e].filter(Boolean).join(" ");
+  return i && n ? `${i}: ${n}` : i || n;
+}
+function w(t) {
+  const e = [], n = /* @__PURE__ */ new Set();
+  for (const [i] of t.matchAll(p)) {
+    const r = s(i, "data-printout");
+    if (!r || n.has(r))
+      continue;
+    n.add(r);
+    const o = s(i, "data-printout-type") ?? "", c = s(i, "data-printout-number") ?? "", a = s(i, "data-printout-title") ?? "";
+    e.push({
+      id: r,
+      type: o,
+      number: c,
+      title: a,
+      label: l(o, c, a)
+    });
+  }
+  return e;
+}
+const f = /* @__PURE__ */ new Set([
+  "worksheet",
+  "handout",
+  "project",
+  "activity",
+  "exploration",
+  "investigation"
+]);
+function E(t, e) {
+  if (!(!e || !f.has(e)))
+    return t[0]?.id;
+}
+const g = "__ptxPrintPreview";
+function v(t) {
+  const e = JSON.stringify(t ?? null);
+  return [
+    "<script>",
+    "(function () {",
+    "  var KEY = " + JSON.stringify(g) + ";",
+    "  window[KEY] = " + e + ";",
+    // Pin the page to light mode for the print layout; see printPreviewCss.
+    // `data-darkmode="disabled"` is upstream's own switch — pretext-core.js
+    // checks it in both isDarkMode and setDarkMode, the only two places that
+    // touch the class — and the theme bridge honours it too (theme.ts), so a
+    // later theme message from the embedder cannot undo this. Nothing removes
+    // the attribute again: leaving print preview delivers a new document,
+    // whose <html> carries whatever the render authored.
+    "  if (window[KEY] && window.document.documentElement) {",
+    "    var root = window.document.documentElement;",
+    "    if (root.classList) { root.classList.remove('dark-mode'); }",
+    "    root.setAttribute('data-darkmode', 'disabled');",
+    "  }",
+    // The patch survives a document.write rebuild along with the Window, so
+    // installing it twice would stack wrappers; the id above is what changes.
+    "  if (window.__ptxPrintPreviewPatched) { return; }",
+    "  var Base = window.URLSearchParams;",
+    "  if (!Base) { return; }",
+    "  window.__ptxPrintPreviewPatched = true;",
+    "  function Patched(init) {",
+    "    var params = new Base(init === undefined || init === null ? '' : init);",
+    "    var id = window[KEY];",
+    "    if (id && typeof init === 'string' && init === window.location.search) {",
+    "      params.set('printpreview', id);",
+    "    }",
+    "    return params;",
+    "  }",
+    "  Patched.prototype = Base.prototype;",
+    "  window.URLSearchParams = Patched;",
+    "})();",
+    "<\/script>"
+  ].join(`
+`);
+}
+function P() {
+  return [
+    "<style>",
+    ":root {",
+    "  color-scheme: light;",
+    "}",
+    // !important because the rule this has to beat is the *host's*, not the
+    // page's: VS Code injects a `body { background-color:
+    // var(--vscode-editor-background) }` of its own into every webview
+    // document, and where it injects it is not ours to rely on. The values
+    // still come from the print stylesheet's variables, so it stays in charge
+    // of what "paper" looks like.
+    "html, body {",
+    "  background: var(--page-color, #fff) !important;",
+    "  color: var(--body-text-color, #000) !important;",
+    "}",
+    "</style>"
+  ].join(`
+`);
+}
+const h = "<!--ptx-print-preview-->", m = "<!--/ptx-print-preview-->", x = /\n?<!--ptx-print-preview-->[\s\S]*?<!--\/ptx-print-preview-->/;
+function b(t, e) {
+  const n = x.exec(t), i = n ? t.slice(0, n.index) + t.slice(n.index + n[0].length) : t, r = /<head[^>]*>/i.exec(i);
+  if (!r)
+    return i;
+  const o = e && w(i).some((d) => d.id === e) ? e : void 0, c = `
+${h}
+${v(o)}
+${o ? `${P()}
+` : ""}${m}`, a = r.index + r[0].length;
+  return i.slice(0, a) + c + i.slice(a);
+}
+export {
+  g as PRINT_PREVIEW_GLOBAL,
+  b as injectPrintPreview,
+  w as listPrintouts,
+  v as printPreviewBridgeScript,
+  E as rootPrintoutId
+};

package/dist/renderer.d.ts

@@ -1,4 +1,5 @@
 import { PreviewBannerOptions } from './banner.js';
+import { PrintoutInfo } from './printout.js';
 import { RevealView } from './reveal.js';
 import { PtxSourceMap } from './sourcemap.js';
 import { RenderTarget } from './target.js';
@@ -229,6 +230,21 @@ export interface RenderOptions {
      * settings"), so there is no default text here.
      */
     previewBanner?: PreviewBannerOptions;
+    /**
+     * Open the page in the print-preview layout for the printout with this HTML
+     * id — paginated to a paper size, headers and footers, workspaces at their
+     * true height (see printout.ts). The ids to choose from come back as
+     * {@link RenderResult.printouts}; {@link RenderResult.rootPrintout} names the
+     * one worth defaulting to.
+     *
+     * Omit for the ordinary layout, which leaves the output byte-identical to a
+     * render without this option. An embedder that toggles the layout should
+     * re-inject over the rendered HTML instead of re-rendering
+     * (`injectPrintPreview`), which is both instant and — because it states the
+     * *off* case explicitly — the only way to leave print preview in a host that
+     * rewrites its document in place.
+     */
+    printPreview?: string;
 }
 export interface RenderResult {
     /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */
@@ -241,6 +257,20 @@ export interface RenderResult {
     target: RenderTarget;
     /** Present when RenderOptions.sourceMap was set. */
     sourceMap?: PtxSourceMap;
+    /**
+     * The page's printouts — worksheets, handouts, and projects with a workspace
+     * — in document order, each of which can be shown in the print-preview
+     * layout (see printout.ts). Empty when the document has none, which is also
+     * when the page carries no print controls to drive that layout with.
+     */
+    printouts: PrintoutInfo[];
+    /**
+     * The printout to open in print preview by default, set when the rendered
+     * document *is* a printout rather than merely containing some — previewing a
+     * `worksheet.ptx`, whose root element is the `<worksheet>` itself. Undefined
+     * otherwise, meaning the page should open in the ordinary layout.
+     */
+    rootPrintout?: string;
     /**
      * Absolute directories that the `external/` and `generated/` URL prefixes in
      * `html` refer to, resolved from the publication file against the main

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -26,6 +26,9 @@
       ],
       "reveal": [
         "./dist/reveal.d.ts"
+      ],
+      "printout": [
+        "./dist/printout.d.ts"
       ]
     }
   },
@@ -57,6 +60,11 @@
       "import": "./dist/reveal.js",
       "default": "./dist/reveal.js"
     },
+    "./printout": {
+      "types": "./dist/printout.d.ts",
+      "import": "./dist/printout.js",
+      "default": "./dist/printout.js"
+    },
     "./cli": "./dist/cli.js"
   },
   "sideEffects": false,