brookmd 0.22.0

package/dist/react.d.ts

@@ -0,0 +1,236 @@
+import type { Block, BlockComponentProps, Components } from "./types.js";
+import { BrookClient } from "./client.js";
+import type { Decorator, ParserConfig, RenderMetricsHook, UrlTransform } from "./types-core.js";
+/**
+ * Render a streaming markdown document from a BrookClient. Each block is its
+ * own memoized React node keyed by its stable parser-assigned ID, so React
+ * only reconciles the blocks whose HTML actually changed since the last
+ * patch. Heavy renderers (Shiki, KaTeX, Mermaid) defer work until a block
+ * is closed.
+ *
+ * ## Custom components
+ *
+ * Pass `components` to override rendering (see {@link Components}):
+ *
+ * ```tsx
+ * <BrookMarkdown
+ *   client={client}
+ *   components={{
+ *     table: (p) => <table className="my-table" {...p} />, // tag-level
+ *     a: (p) => <a target="_blank" rel="noreferrer" {...p} />,
+ *     CodeBlock: (p) => <MyCodeBlock {...p} />,             // block-kind
+ *   }}
+ * />
+ * ```
+ *
+ * Rules:
+ *   - **Tag-level** keys (`table`, `a`, `code`, `h1`…) replace that element
+ *     wherever it appears inside a block. Applied by converting the block's
+ *     trusted HTML to a React tree.
+ *   - **Block-kind** keys ({@link BlockKindTag}: `CodeBlock`, `Mermaid`,
+ *     `Table`…) replace the whole block; the component gets
+ *     {@link BlockComponentProps}.
+ *   - **Open / speculative** blocks always render via `innerHTML` (their HTML
+ *     is partial); a tag-level override takes effect once the block commits.
+ *   - With no `components` prop the renderer takes the original fast
+ *     `innerHTML` path — output is byte-identical to before.
+ *   - **Memoize `components`** (or hoist it) if you define it inside a
+ *     component — a fresh object identity each render busts the block memo and
+ *     forces every block to re-parse on every patch.
+ *   - For code blocks the built-in highlighter is the default; it is bypassed
+ *     (so your override wins) when you provide `components.CodeBlock`,
+ *     `components.pre`, or `components.code`.
+ */
+interface BrookMarkdownProps {
+    /**
+     * A caller-owned client (you drive `append`/`finalize` and own its lifecycle —
+     * the component never destroys it). Mutually exclusive with `stream`; if both
+     * are given, `client` wins (a dev warning fires).
+     */
+    client?: BrookClient;
+    /**
+     * A stream to render directly — the 1-line common case. Pass a `Response`, a
+     * `ReadableStream<Uint8Array>`, or an `AsyncIterable<string>` (e.g. SSE
+     * deltas) and the component owns an internal client, pipes the stream, and
+     * destroys it on unmount. A new `stream` identity supersedes the old.
+     */
+    stream?: AsyncIterable<string> | ReadableStream<Uint8Array> | Response;
+    /** Parser config for the internally-created client (stream mode only). */
+    streamConfig?: ParserConfig;
+    /** Called if piping the `stream` rejects (the source errored). Not the worker error channel. */
+    onStreamError?: (err: Error) => void;
+    components?: Components;
+    /**
+     * Skip layout/paint for off-screen blocks via CSS `content-visibility: auto`
+     * — for very long documents (hundreds+ of blocks). Off by default. Applies
+     * only to *closed* blocks (the streaming tail always renders fully). Keeps
+     * nodes in the DOM; it cuts rendering cost, not node count.
+     */
+    virtualize?: boolean;
+    /**
+     * Render a bottom snap target so the view follows the streaming tail. This is
+     * CSS-only: it emits a sentinel with `scroll-snap-align: end`; **you** add
+     * `scroll-snap-type: y proximity` to your scroll container. The view then
+     * follows the bottom as content streams in and releases when the user scrolls
+     * up (and re-locks when they scroll back near the bottom). Off by default.
+     */
+    stickToBottom?: boolean;
+    /**
+     * Optional HTML sanitizer applied to every block's HTML before it is injected
+     * via `innerHTML` — **including the streaming (open/speculative) tail**, the
+     * path that raw `innerHTML` would otherwise expose. Pass a real sanitizer
+     * (e.g. DOMPurify's `sanitize`) when rendering untrusted / LLM HTML with
+     * `unsafeHtml` on. brookmd stays zero-dep — you bring the sanitizer. The
+     * built-in code/math renderers operate on already-escaped content and are not
+     * run through it. When omitted, rendering is byte-identical and zero-cost.
+     *
+     * **Memoize / hoist this** (same trap as `components`): a fresh closure each
+     * render busts the per-block memo, so every block re-sanitizes and re-parses
+     * on every patch instead of only the streaming tail.
+     */
+    sanitize?: (html: string) => string;
+    /**
+     * Wrap or replace matched inline **text** while streaming, in O(n) — e.g. to
+     * bold financial figures (`$2.5B`, `10-15%`, `FY2024`) or linkify tickers. Each
+     * {@link Decorator} runs POST-PARSE on real inline TEXT nodes only (never URLs,
+     * code, or markup), once per committed block, so a long document stays linear.
+     *
+     * **Trusted surface.** A decorator's `replace` output is spliced straight into
+     * the tree and is **NOT** sanitized (React renders a `javascript:` href without
+     * complaint). Treat this exactly like `components`: build only trusted nodes,
+     * and route any link href through the exported `safeUrl` / the `wrapLink`
+     * helper. Matching is per-text-node — a value split by inline markup like
+     * `$2.<em>5</em>B` is two text nodes and won't match across them.
+     *
+     * **HOIST / memoize this array.** A fresh identity each render busts the block
+     * memo, forcing every committed block to re-parse + re-decorate every patch
+     * (O(n²)); a one-time dev warning fires if the identity changes. Enabling
+     * decorators routes a block through the walk path (off the `innerHTML` fast
+     * path) — expected, and still O(n) per block.
+     */
+    decorators?: Decorator[];
+    /**
+     * Rewrite `href`/`src`/`poster` URLs as blocks render — proxy images, add UTM
+     * params, etc. The output is re-sanitized (`safeUrl(urlTransform(safeUrl(v)))`)
+     * so it can never introduce a `javascript:` / `data:text/html` URL. **HOIST /
+     * memoize** for the same reason as `decorators`.
+     */
+    urlTransform?: UrlTransform;
+    /**
+     * Opt-in: when an OPEN (streaming) block re-renders each patch, reuse the
+     * React nodes of its top-level children whose HTML is unchanged and re-parse
+     * only the new trailing content, instead of re-parsing the block's whole HTML
+     * every tick. Only takes effect when `components` (or `sanitize`) routes a
+     * block through the parser; the no-`components` fast path (`innerHTML`) is
+     * untouched. Off by default and byte-identical to default rendering — enable
+     * it for documents with a long, slowly-growing streamed block under a custom
+     * `components` map. Closed blocks are already wholesale memo-skipped, so this
+     * applies only to the streaming tail.
+     */
+    childMemo?: boolean;
+    /** Appended to the root's `className` (the `brook-md` class is always present). */
+    className?: string;
+    /** Set on the root element. */
+    id?: string;
+    /** Set on the root element (e.g. `"article"`, `"log"`). */
+    role?: string;
+    /**
+     * Make the root a live region so screen readers announce streamed content.
+     * `"polite"` (recommended) coalesces rapid updates and announces when the
+     * reader is idle — it does **not** read every token. Off by default.
+     */
+    "aria-live"?: "off" | "polite" | "assertive";
+    /** Live-region atomicity; pair with `aria-live`. Off by default. */
+    "aria-atomic"?: boolean;
+    /**
+     * Optional render-churn probe. Fires once per ACTUAL render of a block —
+     * never for a committed block that memo-skips on a tail-only patch. The
+     * callback gets the block id and a {@link RenderMetrics} sample (per-block
+     * `renderCount`, `speculativeToggleCount`, `lastRenderMs`, `kind`). Zero
+     * overhead when omitted. **Memoize / hoist this** (same trap as `components`):
+     * a fresh closure each render busts the per-block memo, forcing every block to
+     * re-render on every patch.
+     */
+    onRenderMetrics?: RenderMetricsHook;
+    /**
+     * **Opt-in, off by default.** Render the block list through React's
+     * `useDeferredValue`, so a burst of patches can yield to higher-priority
+     * updates and the streaming tail commits at a lower priority. When a deferred
+     * render is in flight the root carries an extra `brook-deferred` class (style it
+     * however you like). This is a *no-op on a single patch*, has no effect during
+     * SSR (`useDeferredValue` is a client-only concern), and **does not change
+     * output** — only commit timing. Leaving it unset is recommended; rAF
+     * coalescing (the DOM adapter's batched path) is the preferred way to absorb
+     * high-frequency patches. Provided for callers who specifically want React's
+     * concurrent deferral of the visible tail.
+     */
+    deferTail?: boolean;
+}
+export declare function __resetUnstableWarnings(): void;
+/**
+ * Own a {@link BrookClient} for the lifetime of a component and drive it from a
+ * `stream` (a `Response`, `ReadableStream<Uint8Array>`, or
+ * `AsyncIterable<string>`). Returns the client (read `outline()` / `getMetrics()`
+ * off it, or pass it to `<BrookMarkdown client={…} />`). The client is created
+ * once and destroyed on unmount; a new `stream` identity supersedes the old
+ * (the prior pipe is aborted, the parser is reset, the new stream is piped).
+ *
+ * Caveat (matches the manual `useEffect` form): a single-use stream — a
+ * `Response`/`ReadableStream`, or an async generator — can only be consumed
+ * once, so React **StrictMode**'s dev-only double-mount may truncate it in
+ * development. Production mounts once and is unaffected. If you need dev-exact
+ * streaming, drive a caller-owned client manually.
+ */
+export declare function useBrookStream(stream: AsyncIterable<string> | ReadableStream<Uint8Array> | Response | null | undefined, options?: {
+    config?: ParserConfig;
+    onError?: (err: Error) => void;
+}): BrookClient;
+/**
+ * Own a {@link BrookClient} driven by a CONTROLLED full string — the bridge for
+ * UIs that hold a streaming message as a single growing string prop (the common
+ * React shape) rather than as a stream. Pass the whole document-so-far on each
+ * render and {@link BrookClient.setContent} diffs it: a prefix-extension appends
+ * only the delta; any divergence (e.g. the finished text swapped for a
+ * re-processed final string) resets and reparses. Returns the owned client —
+ * pass it to `<BrookMarkdown client={…} />` (and read `outline()` etc.).
+ *
+ * Pass `streaming: false` once the content is final to finalize the stream and
+ * commit its last block (only then does a finished code fence highlight + show
+ * its copy button). If `streaming` is omitted or `true` the stream is left OPEN
+ * — right for a still-growing string, but a *complete static* string rendered as
+ * `useBrookMarkdownString(md)` keeps its last block in the streaming state until
+ * you pass `{ streaming: false }`. (Inferring "done" from an absent flag is
+ * deliberately avoided: it would re-finalize on every token for callers that
+ * grow the string without the flag — an O(n²) reparse trap.) The client is
+ * created once and destroyed on unmount; StrictMode's dev double-mount is handled
+ * (reattach re-feeds the document). For a true stream source
+ * (`Response` / `ReadableStream` / SSE generator) use {@link useBrookStream}
+ * instead — it avoids buffering the whole document as a string.
+ */
+export declare function useBrookMarkdownString(content: string, options?: {
+    config?: ParserConfig;
+    streaming?: boolean;
+}): BrookClient;
+declare function BrookMarkdownImpl(props: BrookMarkdownProps): import("react/jsx-runtime").JSX.Element;
+export declare const BrookMarkdown: import("react").MemoExoticComponent<typeof BrookMarkdownImpl>;
+export declare function blockKindProps(block: Block, components?: Components): BlockComponentProps;
+export declare function blocksEqual(prev: {
+    block: Block;
+    components?: Components;
+    virtualize?: boolean;
+    sanitize?: (html: string) => string;
+    childMemo?: boolean;
+    onRenderMetrics?: RenderMetricsHook;
+    decorators?: Decorator[];
+    urlTransform?: UrlTransform;
+}, next: {
+    block: Block;
+    components?: Components;
+    virtualize?: boolean;
+    sanitize?: (html: string) => string;
+    childMemo?: boolean;
+    onRenderMetrics?: RenderMetricsHook;
+    decorators?: Decorator[];
+    urlTransform?: UrlTransform;
+}): boolean;
+export {};