@fuzdev/fuz_ui 0.191.1 → 0.191.2

package/src/lib/library_gen.ts

@@ -7,9 +7,9 @@
  *
  * For build-tool agnostic usage, see `library_generate.ts`.
  *
- * @see library_generate.ts for the generic generation entry point
- * @see library_pipeline.ts for pipeline helpers
- * @see library_output.ts for output file generation
+ * @see `library_generate.ts` for the generic generation entry point
+ * @see `library_pipeline.ts` for pipeline helpers
+ * @see `library_output.ts` for output file generation
  *
  * @module
  */
@@ -46,6 +46,7 @@ export interface LibraryGenOptions {
 	 * Use `library_throw_on_duplicates` for strict flat namespace enforcement.
 	 *
 	 * @example
+	 * ```ts
 	 * // Throw on duplicates (strict flat namespace)
 	 * library_gen({ on_duplicates: library_throw_on_duplicates });
 	 *
@@ -57,12 +58,13 @@ export interface LibraryGenOptions {
 	 *     }
 	 *   }
 	 * });
+	 * ```
 	 */
 	on_duplicates?: OnDuplicatesCallback;
 }
 
 /**
- * Convert Gro's Disknode to the build-tool agnostic SourceFileInfo interface.
+ * Convert Gro's `Disknode` to the build-tool agnostic `SourceFileInfo` interface.
  *
  * Use this when you want to analyze files using Gro's filer directly.
  *
@@ -83,7 +85,7 @@ export const source_file_from_disknode = (disknode: Disknode): SourceFileInfo =>
 };
 
 /**
- * Collect source files from Gro disknodes, filtering BEFORE conversion to SourceFileInfo.
+ * Collect source files from Gro disknodes, filtering BEFORE conversion to `SourceFileInfo`.
  *
  * This avoids errors from files outside source directories (like test fixtures that may
  * have malformed paths or missing content). The filtering uses `module_is_source` which
@@ -129,12 +131,12 @@ export const library_collect_source_files_from_disknodes = (
 };
 
 /**
- * Creates a Gen object for generating library metadata with full TypeScript analysis.
+ * Creates a `Gen` object for generating library metadata with full TypeScript analysis.
  *
  * This is the Gro-specific entry point. It handles:
  * - Reading files from Gro's filer
- * - Loading package.json via Gro utilities
- * - Returning output in Gro's Gen format
+ * - Loading `package.json` via Gro utilities
+ * - Returning output in Gro's `Gen` format
  *
  * For build-tool agnostic usage, use `library_generate` directly.
  *

package/src/lib/library_generate.ts

@@ -12,9 +12,9 @@
  * - Dependency graphs
  * - Svelte component props
  *
- * For Gro integration, see `library_gen.ts` which wraps this with Gro's Gen interface.
+ * For Gro integration, see `library_gen.ts` which wraps this with Gro's `Gen` interface.
  *
- * @see @fuzdev/fuz_util/source_json.js for type definitions
+ * @see `@fuzdev/fuz_util/source_json.js` for type definitions
  * @see `library_analysis.ts` for the unified analysis entry point
  * @see `library_pipeline.ts` for pipeline helpers
  * @see `library_output.ts` for JSON/TS file generation

package/src/lib/library_helpers.ts

@@ -67,9 +67,11 @@ export const url_package_logo = (
  * @returns root-relative URL starting with '/'
  *
  * @example
+ * ```ts
  * // Assuming page.url.origin is 'https://example.com'
  * url_to_root_relative('https://example.com/docs/api')
  * // => '/docs/api'
+ * ```
  */
 export const url_to_root_relative = (url: string, origin: string = page.url.origin): string => {
 	const origin_with_slash = ensure_end(origin, '/');

package/src/lib/library_output.ts

@@ -1,11 +1,11 @@
 /**
  * Library output generation.
  *
- * Generates the library.json and library.ts files from analyzed metadata.
+ * Generates the `library.json` and `library.ts` files from analyzed metadata.
  *
- * @see library_generate.ts for the main generation entry point
- * @see library_pipeline.ts for pipeline orchestration functions
- * @see library_gen.ts for Gro-specific integration
+ * @see `library_generate.ts` for the main generation entry point
+ * @see `library_pipeline.ts` for pipeline orchestration functions
+ * @see `library_gen.ts` for Gro-specific integration
  *
  * @module
  */
@@ -19,14 +19,14 @@ import {library_json_parse, type LibraryJson} from '@fuzdev/fuz_util/library_jso
  * Contains both the JSON data and the TypeScript wrapper file.
  */
 export interface LibraryOutputResult {
-	/** JSON content for library.json */
+	/** JSON content for `library.json`. */
 	json_content: string;
-	/** TypeScript wrapper content for library.ts */
+	/** TypeScript wrapper content for `library.ts`. */
 	ts_content: string;
 }
 
 /**
- * Generate the library.json and library.ts file contents.
+ * Generate the `library.json` and `library.ts` file contents.
  * Parses at generation time so runtime only needs the pre-computed result.
  *
  * Returns JSON + .ts wrapper because:

package/src/lib/library_pipeline.ts

@@ -6,15 +6,15 @@
  *
  * Pipeline stages:
  * 1. **Collection** - `library_collect_source_files` gathers and filters source files
- * 2. **Analysis** - `library_analyze_module` (in library_analysis.ts) extracts metadata
+ * 2. **Analysis** - `library_analyze_module` (in `library_analysis.ts`) extracts metadata
  * 3. **Validation** - `library_find_duplicates` checks flat namespace constraints
  * 4. **Transformation** - `library_merge_re_exports` resolves re-export relationships
  * 5. **Output** - `library_sort_modules` prepares deterministic output
  *
- * @see library_generate.ts for the main generation entry point
- * @see library_analysis.ts for module-level analysis
- * @see library_output.ts for output file generation (JSON/TS wrapper)
- * @see library_gen.ts for Gro-specific integration
+ * @see `library_generate.ts` for the main generation entry point
+ * @see `library_analysis.ts` for module-level analysis
+ * @see `library_output.ts` for output file generation (JSON/TS wrapper)
+ * @see `library_gen.ts` for Gro-specific integration
  *
  * @module
  */
@@ -48,6 +48,7 @@ export interface DuplicateInfo {
  * Callers can decide how to handle duplicates (throw, warn, ignore).
  *
  * @example
+ * ```ts
  * const duplicates = library_find_duplicates(source_json);
  * if (duplicates.size > 0) {
  *   for (const [name, occurrences] of duplicates) {
@@ -58,6 +59,7 @@ export interface DuplicateInfo {
  *   }
  *   throw new Error(`Found ${duplicates.size} duplicate declaration names`);
  * }
+ * ```
  */
 export const library_find_duplicates = (
 	source_json: SourceJson,
@@ -123,12 +125,14 @@ export interface CollectedReExport {
  * after all modules are analyzed.
  *
  * @example
+ * ```ts
  * // helpers.ts exports: foo, bar
  * // index.ts does: export {foo, bar} from './helpers.js'
  * //
  * // After processing:
  * // - helpers.ts foo declaration gets: also_exported_from: ['index.ts']
  * // - helpers.ts bar declaration gets: also_exported_from: ['index.ts']
+ * ```
  *
  * @param source_json - the source JSON with all modules (will be mutated)
  * @param collected_re_exports - array of re-exports collected during phase 1

package/src/lib/logos.ts

@@ -63,9 +63,9 @@ export const logo_fuz = {
 	],
 } satisfies SvgData;
 
-export const logo_fuz_ui = {
-	label: 'a friendly red spider facing you',
-	fill: '#d93636',
+export const logo_fuz_app = {
+	label: 'a friendly teal spider facing you',
+	fill: '#2e9e6f',
 	paths: logo_fuz.paths,
 } satisfies SvgData;
 
@@ -76,6 +76,12 @@ export const logo_fuz_css = {
 	attrs: {style: 'transform: scaleX(-1) rotate(180deg)'},
 } satisfies SvgData;
 
+export const logo_fuz_ui = {
+	label: 'a friendly red spider facing you',
+	fill: '#d93636',
+	paths: logo_fuz.paths,
+} satisfies SvgData;
+
 export const logo_fuz_code = {
 	label: 'a friendly pink spider facing you',
 	fill: '#e55d95',

package/src/lib/module.svelte.ts

@@ -24,7 +24,7 @@ export class Module {
 	module_comment = $derived(this.module_json.module_comment);
 
 	/**
-	 * Array of Declaration instances. Filters out default exports.
+	 * Array of `Declaration` instances. Filters out default exports.
 	 */
 	declarations = $derived(
 		this.module_json.declarations

package/src/lib/module_helpers.ts

@@ -20,7 +20,7 @@ export type AnalyzerType = 'typescript' | 'svelte';
 /**
  * File information for source analysis.
  *
- * Can be constructed from Gro's Disknode or from plain file system access.
+ * Can be constructed from Gro's `Disknode` or from plain file system access.
  * This abstraction enables non-Gro usage while keeping Gro support via adapter.
  *
  * Note: `content` is required to keep analysis functions pure (no hidden I/O).
@@ -328,7 +328,7 @@ export const module_validate_source_options = (options: ModuleSourceOptions): vo
  *
  * Returns `source_root` if provided, otherwise returns `source_paths[0]` for single-path configs.
  *
- * @throws Error if source_root is required but not provided (multiple source_paths)
+ * @throws Error if `source_root` is required but not provided (multiple `source_paths`)
  */
 export const module_get_source_root = (options: ModuleSourceOptions): string => {
 	if (options.source_root !== undefined) {

package/src/lib/package_helpers.ts

@@ -11,7 +11,7 @@
  * - `url_well_known` - .well-known metadata file
  *
  * Parsers:
- * - `repo_url_parse` - extract repo URL from package.json repository field
+ * - `repo_url_parse` - extract repo URL from `package.json` repository field
  * - `repo_name_parse` - extract repo name from scoped package name
  * - `repo_url_github_owner` - extract GitHub owner from repo URL
  *
@@ -115,7 +115,7 @@ export const url_npm_package = (package_name: string): string =>
  * - It has exports defined
  * - Its version is not the initial '0.0.1'
  *
- * @param package_json - the package.json object to check
+ * @param package_json - the `package.json` object to check
  * @returns `true` if the package appears to be published
  */
 export const package_is_published = (package_json: PackageJson): boolean => {
@@ -153,12 +153,12 @@ export const repo_name_parse = (name: string): string => {
 };
 
 /**
- * Parse repository URL from package.json format.
+ * Parse repository URL from `package.json` format.
  *
  * Handles both string format and object format with `url` property.
  * Strips common prefixes ('git+') and suffixes ('.git', '/').
  *
- * @param repository - the repository field from package.json
+ * @param repository - the repository field from `package.json`
  * @returns clean repository URL, or null if not provided
  *
  * @example

package/src/lib/svelte_preprocess_mdz.ts

@@ -59,20 +59,20 @@ export interface SveltePreprocessMdzOptions {
 	 * Value: import path (e.g., '$lib/Alert.svelte').
 	 *
 	 * If mdz content references a component not in this map,
-	 * that Mdz usage is skipped (left as runtime).
+	 * that `Mdz` usage is skipped (left as runtime).
 	 */
 	components?: Record<string, string>;
 
 	/**
 	 * Allowed HTML elements in mdz content.
 	 * If mdz content references an element not in this list,
-	 * that Mdz usage is skipped (left as runtime).
+	 * that `Mdz` usage is skipped (left as runtime).
 	 */
 	elements?: Array<string>;
 
 	/**
-	 * Import sources that resolve to the Mdz component.
-	 * Used to verify that `Mdz` in templates refers to fuz_ui's Mdz.svelte.
+	 * Import sources that resolve to the `Mdz` component.
+	 * Used to verify that `Mdz` in templates refers to fuz_ui's `Mdz.svelte`.
 	 *
 	 * @default ['@fuzdev/fuz_ui/Mdz.svelte']
 	 */
@@ -204,9 +204,9 @@ interface MdzTransformation {
 
 interface FindMdzUsagesResult {
 	transformations: Array<MdzTransformation>;
-	/** Total template usages per Mdz local name. */
+	/** Total template usages per `Mdz` local name. */
 	total_usages: Map<string, number>;
-	/** Successfully transformed usages per Mdz local name. */
+	/** Successfully transformed usages per `Mdz` local name. */
 	transformed_usages: Map<string, number>;
 }
 
@@ -487,7 +487,7 @@ const remove_dead_const_bindings = (
 };
 
 /**
- * Builds the replacement string for a transformed Mdz component.
+ * Builds the replacement string for a transformed `Mdz` component.
  *
  * Reconstructs the opening tag as `<MdzPrecompiled` with all attributes except `content`,
  * using source text slicing to preserve exact formatting and dynamic expressions.
@@ -515,24 +515,24 @@ const build_replacement = (
 	return `${opening}${children_markup}</${PRECOMPILED_NAME}>`;
 };
 
-/** Result of import removability analysis for a single Mdz name. */
+/** Result of import removability analysis for a single `Mdz` name. */
 interface ImportRemovalAction {
 	/** The import declaration node. */
 	node: PositionedImportDeclaration;
-	/** 'full' removes the entire declaration; 'partial' removes only the Mdz specifier. */
+	/** 'full' removes the entire declaration; 'partial' removes only the `Mdz` specifier. */
 	kind: 'full' | 'partial';
 	/** For partial removal: the specifier to remove. */
 	specifier_to_remove?: ImportDeclaration['specifiers'][number];
 }
 
 /**
- * Determines which Mdz import declarations can be safely removed or trimmed.
+ * Determines which `Mdz` import declarations can be safely removed or trimmed.
  *
  * An import is removable when:
  * 1. All template usages of that name were successfully transformed.
  * 2. The identifier is not referenced elsewhere in script or template expressions.
  *
- * For multi-specifier imports, only the Mdz specifier is removed (partial removal).
+ * For multi-specifier imports, only the `Mdz` specifier is removed (partial removal).
  * For single-specifier imports, the entire declaration is removed.
  */
 const find_removable_mdz_imports = (
@@ -587,13 +587,13 @@ const find_removable_mdz_imports = (
  * Manages import additions and removals.
  *
  * Adds the `MdzPrecompiled` import and other required imports (DocsLink, Code, resolve).
- * Removes Mdz import declarations that are no longer referenced.
+ * Removes `Mdz` import declarations that are no longer referenced.
  *
  * Handles both full removal (single-specifier imports) and partial removal
- * (multi-specifier imports where only the Mdz specifier is removed).
+ * (multi-specifier imports where only the `Mdz` specifier is removed).
  *
  * To avoid MagicString boundary conflicts when the insertion position falls inside
- * a removal range, one removable Mdz import is overwritten with the MdzPrecompiled
+ * a removal range, one removable `Mdz` import is overwritten with the `MdzPrecompiled`
  * import line instead of using separate remove + appendLeft.
  */
 const manage_imports = (

package/src/lib/ts_helpers.ts

@@ -32,7 +32,7 @@ import type {DeclarationAnalysis, ReExportInfo, ModuleAnalysis} from './library_
 export interface TsProgramOptions {
 	/** Project root directory. @default './' */
 	root?: string;
-	/** Path to tsconfig.json (relative to root). @default 'tsconfig.json' */
+	/** Path to `tsconfig.json` (relative to root). @default 'tsconfig.json' */
 	tsconfig?: string;
 	/** Override compiler options. */
 	compiler_options?: ts.CompilerOptions;
@@ -54,7 +54,7 @@ export interface ModuleExportsAnalysis {
 	module_comment?: string;
 	/** All exported declarations with nodocs flags - consumer filters based on policy. */
 	declarations: Array<DeclarationAnalysis>;
-	/** Same-name re-exports (for building also_exported_from in post-processing). */
+	/** Same-name re-exports (for building `also_exported_from` in post-processing). */
 	re_exports: Array<ReExportInfo>;
 	/** Star exports (`export * from './module'`) - module paths that are fully re-exported. */
 	star_exports: Array<string>;
@@ -66,7 +66,7 @@ export interface ModuleExportsAnalysis {
  * @param options - configuration options for program creation
  * @param log - optional logger for info messages
  * @returns the program and type checker
- * @throws Error if tsconfig.json is not found
+ * @throws Error if `tsconfig.json` is not found
  */
 export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsProgram => {
 	const root = options?.root ?? './';
@@ -332,7 +332,7 @@ export const ts_analyze_declaration = (
  * Requires `@module` tag to identify module comments. The tag line is stripped
  * from the output. Supports optional module renaming: `@module custom-name`.
  *
- * @see https://typedoc.org/documents/Tags._module.html
+ * @see {@link https://typedoc.org/documents/Tags._module.html}
  */
 export const ts_extract_module_comment = (source_file: ts.SourceFile): string | undefined => {
 	const full_text = source_file.getFullText();

package/src/lib/vite_plugin_library_well_known.ts

@@ -6,7 +6,7 @@ import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
 
 export interface VitePluginLibraryWellKnownOptions {
 	/**
-	 * Path to the library.json file (relative to vite.config.ts).
+	 * Path to the `library.json` file (relative to `vite.config.ts`).
 	 * @default './src/routes/library.json'
 	 */
 	library_path?: string;
@@ -27,7 +27,7 @@ const respond_json = (res: ServerResponse, body: string): void => {
 /**
  * Vite plugin that publishes `package.json` and `library.json` to `.well-known/`.
  *
- * Requires a generated library.json file (created by `library_gen` from `gro gen`).
+ * Requires a generated `library.json` file (created by `library_gen` from `gro gen`).
  * The plugin reads this JSON file and publishes its metadata to `.well-known/` for
  * both dev and production builds.
  *