@fuzdev/fuz_ui 0.174.0 → 0.176.0

package/src/lib/tsdoc_helpers.ts

@@ -35,6 +35,8 @@
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
  * All functions are prefixed with `tsdoc_` for clarity.
+ *
+ * @module
  */
 
 import ts from 'typescript';
@@ -66,53 +68,6 @@ export interface TsdocParsedComment {
 	nodocs?: boolean;
 }
 
-/**
- * Convert TSDoc link syntax to mdz-compatible format.
- *
- * Conversions:
- * - `{@link url|text}` → `[text](url)` (markdown link)
- * - `{@link https://...}` → `https://...` (bare URL)
- * - `{@link identifier}` → `` `identifier` `` (backticks)
- * - `@see` variants follow same rules
- *
- * @param content The @see tag content to convert
- */
-const tsdoc_convert_link_to_mdz = (content: string): string => {
-	// Check for {@link ...} or {@see ...} syntax
-	const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(content.trim());
-	if (link_match) {
-		const inner = link_match[1]!.trim();
-
-		// Check for pipe separator (custom display text)
-		const pipe_index = inner.indexOf('|');
-		if (pipe_index !== -1) {
-			const reference = inner.slice(0, pipe_index).trim();
-			const display_text = inner.slice(pipe_index + 1).trim();
-			// Convert to markdown link: [text](url)
-			return `[${display_text}](${reference})`;
-		}
-
-		// No pipe - check if it's a URL or declaration
-		if (inner.startsWith('https://') || inner.startsWith('http://')) {
-			// Bare URL - return as-is
-			return inner;
-		} else {
-			// Declaration or module - wrap in backticks
-			return `\`${inner}\``;
-		}
-	}
-
-	// No {@link} or {@see} syntax - check if it's a bare URL or declaration
-	const trimmed = content.trim();
-	if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
-		// Already a bare URL - return as-is
-		return trimmed;
-	} else {
-		// Declaration or module - wrap in backticks
-		return `\`${trimmed}\``;
-	}
-};
-
 /**
  * Parse JSDoc comment from a TypeScript node.
  *
@@ -193,11 +148,11 @@ export const tsdoc_parse = (
 			const see_content = full_tag_text
 				.replace(/^@see\s+/, '') // remove @see prefix
 				.replace(/\n\s*\*\s*/g, ' ') // remove JSDoc line continuations
+				.replace(/\s*\*\s*$/, '') // remove trailing asterisk artifacts
 				.trim();
 
 			if (see_content) {
-				// Convert TSDoc link syntax to mdz-compatible format
-				see_also.push(tsdoc_convert_link_to_mdz(see_content));
+				see_also.push(see_content);
 			}
 		} else if (tag_name === 'since' && tag_text) {
 			since = tag_text.trim();
@@ -257,3 +212,23 @@ export const tsdoc_apply_to_declaration = (
 		declaration.since = tsdoc.since;
 	}
 };
+
+/**
+ * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
+ *
+ * Transforms `/** ... *\/` style comments into clean text.
+ *
+ * @param comment_text The raw comment text including `/**` and `*\/` markers
+ * @returns Cleaned comment text, or undefined if empty after cleaning
+ */
+export const tsdoc_clean_comment = (comment_text: string): string | undefined => {
+	const text = comment_text
+		.replace(/^\/\*\*/, '')
+		.replace(/\*\/$/, '')
+		.split('\n')
+		.map((line) => line.replace(/^\s*\*\s?/, ''))
+		.join('\n')
+		.trim();
+
+	return text || undefined;
+};

package/src/lib/tsdoc_mdz.ts

@@ -0,0 +1,62 @@
+/**
+ * Bridge between TSDoc format and mdz for rendering.
+ *
+ * This module converts raw TSDoc syntax (from the analysis library) to mdz format
+ * (Fuz's documentation rendering dialect). It lives in fuz_ui, not the extracted
+ * analysis library, to keep that library format-agnostic.
+ *
+ * @module
+ */
+
+import {mdz_is_url} from './mdz.js';
+
+/** Format a reference as mdz: URLs pass through, identifiers get backticks. */
+const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${ref}\``);
+
+/**
+ * Convert raw TSDoc `@see` content to mdz format for rendering.
+ *
+ * Handles TSDoc link syntax:
+ * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
+ * - `{@link identifier}` → `` `identifier` `` (code formatting)
+ * - Bare URLs → returned as-is
+ * - Bare identifiers → wrapped in backticks
+ *
+ * @param content Raw `@see` tag content in TSDoc format
+ * @returns mdz-formatted string ready for `<Mdz>` component
+ *
+ * @example
+ * ```ts
+ * tsdoc_see_to_mdz('{@link https://fuz.dev|API Docs}')
+ * // → '[API Docs](https://fuz.dev)'
+ *
+ * tsdoc_see_to_mdz('{@link SomeType}')
+ * // → '`SomeType`'
+ *
+ * tsdoc_see_to_mdz('https://example.com')
+ * // → 'https://example.com'
+ * ```
+ */
+export const tsdoc_see_to_mdz = (content: string): string => {
+	const trimmed = content.trim();
+	if (!trimmed) return '';
+
+	// Check for {@link ...} or {@see ...} syntax
+	const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(trimmed);
+	if (link_match) {
+		const inner = link_match[1]!.trim();
+
+		// Check for pipe separator (custom display text)
+		const pipe_index = inner.indexOf('|');
+		if (pipe_index !== -1) {
+			const reference = inner.slice(0, pipe_index).trim();
+			const display_text = inner.slice(pipe_index + 1).trim();
+			return `[${display_text}](${reference})`;
+		}
+
+		return format_reference(inner);
+	}
+
+	return format_reference(trimmed);
+};

package/src/lib/vite_plugin_library_well_known.ts

@@ -75,22 +75,22 @@ export const vite_plugin_library_well_known = (
 		let json_content: string;
 		try {
 			json_content = await readFile(resolved_path, 'utf-8');
-		} catch (err) {
+		} catch (error) {
 			throw new Error(
 				`vite_plugin_library_well_known: failed to read library.json from "${library_path}"\n` +
 					`Resolved to: ${resolved_path}\n` +
 					`Make sure you've run \`gro gen\` to generate the library metadata.\n` +
-					`Error: ${err}`,
+					`Error: ${error}`,
 			);
 		}
 
 		let raw: unknown;
 		try {
 			raw = JSON.parse(json_content);
-		} catch (err) {
+		} catch (error) {
 			throw new Error(
 				`vite_plugin_library_well_known: failed to parse library.json from "${library_path}"\n` +
-					`Error: ${err}`,
+					`Error: ${error}`,
 			);
 		}
 
@@ -146,7 +146,7 @@ export const vite_plugin_library_well_known = (
 				try {
 					if (!ready_promise) throw new Error('not initialized');
 					await ready_promise;
-				} catch {
+				} catch (_error) {
 					res.statusCode = 503;
 					respond_json(res, JSON.stringify({error: 'Library not ready'}));
 					return;