@dogsbay/render-html 0.0.0-stage → 0.2.0-beta.116

package/dist/render.d.ts

@@ -0,0 +1,114 @@
+/**
+ * TreeNode → HTML. Emits plain semantic HTML plus light-DOM custom
+ * elements (`db-tabs`, `db-accordion`, `db-code-block`) whose markup
+ * contract comes from `@dogsbay/elements`. Everything is a string, so
+ * rendering is synchronous and runs anywhere.
+ */
+import type { InlineNode, TreeNode } from "@dogsbay/types";
+import { FOREIGN_END, FOREIGN_START } from "./html.js";
+import { type Highlighter } from "./lines.js";
+import { scriptUrl } from "./url.js";
+export interface Heading {
+    depth: number;
+    id: string;
+    text: string;
+}
+export interface RenderContext {
+    /** Rewrite a link target (root-relative, relative, `.md`) to its published URL. */
+    link(href: string): string;
+    /** Rewrite an image or asset path. */
+    asset(src: string): string;
+    /** Script links and images refused on this page (scriptUrl), for the caller to report. */
+    unsafeUrls?: Set<string>;
+    /** Syntax highlighting (highlight.ts). Without one, code renders as plain text with the same markup. */
+    highlighter?: Highlighter;
+    /** Collected h2/h3 for the table of contents. */
+    headings: Heading[];
+    /** Ids already used on the page; keeps generated ids unique. */
+    ids: Set<string>;
+    /** Node types the renderer did not recognise (for build warnings). */
+    unknown: Set<string>;
+    /** Page-local counter for generated ids. */
+    seq: number;
+    /** Localised UI strings. */
+    t(key: string): string;
+    /** References seen per footnote label (repeat references get distinct ids). */
+    fnRefs?: Map<string, number>;
+    /** LaTeX → HTML (`katexMath` from `@dogsbay/render-html/math`, or your own); without it, math stays LaTeX in code. */
+    math?: (latex: string, display: boolean) => string;
+    /** Set when the page rendered math with KaTeX, so it links the KaTeX stylesheet. */
+    usedMath?: boolean;
+    /** content.codeBlockTitle: true shows a header for a title or a language, "auto" for a title only, false never. */
+    codeBlockTitle?: boolean | "auto";
+    /**
+     * Resolves an icon name (`rocket`, `lucide:book-open`, `material:tune`) to SVG markup or an emoji,
+     * as @dogsbay/icons does for the Astro pipeline. The Node CLI passes one; without it only the
+     * built-in Lucide set in icons.ts is available.
+     */
+    icons?: (name: string) => string | undefined;
+    /** Icon names that could not be resolved; the build warns about them. */
+    missingIcons?: Set<string>;
+    /** The SVG for a diagram's source, when the caller rendered it (dogsbay-ssg: src/core/diagrams.ts); otherwise the diagram stays a code block. */
+    diagram?: (lang: string, code: string) => string | undefined;
+    /** Tag images for click-to-zoom (the image zoom plugin); "outside-links" skips images inside links. */
+    imageZoom?: "all" | "outside-links";
+    /** A paragraph that is one titled image → a figure captioned by the title (content.imageCaptions). */
+    imageCaptions?: "title" | false;
+    /** Rendering inside a link's text. */
+    inLink?: boolean;
+    /**
+     * A filter for raw HTML (html and html-inline nodes, and HTML found in props such
+     * as a callout title), applied where it is written. @dogsbay/render passes its
+     * sanitizer here; without one, raw HTML is written as authored.
+     */
+    rawHtml?: (html: string) => string;
+}
+export { FOREIGN_END, FOREIGN_START };
+export { scriptUrl };
+/** ctx.link, unless the target is a script link: then "#", and it is reported. */
+export declare function linkUrl(href: string, ctx: RenderContext): string;
+/** ctx.asset, unless the source is a script URL: then empty, and it is reported. */
+export declare function assetUrl(src: string, ctx: RenderContext): string;
+/**
+ * LaTeX → HTML with MathML for screen readers, at build time: no script on
+ * the page. As `@dogsbay/ui`'s MathKatex; a formula KaTeX cannot parse is
+ * shown in the error colour instead of failing the build.
+ */
+export declare function renderMath(latex: string, display: boolean, ctx: RenderContext): string | undefined;
+export declare function uniqueId(ctx: RenderContext, base: string): string;
+export declare function renderInline(nodes: InlineNode[] | undefined, ctx: RenderContext): string;
+/** Plain text of inline nodes (for TOC entries, titles and search). */
+export declare function inlineText(nodes: InlineNode[] | undefined): string;
+/**
+ * Rewrite href/src attributes of tags in raw HTML so root-relative links follow
+ * the site layout. Only attributes inside a start tag are touched (not text such
+ * as an escaped code example, nor data-href), and values are entity-decoded
+ * before resolving so `&amp;` is not escaped twice.
+ */
+export declare function rewriteHtml(raw: string, ctx: RenderContext): string;
+export declare function renderBlocks(nodes: TreeNode[] | undefined, ctx: RenderContext): string;
+/** What highlighting a code node asks of the highlighter; the look-ahead in `build` uses it to highlight blocks ahead of their page. */
+export interface CodeRequest {
+    code: string;
+    lang: string | undefined;
+    opts: {
+        highlights: number[];
+        lineNumbers: boolean;
+        diffAdd: number[];
+        diffRemove: number[];
+    };
+}
+export declare function codeRequest(n: TreeNode): CodeRequest;
+/**
+ * Every block (language tag as written, and code) a tree's rendering may ask
+ * the highlighter for, so a highlighter that loads grammars per language
+ * (`Highlighter.load`) can load them before rendering: code nodes, and
+ * diagrams, which fall back to a code block when not rendered. The code is
+ * part of it: a markdown block needs the grammars its fences name. Looks
+ * through props as well as children, so a node a component nests elsewhere
+ * is found.
+ */
+export declare function highlightInputs(tree: unknown): Array<{
+    lang: string | undefined;
+    code: string;
+}>;