@fuzdev/mdz 0.3.0 → 0.5.0

package/src/lib/mdz_helpers.ts

@@ -7,7 +7,18 @@
  * @module
  */
 
-import type {MdzNode, MdzNodeText, MdzNodeComponent, MdzNodeElement, MdzTableAlign} from './mdz.ts';
+import { DEV } from 'esm-env';
+import type { Component } from 'svelte';
+
+import type {
+	MdzAttribute,
+	MdzNode,
+	MdzNodeText,
+	MdzNodeComponent,
+	MdzNodeElement,
+	MdzTableAlign
+} from './mdz.ts';
+import type { MdzComponentConfig, MdzComponentProps } from './mdz_contexts.ts';
 
 // Character codes for performance
 /** @nodocs */
@@ -70,6 +81,8 @@ export const AMPERSAND = 38; // &
 /** @nodocs */
 export const APOSTROPHE = 39; // '
 /** @nodocs */
+export const DOUBLE_QUOTE = 34; // "
+/** @nodocs */
 export const PLUS = 43; // +
 /** @nodocs */
 export const EQUALS = 61; // =
@@ -197,7 +210,7 @@ export interface MdzBlockquotePrefix {
 export const mdz_match_blockquote_prefix = (
 	text: string,
 	i: number,
-	forced: boolean,
+	forced: boolean
 ): MdzBlockquotePrefix | 'pending' | null => {
 	let depth = 0;
 	let pos = i;
@@ -207,23 +220,23 @@ export const mdz_match_blockquote_prefix = (
 		depth++;
 		pos++;
 		if (pos >= text.length) {
-			return forced ? {depth, content_start: pos} : 'pending';
+			return forced ? { depth, content_start: pos } : 'pending';
 		}
 		const c = text.charCodeAt(pos);
 		if (c === RIGHT_ANGLE) continue; // tight run
 		if (c === SPACE) {
 			if (pos + 1 >= text.length) {
 				// could be a separator (next chunk starts with `>`) or the terminator
-				return forced ? {depth, content_start: pos + 1} : 'pending';
+				return forced ? { depth, content_start: pos + 1 } : 'pending';
 			}
 			if (text.charCodeAt(pos + 1) === RIGHT_ANGLE) {
 				pos++; // separator — continue the run at the next `>`
 				continue;
 			}
-			return {depth, content_start: pos + 1}; // terminating space
+			return { depth, content_start: pos + 1 }; // terminating space
 		}
 		if (c === NEWLINE) {
-			return {depth, content_start: pos}; // bare prefix line
+			return { depth, content_start: pos }; // bare prefix line
 		}
 		if (is_line_whitespace(c)) {
 			// tab/CR is not the marker space — valid only as tolerated trailing
@@ -233,17 +246,17 @@ export const mdz_match_blockquote_prefix = (
 				j++;
 			}
 			if (j >= text.length) {
-				return forced ? {depth, content_start: pos} : 'pending';
+				return forced ? { depth, content_start: pos } : 'pending';
 			}
 			if (text.charCodeAt(j) === NEWLINE) {
-				return {depth, content_start: pos};
+				return { depth, content_start: pos };
 			}
 			// trailing content after non-space whitespace — fall through to backtrack
 		}
 		// invalid char directly after a `>`: this `>` is content; the separator
 		// space before it (if any) re-serves as the terminator
 		if (depth >= 2 && text.charCodeAt(pos - 2) === SPACE) {
-			return {depth: depth - 1, content_start: pos - 1};
+			return { depth: depth - 1, content_start: pos - 1 };
 		}
 		return null;
 	}
@@ -260,7 +273,7 @@ export const mdz_match_blockquote_prefix = (
 export const mdz_blockquote_line_has_content = (
 	text: string,
 	content_start: number,
-	forced: boolean,
+	forced: boolean
 ): boolean | 'pending' => {
 	let i = content_start;
 	while (i < text.length && is_line_whitespace(text.charCodeAt(i))) {
@@ -291,8 +304,8 @@ export const mdz_blockquote_strip_width = (text: string, i: number): number =>
  * @nodocs
  */
 export const mdz_remap_segments = (
-	segments: Array<{inner_start: number; source_start: number}>,
-	p: number,
+	segments: Array<{ inner_start: number; source_start: number }>,
+	p: number
 ): number => {
 	let lo = 0;
 	let hi = segments.length - 1;
@@ -314,13 +327,13 @@ export const mdz_remap_segments = (
 const trim_table_cell = (
 	text: string,
 	start: number,
-	end: number,
-): {start: number; end: number} => {
+	end: number
+): { start: number; end: number } => {
 	let s = start;
 	let e = end;
 	while (s < e && is_line_whitespace(text.charCodeAt(s))) s++;
 	while (e > s && is_line_whitespace(text.charCodeAt(e - 1))) e--;
-	return {start: s, end: e};
+	return { start: s, end: e };
 };
 
 /**
@@ -343,10 +356,10 @@ const trim_table_cell = (
 export const mdz_split_table_row = (
 	text: string,
 	line_start: number,
-	line_end: number,
-): Array<{start: number; end: number}> | null => {
+	line_end: number
+): Array<{ start: number; end: number }> | null => {
 	if (line_start >= line_end || text.charCodeAt(line_start) !== PIPE) return null;
-	const cells: Array<{start: number; end: number}> = [];
+	const cells: Array<{ start: number; end: number }> = [];
 	let i = line_start + 1; // past the leading pipe
 	let cell_start = i;
 	while (i < line_end) {
@@ -415,7 +428,7 @@ const table_delimiter_align = (text: string, start: number, end: number): MdzTab
 export const mdz_parse_table_delimiter = (
 	text: string,
 	line_start: number,
-	line_end: number,
+	line_end: number
 ): Array<MdzTableAlign> | null => {
 	const cells = mdz_split_table_row(text, line_start, line_end);
 	if (cells === null) return null;
@@ -769,7 +782,7 @@ const VOID_ELEMENTS = new Set([
 	'meta',
 	'source',
 	'track',
-	'wbr',
+	'wbr'
 ]);
 
 /**
@@ -781,6 +794,93 @@ const VOID_ELEMENTS = new Set([
 // implicitly self-closing at parse time, or rejecting the open/close form
 export const mdz_is_void_element = (name: string): boolean => VOID_ELEMENTS.has(name);
 
+/**
+ * The closed, global set of attribute names allowed on rendered HTML elements.
+ * Every name is inert on any element (no URL, no script, no focus or DOM
+ * clobbering), so element safety is independent of which element names a
+ * consumer registers. Anything outside this set is dropped by
+ * `mdz_filter_element_attributes`.
+ */
+export const ALLOWED_ELEMENT_ATTRIBUTES: ReadonlySet<string> = new Set([
+	'class',
+	'title',
+	'lang',
+	'dir',
+	'role',
+	'aria-label',
+	'aria-hidden',
+	'aria-describedby',
+	'aria-labelledby'
+]);
+
+// filters an element's parsed attributes against the allowlist, returning a
+// name→value object ready to spread onto `<svelte:element {...}>`. Disallowed
+// names are dropped (DEV-warned). Used identically by MdzNodeView,
+// MdzStreamNodeView, and mdz_to_svelte, so precompiled and runtime output match.
+export const mdz_filter_element_attributes = (
+	element_name: string,
+	attributes: Array<MdzAttribute>,
+	allowlist: ReadonlySet<string>
+): Record<string, string | true> => {
+	const filtered: Record<string, string | true> = {};
+	for (const attr of attributes) {
+		if (allowlist.has(attr.name)) {
+			filtered[attr.name] = attr.value;
+		} else if (DEV) {
+			console.warn(
+				`mdz: dropped disallowed attribute \`${attr.name}\` on <${element_name}> — not in the element attribute allowlist`
+			);
+		}
+	}
+	return filtered;
+};
+
+// filters a component's parsed attributes against its registered `props`,
+// returning a name→value props object spread onto `<Component {...props}>`.
+// Omitted `props` passes nothing, `'all'` passes everything; dropped names are
+// DEV-warned. Used identically by MdzNodeView, MdzStreamNodeView, and
+// mdz_to_svelte, so precompiled and runtime output match.
+export const mdz_filter_component_attributes = (
+	component_name: string,
+	attributes: Array<MdzAttribute>,
+	props: MdzComponentProps | undefined
+): Record<string, string | true> => {
+	const filtered: Record<string, string | true> = {};
+	for (const attr of attributes) {
+		if (props === 'all' || props?.includes(attr.name)) {
+			filtered[attr.name] = attr.value;
+		} else if (DEV) {
+			console.warn(
+				`mdz: dropped attribute \`${attr.name}\` on <${component_name}> — not in its registered props`
+			);
+		}
+	}
+	return filtered;
+};
+
+// normalizes a component registry entry to its config form
+export const mdz_component_config = (
+	entry: Component<any, any> | MdzComponentConfig
+): MdzComponentConfig => (typeof entry === 'function' ? { component: entry } : entry);
+
+// reconstructs authored attribute text (` name="value"` / ` name`) for the
+// unregistered-tag literal placeholder. The quote char is chosen so a value
+// containing one quote type stays balanced — a parsed value holds at most one
+// (a `"`-delimited value can't contain `"`, a `'`-delimited one can't contain
+// `'`). The caller interpolates the result as Svelte text (auto-escaped).
+export const mdz_format_unregistered_attributes = (attributes: Array<MdzAttribute>): string => {
+	let text = '';
+	for (const attr of attributes) {
+		if (attr.value === true) {
+			text += ` ${attr.name}`;
+		} else {
+			const quote = attr.value.includes('"') ? "'" : '"';
+			text += ` ${attr.name}=${quote}${attr.value}${quote}`;
+		}
+	}
+	return text;
+};
+
 /**
  * Resolves a relative path (`./` or `../`) against a base path.
  * The base is treated as a directory regardless of trailing slash
@@ -811,6 +911,20 @@ export const mdz_resolve_relative_path = (reference: string, base: string): stri
 	return segments.join('/');
 };
 
+// `/a` → `a`, `//a` → `a` — the pathname form `resolve()` takes; `\` counts as a
+// slash too, and tab/LF/CR are dropped, since browsers read `/\host` and
+// `/<tab>/host` as protocol-relative
+const strip_leading_slashes = (path: string): string => {
+	let i = 0;
+	for (;;) {
+		const c = path.charCodeAt(i);
+		if (c !== SLASH && c !== BACKSLASH && c !== TAB && c !== NEWLINE && c !== CARRIAGE_RETURN)
+			break;
+		i++;
+	}
+	return path.slice(i);
+};
+
 /**
  * How a `Link` node's `reference` should render, shared by all three renderers
  * (`MdzNodeView`, `MdzStreamNodeView`, `mdz_to_svelte`) so the safety gate and
@@ -819,42 +933,49 @@ export const mdz_resolve_relative_path = (reference: string, base: string): stri
  */
 export type MdzLinkRender =
 	/** Unsafe protocol — render children only, no `<a>`. */
-	| {kind: 'unsafe'}
-	/** Route/relative path — wrap in `resolve()` (needs `$app/paths`). */
-	| {kind: 'resolve'; href: string}
+	| { kind: 'unsafe' }
+	/**
+	 * Absolute path — render `resolve(path)` (needs `$app/paths`). `path` is the
+	 * reference minus its leading slash, SvelteKit's pathname form, which only
+	 * prepends the base path (or `#` under hash routing; a relative `./`/`../`
+	 * prefix under `paths.relative` SSR) and keeps the rest verbatim.
+	 */
+	| { kind: 'resolve'; path: string }
 	/** Internal fragment/query/relative/bare ref — raw `href`, no `resolve()`. */
-	| {kind: 'internal'; href: string}
+	| { kind: 'internal'; href: string }
 	/** External link — raw `href` plus `target="_blank" rel="noopener"`. */
-	| {kind: 'external'; href: string};
+	| { kind: 'external'; href: string };
 
 /**
  * Classify a `Link` reference into how it should render. Pure — no rendering,
  * no context; `base` is the resolved base path (or `undefined`).
+ *
+ * Absolute references are authored URLs, not SvelteKit route ids: they classify
+ * as `resolve` with the base-relative pathname, never a leading-slash route id,
+ * whose resolution would drop `(group)` and empty segments, decode `[x+nn]`
+ * escapes, and throw on `[param]` segments. A leading `/` followed by any `/`
+ * or `\` run collapses to one `/`, so `//host` and `/\host` stay under the base
+ * rather than becoming protocol-relative.
  * @nodocs
  */
 export const mdz_classify_link = (
 	reference: string,
 	link_type: 'internal' | 'external' | undefined,
-	base: string | undefined,
+	base: string | undefined
 ): MdzLinkRender => {
-	if (!mdz_is_safe_reference(reference)) return {kind: 'unsafe'};
+	if (!mdz_is_safe_reference(reference)) return { kind: 'unsafe' };
 	if (link_type === 'internal') {
 		if (reference.startsWith('.') && base) {
-			return {kind: 'resolve', href: mdz_resolve_relative_path(reference, base)};
-		}
-		// fragment/query/relative/bare — `resolve()` only accepts absolute paths or
-		// route ids and throws on anything else
-		if (
-			reference.startsWith('#') ||
-			reference.startsWith('?') ||
-			reference.startsWith('.') ||
-			!reference.startsWith('/')
-		) {
-			return {kind: 'internal', href: reference};
+			return {
+				kind: 'resolve',
+				path: strip_leading_slashes(mdz_resolve_relative_path(reference, base))
+			};
 		}
-		return {kind: 'resolve', href: reference};
+		// fragment/query/relative/bare — not under the base, so a raw `href`
+		if (!reference.startsWith('/')) return { kind: 'internal', href: reference };
+		return { kind: 'resolve', path: strip_leading_slashes(reference) };
 	}
-	return {kind: 'external', href: reference};
+	return { kind: 'external', href: reference };
 };
 
 /**
@@ -901,10 +1022,10 @@ export const mdz_merge_adjacent_text = (nodes: Array<MdzNode>): Array<MdzNode> =
 					type: 'Text',
 					content: pending.content + node.content,
 					start: pending.start,
-					end: node.end,
+					end: node.end
 				};
 			} else {
-				pending = {...node};
+				pending = { ...node };
 			}
 		} else {
 			if (pending) {
@@ -927,7 +1048,7 @@ export const mdz_merge_adjacent_text = (nodes: Array<MdzNode>): Array<MdzNode> =
  *   or `null` if the content should be wrapped in a paragraph
  */
 export const mdz_extract_single_tag = (
-	nodes: Array<MdzNode>,
+	nodes: Array<MdzNode>
 ): MdzNodeComponent | MdzNodeElement | null => {
 	let tag: MdzNodeComponent | MdzNodeElement | null = null;