@pretextbook/pretext-html 0.6.0 → 0.7.0

package/dist/banner.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dismissible "this is a live preview" warning banner.
+ *
+ * The preview forces `<html><platform portable="yes"/></html>` (see
+ * {@link forcePortablePublication}) and skips the asset-generation step
+ * entirely, so what an author sees while editing can genuinely differ from a
+ * real build — different chunking, no locally generated images, etc. The
+ * banner exists to say so, once, without nagging: it renders across the top
+ * of the page, can be dismissed, and leaves an unobtrusive link behind that
+ * brings it back.
+ *
+ * The warning text itself is entirely the caller's: the two embedders this
+ * package ships for phrase the same fact differently (the VS Code extension
+ * talks about "the publication file"; pretext.plus talks about "build
+ * settings"), and there is no wording that fits both. See
+ * {@link RenderOptions.previewBanner}.
+ *
+ * Dismissal is remembered in `localStorage`, not on `window` the way the
+ * theme/reveal bridges remember their state. Those need to survive only an
+ * in-place `document.write` rebuild (same window, new render moments later);
+ * a reader dismissing this banner expects it to stay dismissed the next time
+ * they open the preview too, including after the extension falls back to a
+ * full `webview.html` reassignment (a new document, same as a page reload).
+ */
+export interface PreviewBannerOptions {
+    /**
+     * Warning text shown in the banner. Plain text — it is HTML-escaped before
+     * being embedded, so no markup can be passed through it.
+     */
+    message: string;
+}
+/** localStorage key the injected script reads/writes to remember dismissal. */
+export declare const PREVIEW_BANNER_STORAGE_KEY = "ptxPreviewBannerDismissed";
+/**
+ * The inline `<script>` (as a string) that wires up dismiss/restore.
+ *
+ * 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. It is idempotent: re-reading
+ * `localStorage` and re-applying the resulting visibility is harmless however
+ * many times it runs.
+ */
+export declare function previewBannerScript(): string;
+/**
+ * Inject the warning banner into a rendered page, as the first thing inside
+ * `<body>` — ahead of PreTeXt's own masthead, so it reads as a notice about
+ * the page rather than part of it.
+ *
+ * Returns the page unchanged when no `<body>` tag is found.
+ */
+export declare function injectPreviewBanner(html: string, options: PreviewBannerOptions): string;