@fuzdev/fuz_ui 0.203.1 → 0.205.0

package/src/lib/mdz_stream_state.svelte.ts

@@ -1,387 +0,0 @@
-/**
- * Reactive state for the mdz streaming renderer.
- *
- * Maintains a reactive tree of `MdzStreamNode` objects that Svelte 5 can
- * efficiently update. Opcodes from `MdzStreamParser` are applied via
- * `apply()` or `apply_batch()`, mutating the tree in place.
- *
- * @module
- */
-
-import {DEV} from 'esm-env';
-
-import type {MdzNodeId, MdzNodeType, MdzOpcode} from './mdz_opcodes.js';
-
-/**
- * A reactive node in the stream renderer tree.
- * Fields are `$state` so Svelte re-renders only what changes.
- */
-export class MdzStreamNode {
-	id: MdzNodeId;
-	type: MdzNodeType;
-	content: string = $state('');
-	children: Array<MdzStreamNode> = $state([]);
-	// metadata
-	level?: number;
-	reference?: string = $state();
-	link_type?: string = $state();
-	name?: string;
-	lang?: string | null;
-	heading_id?: string = $state();
-
-	constructor(id: MdzNodeId, type: MdzNodeType) {
-		this.id = id;
-		this.type = type;
-	}
-}
-
-/**
- * Reactive state manager for streaming mdz content.
- * Apply opcodes to incrementally build and update the render tree.
- */
-export class MdzStreamState {
-	root: Array<MdzStreamNode> = $state([]);
-
-	/** Node lookup by ID. */
-	#nodes = new Map<MdzNodeId, MdzStreamNode>();
-
-	/** Parent tracking for re-parenting during revert. */
-	#parents = new Map<MdzNodeId, MdzNodeId | null>();
-
-	/** Stack of open container IDs (for knowing current parent). */
-	#stack: Array<MdzNodeId> = [];
-
-	/**
-	 * Register a new node and attach it to its current parent (innermost open
-	 * container, or root). Shared by `open`, `text`, and `void` paths.
-	 */
-	#attach(node: MdzStreamNode): void {
-		this.#nodes.set(node.id, node);
-		const parent_id = this.#stack.length > 0 ? this.#stack[this.#stack.length - 1]! : null;
-		this.#parents.set(node.id, parent_id);
-		if (parent_id !== null) {
-			const parent = this.#nodes.get(parent_id);
-			if (DEV && !parent) {
-				throw new Error(`MdzStreamState: parent id ${parent_id} on stack but missing from nodes`);
-			}
-			if (parent) parent.children.push(node);
-		} else {
-			this.root.push(node);
-		}
-	}
-
-	/**
-	 * Apply a single opcode.
-	 */
-	apply(opcode: MdzOpcode): void {
-		switch (opcode.type) {
-			case 'open': {
-				if (DEV && this.#nodes.has(opcode.id)) {
-					throw new Error(
-						`MdzStreamState: duplicate open for id ${opcode.id} (node_type '${opcode.node_type}')`,
-					);
-				}
-				const node = new MdzStreamNode(opcode.id, opcode.node_type);
-				if (opcode.level !== undefined) node.level = opcode.level;
-				if (opcode.name !== undefined) node.name = opcode.name;
-				if (opcode.lang !== undefined) node.lang = opcode.lang;
-				this.#attach(node);
-				this.#stack.push(opcode.id);
-				break;
-			}
-
-			case 'close': {
-				if (DEV) {
-					if (!this.#nodes.has(opcode.id)) {
-						throw new Error(`MdzStreamState: close for unknown id ${opcode.id}`);
-					}
-					if (!this.#stack.includes(opcode.id)) {
-						throw new Error(`MdzStreamState: close for id ${opcode.id} which is not on the stack`);
-					}
-				}
-				const node = this.#nodes.get(opcode.id);
-				if (node) {
-					if (opcode.discard) {
-						// drop the node and its descendants from its parent's children
-						const parent_id = this.#parents.get(opcode.id);
-						const parent_children =
-							parent_id !== null && parent_id !== undefined
-								? this.#nodes.get(parent_id)?.children
-								: this.root;
-						if (parent_children) {
-							const idx = parent_children.indexOf(node);
-							if (idx !== -1) parent_children.splice(idx, 1);
-						}
-					} else {
-						// apply deferred metadata
-						if (opcode.reference !== undefined) node.reference = opcode.reference;
-						if (opcode.link_type !== undefined) node.link_type = opcode.link_type;
-						if (opcode.heading_id !== undefined) node.heading_id = opcode.heading_id;
-						// Code/Codeblock: collapse text children into `content` so renderers
-						// can read it directly without walking children every render.
-						if (node.type === 'Code' || node.type === 'Codeblock') {
-							let content = '';
-							for (const child of node.children) content += child.content;
-							node.content = content;
-						}
-					}
-				}
-				// pop from stack
-				const idx = this.#stack.lastIndexOf(opcode.id);
-				if (idx !== -1) this.#stack.splice(idx, 1);
-				// cleanup: closed nodes have no further opcode interactions.
-				// children are retained in the render tree via children arrays
-				// (discarded nodes' subtrees also need full cleanup, which the
-				// traversal in `#cleanup_node` already handles).
-				this.#cleanup_node(opcode.id);
-				break;
-			}
-
-			case 'text': {
-				if (DEV && this.#nodes.has(opcode.id)) {
-					throw new Error(
-						`MdzStreamState: duplicate text for id ${opcode.id} (text_type '${opcode.text_type}')`,
-					);
-				}
-				const node = new MdzStreamNode(opcode.id, opcode.text_type);
-				node.content = opcode.content;
-				this.#attach(node);
-				break;
-			}
-
-			case 'append_text': {
-				if (DEV && !this.#nodes.has(opcode.id)) {
-					throw new Error(`MdzStreamState: append_text for unknown id ${opcode.id}`);
-				}
-				const node = this.#nodes.get(opcode.id);
-				if (node) {
-					node.content += opcode.content;
-				}
-				break;
-			}
-
-			case 'trim_text': {
-				if (DEV && !this.#nodes.has(opcode.id)) {
-					throw new Error(`MdzStreamState: trim_text for unknown id ${opcode.id}`);
-				}
-				const node = this.#nodes.get(opcode.id);
-				if (node) {
-					node.content = node.content.slice(0, node.content.length - opcode.count);
-					if (node.content.length === 0) {
-						const parent_id = this.#parents.get(opcode.id);
-						const parent_children =
-							parent_id !== null && parent_id !== undefined
-								? this.#nodes.get(parent_id)?.children
-								: this.root;
-						if (parent_children) {
-							const idx = parent_children.indexOf(node);
-							if (idx !== -1) parent_children.splice(idx, 1);
-						}
-						this.#nodes.delete(opcode.id);
-						this.#parents.delete(opcode.id);
-					}
-				}
-				break;
-			}
-
-			case 'void': {
-				if (DEV && this.#nodes.has(opcode.id)) {
-					throw new Error(
-						`MdzStreamState: duplicate void for id ${opcode.id} (node_type '${opcode.node_type}')`,
-					);
-				}
-				const node = new MdzStreamNode(opcode.id, opcode.node_type);
-				this.#attach(node);
-				break;
-			}
-
-			case 'revert': {
-				if (DEV) {
-					if (!this.#nodes.has(opcode.id)) {
-						throw new Error(`MdzStreamState: revert for unknown id ${opcode.id}`);
-					}
-					if (!this.#stack.includes(opcode.id)) {
-						throw new Error(`MdzStreamState: revert for id ${opcode.id} which is not on the stack`);
-					}
-				}
-				const node = this.#nodes.get(opcode.id);
-				if (!node) break;
-
-				const parent_id = this.#parents.get(opcode.id);
-				const parent_children =
-					parent_id !== null && parent_id !== undefined
-						? this.#nodes.get(parent_id)?.children
-						: this.root;
-
-				if (!parent_children) {
-					if (DEV) {
-						throw new Error(
-							`MdzStreamState: revert for id ${opcode.id} but parent has no children array`,
-						);
-					}
-					break;
-				}
-
-				// find the node in parent's children
-				let node_idx = -1;
-				for (let i = 0; i < parent_children.length; i++) {
-					if (parent_children[i]!.id === opcode.id) {
-						node_idx = i;
-						break;
-					}
-				}
-				if (node_idx === -1) {
-					if (DEV) {
-						throw new Error(
-							`MdzStreamState: revert for id ${opcode.id} but node not found in parent's children`,
-						);
-					}
-					break;
-				}
-
-				// collect replacement content: literal delimiter text + re-parented children
-				const replacement_nodes: Array<MdzStreamNode> = [];
-				if (opcode.replacement_text) {
-					const text_node = new MdzStreamNode(opcode.id, 'Text');
-					text_node.content = opcode.replacement_text;
-					replacement_nodes.push(text_node);
-				}
-				for (const child of node.children) {
-					replacement_nodes.push(child);
-				}
-
-				if (opcode.wrap_node_type != null && opcode.wrap_id != null) {
-					if (DEV && this.#nodes.has(opcode.wrap_id)) {
-						throw new Error(
-							`MdzStreamState: revert wrap_id ${opcode.wrap_id} already exists in nodes`,
-						);
-					}
-					// block-level revert: wrap content in a new container and push onto stack
-					const wrapper = new MdzStreamNode(opcode.wrap_id, opcode.wrap_node_type);
-					for (const rn of replacement_nodes) {
-						wrapper.children.push(rn);
-					}
-					for (const child of node.children) {
-						this.#parents.set(child.id, opcode.wrap_id);
-					}
-					this.#nodes.set(opcode.wrap_id, wrapper);
-					this.#parents.set(opcode.wrap_id, parent_id ?? null);
-					parent_children.splice(node_idx, 1, wrapper);
-					this.#stack.push(opcode.wrap_id);
-				} else {
-					// inline revert: re-parent directly to grandparent
-					for (const child of node.children) {
-						this.#parents.set(child.id, parent_id ?? null);
-					}
-					parent_children.splice(node_idx, 1, ...replacement_nodes);
-				}
-
-				// remove reverted node from stack
-				const stack_idx = this.#stack.lastIndexOf(opcode.id);
-				if (stack_idx !== -1) this.#stack.splice(stack_idx, 1);
-
-				// cleanup
-				this.#nodes.delete(opcode.id);
-				this.#parents.delete(opcode.id);
-				break;
-			}
-
-			case 'wrap': {
-				if (DEV) {
-					if (!this.#nodes.has(opcode.target_id)) {
-						throw new Error(`MdzStreamState: wrap target_id ${opcode.target_id} not in nodes`);
-					}
-					if (this.#nodes.has(opcode.id)) {
-						throw new Error(`MdzStreamState: wrap id ${opcode.id} already exists in nodes`);
-					}
-				}
-				const target = this.#nodes.get(opcode.target_id);
-				if (!target) break;
-
-				const parent_id = this.#parents.get(opcode.target_id);
-				const parent_children =
-					parent_id !== null && parent_id !== undefined
-						? this.#nodes.get(parent_id)?.children
-						: this.root;
-
-				if (!parent_children) break;
-
-				// find target in parent's children
-				let target_idx = -1;
-				for (let i = 0; i < parent_children.length; i++) {
-					if (parent_children[i]!.id === opcode.target_id) {
-						target_idx = i;
-						break;
-					}
-				}
-				if (target_idx === -1) break;
-
-				// handle trailing punctuation trim
-				let trimmed_node: MdzStreamNode | null = null;
-				if (opcode.trim_end && opcode.trim_end > 0 && opcode.trim_id != null) {
-					const trimmed_content = target.content.slice(target.content.length - opcode.trim_end);
-					target.content = target.content.slice(0, target.content.length - opcode.trim_end);
-					trimmed_node = new MdzStreamNode(opcode.trim_id, 'Text');
-					trimmed_node.content = trimmed_content;
-					this.#nodes.set(opcode.trim_id, trimmed_node);
-					this.#parents.set(opcode.trim_id, parent_id ?? null);
-				}
-
-				// create Link wrapper containing target
-				const link = new MdzStreamNode(opcode.id, opcode.node_type);
-				link.reference = opcode.reference;
-				link.link_type = opcode.link_type;
-				link.children.push(target);
-				this.#nodes.set(opcode.id, link);
-				this.#parents.set(opcode.id, parent_id ?? null);
-				this.#parents.set(opcode.target_id, opcode.id);
-
-				// replace target with [Link, trimmed?] in parent's children
-				if (trimmed_node) {
-					parent_children.splice(target_idx, 1, link, trimmed_node);
-				} else {
-					parent_children[target_idx] = link;
-				}
-
-				// cleanup: Link is complete (no close opcode coming).
-				// trim_id (if any) stays in maps — cleaned when parent closes.
-				this.#cleanup_node(opcode.id);
-				break;
-			}
-		}
-	}
-
-	/**
-	 * Remove a node and its descendants from the lookup maps. Iterative to avoid
-	 * stack overflow on deep trees.
-	 *
-	 * Parser invariant: once a container closes, no future opcode targets that
-	 * subtree (no `append_text` to a closed Text, no nested `wrap`/`revert`).
-	 * Children stay reachable via `parent.children` arrays — only the lookup
-	 * maps are pruned. If this invariant is violated, the misbehaving opcode
-	 * triggers a DEV throw in `apply()` and silently no-ops in production.
-	 */
-	#cleanup_node(id: MdzNodeId): void {
-		const queue: Array<MdzNodeId> = [id];
-		while (queue.length > 0) {
-			const current_id = queue.pop()!;
-			const node = this.#nodes.get(current_id);
-			if (node) {
-				for (const child of node.children) {
-					queue.push(child.id);
-				}
-			}
-			this.#nodes.delete(current_id);
-			this.#parents.delete(current_id);
-		}
-	}
-
-	/**
-	 * Apply a batch of opcodes.
-	 */
-	apply_batch(opcodes: Array<MdzOpcode>): void {
-		for (const op of opcodes) {
-			this.apply(op);
-		}
-	}
-}

package/src/lib/mdz_to_svelte.ts

@@ -1,141 +0,0 @@
-/**
- * Converts parsed `MdzNode` arrays to Svelte markup strings.
- *
- * Used by the `svelte_preprocess_mdz` preprocessor to expand static `<Mdz content="...">` usages
- * into pre-rendered Svelte markup at build time. The output for each node type matches what
- * `MdzNodeView.svelte` renders at runtime, so precompiled and runtime rendering are identical.
- *
- * @module
- */
-
-import {UnreachableError} from '@fuzdev/fuz_util/error.js';
-import {escape_svelte_text} from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
-import {escape_js_string} from '@fuzdev/fuz_util/string.js';
-
-import type {MdzNode} from './mdz.js';
-import {resolve_relative_path} from './mdz_helpers.js';
-
-/**
- * Result of converting `MdzNode` arrays to Svelte markup.
- */
-export interface MdzToSvelteResult {
-	/** Generated Svelte markup string. */
-	markup: string;
-
-	/** Required imports: `Map<local_name, {path, kind}>`. */
-	imports: Map<string, {path: string; kind: 'default' | 'named'}>;
-
-	/** Whether content references unconfigured Component or Element tags. */
-	has_unconfigured_tags: boolean;
-}
-
-/**
- * Converts an array of `MdzNode` to a Svelte markup string.
- *
- * Each node type produces output matching what `MdzNodeView.svelte` renders at runtime.
- * Collects required imports and flags unconfigured component/element references.
- *
- * @param nodes - parsed mdz nodes to render
- * @param components - Component name to import path mapping (e.g., `{Alert: '$lib/Alert.svelte'}`)
- *   If content references a component not in this map, `has_unconfigured_tags` is set.
- * @param elements - Allowed HTML element names (e.g., `new Set(['aside', 'details'])`)
- *   If content references an element not in this set, `has_unconfigured_tags` is set.
- * @param base - Base path for resolving relative links (e.g., `'/docs/mdz/'`)
- *   When provided, relative references (`./`, `../`) are resolved to absolute paths
- *   and passed through `resolve()`. Trailing slash recommended.
- */
-export const mdz_to_svelte = (
-	nodes: Array<MdzNode>,
-	components: Record<string, string>,
-	elements: ReadonlySet<string>,
-	base?: string,
-): MdzToSvelteResult => {
-	const imports: Map<string, {path: string; kind: 'default' | 'named'}> = new Map();
-	let has_unconfigured_tags = false;
-
-	const render_nodes = (children: Array<MdzNode>): string => {
-		return children.map((child) => render_node(child)).join('');
-	};
-
-	const render_node = (node: MdzNode): string => {
-		switch (node.type) {
-			case 'Text':
-				return escape_svelte_text(node.content);
-
-			case 'Code':
-				imports.set('DocsLink', {path: '@fuzdev/fuz_ui/DocsLink.svelte', kind: 'default'});
-				return `<DocsLink reference={'${escape_js_string(node.content)}'} />`;
-
-			case 'Codeblock': {
-				imports.set('Code', {path: '@fuzdev/fuz_code/Code.svelte', kind: 'default'});
-				const lang_attr =
-					node.lang === null ? 'lang={null}' : `lang={'${escape_js_string(node.lang)}'}`;
-				return `<Code ${lang_attr} content={'${escape_js_string(node.content)}'} />`;
-			}
-
-			case 'Bold':
-				return `<strong>${render_nodes(node.children)}</strong>`;
-
-			case 'Italic':
-				return `<em>${render_nodes(node.children)}</em>`;
-
-			case 'Strikethrough':
-				return `<s>${render_nodes(node.children)}</s>`;
-
-			case 'Link': {
-				const children_markup = render_nodes(node.children);
-				if (node.link_type === 'internal') {
-					if (node.reference.startsWith('.') && base) {
-						const resolved = resolve_relative_path(node.reference, base);
-						imports.set('resolve', {path: '$app/paths', kind: 'named'});
-						return `<a href={resolve('${escape_js_string(resolved)}')}>${children_markup}</a>`;
-					}
-					if (
-						node.reference.startsWith('#') ||
-						node.reference.startsWith('?') ||
-						node.reference.startsWith('.')
-					) {
-						return `<a href={'${escape_js_string(node.reference)}'}>${children_markup}</a>`;
-					}
-					imports.set('resolve', {path: '$app/paths', kind: 'named'});
-					return `<a href={resolve('${escape_js_string(node.reference)}')}>${children_markup}</a>`;
-				}
-				// External link — matches MdzNodeView: target="_blank" rel="noopener"
-				return `<a href={'${escape_js_string(node.reference)}'} target="_blank" rel="noopener">${children_markup}</a>`;
-			}
-
-			case 'Paragraph':
-				return `<p>${render_nodes(node.children)}</p>`;
-
-			case 'Hr':
-				return '<hr />';
-
-			case 'Heading':
-				return `<h${node.level}>${render_nodes(node.children)}</h${node.level}>`;
-
-			case 'Element': {
-				if (!elements.has(node.name)) {
-					has_unconfigured_tags = true;
-					return '';
-				}
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
-			}
-
-			case 'Component': {
-				const import_path = components[node.name];
-				if (!import_path) {
-					has_unconfigured_tags = true;
-					return '';
-				}
-				imports.set(node.name, {path: import_path, kind: 'default'});
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
-			}
-
-			default:
-				throw new UnreachableError(node);
-		}
-	};
-
-	const markup = render_nodes(nodes);
-	return {markup, imports, has_unconfigured_tags};
-};