@fuzdev/fuz_ui 0.185.1 → 0.186.0

package/src/lib/mdz_to_svelte.ts

@@ -12,7 +12,7 @@ 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 {type MdzNode, resolve_relative_path} from './mdz.js';
 
 /**
  * Result of converting `MdzNode` arrays to Svelte markup.
@@ -39,11 +39,15 @@ export interface MdzToSvelteResult {
  *   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;
@@ -80,7 +84,16 @@ export const mdz_to_svelte = (
 			case 'Link': {
 				const children_markup = render_nodes(node.children);
 				if (node.link_type === 'internal') {
-					if (node.reference.startsWith('#') || node.reference.startsWith('?')) {
+					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'});

package/src/lib/mdz_token_parser.ts

@@ -0,0 +1,460 @@
+/**
+ * mdz token parser — consumes a `MdzToken[]` stream to build the `MdzNode[]` AST.
+ *
+ * Phase 2 of the two-phase lexer+parser alternative to the single-pass parser
+ * in `mdz.ts`. Phase 1 (lexer) is in `mdz_lexer.ts`.
+ *
+ * @module
+ */
+
+import type {
+	MdzNode,
+	MdzTextNode,
+	MdzBoldNode,
+	MdzItalicNode,
+	MdzStrikethroughNode,
+	MdzLinkNode,
+	MdzHeadingNode,
+	MdzElementNode,
+	MdzComponentNode,
+} from './mdz.js';
+import {extract_single_tag} from './mdz_helpers.js';
+import {
+	MdzLexer,
+	type MdzToken,
+	type MdzTokenHeadingStart,
+	type MdzTokenBoldOpen,
+	type MdzTokenItalicOpen,
+	type MdzTokenStrikethroughOpen,
+	type MdzTokenLinkTextOpen,
+	type MdzTokenLinkRef,
+	type MdzTokenAutolink,
+	type MdzTokenTagOpen,
+	type MdzTokenTagSelfClose,
+} from './mdz_lexer.js';
+
+/**
+ * Parses text to an array of `MdzNode` using a two-phase lexer+parser approach.
+ */
+export const mdz_parse_lexer = (text: string): Array<MdzNode> => {
+	const tokens = new MdzLexer(text).tokenize();
+	return new MdzTokenParser(tokens).parse();
+};
+
+class MdzTokenParser {
+	#tokens: Array<MdzToken>;
+	#index: number = 0;
+
+	constructor(tokens: Array<MdzToken>) {
+		this.#tokens = tokens;
+	}
+
+	parse(): Array<MdzNode> {
+		const root_nodes: Array<MdzNode> = [];
+		const paragraph_children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const token = this.#tokens[this.#index]!;
+
+			// Block-level tokens
+			if (token.type === 'heading_start') {
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				root_nodes.push(this.#parse_heading());
+				continue;
+			}
+
+			if (token.type === 'hr') {
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				root_nodes.push({type: 'Hr', start: token.start, end: token.end});
+				this.#index++;
+				continue;
+			}
+
+			if (token.type === 'codeblock') {
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				root_nodes.push({
+					type: 'Codeblock',
+					lang: token.lang,
+					content: token.content,
+					start: token.start,
+					end: token.end,
+				});
+				this.#index++;
+				continue;
+			}
+
+			if (token.type === 'paragraph_break') {
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				this.#index++;
+				continue;
+			}
+
+			// Inline tokens → paragraph children
+			const node = this.#parse_inline();
+			if (node) paragraph_children.push(node);
+		}
+
+		// Flush remaining content
+		const final_paragraph = this.#flush_paragraph(paragraph_children, true);
+		if (final_paragraph) root_nodes.push(final_paragraph);
+
+		return root_nodes;
+	}
+
+	#parse_heading(): MdzHeadingNode {
+		const token = this.#tokens[this.#index]! as MdzTokenHeadingStart;
+		const start = token.start;
+		const level = token.level;
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		// Collect inline nodes until heading_end marker
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'heading_end') {
+				this.#index++; // consume the marker
+				break;
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		const end = children.length > 0 ? children[children.length - 1]!.end : start + level + 1;
+
+		return {type: 'Heading', level, children, start, end};
+	}
+
+	#parse_inline(): MdzNode | null {
+		if (this.#index >= this.#tokens.length) return null;
+
+		const token = this.#tokens[this.#index]!;
+
+		switch (token.type) {
+			case 'text':
+				this.#index++;
+				return {type: 'Text', content: token.content, start: token.start, end: token.end};
+
+			case 'code':
+				this.#index++;
+				return {type: 'Code', content: token.content, start: token.start, end: token.end};
+
+			case 'bold_open':
+				return this.#parse_bold();
+
+			case 'italic_open':
+				return this.#parse_italic();
+
+			case 'strikethrough_open':
+				return this.#parse_strikethrough();
+
+			case 'link_text_open':
+				return this.#parse_link();
+
+			case 'autolink':
+				return this.#parse_autolink();
+
+			case 'tag_open':
+				return this.#parse_tag_node();
+
+			case 'tag_self_close':
+				return this.#parse_self_close_tag();
+
+			// Orphaned close tokens - treat as text
+			case 'bold_close':
+				this.#index++;
+				return {type: 'Text', content: '**', start: token.start, end: token.end};
+
+			case 'italic_close':
+				this.#index++;
+				return {type: 'Text', content: '_', start: token.start, end: token.end};
+
+			case 'strikethrough_close':
+				this.#index++;
+				return {type: 'Text', content: '~', start: token.start, end: token.end};
+
+			case 'link_text_close':
+				this.#index++;
+				return {type: 'Text', content: ']', start: token.start, end: token.end};
+
+			case 'link_ref':
+				this.#index++;
+				return {
+					type: 'Text',
+					content: `(${token.reference})`,
+					start: token.start,
+					end: token.end,
+				};
+
+			case 'tag_close':
+				this.#index++;
+				return {
+					type: 'Text',
+					content: `</${token.name}>`,
+					start: token.start,
+					end: token.end,
+				};
+
+			default:
+				this.#index++;
+				return null;
+		}
+	}
+
+	#parse_bold(): MdzBoldNode | MdzTextNode {
+		const token = this.#tokens[this.#index]! as MdzTokenBoldOpen;
+		const start = token.start;
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'bold_close') {
+				this.#index++;
+				return {type: 'Bold', children, start, end: t.end};
+			}
+			if (
+				t.type === 'paragraph_break' ||
+				t.type === 'heading_start' ||
+				t.type === 'hr' ||
+				t.type === 'codeblock'
+			) {
+				break;
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		// Unclosed - treat as text
+		return {type: 'Text', content: '**', start, end: start + 2};
+	}
+
+	#parse_italic(): MdzItalicNode | MdzTextNode {
+		const token = this.#tokens[this.#index]! as MdzTokenItalicOpen;
+		const start = token.start;
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'italic_close') {
+				this.#index++;
+				return {type: 'Italic', children, start, end: t.end};
+			}
+			if (
+				t.type === 'paragraph_break' ||
+				t.type === 'heading_start' ||
+				t.type === 'hr' ||
+				t.type === 'codeblock'
+			) {
+				break;
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		return {type: 'Text', content: '_', start, end: start + 1};
+	}
+
+	#parse_strikethrough(): MdzStrikethroughNode | MdzTextNode {
+		const token = this.#tokens[this.#index]! as MdzTokenStrikethroughOpen;
+		const start = token.start;
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'strikethrough_close') {
+				this.#index++;
+				return {type: 'Strikethrough', children, start, end: t.end};
+			}
+			if (
+				t.type === 'paragraph_break' ||
+				t.type === 'heading_start' ||
+				t.type === 'hr' ||
+				t.type === 'codeblock'
+			) {
+				break;
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		return {type: 'Text', content: '~', start, end: start + 1};
+	}
+
+	#parse_link(): MdzLinkNode | MdzTextNode {
+		const open_token = this.#tokens[this.#index]! as MdzTokenLinkTextOpen;
+		const start = open_token.start;
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'link_text_close') {
+				this.#index++;
+
+				// Expect link_ref next
+				if (this.#index < this.#tokens.length && this.#tokens[this.#index]!.type === 'link_ref') {
+					const ref_token = this.#tokens[this.#index]! as MdzTokenLinkRef;
+					this.#index++;
+					return {
+						type: 'Link',
+						reference: ref_token.reference,
+						children,
+						link_type: ref_token.link_type,
+						start,
+						end: ref_token.end,
+					};
+				}
+
+				// No link_ref - treat as text
+				return {type: 'Text', content: '[', start, end: start + 1};
+			}
+			if (
+				t.type === 'paragraph_break' ||
+				t.type === 'heading_start' ||
+				t.type === 'hr' ||
+				t.type === 'codeblock'
+			) {
+				break;
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		return {type: 'Text', content: '[', start, end: start + 1};
+	}
+
+	#parse_autolink(): MdzLinkNode {
+		const token = this.#tokens[this.#index]! as MdzTokenAutolink;
+		this.#index++;
+		return {
+			type: 'Link',
+			reference: token.reference,
+			children: [{type: 'Text', content: token.reference, start: token.start, end: token.end}],
+			link_type: token.link_type,
+			start: token.start,
+			end: token.end,
+		};
+	}
+
+	#parse_tag_node(): MdzElementNode | MdzComponentNode | MdzTextNode {
+		const open_token = this.#tokens[this.#index]! as MdzTokenTagOpen;
+		const start = open_token.start;
+		const tag_name = open_token.name;
+		const node_type: 'Component' | 'Element' = open_token.is_component ? 'Component' : 'Element';
+		this.#index++;
+
+		const children: Array<MdzNode> = [];
+
+		while (this.#index < this.#tokens.length) {
+			const t = this.#tokens[this.#index]!;
+			if (t.type === 'tag_close' && t.name === tag_name) {
+				this.#index++;
+				return {type: node_type, name: tag_name, children, start, end: t.end};
+			}
+			const node = this.#parse_inline();
+			if (node) children.push(node);
+		}
+
+		// Unclosed tag
+		return {type: 'Text', content: '<', start, end: start + 1};
+	}
+
+	#parse_self_close_tag(): MdzElementNode | MdzComponentNode {
+		const token = this.#tokens[this.#index]! as MdzTokenTagSelfClose;
+		const node_type: 'Component' | 'Element' = token.is_component ? 'Component' : 'Element';
+		this.#index++;
+		return {type: node_type, name: token.name, children: [], start: token.start, end: token.end};
+	}
+
+	// -- Paragraph flushing --
+
+	#flush_paragraph(paragraph_children: Array<MdzNode>, trim_trailing = false): MdzNode | null {
+		if (paragraph_children.length === 0) return null;
+
+		if (trim_trailing) {
+			// Trim trailing newlines from last text node
+			const last = paragraph_children[paragraph_children.length - 1]!;
+			if (last.type === 'Text') {
+				const trimmed = last.content.replace(/\n+$/, '');
+				if (trimmed) {
+					last.content = trimmed;
+					last.end = last.start + trimmed.length;
+				} else {
+					paragraph_children.pop();
+				}
+			}
+
+			// Skip whitespace-only paragraphs
+			const has_content = paragraph_children.some(
+				(n) => n.type !== 'Text' || n.content.trim().length > 0,
+			);
+			if (!has_content) {
+				paragraph_children.length = 0;
+				return null;
+			}
+		}
+
+		// Single tag extraction (MDX convention)
+		const single_tag = extract_single_tag(paragraph_children);
+		if (single_tag) {
+			paragraph_children.length = 0;
+			return single_tag;
+		}
+
+		// Merge adjacent text nodes
+		const merged = this.#merge_adjacent_text(paragraph_children.slice());
+		paragraph_children.length = 0;
+
+		if (merged.length === 0) return null;
+
+		return {
+			type: 'Paragraph',
+			children: merged,
+			start: merged[0]!.start,
+			end: merged[merged.length - 1]!.end,
+		};
+	}
+
+	#merge_adjacent_text(nodes: Array<MdzNode>): Array<MdzNode> {
+		if (nodes.length <= 1) return nodes;
+
+		const merged: Array<MdzNode> = [];
+		let pending_text: MdzTextNode | null = null;
+
+		for (const node of nodes) {
+			if (node.type === 'Text') {
+				if (pending_text) {
+					pending_text = {
+						type: 'Text',
+						content: pending_text.content + node.content,
+						start: pending_text.start,
+						end: node.end,
+					};
+				} else {
+					pending_text = {...node} as MdzTextNode;
+				}
+			} else {
+				if (pending_text) {
+					merged.push(pending_text);
+					pending_text = null;
+				}
+				merged.push(node);
+			}
+		}
+
+		if (pending_text) merged.push(pending_text);
+
+		return merged;
+	}
+}

package/src/lib/svelte_preprocess_mdz.ts

@@ -305,6 +305,22 @@ const find_mdz_usages = (
 			const content_attr = find_attribute(node, 'content');
 			if (!content_attr) return;
 
+			// Extract optional static base prop for relative path resolution.
+			// If base is present but dynamic, skip precompilation entirely —
+			// MdzPrecompiled doesn't resolve relative paths at runtime,
+			// so precompiling with unresolved relative links would be wrong.
+			const base_attr = find_attribute(node, 'base');
+			let base: string | undefined;
+			if (base_attr) {
+				const base_value = extract_static_string(base_attr.value, context.bindings);
+				if (base_value === null) return; // dynamic base — fall back to runtime
+				base = base_value;
+			}
+
+			// Collect attributes to exclude from precompiled output
+			const exclude_attrs: Set<AST.Attribute> = new Set([content_attr]);
+			if (base_attr) exclude_attrs.add(base_attr);
+
 			// Extract static string value
 			const content_value = extract_static_string(content_attr.value, context.bindings);
 			if (content_value !== null) {
@@ -312,7 +328,7 @@ const find_mdz_usages = (
 				let result;
 				try {
 					const nodes = mdz_parse(content_value);
-					result = mdz_to_svelte(nodes, context.components, context.elements);
+					result = mdz_to_svelte(nodes, context.components, context.elements, base);
 				} catch (error) {
 					handle_preprocess_error(error, '[fuz-mdz]', context.filename, context.on_error);
 					return;
@@ -322,7 +338,7 @@ const find_mdz_usages = (
 				if (result.has_unconfigured_tags) return;
 
 				const consumed = collect_consumed_bindings(content_attr.value, context.bindings);
-				const replacement = build_replacement(node, content_attr, result.markup, context.source);
+				const replacement = build_replacement(node, exclude_attrs, result.markup, context.source);
 				transformed_usages.set(node.name, (transformed_usages.get(node.name) ?? 0) + 1);
 				transformations.push({
 					start: node.start,
@@ -349,7 +365,7 @@ const find_mdz_usages = (
 			try {
 				for (const branch of chain) {
 					const nodes = mdz_parse(branch.value);
-					const result = mdz_to_svelte(nodes, context.components, context.elements);
+					const result = mdz_to_svelte(nodes, context.components, context.elements, base);
 					if (result.has_unconfigured_tags) return;
 					branch_results.push({markup: result.markup, imports: result.imports});
 				}
@@ -373,7 +389,7 @@ const find_mdz_usages = (
 			}
 			children_markup += '{/if}';
 
-			const replacement = build_replacement(node, content_attr, children_markup, context.source);
+			const replacement = build_replacement(node, exclude_attrs, children_markup, context.source);
 
 			// Merge imports from all branches
 			const merged_imports: Map<string, PreprocessImportInfo> = new Map();
@@ -478,14 +494,14 @@ const remove_dead_const_bindings = (
  */
 const build_replacement = (
 	node: AST.Component,
-	content_attr: AST.Attribute,
+	exclude_attrs: ReadonlySet<AST.Attribute>,
 	children_markup: string,
 	source: string,
 ): string => {
-	// Collect source ranges of all attributes EXCEPT content
+	// Collect source ranges of all attributes except excluded ones (content, base when resolved)
 	const other_attr_ranges: Array<{start: number; end: number}> = [];
 	for (const attr of node.attributes) {
-		if (attr === content_attr) continue;
+		if (exclude_attrs.has(attr as AST.Attribute)) continue;
 		other_attr_ranges.push({start: attr.start, end: attr.end});
 	}