@fuzdev/fuz_ui 0.190.0 → 0.191.1

package/src/lib/package_helpers.ts

@@ -27,10 +27,10 @@ import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
 /**
  * Build GitHub file URL for a repository.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
- * @param file_path Path to the file (leading './' is stripped)
- * @param line Optional line number for deep linking
- * @returns Full GitHub URL to the file on the main branch
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
+ * @param file_path - path to the file (leading './' is stripped)
+ * @param line - optional line number for deep linking
+ * @returns full GitHub URL to the file on the main branch
  *
  * @example
  * ```ts
@@ -53,9 +53,9 @@ export const url_github_file = (repo_url: string, file_path: string, line?: numb
 /**
  * Build GitHub organization URL from repo URL and repo name.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
- * @param repo_name Repository name to strip from the URL
- * @returns Organization URL, or null if repo_url doesn't end with repo_name
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
+ * @param repo_name - repository name to strip from the URL
+ * @returns organization URL, or null if repo_url doesn't end with repo_name
  *
  * @example
  * ```ts
@@ -70,8 +70,8 @@ export const url_github_org = (repo_url: string, repo_name: string): string | nu
 /**
  * Extract GitHub owner/org name from repository URL.
  *
- * @param repo_url Repository URL (e.g., 'https://github.com/owner/repo')
- * @returns Owner name, or null if not a valid GitHub URL
+ * @param repo_url - repository URL (e.g., 'https://github.com/owner/repo')
+ * @returns owner name, or null if not a valid GitHub URL
  *
  * @example
  * ```ts
@@ -95,8 +95,8 @@ export const repo_url_github_owner = (repo_url: string): string | null => {
 /**
  * Build npm package URL.
  *
- * @param package_name Package name (can be scoped like '@org/package')
- * @returns Full npm package page URL
+ * @param package_name - package name (can be scoped like '@org/package')
+ * @returns full npm package page URL
  *
  * @example
  * ```ts
@@ -115,8 +115,8 @@ 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
- * @returns True if the package appears to be published
+ * @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 => {
 	return !package_json.private && !!package_json.exports && package_json.version !== '0.0.1';
@@ -125,8 +125,8 @@ export const package_is_published = (package_json: PackageJson): boolean => {
 /**
  * Extract repository name without scope from package name.
  *
- * @param name Package name (can be scoped like '@org/package')
- * @returns Repository name without scope
+ * @param name - package name (can be scoped like '@org/package')
+ * @returns repository name without scope
  * @throws Error if scoped package name is malformed
  *
  * @example
@@ -158,8 +158,8 @@ export const repo_name_parse = (name: string): string => {
  * 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
- * @returns Clean repository URL, or null if not provided
+ * @param repository - the repository field from package.json
+ * @returns clean repository URL, or null if not provided
  *
  * @example
  * ```ts
@@ -189,9 +189,9 @@ export const repo_url_parse = (repository: PackageJson['repository']): string |
 /**
  * Build .well-known URL for package metadata files.
  *
- * @param homepage_url Package homepage URL
- * @param filename Filename in .well-known directory
- * @returns Full URL to the .well-known file
+ * @param homepage_url - package homepage URL
+ * @param filename - filename in .well-known directory
+ * @returns full URL to the .well-known file
  *
  * @example
  * ```ts

package/src/lib/storage.ts

@@ -18,10 +18,10 @@ export const save_to_storage = (key: string, value: any, is_json = false): void
 
 /**
  * Utility function to load a value from `localStorage` with optional parsing
- * @param key The localStorage key
- * @param is_json Whether to parse the value as JSON
- * @param parse_fn Optional custom parsing function to transform the value
- * @returns The parsed value or null if not found or parsing fails
+ * @param key - the localStorage key
+ * @param is_json - whether to parse the value as JSON
+ * @param parse_fn - optional custom parsing function to transform the value
+ * @returns the parsed value or null if not found or parsing fails
  */
 export const load_from_storage = <T>(
 	key: string,

package/src/lib/svelte_helpers.ts

@@ -76,12 +76,12 @@ export interface SvelteFileAnalysis {
  * Returns raw analysis data matching `ModuleAnalysis` structure.
  * Consumer decides filtering policy (Svelte components are never nodocs).
  *
- * @param source_file The source file info (from Gro filer, file system, or other source)
- * @param module_path The module path (relative to source root)
- * @param checker TypeScript type checker
- * @param options Module source options for path extraction
- * @param ctx Analysis context for collecting diagnostics
- * @returns Module analysis matching ModuleAnalysis structure
+ * @param source_file - the source file info (from Gro filer, file system, or other source)
+ * @param module_path - the module path (relative to source root)
+ * @param checker - TypeScript type checker
+ * @param options - module source options for path extraction
+ * @param ctx - analysis context for collecting diagnostics
+ * @returns module analysis matching `ModuleAnalysis` structure
  */
 export const svelte_analyze_module = (
 	source_file: SourceFileInfo,
@@ -118,11 +118,11 @@ export const svelte_analyze_module = (
  *
  * Suitable for use in documentation generators, build tools, and analysis.
  *
- * @param source_file Source file info with path and content
- * @param module_path Module path relative to source root (e.g., 'Alert.svelte')
- * @param checker TypeScript type checker for type resolution
- * @param ctx Analysis context for collecting diagnostics
- * @returns Component declaration and optional module-level comment
+ * @param source_file - source file info with path and content
+ * @param module_path - module path relative to source root (e.g., 'Alert.svelte')
+ * @param checker - TypeScript type checker for type resolution
+ * @param ctx - analysis context for collecting diagnostics
+ * @returns component declaration and optional module-level comment
  */
 export const svelte_analyze_file = (
 	source_file: SourceFileInfo,
@@ -259,8 +259,8 @@ export const svelte_extract_script_content = (svelte_source: string): string | u
  * Requires `@module` tag to identify module comments. The tag line is stripped
  * from the output.
  *
- * @param script_content - The content of the `<script>` tag.
- * @returns The cleaned module comment text, or undefined if none found.
+ * @param script_content - the content of the `<script>` tag
+ * @returns the cleaned module comment text, or undefined if none found
  */
 export const svelte_extract_module_comment = (script_content: string): string | undefined => {
 	// Parse the script content as TypeScript and reuse the shared extraction logic

package/src/lib/svelte_preprocess_mdz.ts

@@ -98,8 +98,8 @@ const PRECOMPILED_NAME = 'MdzPrecompiled';
 /**
  * Creates a Svelte preprocessor that compiles static `Mdz` content at build time.
  *
- * @param options Configuration for component/element resolution and file filtering.
- * @returns A Svelte `PreprocessorGroup` for use in `svelte.config.js`.
+ * @param options - configuration for component/element resolution and file filtering
+ * @returns a Svelte `PreprocessorGroup` for use in `svelte.config.js`
  */
 export const svelte_preprocess_mdz = (
 	options: SveltePreprocessMdzOptions = {},

package/src/lib/tome.ts

@@ -18,7 +18,7 @@ export const Tome = z.object({
 export type Tome = z.infer<typeof Tome>;
 
 /**
- * @param hash - URL fragment to append, with or without the `#`.
+ * @param hash - URL fragment to append, with or without the `#`
  */
 export const to_tome_pathname = (
 	item: Tome | string,

package/src/lib/ts_helpers.ts

@@ -63,9 +63,9 @@ export interface ModuleExportsAnalysis {
 /**
  * Create TypeScript program for analysis.
  *
- * @param options Configuration options for program creation
- * @param log Optional logger for info messages
- * @returns The program and type checker
+ * @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
  */
 export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsProgram => {
@@ -100,13 +100,13 @@ export const ts_create_program = (options?: TsProgramOptions, log?: Logger): TsP
  * This is a high-level function suitable for building documentation or library metadata.
  * For lower-level analysis, use `ts_analyze_module_exports` directly.
  *
- * @param source_file_info The source file info (from Gro filer, file system, or other source)
- * @param ts_source_file TypeScript source file from the program
- * @param module_path The module path (relative to source root)
- * @param checker TypeScript type checker
- * @param options Module source options for path extraction
- * @param ctx Analysis context for collecting diagnostics
- * @returns Module metadata and re-export information
+ * @param source_file_info - the source file info (from Gro filer, file system, or other source)
+ * @param ts_source_file - TypeScript source file from the program
+ * @param module_path - the module path (relative to source root)
+ * @param checker - TypeScript type checker
+ * @param options - module source options for path extraction
+ * @param ctx - analysis context for collecting diagnostics
+ * @returns module metadata and re-export information
  */
 export const ts_analyze_module = (
 	source_file_info: SourceFileInfo,
@@ -151,11 +151,11 @@ export const ts_analyze_module = (
  * suitable for building documentation, API explorers, or analysis tools.
  * For standard SvelteKit library layouts, use `module_create_source_options(process.cwd())`.
  *
- * @param source_file The TypeScript source file to analyze
- * @param checker The TypeScript type checker
- * @param options Module source options for path extraction in re-exports
- * @param ctx Analysis context for collecting diagnostics
- * @returns Module comment, declarations, re-exports, and star exports
+ * @param source_file - the TypeScript source file to analyze
+ * @param checker - the TypeScript type checker
+ * @param options - module source options for path extraction in re-exports
+ * @param ctx - analysis context for collecting diagnostics
+ * @returns module comment, declarations, re-exports, and star exports
  */
 export const ts_analyze_module_exports = (
 	source_file: ts.SourceFile,
@@ -275,11 +275,11 @@ export const ts_analyze_module_exports = (
  * type analysis to produce complete declaration metadata. Suitable for use
  * in documentation generators, IDE integrations, and other tooling.
  *
- * @param symbol The TypeScript symbol to analyze
- * @param source_file The source file containing the symbol
- * @param checker The TypeScript type checker
- * @param ctx Optional analysis context for collecting diagnostics
- * @returns Complete declaration metadata including docs, types, and parameters, plus nodocs flag
+ * @param symbol - the TypeScript symbol to analyze
+ * @param source_file - the source file containing the symbol
+ * @param checker - the TypeScript type checker
+ * @param ctx - optional analysis context for collecting diagnostics
+ * @returns complete declaration metadata including docs, types, and parameters, plus nodocs flag
  */
 export const ts_analyze_declaration = (
 	symbol: ts.Symbol,
@@ -431,10 +431,10 @@ export const ts_infer_declaration_kind = (symbol: ts.Symbol, node: ts.Node): Dec
  * Shared helper for extracting parameter information from both standalone functions
  * and class methods/constructors.
  *
- * @param sig The TypeScript signature to extract parameters from
- * @param checker TypeScript type checker for type resolution
- * @param tsdoc_params Map of parameter names to TSDoc descriptions (from tsdoc.params)
- * @returns Array of parameter info objects
+ * @param sig - the TypeScript signature to extract parameters from
+ * @param checker - TypeScript type checker for type resolution
+ * @param tsdoc_params - map of parameter names to TSDoc descriptions (from tsdoc.params)
+ * @returns array of parameter info objects
  */
 export const ts_extract_signature_parameters = (
 	sig: ts.Signature,

package/src/lib/tsdoc_helpers.ts

@@ -83,8 +83,8 @@ export interface TsdocParsedComment {
  * - `@since` - version information
  * - `@mutates` - mutation documentation (non-standard)
  *
- * @param node The TypeScript node to extract JSDoc from
- * @param source_file Source file (used for extracting full` @see` tag text)
+ * @param node - the TypeScript node to extract JSDoc from
+ * @param source_file - source file (used for extracting full ` @see` tag text)
  */
 export const tsdoc_parse = (
 	node: ts.Node,
@@ -186,8 +186,8 @@ export const tsdoc_parse = (
  * Consolidates the common pattern of assigning TSDoc fields to declarations,
  * with conditional assignment for array fields (only if non-empty).
  *
- * @param declaration declaration object to update
- * @param tsdoc parsed TSDoc comment (if available)
+ * @param declaration - declaration object to update
+ * @param tsdoc - parsed TSDoc comment (if available)
  * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
  */
 export const tsdoc_apply_to_declaration = (
@@ -219,8 +219,8 @@ export const tsdoc_apply_to_declaration = (
  *
  * 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
+ * @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

package/src/lib/tsdoc_mdz.ts

@@ -8,7 +8,7 @@
  * @module
  */
 
-import {mdz_is_url} from './mdz.js';
+import {mdz_is_url} from './mdz_helpers.js';
 
 /** Format a reference as mdz: URLs pass through, identifiers get backticks. */
 const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${ref}\``);