@fuzdev/fuz_ui 0.206.7 → 0.206.9

package/src/lib/declaration.svelte.ts

@@ -5,12 +5,13 @@ import type {
 	ParameterJsonInput,
 	ComponentPropJsonInput,
 	OverloadJsonInput,
-	Reactivity,
+	Reactivity
 } from 'svelte-docinfo/types.js';
-import {generateImport, getDisplayName} from 'svelte-docinfo/declaration-helpers.js';
+import { generateImport, getDisplayName } from 'svelte-docinfo/declaration-helpers.js';
+import { EMPTY_ARRAY } from '@fuzdev/fuz_util/array.ts';
 
-import type {Module} from './module.svelte.ts';
-import {url_github_file} from '@fuzdev/fuz_util/package_helpers.ts';
+import type { Module } from './module.svelte.ts';
+import { url_github_file } from '@fuzdev/fuz_util/package_helpers.ts';
 
 // The `virtual:svelte-docinfo` module is serialized with svelte-docinfo's
 // `compactReplacer`, which strips empty default arrays — so the runtime data
@@ -27,9 +28,11 @@ const field = <T>(decl: DeclarationJsonInput, key: string): T | undefined =>
  * Rich runtime representation of an exported declaration.
  *
  * Wraps svelte-docinfo's `DeclarationJson` discriminated union (on `kind`)
- * with Svelte 5 reactive derivations and computed URLs.
- * Kind-specific fields are accessed via the `field()` helper since
- * not all fields exist on all variants.
+ * with computed properties and URLs. Kind-specific fields are accessed via
+ * the `field()` helper since not all fields exist on all variants.
+ *
+ * Computed properties are plain getters rather than `$derived` — see
+ * `Library` for why.
  *
  * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
  * @see `DeclarationDetail.svelte` for the rendering component
@@ -38,136 +41,228 @@ export class Declaration {
 	readonly module: Module = $state.raw()!;
 	readonly declaration_json: DeclarationJsonInput = $state.raw()!;
 
-	library = $derived(this.module.library);
+	get library(): Module['library'] {
+		return this.module.library;
+	}
 
 	/**
 	 * Module path where this declaration is defined.
 	 */
-	module_path = $derived(this.module.path);
+	get module_path(): string {
+		return this.module.path;
+	}
+
+	get name(): string {
+		return this.declaration_json.name;
+	}
 
-	name = $derived(this.declaration_json.name);
-	kind = $derived(this.declaration_json.kind);
+	get kind(): DeclarationJsonInput['kind'] {
+		return this.declaration_json.kind;
+	}
 
 	/**
 	 * GitHub source URL with line number.
 	 */
-	url_github = $derived(
-		this.library.repo_url && this.declaration_json.sourceLine
+	get url_github(): string | undefined {
+		return this.library.repo_url && this.declaration_json.sourceLine
 			? url_github_file(
 					this.library.repo_url,
 					`src/lib/${this.module_path}`,
-					this.declaration_json.sourceLine,
+					this.declaration_json.sourceLine
 				)
-			: undefined,
-	);
+			: undefined;
+	}
 
 	/**
 	 * API documentation URL.
 	 */
-	url_api = $derived(`/docs/api${this.library.url_prefix}/${this.module_path}#${this.name}`);
+	get url_api(): string {
+		return `/docs/api${this.library.url_prefix}/${this.module_path}#${this.name}`;
+	}
+
+	#import_statement: string | undefined;
 
 	/**
 	 * Generated TypeScript import statement.
 	 */
-	import_statement = $derived(
+	get import_statement(): string {
 		// `generateImport` reads only `name`/`kind`/path, none of the defaulted
 		// arrays, so asserting the parsed shape here is sound.
-		generateImport(
+		return (this.#import_statement ??= generateImport(
 			this.declaration_json as DeclarationJson,
 			this.module_path,
-			this.library.pkg_json.name,
-		),
-	);
+			this.library.pkg_json.name
+		));
+	}
 
 	/**
 	 * Public documentation link (if homepage_url is available).
 	 */
-	url_api_full = $derived(
-		this.library.homepage_url
+	get url_api_full(): string | undefined {
+		return this.library.homepage_url
 			? `${this.library.homepage_url.replace(/\/$/, '')}/docs/api/${this.module_path}#${this.name}`
-			: undefined,
-	);
+			: undefined;
+	}
+
+	#display_name: string | undefined;
 
 	/**
 	 * Display name with generic parameters.
 	 */
-	// `getDisplayName` reads `genericParams` unguarded, so feed it the defaulted
-	// value rather than the raw (possibly-absent) input field.
-	display_name = $derived(
-		getDisplayName({
+	get display_name(): string {
+		// `getDisplayName` reads `genericParams` unguarded, so feed it the defaulted
+		// value rather than the raw (possibly-absent) input field.
+		return (this.#display_name ??= getDisplayName({
 			...this.declaration_json,
-			genericParams: this.declaration_json.genericParams ?? [],
-		} as DeclarationJson),
-	);
-
-	type_signature = $derived(this.declaration_json.typeSignature);
-	doc_comment = $derived(this.declaration_json.docComment);
-	deprecated_message = $derived(this.declaration_json.deprecatedMessage);
-	parameters = $derived(field<Array<ParameterJsonInput>>(this.declaration_json, 'parameters'));
-	props = $derived(field<Array<ComponentPropJsonInput>>(this.declaration_json, 'props'));
-	return_type = $derived(field<string>(this.declaration_json, 'returnType'));
-	return_description = $derived(field<string>(this.declaration_json, 'returnDescription'));
-	generic_params = $derived(this.declaration_json.genericParams ?? []);
-	extends_type = $derived(field<string | Array<string>>(this.declaration_json, 'extends'));
-	implements_types = $derived(field<Array<string>>(this.declaration_json, 'implements'));
-	throws = $derived(this.declaration_json.throws ?? []);
-	since = $derived(this.declaration_json.since);
-	examples = $derived(this.declaration_json.examples ?? []);
-	see_also = $derived(this.declaration_json.seeAlso ?? []);
+			genericParams: this.declaration_json.genericParams ?? []
+		} as DeclarationJson));
+	}
+
+	get type_signature(): string | undefined {
+		return this.declaration_json.typeSignature;
+	}
+
+	get doc_comment(): string | undefined {
+		return this.declaration_json.docComment;
+	}
+
+	get deprecated_message(): string | undefined {
+		return this.declaration_json.deprecatedMessage;
+	}
+
+	get parameters(): Array<ParameterJsonInput> | undefined {
+		return field<Array<ParameterJsonInput>>(this.declaration_json, 'parameters');
+	}
+
+	get props(): Array<ComponentPropJsonInput> | undefined {
+		return field<Array<ComponentPropJsonInput>>(this.declaration_json, 'props');
+	}
+
+	get return_type(): string | undefined {
+		return field<string>(this.declaration_json, 'returnType');
+	}
+
+	get return_description(): string | undefined {
+		return field<string>(this.declaration_json, 'returnDescription');
+	}
+
+	get generic_params(): NonNullable<DeclarationJsonInput['genericParams']> {
+		return this.declaration_json.genericParams ?? EMPTY_ARRAY;
+	}
+
+	get extends_type(): string | Array<string> | undefined {
+		return field<string | Array<string>>(this.declaration_json, 'extends');
+	}
+
+	get implements_types(): Array<string> | undefined {
+		return field<Array<string>>(this.declaration_json, 'implements');
+	}
+
+	get throws(): NonNullable<DeclarationJsonInput['throws']> {
+		return this.declaration_json.throws ?? EMPTY_ARRAY;
+	}
+
+	get since(): string | undefined {
+		return this.declaration_json.since;
+	}
+
+	get examples(): NonNullable<DeclarationJsonInput['examples']> {
+		return this.declaration_json.examples ?? EMPTY_ARRAY;
+	}
+
+	get see_also(): NonNullable<DeclarationJsonInput['seeAlso']> {
+		return this.declaration_json.seeAlso ?? EMPTY_ARRAY;
+	}
+
 	/**
 	 * Nested members for classes, interfaces, types, and enums.
 	 */
-	members = $derived(field<Array<MemberJsonInput>>(this.declaration_json, 'members'));
+	get members(): Array<MemberJsonInput> | undefined {
+		return field<Array<MemberJsonInput>>(this.declaration_json, 'members');
+	}
 
 	/**
 	 * Intersection types whose properties are external (filtered out of props/members).
 	 * Present on `component` and `type` kinds.
 	 */
-	intersects = $derived(field<Array<string>>(this.declaration_json, 'intersects'));
+	get intersects(): Array<string> | undefined {
+		return field<Array<string>>(this.declaration_json, 'intersects');
+	}
 
 	/**
 	 * Whether a component accepts children via props or template usage.
 	 * Present on `component` kind only.
 	 */
-	accepts_children = $derived(field<boolean>(this.declaration_json, 'acceptsChildren'));
+	get accepts_children(): boolean | undefined {
+		return field<boolean>(this.declaration_json, 'acceptsChildren');
+	}
 
 	/**
 	 * Function overload signatures when multiple public overloads exist.
 	 * Present on `function` and `snippet` kinds, and on function/constructor members.
 	 */
-	overloads = $derived(field<Array<OverloadJsonInput>>(this.declaration_json, 'overloads'));
+	get overloads(): Array<OverloadJsonInput> | undefined {
+		return field<Array<OverloadJsonInput>>(this.declaration_json, 'overloads');
+	}
 
 	/**
 	 * Re-export alias info when this declaration is a renamed re-export.
 	 */
-	alias_of = $derived(this.declaration_json.aliasOf);
+	get alias_of(): DeclarationJsonInput['aliasOf'] {
+		return this.declaration_json.aliasOf;
+	}
 
 	/**
 	 * Other modules that also export this declaration (re-export paths
 	 * relative to src/lib). Absent when only exported from its defining module.
 	 * The back-link of those modules' `Module.re_exports` edges.
 	 */
-	also_exported_from = $derived(this.declaration_json.alsoExportedFrom);
+	get also_exported_from(): DeclarationJsonInput['alsoExportedFrom'] {
+		return this.declaration_json.alsoExportedFrom;
+	}
 
 	/**
 	 * Mutation documentation from `@mutates` tags, mapping parameter names to descriptions.
 	 */
-	mutates = $derived(this.declaration_json.mutates);
+	get mutates(): DeclarationJsonInput['mutates'] {
+		return this.declaration_json.mutates;
+	}
 
 	/**
 	 * Svelte reactivity flavor (`$state`, `$state.raw`, `$derived`, `$derived.by`)
 	 * when this variable is initialized with a value-producing rune.
 	 * Present on `variable` kind only.
 	 */
-	reactivity = $derived(field<Reactivity>(this.declaration_json, 'reactivity'));
+	get reactivity(): Reactivity | undefined {
+		return field<Reactivity>(this.declaration_json, 'reactivity');
+	}
+
+	get has_examples(): boolean {
+		return this.examples.length > 0;
+	}
 
-	has_examples = $derived(this.examples.length > 0);
 	// presence, not truthiness — a bare `@deprecated` (no message text) arrives as `''`
-	is_deprecated = $derived(this.deprecated_message !== undefined);
-	has_documentation = $derived(!!this.doc_comment);
-	has_parameters = $derived(!!(this.parameters && this.parameters.length > 0));
-	has_props = $derived(!!(this.props && this.props.length > 0));
-	has_generics = $derived(this.generic_params.length > 0);
+	get is_deprecated(): boolean {
+		return this.deprecated_message !== undefined;
+	}
+
+	get has_documentation(): boolean {
+		return !!this.doc_comment;
+	}
+
+	get has_parameters(): boolean {
+		const { parameters } = this;
+		return !!(parameters && parameters.length > 0);
+	}
+
+	get has_props(): boolean {
+		const { props } = this;
+		return !!(props && props.length > 0);
+	}
+
+	get has_generics(): boolean {
+		return this.generic_params.length > 0;
+	}
 
 	constructor(module: Module, declaration_json: DeclarationJsonInput) {
 		this.module = module;

package/src/lib/declaration_contextmenu.ts

@@ -1,10 +1,10 @@
-import type {Declaration} from './declaration.svelte.ts';
-import type {ContextmenuParams} from './contextmenu_state.svelte.ts';
+import type { Declaration } from './declaration.svelte.ts';
+import type { ContextmenuParams } from './contextmenu_state.svelte.ts';
 
 // TODO @many expand contextmenus for docs
 
 export const create_declaration_contextmenu = (
-	declaration: Declaration,
+	declaration: Declaration
 ): Array<ContextmenuParams> => {
 	const entries: Array<ContextmenuParams> = [];
 
@@ -13,8 +13,8 @@ export const create_declaration_contextmenu = (
 		entries.push({
 			snippet: 'link',
 			props: {
-				href: declaration.url_github,
-			},
+				href: declaration.url_github
+			}
 		});
 	}
 

package/src/lib/dialog.ts

@@ -1,4 +1,4 @@
-import {create_context} from './context_helpers.ts';
+import { create_context } from './context_helpers.ts';
 
 export type DialogAlign = 'center' | 'top';
 export const dialog_aligns: Array<DialogAlign> = ['center', 'top'];

package/src/lib/docs_helpers.svelte.ts

@@ -1,8 +1,8 @@
-import {resolve} from '$app/paths';
-import {SvelteMap, SvelteSet} from 'svelte/reactivity';
-import {ensure_end, ensure_start} from '@fuzdev/fuz_util/string.ts';
+import { resolve } from '$app/paths';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { ensure_end, ensure_start } from '@fuzdev/fuz_util/string.ts';
 
-import {create_context} from './context_helpers.ts';
+import { create_context } from './context_helpers.ts';
 
 export const docs_links_context = create_context<DocsLinks>();
 
@@ -36,12 +36,12 @@ export const DOCS_API_PATH = DOCS_PATH + '/api';
 export const to_docs_path_info = (
 	path_slug: string,
 	pathname: string,
-	root_path = DOCS_PATH_DEFAULT,
-): {path: string; path_is_selected: boolean; path_segment: string | undefined} => {
+	root_path = DOCS_PATH_DEFAULT
+): { path: string; path_is_selected: boolean; path_segment: string | undefined } => {
 	const path_segment = pathname.split('/').at(-1);
 	const path = resolve((ensure_end(ensure_start(root_path, '/'), '/') + path_slug) as any);
 	const path_is_selected = path_segment === path_slug; // messy but works
-	return {path, path_is_selected, path_segment};
+	return { path, path_is_selected, path_segment };
 };
 
 export type DocsLinkTag = 'h2' | 'h3' | 'h4';
@@ -118,7 +118,7 @@ export class DocsLinks {
 		tag?: DocsLinkTag,
 		depth = 1,
 		parent_id?: string,
-		explicit_id?: string,
+		explicit_id?: string
 	): string {
 		// Use explicit ID if provided, otherwise generate one
 		const id = explicit_id ?? 'docs_link_' + this.#next_id++;
@@ -133,7 +133,7 @@ export class DocsLinks {
 			this.#fragment_to_order.set(page_fragment_key, order);
 		}
 
-		this.links.set(id, {id, fragment, text, tag, depth, order, parent_id});
+		this.links.set(id, { id, fragment, text, tag, depth, order, parent_id });
 		return id;
 	}