@fuzdev/mdz 0.4.0 → 0.5.0

package/src/lib/mdz_opcodes.ts

@@ -12,7 +12,7 @@
  * @module
  */
 
-import type { MdzTableAlign } from './mdz.ts';
+import type { MdzAttribute, MdzTableAlign } from './mdz.ts';
 
 /**
  * Unique monotonic identifier for each node created by the parser.
@@ -66,6 +66,8 @@ export interface MdzOpcodeOpen {
 	level?: 1 | 2 | 3 | 4 | 5 | 6;
 	/** Tag name. Present when `node_type` is `'Element'` or `'Component'`. */
 	name?: string;
+	/** Parsed attributes. Present (possibly empty) when `node_type` is `'Element'` or `'Component'`. */
+	attributes?: Array<MdzAttribute>;
 	/** Language hint. Present when `node_type` is `'Codeblock'`. */
 	lang?: string | null;
 	/** Whether the list is ordered. Present when `node_type` is `'List'`. */

package/src/lib/mdz_opcodes_to_nodes.ts

@@ -20,6 +20,7 @@
 import { DEV } from 'esm-env';
 
 import type {
+	MdzAttribute,
 	MdzNode,
 	MdzNodeText,
 	MdzNodeLink,
@@ -42,6 +43,7 @@ interface StackFrame {
 	// metadata from open opcode
 	level?: number;
 	name?: string;
+	attributes?: Array<MdzAttribute>;
 	lang?: string | null;
 	ordered?: boolean;
 	start_number?: number;
@@ -77,6 +79,7 @@ export const mdz_opcodes_to_nodes = (opcodes: Array<MdzOpcode>): Array<MdzNode>
 					start: op.start,
 					level: op.level,
 					name: op.name,
+					attributes: op.attributes,
 					lang: op.lang,
 					ordered: op.ordered,
 					start_number: op.start_number,
@@ -489,6 +492,7 @@ const build_node = (frame: StackFrame, frame_children: Array<MdzNode>): MdzNode
 			return {
 				type: 'Element',
 				name: frame.name ?? '',
+				attributes: frame.attributes ?? [],
 				children: mdz_merge_adjacent_text(frame_children),
 				start: frame.start,
 				end: frame.end!
@@ -498,6 +502,7 @@ const build_node = (frame: StackFrame, frame_children: Array<MdzNode>): MdzNode
 			return {
 				type: 'Component',
 				name: frame.name ?? '',
+				attributes: frame.attributes ?? [],
 				children: mdz_merge_adjacent_text(frame_children),
 				start: frame.start,
 				end: frame.end!

package/src/lib/mdz_stream_parser_link.ts

@@ -6,8 +6,12 @@
  */
 
 import type { MdzNodeTypeContainer } from './mdz_opcodes.ts';
+import type { MdzAttribute } from './mdz.ts';
 import {
 	A_UPPER,
+	APOSTROPHE,
+	DOUBLE_QUOTE,
+	EQUALS,
 	LEFT_BRACKET,
 	LEFT_PAREN,
 	MAX_INLINE_NESTING_DEPTH,
@@ -211,11 +215,77 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 
 	const name = state.buffer.slice(name_start, i);
 
-	// skip whitespace
-	while (i < state.buffer.length && state.buffer.charCodeAt(i) === SPACE) {
-		i++;
+	// Attribute loop: consume space-separated attributes until `/>` or `>`.
+	// This widens the held-tag-open rescan surface (the TODO above) with the
+	// attribute/value text — still line-bounded, since a newline anywhere aborts
+	// the whole tag (`not_match`). Every buffer-end point holds (`need_more`) so
+	// the same tree is produced regardless of where feeds split. The quoted-value
+	// terminator search reuses `buffer_index_of` (memoized, append-aware) so a
+	// long streamed value doesn't rescan quadratically across held retries,
+	// matching `try_complete_link`.
+	const attributes: Array<MdzAttribute> = [];
+	const seen = new Set<string>();
+	for (;;) {
+		// skip a run of literal spaces only (tabs/newlines are not SPACE)
+		let had_space = false;
+		while (i < state.buffer.length && state.buffer.charCodeAt(i) === SPACE) {
+			i++;
+			had_space = true;
+		}
+		if (i >= state.buffer.length) return 'need_more';
+
+		const c = state.buffer.charCodeAt(i);
+		// `/>` or `>` ends the open tag — break to the existing self-close / commit
+		if (c === SLASH || c === RIGHT_ANGLE) break;
+		// otherwise an attribute name must follow, space-separated from what
+		// precedes it (`<a x="1"y="2">` — `y` abuts the closing quote — reverts)
+		if (!is_letter(c)) return 'not_match';
+		if (!had_space) return 'not_match';
+
+		// collect the attribute name (same grammar as tag names)
+		const attr_start = i;
+		i++; // first char already passed is_letter
+		while (i < state.buffer.length && is_tag_name_char(state.buffer.charCodeAt(i))) {
+			i++;
+		}
+		if (i >= state.buffer.length) return 'need_more'; // mid-name — could still grow
+		const attr_name = state.buffer.slice(attr_start, i);
+		// duplicate names are ambiguous (Svelte compile-errors) → literal tag
+		if (seen.has(attr_name)) return 'not_match';
+		seen.add(attr_name);
+
+		let value: string | true = true; // bare name is boolean `true`
+		if (state.buffer.charCodeAt(i) === EQUALS) {
+			i++; // consume =
+			if (i >= state.buffer.length) return 'need_more'; // nothing after `=` yet
+			// the value must be immediately quoted — no space, no `{`, no unquoted
+			const quote_code = state.buffer.charCodeAt(i);
+			if (quote_code !== DOUBLE_QUOTE && quote_code !== APOSTROPHE) return 'not_match';
+			i++; // consume opening quote
+			const value_start = i;
+			// find the matching quote and the next newline via the memoized,
+			// append-aware search; a `>` inside the value is content, consumed
+			// atomically here so a `</Name>`-shaped substring never reaches
+			// `try_close_tag`
+			const quote_str = quote_code === DOUBLE_QUOTE ? '"' : "'";
+			const q = buffer_index_of(state, quote_str, value_start);
+			const n = buffer_index_of(state, '\n', value_start);
+			if (q !== -1 && (n === -1 || q < n)) {
+				value = state.buffer.slice(value_start, q);
+				i = q + 1; // past the closing quote
+			} else if (n !== -1 && (q === -1 || n < q)) {
+				return 'not_match'; // newline inside the value → literal tag
+			} else {
+				return 'need_more'; // neither found yet — unterminated so far, hold
+			}
+		}
+		attributes.push({
+			name: attr_name,
+			value,
+			start: offset(state, attr_start),
+			end: offset(state, i)
+		});
 	}
-	if (i >= state.buffer.length) return 'need_more';
 
 	// check for self-closing />
 	if (state.buffer.charCodeAt(i) === SLASH && i + 1 >= state.buffer.length) {
@@ -230,7 +300,7 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 		ensure_paragraph(state);
 		const id = alloc_id(state);
 		const tag_start = offset(state, start);
-		emit(state, { type: 'open', id, node_type, start: tag_start, name });
+		emit(state, { type: 'open', id, node_type, start: tag_start, name, attributes });
 		emit(state, { type: 'close', id, end: offset(state, i + 2) });
 		state.active_text_id = null;
 		state.pos = i + 2;
@@ -253,8 +323,8 @@ export const try_tag_open = (state: MdzStreamParserState): TryResult => {
 	ensure_paragraph(state);
 	const id = alloc_id(state);
 	const tag_start = offset(state, start);
-	const delimiter = state.buffer.slice(start, i); // e.g., "<Alert>"
-	emit(state, { type: 'open', id, node_type, start: tag_start, name });
+	const delimiter = state.buffer.slice(start, i); // e.g., "<Alert>" or "<Alert x="1">"
+	emit(state, { type: 'open', id, node_type, start: tag_start, name, attributes });
 	push_stack_entry(state, id, node_type, tag_start, delimiter, name);
 	state.active_text_id = null;
 	state.pos = i;

package/src/lib/mdz_stream_parser_table.ts

@@ -402,7 +402,14 @@ const emit_inline_nodes = (state: MdzStreamParserState, nodes: Array<MdzNode>):
 			case 'Component': {
 				const id = alloc_id(state);
 				const s = offset(state, node.start);
-				emit(state, { type: 'open', id, node_type: node.type, start: s, name: node.name });
+				emit(state, {
+					type: 'open',
+					id,
+					node_type: node.type,
+					start: s,
+					name: node.name,
+					attributes: node.attributes
+				});
 				push_stack_entry(state, id, node.type, s, '', node.name);
 				emit_inline_nodes(state, node.children);
 				pop_stack_entry(state);

package/src/lib/mdz_stream_state.svelte.ts

@@ -11,7 +11,7 @@
 import { DEV } from 'esm-env';
 
 import type { MdzNodeId, MdzNodeType, MdzOpcode } from './mdz_opcodes.ts';
-import type { MdzTableAlign } from './mdz.ts';
+import type { MdzAttribute, MdzTableAlign } from './mdz.ts';
 
 /**
  * A reactive node in the stream renderer tree.
@@ -27,6 +27,8 @@ export class MdzStreamNode {
 	reference?: string = $state();
 	link_type?: 'external' | 'internal' = $state();
 	name?: string;
+	/** Parsed tag attributes (Element/Component nodes); known at open, never mutated, so plain not `$state`. */
+	attributes?: Array<MdzAttribute>;
 	lang?: string | null;
 	heading_id?: string = $state();
 	ordered?: boolean;
@@ -105,6 +107,7 @@ export class MdzStreamState {
 				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.attributes !== undefined) node.attributes = opcode.attributes;
 				if (opcode.lang !== undefined) node.lang = opcode.lang;
 				if (opcode.ordered !== undefined) node.ordered = opcode.ordered;
 				if (opcode.start_number !== undefined) node.start_number = opcode.start_number;

package/src/lib/mdz_to_svelte.ts

@@ -13,7 +13,34 @@ import { escape_svelte_text } from '@fuzdev/fuz_util/svelte_preprocess_helpers.t
 import { escape_js_string } from '@fuzdev/fuz_util/string.ts';
 
 import type { MdzNode, MdzNodeTableRow } from './mdz.ts';
-import { mdz_is_void_element, mdz_classify_link } from './mdz_helpers.ts';
+import type { MdzComponentProps } from './mdz_contexts.ts';
+import {
+	mdz_is_void_element,
+	mdz_classify_link,
+	mdz_filter_element_attributes,
+	mdz_filter_component_attributes,
+	ALLOWED_ELEMENT_ATTRIBUTES
+} from './mdz_helpers.ts';
+
+// emits parsed attributes as Svelte markup, matching the file's `name={'...'}`
+// idiom for string attrs. Booleans emit as `name={true}`, not bare — a bare
+// attribute compiles to `name=""`, while the runtime views spread `true`, which
+// Svelte renders per attribute (`aria-hidden="true"`); the expression form
+// keeps precompiled and runtime output identical. Each entry gets a leading
+// space, so the result splices straight after the tag name.
+/**
+ * A build-time component registry entry: an import path, or an import path
+ * plus the attribute names passed as props (see `MdzComponentProps`).
+ */
+export type MdzComponentImport = string | { path: string; props?: MdzComponentProps };
+
+const format_attributes = (entries: Array<[string, string | true]>): string => {
+	let out = '';
+	for (const [name, value] of entries) {
+		out += value === true ? ` ${name}={true}` : ` ${name}={'${escape_js_string(value)}'}`;
+	}
+	return out;
+};
 
 /**
  * Result of converting `MdzNode` arrays to Svelte markup.
@@ -38,10 +65,13 @@ const component_local_name = (import_path: string): string =>
  */
 export interface MdzToSvelteOptions {
 	/**
-	 * Component name to import path mapping (e.g., `{Alert: '#lib/Alert.svelte'}`).
+	 * Component name to import mapping, mirroring the runtime `MdzComponents`
+	 * registry: a bare import path receives no attributes
+	 * (`{Note: '#lib/Note.svelte'}`), and the config form names the attributes
+	 * passed as props (`{Alert: {path: '#lib/Alert.svelte', props: ['status']}}`).
 	 * If content references a component not in this map, `has_unconfigured_tags` is set.
 	 */
-	components: Record<string, string>;
+	components: Record<string, MdzComponentImport>;
 
 	/**
 	 * Allowed HTML elements (e.g., `{aside: true, details: true}`).
@@ -53,8 +83,9 @@ export interface MdzToSvelteOptions {
 
 	/**
 	 * Base path for resolving relative links (e.g., `'/docs/usage/'`).
-	 * When provided, relative references (`./`, `../`) are resolved to absolute paths
-	 * and passed through `resolve()`. Trailing slash recommended.
+	 * When provided, relative references (`./`, `../`) are resolved against it and,
+	 * like absolute references, passed through `resolve()` in its pathname form.
+	 * Trailing slash recommended.
 	 */
 	base?: string;
 
@@ -140,7 +171,7 @@ export const mdz_to_svelte = (
 				if (link.kind === 'unsafe') return children_markup;
 				if (link.kind === 'resolve') {
 					imports.set('resolve', { path: '$app/paths', kind: 'named' });
-					return `<a href={resolve('${escape_js_string(link.href)}')}>${children_markup}</a>`;
+					return `<a href={resolve('${escape_js_string(link.path)}')}>${children_markup}</a>`;
 				}
 				if (link.kind === 'external') {
 					return `<a href={'${escape_js_string(link.href)}'} target="_blank" rel="noopener">${children_markup}</a>`;
@@ -208,25 +239,38 @@ export const mdz_to_svelte = (
 			}
 
 			case 'Element': {
-				if (elements[node.name] === undefined) {
+				if (elements[node.name] !== true) {
 					has_unconfigured_tags = true;
 					return '';
 				}
+				// filter via the SAME helper the node views use, so precompiled and
+				// runtime output stay identical (its DEV-warn fires at build time too)
+				const attrs_str = format_attributes(
+					Object.entries(
+						mdz_filter_element_attributes(node.name, node.attributes, ALLOWED_ELEMENT_ATTRIBUTES)
+					)
+				);
 				if (mdz_is_void_element(node.name)) {
 					// void elements cannot have content — any parsed children are dropped
-					return `<${node.name} />`;
+					return `<${node.name}${attrs_str} />`;
 				}
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
+				return `<${node.name}${attrs_str}>${render_nodes(node.children)}</${node.name}>`;
 			}
 
 			case 'Component': {
-				const import_path = components[node.name];
-				if (!import_path) {
+				const entry = components[node.name];
+				if (!entry) {
 					has_unconfigured_tags = true;
 					return '';
 				}
-				imports.set(node.name, { path: import_path, kind: 'default' });
-				return `<${node.name}>${render_nodes(node.children)}</${node.name}>`;
+				const { path, props } =
+					typeof entry === 'string' ? { path: entry, props: undefined } : entry;
+				imports.set(node.name, { path, kind: 'default' });
+				// filter via the SAME helper the node views use
+				const attrs_str = format_attributes(
+					Object.entries(mdz_filter_component_attributes(node.name, node.attributes, props))
+				);
+				return `<${node.name}${attrs_str}>${render_nodes(node.children)}</${node.name}>`;
 			}
 
 			default:

package/src/lib/mdz_token_parser.ts

@@ -581,7 +581,14 @@ export class MdzTokenParser {
 			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 };
+				return {
+					type: node_type,
+					name: tag_name,
+					attributes: open_token.attributes,
+					children,
+					start,
+					end: t.end
+				};
 			}
 			const node = this.#parse_inline();
 			if (node) mdz_push_merging_text(children, node);
@@ -595,7 +602,14 @@ export class MdzTokenParser {
 		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 };
+		return {
+			type: node_type,
+			name: token.name,
+			attributes: token.attributes,
+			children: [],
+			start: token.start,
+			end: token.end
+		};
 	}
 
 	// -- Paragraph flushing --

package/src/lib/svelte_preprocess_mdz.ts

@@ -37,7 +37,7 @@ import {
 } from '@fuzdev/fuz_util/svelte_preprocess_helpers.ts';
 
 import { mdz_parse } from './mdz.ts';
-import { mdz_to_svelte, type MdzToSvelteResult } from './mdz_to_svelte.ts';
+import { mdz_to_svelte, type MdzComponentImport, type MdzToSvelteResult } from './mdz_to_svelte.ts';
 
 /**
  * An estree `ImportDeclaration` augmented with Svelte's position data.
@@ -56,12 +56,14 @@ export interface SveltePreprocessMdzOptions {
 	/**
 	 * Component import mapping for mdz content.
 	 * Key: component name as used in mdz (e.g., 'Alert').
-	 * Value: import path (e.g., '#lib/Alert.svelte').
+	 * Value: import path (e.g., '#lib/Alert.svelte'), which receives no attributes,
+	 * or `{path, props}` naming the attributes passed as props
+	 * (e.g., `{path: '#lib/Alert.svelte', props: ['status']}`, or `props: 'all'`).
 	 *
 	 * If mdz content references a component not in this map,
 	 * that `Mdz` usage is skipped (left as runtime).
 	 */
-	components?: Record<string, string>;
+	components?: Record<string, MdzComponentImport>;
 
 	/**
 	 * Allowed HTML elements in mdz content (e.g., `{aside: true, details: true}`).
@@ -235,7 +237,7 @@ interface FindMdzUsagesResult {
 }
 
 interface FindMdzUsagesContext {
-	components: Record<string, string>;
+	components: Record<string, MdzComponentImport>;
 	elements: Record<string, boolean>;
 	filename: string | undefined;
 	source: string;