@fuzdev/fuz_ui 0.191.4 → 0.193.0

package/src/lib/tome.ts

@@ -4,10 +4,22 @@ import {z} from 'zod';
 import {ensure_start} from '@fuzdev/fuz_util/string.js';
 
 import {create_context} from './context_helpers.js';
-import {DOCS_PATH_DEFAULT, docs_slugify} from './docs_helpers.svelte.js';
+import {DOCS_PATH_DEFAULT} from './docs_helpers.svelte.js';
 
 export const Tome = z.object({
-	name: z.string(),
+	/**
+	 * Stable identifier and URL path segment — must be a URL-safe slug
+	 * (used directly as the route segment, the lookup key, and in
+	 * `related_tomes` cross-references). Set `title` for the display label.
+	 */
+	slug: z.string(),
+	/**
+	 * Human-readable display label shown in menus, headings, and links.
+	 * Falls back to `slug` when omitted, so set `title` to give multi-word or
+	 * specially cased tomes a readable label (e.g. `slug: 'vite-plugin'` →
+	 * `title: 'vite plugin'`).
+	 */
+	title: z.string().optional(),
 	// TODO maybe now this makes sense with mdz? summary: z.string(),
 	category: z.string(),
 	Component: z.custom<Component<any, any>>(),
@@ -20,22 +32,27 @@ export type Tome = z.infer<typeof Tome>;
 /**
  * @param hash - URL fragment to append, with or without the `#`
  */
-export const to_tome_pathname = (
+export const tome_to_pathname = (
 	item: Tome | string,
 	docs_path = DOCS_PATH_DEFAULT,
 	hash?: string,
 ): string => {
-	const name = typeof item === 'string' ? item : item.name;
-	const path = docs_path + '/' + docs_slugify(name);
+	const slug = typeof item === 'string' ? item : item.slug;
+	const path = docs_path + '/' + slug;
 	return resolve((hash ? path + ensure_start(hash, '#') : path) as any);
 };
 
+/**
+ * The display label for a tome — its `title` if set, else its `slug`.
+ */
+export const tome_to_title = (tome: Tome): string => tome.title ?? tome.slug;
+
 export const tomes_context = create_context<() => Map<string, Tome>>();
 
-export const get_tome_by_name = (name: string): Tome => {
+export const tome_get_by_slug = (slug: string): Tome => {
 	const get_tomes = tomes_context.get();
-	const tome = get_tomes().get(name);
-	if (!tome) throw Error(`unable to find tome "${name}"`);
+	const tome = get_tomes().get(slug);
+	if (!tome) throw Error(`unable to find tome "${slug}"`);
 	return tome;
 };
 

package/src/lib/tsdoc_helpers.ts

@@ -107,19 +107,14 @@ export const tsdoc_parse = (
 	// Extract main comment text
 	for (const comment of tsdoc_comments) {
 		if (ts.isJSDoc(comment) && comment.comment) {
-			const text =
-				typeof comment.comment === 'string'
-					? comment.comment
-					: comment.comment.map((c) => c.text).join('');
-			full_text += text + '\n';
+			full_text += tsdoc_comment_to_text(comment.comment, source_file) + '\n';
 		}
 	}
 
 	// Extract tags
 	const tags = ts.getJSDocTags(node);
 	for (const tag of tags) {
-		const tag_text =
-			typeof tag.comment === 'string' ? tag.comment : tag.comment?.map((c) => c.text).join('');
+		const tag_text = tag.comment ? tsdoc_comment_to_text(tag.comment, source_file) : undefined;
 		const tag_name = tag.tagName.text;
 
 		if (tag_name === 'param' && ts.isJSDocParameterTag(tag)) {
@@ -214,6 +209,22 @@ export const tsdoc_apply_to_declaration = (
 	}
 };
 
+/**
+ * Concatenates a JSDoc comment (string or node array) into plain text, preserving `{@link ...}`.
+ *
+ * `JSDocLink` / `JSDocLinkCode` / `JSDocLinkPlain` nodes have empty `.text` — the identifier
+ * lives on `.name`, not `.text`. Using `.text` alone silently drops link content; we fall back
+ * to the source-text representation for link nodes so `{@link Foo}` survives intact for downstream
+ * renderers (see `tsdoc_mdz.ts`).
+ */
+export const tsdoc_comment_to_text = (
+	comment: string | ts.NodeArray<ts.JSDocComment>,
+	source_file: ts.SourceFile,
+): string => {
+	if (typeof comment === 'string') return comment;
+	return comment.map((c) => (ts.isJSDocLinkLike(c) ? c.getText(source_file) : c.text)).join('');
+};
+
 /**
  * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
  *