@fuzdev/fuz_ui 0.181.1 → 0.182.1

package/src/lib/mdz_to_svelte.ts

@@ -0,0 +1,127 @@
+/**
+ * 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';
+
+/**
+ * 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.
+ */
+export const mdz_to_svelte = (
+	nodes: Array<MdzNode>,
+	components: Record<string, string>,
+	elements: ReadonlySet<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('#') || 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};
+};

package/src/lib/module_helpers.ts

@@ -52,10 +52,12 @@ export interface SourceFileInfo {
  * handles nested directories without special heuristics.
  *
  * @example
+ * ```ts
  * const options = module_create_source_options(process.cwd(), {
  *   source_paths: ['src/lib', 'src/routes'],
  *   source_root: 'src',
  * });
+ * ```
  */
 export interface ModuleSourceOptions {
 	/**
@@ -64,7 +66,10 @@ export interface ModuleSourceOptions {
 	 * All `source_paths` are relative to this. Typically `process.cwd()` when
 	 * running from the project root via Gro, Vite, or other build tools.
 	 *
-	 * @example '/home/user/my-project'
+	 * @example
+	 * ```ts
+	 * '/home/user/my-project'
+	 * ```
 	 */
 	project_root: string;
 	/**
@@ -73,8 +78,14 @@ export interface ModuleSourceOptions {
 	 * Paths should not have leading or trailing slashes - they are added
 	 * internally for correct matching.
 	 *
-	 * @example ['src/lib'] - single source directory
-	 * @example ['src/lib', 'src/routes'] - multiple directories
+	 * @example
+	 * ```ts
+	 * ['src/lib'] // single source directory
+	 * ```
+	 * @example
+	 * ```ts
+	 * ['src/lib', 'src/routes'] // multiple directories
+	 * ```
 	 */
 	source_paths: Array<string>;
 	/**
@@ -84,8 +95,14 @@ export interface ModuleSourceOptions {
 	 * - Single `source_path`: defaults to that path
 	 * - Multiple `source_paths`: required (no auto-derivation)
 	 *
-	 * @example 'src/lib' - module paths like 'foo.ts', 'utils/bar.ts'
-	 * @example 'src' - module paths like 'lib/foo.ts', 'routes/page.svelte'
+	 * @example
+	 * ```ts
+	 * 'src/lib' // module paths like 'foo.ts', 'utils/bar.ts'
+	 * ```
+	 * @example
+	 * ```ts
+	 * 'src' // module paths like 'lib/foo.ts', 'routes/page.svelte'
+	 * ```
 	 */
 	source_root?: string;
 	/** Patterns to exclude (matched against full path). */
@@ -100,20 +117,24 @@ export interface ModuleSourceOptions {
 	 * @default Uses file extension: `.svelte` → svelte, `.ts`/`.js` → typescript
 	 *
 	 * @example
+	 * ```ts
 	 * // Add MDsveX support
 	 * get_analyzer: (path) => {
 	 *   if (path.endsWith('.svelte') || path.endsWith('.svx')) return 'svelte';
 	 *   if (path.endsWith('.ts') || path.endsWith('.js')) return 'typescript';
 	 *   return null;
 	 * }
+	 * ```
 	 *
 	 * @example
+	 * ```ts
 	 * // Include .d.ts files
 	 * get_analyzer: (path) => {
 	 *   if (path.endsWith('.svelte')) return 'svelte';
 	 *   if (path.endsWith('.ts') || path.endsWith('.d.ts') || path.endsWith('.js')) return 'typescript';
 	 *   return null;
 	 * }
+	 * ```
 	 */
 	get_analyzer: (path: string) => AnalyzerType | null;
 }
@@ -157,21 +178,27 @@ export const MODULE_SOURCE_PARTIAL: ModuleSourcePartial = {
  * @param overrides Optional overrides for default options
  *
  * @example
+ * ```ts
  * // Standard SvelteKit library
  * const options = module_create_source_options(process.cwd());
+ * ```
  *
  * @example
+ * ```ts
  * // Multiple source directories
  * const options = module_create_source_options(process.cwd(), {
  *   source_paths: ['src/lib', 'src/routes'],
  *   source_root: 'src',
  * });
+ * ```
  *
  * @example
+ * ```ts
  * // Custom exclusions
  * const options = module_create_source_options(process.cwd(), {
  *   exclude_patterns: [/\.test\.ts$/, /\.internal\.ts$/],
  * });
+ * ```
  */
 export const module_create_source_options = (
 	project_root: string,
@@ -195,14 +222,17 @@ export const module_create_source_options = (
  * @throws Error if validation fails
  *
  * @example
+ * ```ts
  * // Valid - single source path (source_root auto-derived)
  * module_validate_source_options({
  *   project_root: '/home/user/project',
  *   source_paths: ['src/lib'],
  *   ...
  * });
+ * ```
  *
  * @example
+ * ```ts
  * // Valid - multiple source paths with explicit source_root
  * module_validate_source_options({
  *   project_root: '/home/user/project',
@@ -210,14 +240,17 @@ export const module_create_source_options = (
  *   source_root: 'src',
  *   ...
  * });
+ * ```
  *
  * @example
+ * ```ts
  * // Invalid - multiple source paths without source_root
  * module_validate_source_options({
  *   project_root: '/home/user/project',
  *   source_paths: ['src/lib', 'src/routes'],  // throws
  *   ...
  * });
+ * ```
  */
 export const module_validate_source_options = (options: ModuleSourceOptions): void => {
 	const {project_root, source_paths, source_root} = options;
@@ -319,17 +352,21 @@ export const module_get_source_root = (options: ModuleSourceOptions): string =>
  * @param options Module source options for path extraction
  *
  * @example
+ * ```ts
  * const options = module_create_source_options('/home/user/project');
  * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'foo.ts'
  * module_extract_path('/home/user/project/src/lib/nested/bar.svelte', options) // => 'nested/bar.svelte'
+ * ```
  *
  * @example
+ * ```ts
  * const options = module_create_source_options('/home/user/project', {
  *   source_paths: ['src/lib', 'src/routes'],
  *   source_root: 'src',
  * });
  * module_extract_path('/home/user/project/src/lib/foo.ts', options) // => 'lib/foo.ts'
  * module_extract_path('/home/user/project/src/routes/page.svelte', options) // => 'routes/page.svelte'
+ * ```
  */
 export const module_extract_path = (source_id: string, options: ModuleSourceOptions): string => {
 	const effective_root = module_get_source_root(options);
@@ -347,8 +384,10 @@ export const module_extract_path = (source_id: string, options: ModuleSourceOpti
  * Extract component name from a Svelte module path.
  *
  * @example
+ * ```ts
  * module_get_component_name('Alert.svelte') // => 'Alert'
  * module_get_component_name('components/Button.svelte') // => 'Button'
+ * ```
  */
 export const module_get_component_name = (module_path: string): string =>
 	module_path.replace(/^.*\//, '').replace(/\.svelte$/, '');
@@ -357,7 +396,9 @@ export const module_get_component_name = (module_path: string): string =>
  * Convert module path to module key format (with ./ prefix).
  *
  * @example
+ * ```ts
  * module_get_key('foo.ts') // => './foo.ts'
+ * ```
  */
 export const module_get_key = (module_path: string): string => `./${module_path}`;
 
@@ -394,10 +435,12 @@ export const module_is_test = (path: string): boolean => path.endsWith('.test.ts
  * @returns True if the path is an analyzable source file
  *
  * @example
+ * ```ts
  * const options = module_create_source_options('/home/user/project');
  * module_is_source('/home/user/project/src/lib/foo.ts', options) // => true
  * module_is_source('/home/user/project/src/lib/foo.test.ts', options) // => false (excluded)
  * module_is_source('/home/user/project/src/fixtures/mini/src/lib/bar.ts', options) // => false (wrong prefix)
+ * ```
  */
 export const module_is_source = (path: string, options: ModuleSourceOptions): boolean => {
 	// Check exclusion patterns first (fast regex check)

package/src/lib/package_helpers.ts

@@ -33,12 +33,16 @@ import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
  * @returns Full GitHub URL to the file on the main branch
  *
  * @example
+ * ```ts
  * url_github_file('https://github.com/foo/bar', 'src/index.ts')
  * // => 'https://github.com/foo/bar/blob/main/src/index.ts'
+ * ```
  *
  * @example
+ * ```ts
  * url_github_file('https://github.com/foo/bar', './src/index.ts', 42)
  * // => 'https://github.com/foo/bar/blob/main/src/index.ts#L42'
+ * ```
  */
 export const url_github_file = (repo_url: string, file_path: string, line?: number): string => {
 	const clean_path = file_path.replace(/^\.\//, '');
@@ -54,8 +58,10 @@ export const url_github_file = (repo_url: string, file_path: string, line?: numb
  * @returns Organization URL, or null if repo_url doesn't end with repo_name
  *
  * @example
+ * ```ts
  * url_github_org('https://github.com/fuzdev/fuz_ui', 'fuz_ui')
  * // => 'https://github.com/fuzdev'
+ * ```
  */
 export const url_github_org = (repo_url: string, repo_name: string): string | null => {
 	return repo_url.endsWith('/' + repo_name) ? strip_end(repo_url, '/' + repo_name) : null;
@@ -68,12 +74,16 @@ export const url_github_org = (repo_url: string, repo_name: string): string | nu
  * @returns Owner name, or null if not a valid GitHub URL
  *
  * @example
+ * ```ts
  * repo_url_github_owner('https://github.com/fuzdev/fuz_ui')
  * // => 'fuzdev'
+ * ```
  *
  * @example
+ * ```ts
  * repo_url_github_owner('https://gitlab.com/foo/bar')
  * // => null (not a GitHub URL)
+ * ```
  */
 export const repo_url_github_owner = (repo_url: string): string | null => {
 	const stripped = strip_start(repo_url, 'https://github.com/');
@@ -89,8 +99,10 @@ export const repo_url_github_owner = (repo_url: string): string | null => {
  * @returns Full npm package page URL
  *
  * @example
+ * ```ts
  * url_npm_package('@fuzdev/fuz_ui')
  * // => 'https://www.npmjs.com/package/@fuzdev/fuz_ui'
+ * ```
  */
 export const url_npm_package = (package_name: string): string =>
 	'https://www.npmjs.com/package/' + package_name;
@@ -118,12 +130,16 @@ export const package_is_published = (package_json: PackageJson): boolean => {
  * @throws Error if scoped package name is malformed
  *
  * @example
+ * ```ts
  * repo_name_parse('@fuzdev/fuz_ui')
  * // => 'fuz_ui'
+ * ```
  *
  * @example
+ * ```ts
  * repo_name_parse('lodash')
  * // => 'lodash'
+ * ```
  */
 export const repo_name_parse = (name: string): string => {
 	if (name[0] === '@') {
@@ -146,16 +162,22 @@ export const repo_name_parse = (name: string): string => {
  * @returns Clean repository URL, or null if not provided
  *
  * @example
+ * ```ts
  * repo_url_parse('https://github.com/foo/bar')
  * // => 'https://github.com/foo/bar'
+ * ```
  *
  * @example
+ * ```ts
  * repo_url_parse({url: 'git+https://github.com/foo/bar.git'})
  * // => 'https://github.com/foo/bar'
+ * ```
  *
  * @example
+ * ```ts
  * repo_url_parse(undefined)
  * // => null
+ * ```
  */
 export const repo_url_parse = (repository: PackageJson['repository']): string | null => {
 	if (!repository) return null;
@@ -172,8 +194,10 @@ export const repo_url_parse = (repository: PackageJson['repository']): string |
  * @returns Full URL to the .well-known file
  *
  * @example
+ * ```ts
  * url_well_known('https://fuz.dev', 'package.json')
  * // => 'https://fuz.dev/.well-known/package.json'
+ * ```
  */
 export const url_well_known = (homepage_url: string, filename: string): string => {
 	return `${ensure_end(homepage_url, '/')}.well-known/${filename}`;