@carbon/ai-chat-components 1.4.0 → 1.5.0-rc.1

package/es/components/markdown/src/markdown-token-tree.d.ts

@@ -1,4 +1,22 @@
-import { Token } from "markdown-it";
+/**
+ * The parse/diff layer between raw markdown source and the renderer. Parses with markdown-it (built-in plugins plus any caller-supplied `markdownItPlugins`), builds a nested {@link TokenTree}, and diffs it against the previous tree so streaming updates can reuse stable subtrees.
+ *
+ * ### Why diff
+ *
+ * `diffTokenTree` reuses old nodes by `key` whenever the key matches. This is what lets `./markdown-renderer.ts`'s use of Lit's `repeat` directive keep DOM stable during streaming: each incoming chunk re-parses the full source, but matched keys reuse the prior subtree, so only the genuinely new tail differs.
+ *
+ * ### Why `cachedHtml`
+ *
+ * For the leaf token types in {@link PLUGIN_DELEGABLE_TOKEN_TYPES}, when a user plugin's renderer rule produces the HTML (via `./utils/plugin-fallback.ts`), the result is cached on the `TokenTree` node and carried forward by `diffTokenTree` whenever the underlying token's `content` / `attrs` / `info` are unchanged. A stable earlier-in-document fence/image/etc. therefore isn't re-rendered through the plugin's rule on every streaming chunk. The cache is tagged with the `MarkdownIt` instance that produced it; a plugin swap (which builds a fresh instance) invalidates the cache on read.
+ *
+ * The block comment on {@link PLUGIN_DELEGABLE_TOKEN_TYPES} explains why only those four token types are eligible for delegation.
+ *
+ * ### Related files
+ *
+ * - `./markdown-renderer.ts` — consumes the `TokenTree` and produces a Lit `TemplateResult`.
+ * - `./utils/plugin-fallback.ts` — reads `cachedHtml` and {@link getPluginOverriddenRules} to drive the delegated-render flow.
+ */
+import MarkdownIt, { Token } from "markdown-it";
 /**
  * Represents a node in the token tree structure.
  */
@@ -11,9 +29,20 @@ export interface TokenTree {
     children: TokenTree[];
 }
 /**
- * Parses markdown text into a flat array of markdown-it tokens.
+ * A markdown-it plugin reference. Either a bare plugin function or a
+ * `[plugin, options]` / `[plugin, ...params]` tuple matching
+ * `MarkdownIt.use(...)`.
+ *
+ * @experimental
+ */
+export type MarkdownItPlugin = MarkdownIt.PluginSimple | [MarkdownIt.PluginWithOptions<unknown>, unknown] | [MarkdownIt.PluginWithParams, ...unknown[]];
+/**
+ * Returns a (cached) markdown-it instance for the given plugin set, choosing the
+ * html-enabled variant or the html-disabled (HTML-neutralizing) variant based on
+ * `removeHtml`. Calling with the same `plugins` reference and `removeHtml` returns
+ * the same instance.
  */
-export declare function markdownToMarkdownItTokens(fullText: string, allowHtml?: boolean): Token[];
+export declare function getMarkdownIt(plugins?: MarkdownItPlugin[], removeHtml?: boolean): MarkdownIt;
 /**
  * Converts a flat list of markdown-it tokens into a tree.
  */
@@ -27,6 +56,22 @@ export declare function buildTokenTree(tokens: Token[]): TokenTree;
  */
 export declare function diffTokenTree(oldTree: TokenTree | undefined, newTree: TokenTree): TokenTree;
 /**
- * Converts markdown into a tree with keys on it for Lit.
+ * Result of {@link markdownToTokenTree}. Returns the parsed tree plus the
+ * markdown-it instance used to produce it so the renderer can fall back to
+ * `md.renderer.render()` for plugin-introduced tokens. The set of
+ * plugin-overridden rules is read from the per-instance WeakMap via
+ * {@link getPluginOverriddenRules} as needed.
+ */
+export interface MarkdownToTokenTreeResult {
+    tree: TokenTree;
+    md: MarkdownIt;
+}
+/**
+ * Converts markdown into a tree with keys on it for Lit. The returned `md` is the
+ * (cached) markdown-it instance keyed by `markdownItPlugins` identity and the
+ * `removeHtml` flag (html-enabled vs html-neutralizing variant).
  */
-export declare function markdownToTokenTree(markdown: string, lastTree?: TokenTree, allowHtml?: boolean): TokenTree;
+export declare function markdownToTokenTree(markdown: string, lastTree: TokenTree | undefined, opts?: {
+    removeHtml?: boolean;
+    markdownItPlugins?: MarkdownItPlugin[];
+}): MarkdownToTokenTreeResult;

package/es/components/markdown/src/markdown-token-tree.js

@@ -19,48 +19,148 @@ import { markdownItTaskLists } from './plugins/markdown-it-task-lists.js';
  *  @license
  */
 /**
- * Pre-configured markdown-it instance that allows HTML content.
- * Uses CommonMark preset for GitHub Flavored Markdown compatibility.
+ * The parse/diff layer between raw markdown source and the renderer. Parses with markdown-it (built-in plugins plus any caller-supplied `markdownItPlugins`), builds a nested {@link TokenTree}, and diffs it against the previous tree so streaming updates can reuse stable subtrees.
+ *
+ * ### Why diff
+ *
+ * `diffTokenTree` reuses old nodes by `key` whenever the key matches. This is what lets `./markdown-renderer.ts`'s use of Lit's `repeat` directive keep DOM stable during streaming: each incoming chunk re-parses the full source, but matched keys reuse the prior subtree, so only the genuinely new tail differs.
+ *
+ * ### Why `cachedHtml`
+ *
+ * For the leaf token types in {@link PLUGIN_DELEGABLE_TOKEN_TYPES}, when a user plugin's renderer rule produces the HTML (via `./utils/plugin-fallback.ts`), the result is cached on the `TokenTree` node and carried forward by `diffTokenTree` whenever the underlying token's `content` / `attrs` / `info` are unchanged. A stable earlier-in-document fence/image/etc. therefore isn't re-rendered through the plugin's rule on every streaming chunk. The cache is tagged with the `MarkdownIt` instance that produced it; a plugin swap (which builds a fresh instance) invalidates the cache on read.
+ *
+ * The block comment on {@link PLUGIN_DELEGABLE_TOKEN_TYPES} explains why only those four token types are eligible for delegation.
+ *
+ * ### Related files
+ *
+ * - `./markdown-renderer.ts` — consumes the `TokenTree` and produces a Lit `TemplateResult`.
+ * - `./utils/plugin-fallback.ts` — reads `cachedHtml` and {@link getPluginOverriddenRules} to drive the delegated-render flow.
  */
-const htmlMarkdown = new MarkdownIt("commonmark", {
-    html: true,
-    breaks: true,
-    linkify: true,
-})
-    .enable("table")
-    .enable("strikethrough")
-    .enable("linkify")
-    .use(markdownItAttrs)
-    .use(markdownItHighlight)
-    .use(markdownItTaskLists);
 /**
- * Pre-configured markdown-it instance that strips HTML content.
- * Same features as htmlMarkdown but with HTML disabled for security.
+ * Token types whose renderer rule, when overridden by a user-supplied
+ * markdown-it plugin, will be honored — instead of the native Lit dispatch.
+ * All four are leaf tokens (`nesting === 0`) so the slice handed to
+ * `md.renderer.render()` is a single token and the rendered HTML can be
+ * safely cached on the {@link TokenTree} node.
+ *
+ * Container tokens (paragraph_open, heading_open, list_*_open, table_open)
+ * are intentionally excluded: delegating them would erase Carbon custom
+ * elements (cds-unordered-list, cds-list-item, cds-aichat-table) and break
+ * streaming-friendly per-child diffing for the subtree. Link tokens are
+ * excluded because the native `<a>` dispatch injects `target="_blank"` for
+ * chat-link safety.
+ *
+ * @internal
+ */
+const PLUGIN_DELEGABLE_TOKEN_TYPES = new Set([
+    "fence",
+    "image",
+    "code_inline",
+    "html_block",
+]);
+// Per-instance set of renderer-rule keys that user plugins overrode (or
+// added) relative to the snapshot taken after our built-in plugins ran.
+// WeakMap so cleanup follows the MarkdownIt instance's lifetime.
+const pluginOverriddenRulesByMd = new WeakMap();
+const EMPTY_RULE_SET = new Set();
+/**
+ * Returns the set of renderer-rule keys that user-supplied plugins overrode
+ * (or freshly added) on the given markdown-it instance, relative to the
+ * baseline established after our built-in plugins (markdownItAttrs,
+ * markdownItHighlight, markdownItTaskLists) ran. The renderer uses this to
+ * decide which token types to route through `md.renderer.render()` instead
+ * of native Lit dispatch. Returns an empty set for instances we didn't build.
+ *
+ * @internal
+ */
+function getPluginOverriddenRules(md) {
+    return pluginOverriddenRulesByMd.get(md) ?? EMPTY_RULE_SET;
+}
+/**
+ * Builds a new markdown-it instance with the built-in plugins and any user-supplied
+ * plugins applied on top. `options.html` selects whether raw HTML is parsed as HTML
+ * (`true`, the default) or neutralized to inert escaped text (`false`, used when
+ * {@link CDSAIChatMarkdown.removeHTML} is set). Both variants are built through this
+ * same path so plugin application and overridden-rule snapshotting stay identical.
+ *
+ * Snapshots `md.renderer.rules` after the built-in plugins but before the user
+ * plugins, then records the keys whose function reference changed (or whose
+ * key was added) into {@link pluginOverriddenRulesByMd}.
+ */
+function createMarkdownIt(plugins, options = {}) {
+    const md = new MarkdownIt("commonmark", {
+        html: options.html ?? true,
+        breaks: true,
+        linkify: true,
+    })
+        .enable("table")
+        .enable("strikethrough")
+        .enable("linkify")
+        .use(markdownItAttrs)
+        .use(markdownItHighlight)
+        .use(markdownItTaskLists);
+    const baselineRules = {
+        ...md.renderer.rules,
+    };
+    for (const plugin of plugins ?? []) {
+        if (Array.isArray(plugin)) {
+            const [fn, ...args] = plugin;
+            md.use(fn, ...args);
+        }
+        else {
+            md.use(plugin);
+        }
+    }
+    const currentRules = md.renderer.rules;
+    const overridden = new Set();
+    const allKeys = new Set([
+        ...Object.keys(baselineRules),
+        ...Object.keys(currentRules),
+    ]);
+    for (const key of allKeys) {
+        if (currentRules[key] !== baselineRules[key]) {
+            overridden.add(key);
+        }
+    }
+    pluginOverriddenRulesByMd.set(md, overridden);
+    return md;
+}
+// Cache for the no-plugins default instances.
+const defaultMarkdownIt = {};
+// Cache keyed by plugin-array identity. WeakMap so plugin arrays that go out of
+// scope can be collected.
+const markdownItCache = new WeakMap();
+/**
+ * Returns a (cached) markdown-it instance for the given plugin set, choosing the
+ * html-enabled variant or the html-disabled (HTML-neutralizing) variant based on
+ * `removeHtml`. Calling with the same `plugins` reference and `removeHtml` returns
+ * the same instance.
  */
-const noHtmlMarkdown = new MarkdownIt("commonmark", {
-    html: false,
-    breaks: true,
-    linkify: true,
-})
-    .enable("table")
-    .enable("strikethrough")
-    .enable("linkify")
-    .use(markdownItAttrs)
-    .use(markdownItHighlight)
-    .use(markdownItTaskLists);
+function getMarkdownIt(plugins, removeHtml = false) {
+    const variants = !plugins || plugins.length === 0
+        ? defaultMarkdownIt
+        : (markdownItCache.get(plugins) ??
+            (() => {
+                const created = {};
+                markdownItCache.set(plugins, created);
+                return created;
+            })());
+    const slot = removeHtml ? "noHtml" : "html";
+    if (!variants[slot]) {
+        variants[slot] = createMarkdownIt(plugins, { html: !removeHtml });
+    }
+    return variants[slot];
+}
 // markdown-it treats a closing HTML tag and the next markdown line (ie. </div>\n##Heading) as one HTML
 // block when there is no blank line between them. Insert an extra newline so the
 // following markdown is parsed as markdown, not swallowed into the HTML token.
-function normalizeHtmlBlockBoundaries(markdown, allowHtml) {
-    if (!allowHtml) {
-        return markdown;
-    }
+function normalizeHtmlBlockBoundaries(markdown) {
     return markdown.replace(/(^|\n)(\s*<\/\s*[A-Za-z][\w:-]*\s*>)(\r?\n)(?=\S)/g, "$1$2$3$3");
 }
 // Fallback for html_block tokens that still bundle a closing tag with trailing
 // markdown on the next line. Split them so the closer stays HTML and the rest
 // is re-parsed as markdown.
-function splitHtmlBlockTrailingMarkdown(tokens, allowHtml) {
+function splitHtmlBlockTrailingMarkdown(tokens, md) {
     return tokens.flatMap((token) => {
         if (token.type !== "html_block") {
             return [token];
@@ -77,18 +177,23 @@ function splitHtmlBlockTrailingMarkdown(tokens, allowHtml) {
         };
         return [
             htmlToken,
-            ...markdownToMarkdownItTokens(`${leadingWhitespace}${trailingMarkdown}`, allowHtml),
+            ...md.parse(`${leadingWhitespace}${trailingMarkdown}`, {}),
         ];
     });
 }
 /**
- * Parses markdown text into a flat array of markdown-it tokens.
+ * Parses markdown text into a flat array of markdown-it tokens using the given instance.
+ *
+ * When `removeHtml` is set, `md` is the html-disabled instance: raw HTML is
+ * neutralized to inert escaped text (content preserved) and there are no HTML
+ * blocks to normalize or split, so the boundary fixups are skipped.
  */
-function markdownToMarkdownItTokens(fullText, allowHtml = true) {
-    const normalizedText = normalizeHtmlBlockBoundaries(fullText, allowHtml);
-    return allowHtml
-        ? splitHtmlBlockTrailingMarkdown(htmlMarkdown.parse(normalizedText, {}), true)
-        : noHtmlMarkdown.parse(normalizedText, {});
+function parseMarkdown(fullText, md, removeHtml) {
+    if (removeHtml) {
+        return md.parse(fullText, {});
+    }
+    const normalizedText = normalizeHtmlBlockBoundaries(fullText);
+    return splitHtmlBlockTrailingMarkdown(md.parse(normalizedText, {}), md);
 }
 /**
  * Generates a unique string key for a markdown-it token.
@@ -156,6 +261,23 @@ function buildTokenTree(tokens) {
     });
     return root;
 }
+function attrsEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b) {
+        return false;
+    }
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i][0] !== b[i][0] || a[i][1] !== b[i][1]) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Compares two TokenTree structures and creates a new tree that reuses
  * unchanged nodes from the old tree.
@@ -174,6 +296,18 @@ function diffTokenTree(oldTree, newTree) {
         token: newTree.token,
         children: [],
     };
+    // Carry forward the rendered-HTML cache for leaf tokens delegated to the
+    // markdown-it renderer. Skip when the underlying token content, attrs, or
+    // info changed (info is the fence's language string and drives the rendered
+    // output for plugins like markdown-it-mermaid / syntax highlighters).
+    if (oldTree.cachedHtml !== undefined &&
+        typeof newTree.token.type === "string" &&
+        PLUGIN_DELEGABLE_TOKEN_TYPES.has(newTree.token.type) &&
+        oldTree.token.content === newTree.token.content &&
+        oldTree.token.info === newTree.token.info &&
+        attrsEqual(oldTree.token.attrs ?? undefined, newTree.token.attrs ?? undefined)) {
+        merged.cachedHtml = oldTree.cachedHtml;
+    }
     // Create lookup map of old children by key for efficient comparison
     const oldChildrenByKey = new Map(oldTree.children.map((child) => [child.key, child]));
     // Process each new child, reusing old ones where possible
@@ -191,16 +325,17 @@ function diffTokenTree(oldTree, newTree) {
     return merged;
 }
 /**
- * Converts markdown into a tree with keys on it for Lit.
+ * Converts markdown into a tree with keys on it for Lit. The returned `md` is the
+ * (cached) markdown-it instance keyed by `markdownItPlugins` identity and the
+ * `removeHtml` flag (html-enabled vs html-neutralizing variant).
  */
-function markdownToTokenTree(markdown, lastTree, allowHtml = true) {
-    // Parse markdown into flat token array
-    const tokens = markdownToMarkdownItTokens(markdown, allowHtml);
-    // Build hierarchical tree structure
-    const tree = buildTokenTree(tokens);
-    // Optimize by reusing unchanged parts of previous tree
-    return diffTokenTree(lastTree, tree);
+function markdownToTokenTree(markdown, lastTree, opts = {}) {
+    const removeHtml = opts.removeHtml ?? false;
+    const md = getMarkdownIt(opts.markdownItPlugins, removeHtml);
+    const tokens = parseMarkdown(markdown, md, removeHtml);
+    const tree = diffTokenTree(lastTree, buildTokenTree(tokens));
+    return { tree, md };
 }
 
-export { buildTokenTree, diffTokenTree, markdownToMarkdownItTokens, markdownToTokenTree };
+export { PLUGIN_DELEGABLE_TOKEN_TYPES, buildTokenTree, diffTokenTree, getMarkdownIt, getPluginOverriddenRules, markdownToTokenTree };
 //# sourceMappingURL=markdown-token-tree.js.map

package/es/components/markdown/src/markdown-token-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-token-tree.js","sources":["../../../../src/components/markdown/src/markdown-token-tree.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown-token-tree.js","sources":["../../../../src/components/markdown/src/markdown-token-tree.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/es/components/markdown/src/markdown.d.ts

@@ -1,6 +1,33 @@
 import { LitElement, PropertyValues, TemplateResult } from "lit";
+import { type MarkdownItPlugin } from "./markdown-token-tree.js";
+import { type MarkdownCustomRenderers } from "./markdown-renderer.js";
 /**
- * Markdown component
+ * Renders markdown as Carbon-styled DOM. Streaming-friendly: incremental updates reparse the markdown source into a `TokenTree`, diff it against the prior tree to reuse stable subtrees, then walk it into a Lit `TemplateResult` — Lit's `repeat` directive keys off the diffed nodes so unchanged DOM stays put.
+ *
+ * ### Lifecycle
+ *
+ * 1. A property setter (or a light-DOM mutation) lands. `willUpdate` decides whether the change requires a reparse (`markdown`, `removeHTML`, `markdownItPlugins`) or only a re-render (translated strings, `streaming`, `sanitizeHTML`, `customRenderers`).
+ * 2. `scheduleRender` throttles bursts to 100ms (leading + trailing).
+ * 3. `renderMarkdown` parses (if needed) via {@link markdownToTokenTree}, then calls {@link renderMarkdownTree} to produce both a `TemplateResult` and a batch of {@link MarkdownRendererSlotDescriptor} records.
+ * 4. After Lit commits, `updated()` runs `reconcileCustomRendererHosts` — that is where consumer-supplied `customRenderers` callbacks fire and plugin-fallback HTML is adopted into light-DOM slot hosts.
+ *
+ * ### Extensibility
+ *
+ * - {@link markdownItPlugins} runs after the built-in markdown-it plugins (markdown-it-attrs, highlight, task-lists). A new array identity rebuilds the markdown-it instance and forces a full reparse. Tokens introduced by a plugin that the native dispatch can't handle — either an unknown tag, or a plugin-overridden rule on a curated allow-list of leaf tokens — route through `md.renderer.render()` via `./utils/plugin-fallback.ts` and surface as `pluginFallback` descriptors. Their rendered HTML is adopted into a light-DOM slot host so consumer-supplied CSS (e.g. a KaTeX stylesheet on the host page) reaches it.
+ * - {@link customRenderers} overrides per-element rendering for `table` and `codeBlock`. The renderer emits a named `<slot>` placeholder; the reconciler invokes the consumer's callback with the parsed data and appends the returned `HTMLElement` as a `<div slot="…">` light-DOM child. Returning the same element reference across renders avoids DOM churn.
+ *
+ * ### Light-DOM source adoption
+ *
+ * When the `markdown` property has never been set explicitly, the element treats its light-DOM text content as the initial source and watches for further mutations via a `MutationObserver`. Setting the property explicitly stops the observer — the property is then the authoritative source.
+ *
+ * ### Related files
+ *
+ * - `./markdown-token-tree.ts` — markdown-it parse + tree builder + streaming-aware diff (with `cachedHtml` carry-forward for plugin-delegated tokens).
+ * - `./markdown-renderer.ts` — `TokenTree` → Lit `TemplateResult`, plus descriptor collection.
+ * - `./markdown-renderer-types.ts` — public ({@link MarkdownCustomRenderers}) and internal ({@link MarkdownRendererSlotDescriptor}, `RenderTokenTreeOptions`) contracts.
+ * - `./utils/plugin-fallback.ts` — delegation to `md.renderer.render()` for plugin-introduced tokens.
+ * - `./utils/streaming-table.ts` — heuristics that hold a streaming table in a skeleton "loading" state until its tail stabilizes.
+ *
  * @element cds-aichat-markdown
  */
 declare class CDSAIChatMarkdown extends LitElement {
@@ -61,6 +88,26 @@ declare class CDSAIChatMarkdown extends LitElement {
         end: number;
         count: number;
     }) => string;
+    /**
+     * Markdown-it plugins applied after the built-in plugins
+     * (markdown-it-attrs, markdown-it-highlight, markdown-it-task-lists).
+     * Changes force a reparse. Memoize this array — a new reference each render
+     * rebuilds the markdown-it instance.
+     */
+    markdownItPlugins?: MarkdownItPlugin[];
+    /**
+     * Per-element render overrides. For each `kind` whose callback is provided,
+     * the markdown element emits a named `<slot>` placeholder in its shadow
+     * DOM, then — after each render — invokes the callback with the parsed
+     * data and adopts the returned `HTMLElement` as a `<div slot="…">`
+     * light-DOM child of this element. Return `null` to fall back to the
+     * default Carbon rendering. Returning the same element reference across
+     * renders avoids DOM churn.
+     *
+     * The consumer's returned element lives in this element's light DOM, not
+     * in its shadow root, so external CSS applies normally.
+     */
+    customRenderers?: MarkdownCustomRenderers;
     private hasRenderedStreamingTableLoadingFrame;
     private stagedStreamingTokenTree;
     private isStreamingTableLoadingMode;
@@ -72,6 +119,7 @@ declare class CDSAIChatMarkdown extends LitElement {
     private stopObservingLightDom;
     protected willUpdate(changed: PropertyValues<this>): void;
     protected getUpdateComplete(): Promise<boolean>;
+    protected updated(changed: PropertyValues<this>): void;
     protected render(): TemplateResult<1>;
 }
 declare global {