@fuzdev/fuz_ui 0.169.0

package/src/lib/declaration_contextmenu.ts

@@ -0,0 +1,22 @@
+import type {Declaration} from './declaration.svelte.js';
+import type {ContextmenuParams} from './contextmenu_state.svelte.js';
+
+// TODO @many expand contextmenus for docs
+
+export const create_declaration_contextmenu = (
+	declaration: Declaration,
+): Array<ContextmenuParams> => {
+	const entries: Array<ContextmenuParams> = [];
+
+	// View source on GitHub
+	if (declaration.url_github) {
+		entries.push({
+			snippet: 'link',
+			props: {
+				href: declaration.url_github,
+			},
+		});
+	}
+
+	return entries;
+};

package/src/lib/dialog.ts

@@ -0,0 +1,35 @@
+import type {ComponentProps, Component} from 'svelte';
+
+import type Dialog from './Dialog.svelte';
+
+/**
+ * This helper function is needed to construct `DialogParams` with type safety.
+ * It uses TypeScript's inferred generics for functions,
+ * which do not work for plain objects as of v5.0.4.
+ * * `ContextmenuParams` uses a similar strategy.
+ */
+export const to_dialog_params = <T extends Component<any>>(
+	Component: T,
+	props: ComponentProps<T>,
+	dialog_props?: Partial<ComponentProps<typeof Dialog>>,
+): DialogParams<T> => ({
+	Component,
+	props,
+	dialog_props,
+});
+
+/**
+ * This pattern is based on:
+ * https://github.com/ivanhofer/sveltekit-typescript-showcase/blob/main/src/01-props/09-svelte-component/Component.svelte
+ * The main limitation is that the generic cannot be inferred automatically,
+ * so we use `to_dialog_params` to construct instances in most cases.
+ * Definining `DialogParams` with no concrete `T` lacks typechecking for `props`.
+ */
+export interface DialogParams<T extends Component<any> = Component<any>> {
+	Component: T;
+	props: ComponentProps<T>;
+	dialog_props?: Partial<ComponentProps<typeof Dialog>> | undefined;
+}
+
+export type DialogLayout = 'centered' | 'page';
+export const dialog_layouts: Array<DialogLayout> = ['centered', 'page'];

package/src/lib/dimensions.svelte.ts

@@ -0,0 +1,4 @@
+export class Dimensions {
+	width: number = $state(0);
+	height: number = $state(0);
+}

package/src/lib/docs_helpers.svelte.ts

@@ -0,0 +1,149 @@
+import {resolve} from '$app/paths';
+import {SvelteMap, SvelteSet} from 'svelte/reactivity';
+import {ensure_end, ensure_start} from '@fuzdev/fuz_util/string.js';
+
+import {create_context} from './context_helpers.js';
+
+/**
+ * Convert a string to a URL-safe fragment identifier, preserving case for API declarations.
+ * Only transforms spaces and special characters, keeping valid identifier characters intact.
+ * Used for hash anchors in documentation.
+ * @param str - The string to convert to a fragment
+ * @returns A URL-safe fragment identifier
+ */
+export const docs_slugify = (str: string): string => {
+	return (
+		str
+			.trim()
+			// Replace spaces and multiple hyphens with single hyphen
+			.replace(/\s+/g, '-')
+			.replace(/-+/g, '-')
+			// Remove invalid characters (keep letters, digits, _, $, -)
+			.replace(/[^\w$-]/g, '')
+			// Remove leading/trailing hyphens
+			.replace(/^-+|-+$/g, '')
+	);
+};
+
+export const DOCS_PATH_DEFAULT = '/docs';
+export const DOCS_PATH = resolve('/docs');
+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} => {
+	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};
+};
+
+export const docs_links_context = create_context<DocsLinks>();
+
+export type DocsLinkTag = 'h2' | 'h3' | 'h4';
+
+export interface DocsLinkInfo {
+	id: string;
+	text: string;
+	fragment: string;
+	tag: DocsLinkTag | undefined;
+	depth: number;
+	order: number;
+	parent_id: string | undefined;
+}
+
+export class DocsLinks {
+	readonly root_path: string;
+
+	readonly links: SvelteMap<string, DocsLinkInfo> = new SvelteMap();
+
+	// Maps compound keys (pathname#fragment) to their original order
+	// This preserves order across component remounts
+	#fragment_to_order: Map<string, number> = new Map();
+
+	// Counter for generating unique IDs
+	#next_id = 0;
+
+	// Counter for generating section IDs (page-scoped, not module-scoped)
+	#section_counter = 0;
+
+	// Counter for generating link order values (page-scoped, not module-scoped)
+	// This ensures consistent ordering between SSR and client hydration
+	#order_counter = 0;
+
+	docs_links = $derived.by(() => {
+		// Build parent-child map
+		const children_map: Map<string | undefined, Array<DocsLinkInfo>> = new Map();
+
+		for (const link of this.links.values()) {
+			if (!children_map.has(link.parent_id)) {
+				children_map.set(link.parent_id, []);
+			}
+			children_map.get(link.parent_id)!.push(link);
+		}
+
+		// Sort siblings by order
+		for (const siblings of children_map.values()) {
+			siblings.sort((a, b) => a.order - b.order);
+		}
+
+		// Flatten tree with depth-first traversal
+		const result: Array<DocsLinkInfo> = [];
+		const traverse = (parent_id: string | undefined) => {
+			const children = children_map.get(parent_id) || [];
+			for (const child of children) {
+				result.push(child);
+				traverse(child.id); // recursively add children
+			}
+		};
+
+		traverse(undefined); // start with root nodes (no parent)
+		return result;
+	});
+
+	readonly fragments_onscreen: SvelteSet<string> = new SvelteSet();
+
+	constructor(root_path = DOCS_PATH_DEFAULT) {
+		this.root_path = root_path;
+	}
+
+	add(
+		fragment: string,
+		text: string,
+		pathname: string,
+		tag?: DocsLinkTag,
+		depth = 1,
+		parent_id?: string,
+		explicit_id?: string,
+	): string {
+		// Use explicit ID if provided, otherwise generate one
+		const id = explicit_id ?? 'docs_link_' + this.#next_id++;
+
+		// Use compound key (pathname#fragment) to preserve order across remounts
+		const page_fragment_key = `${pathname}#${fragment}`;
+		const existing_order = this.#fragment_to_order.get(page_fragment_key);
+		const order = existing_order ?? this.#order_counter++;
+
+		// Store order for new fragments only
+		if (existing_order === undefined) {
+			this.#fragment_to_order.set(page_fragment_key, order);
+		}
+
+		this.links.set(id, {id, fragment, text, tag, depth, order, parent_id});
+		return id;
+	}
+
+	remove(id: string): void {
+		this.links.delete(id);
+	}
+
+	/**
+	 * Generate a unique section ID for the current page render.
+	 * This counter is instance-scoped, ensuring SSR/client consistency.
+	 */
+	generate_section_id(): string {
+		return `section_${this.#section_counter++}`;
+	}
+}

package/src/lib/helpers.ts

@@ -0,0 +1,10 @@
+export const render_value_to_string = (value: unknown): string => {
+	if (value === null) return 'null';
+	if (value === undefined) return 'undefined';
+	const type = typeof value;
+	if (type === 'string') return `'${value}'`; // eslint-disable-line @typescript-eslint/no-base-to-string
+	if (type === 'number' || type === 'boolean') return value + ''; // eslint-disable-line @typescript-eslint/no-base-to-string
+	if (Array.isArray(value)) return `[${value.map(render_value_to_string).join(', ')}]`;
+	if (type === 'object') return JSON.stringify(value);
+	return value + ''; // eslint-disable-line @typescript-eslint/no-base-to-string
+};

package/src/lib/intersect.svelte.ts

@@ -0,0 +1,152 @@
+import type {Attachment} from 'svelte/attachments';
+import {deep_equal} from '@fuzdev/fuz_util/deep_equal.js';
+
+export interface IntersectParams {
+	/**
+	 * Called when the element enters or leaves the viewport until disconnected.
+	 */
+	onintersect?: OnIntersect;
+	/**
+	 * Called when the attachment's observer is disconnected,
+	 * either by the user calling disconnect or the attachment being destroyed.
+	 */
+	ondisconnect?: OnDisconnect;
+	/**
+	 * A value of `1` disconnects after `el` enters and leaves the viewport one time,
+	 * similar to 'once' for an event.
+	 * `0` disables and `undefined` or a negative number like `-1` never disconnects.
+	 */
+	count?: number;
+	/**
+	 * Same as the `options` param to
+	 * [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#options)
+	 */
+	options?: IntersectionObserverInit;
+}
+
+export type IntersectParamsOrCallback = OnIntersect | IntersectParams;
+
+/**
+ * Creates an attachment that observes element viewport intersection.
+ * Uses the lazy function pattern to optimize reactivity:
+ * callbacks can update without recreating the observer, preserving state.
+ * @param get_params Function that returns callback, params object, or nullish to disable
+ */
+export const intersect =
+	(
+		get_params: () => IntersectParamsOrCallback | null | undefined,
+	): Attachment<HTMLElement | SVGElement> =>
+	(el) => {
+		// State that persists across callback changes
+		let intersecting = false;
+		let intersections = 0;
+		let observer: IntersectionObserver | null = null;
+		let current_options: IntersectionObserverInit | undefined = undefined;
+
+		// Current callbacks - updated reactively without recreating observer
+		let current_onintersect: OnIntersect | undefined;
+		let current_ondisconnect: OnDisconnect | undefined;
+		let current_count: number | undefined;
+
+		const disconnect = (): void => {
+			if (!observer) return;
+			const observer_to_disconnect = observer;
+			observer.disconnect();
+			if (current_ondisconnect) {
+				current_ondisconnect({intersecting, intersections, el, observer: observer_to_disconnect});
+			}
+			observer = null;
+		};
+
+		$effect(() => {
+			const params = get_params();
+
+			if (params == null) {
+				// Params disabled, disconnect if active
+				current_onintersect = undefined;
+				current_ondisconnect = undefined;
+				current_count = undefined;
+				if (observer) {
+					disconnect();
+				}
+				return;
+			}
+
+			// Parse params and update current callbacks
+			let options: IntersectionObserverInit | undefined;
+			if (typeof params === 'function') {
+				current_onintersect = params;
+				current_ondisconnect = undefined;
+				current_count = undefined;
+				options = undefined;
+			} else {
+				current_onintersect = params.onintersect;
+				current_ondisconnect = params.ondisconnect;
+				current_count = params.count;
+				options = params.options;
+			}
+
+			// Check if count is 0 (disabled)
+			if (current_count === 0) {
+				if (observer) {
+					disconnect();
+				}
+				return;
+			}
+
+			// Check if options changed (requires observer recreation)
+			const options_changed = !deep_equal(current_options, options);
+
+			if (options_changed || !observer) {
+				// Disconnect old observer if exists
+				if (observer) {
+					disconnect();
+				}
+
+				// Reset state on observer recreation
+				intersecting = false;
+				intersections = 0;
+				current_options = options;
+
+				// Create new observer
+				observer = new IntersectionObserver((entries) => {
+					intersecting = entries[0]!.isIntersecting;
+					if (current_onintersect && observer) {
+						current_onintersect({intersecting, intersections, el, observer, disconnect});
+					}
+					if (intersecting) {
+						intersections++;
+					} else {
+						if (current_count && current_count > 0 && intersections >= current_count) {
+							disconnect();
+						}
+					}
+				}, options);
+				observer.observe(el);
+			}
+			// If only callbacks changed, observer stays alive and uses new callbacks from closure
+		});
+
+		return disconnect;
+	};
+
+// TODO how to forward generic `el` type?
+export type OnIntersect = (state: IntersectState) => void;
+
+export interface IntersectState {
+	intersecting: boolean;
+	intersections: number;
+	el: HTMLElement | SVGElement;
+	observer: IntersectionObserver;
+	disconnect: () => void;
+}
+
+// TODO how to forward generic `el` type?
+export type OnDisconnect = (state: DisconnectState) => void;
+
+export interface DisconnectState {
+	intersecting: boolean;
+	intersections: number;
+	el: HTMLElement | SVGElement;
+	observer: IntersectionObserver;
+}

package/src/lib/library.svelte.ts

@@ -0,0 +1,162 @@
+import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
+
+import {create_context} from './context_helpers.js';
+import {Declaration} from './declaration.svelte.js';
+import {Module} from './module.svelte.js';
+
+/**
+ * Rich runtime representation of a library.
+ *
+ * Wraps `LibraryJson` with computed properties and provides the root
+ * of the API documentation hierarchy: Library → modules → declarations
+ *
+ * @see module.svelte.ts for Module class
+ * @see declaration.svelte.ts for Declaration class
+ */
+export class Library {
+	readonly library_json: LibraryJson = $state.raw()!;
+
+	package_json = $derived(this.library_json.package_json);
+	source_json = $derived(this.library_json.source_json);
+
+	name = $derived(this.library_json.name);
+	repo_name = $derived(this.library_json.repo_name);
+	repo_url = $derived(this.library_json.repo_url);
+	owner_name = $derived(this.library_json.owner_name);
+	homepage_url = $derived(this.library_json.homepage_url);
+	logo_url = $derived(this.library_json.logo_url);
+	logo_alt = $derived(this.library_json.logo_alt);
+	npm_url = $derived(this.library_json.npm_url);
+	changelog_url = $derived(this.library_json.changelog_url);
+	published = $derived(this.library_json.published);
+
+	/**
+	 * Organization URL (e.g., 'https://github.com/ryanatkn').
+	 */
+	org_url = $derived(
+		this.repo_url && this.repo_name
+			? this.repo_url.endsWith('/' + this.repo_name)
+				? this.repo_url.slice(0, -this.repo_name.length - 1)
+				: null
+			: null,
+	);
+
+	/**
+	 * All modules as rich Module instances.
+	 */
+	modules = $derived(
+		this.source_json.modules
+			? this.source_json.modules.map((module_json) => new Module(this, module_json))
+			: [],
+	);
+
+	/**
+	 * All modules sorted alphabetically by path.
+	 */
+	modules_sorted = $derived([...this.modules].sort((a, b) => a.path.localeCompare(b.path)));
+
+	/**
+	 * All declarations across all modules as a flat array.
+	 */
+	declarations = $derived(this.modules.flatMap((module) => module.declarations));
+
+	/**
+	 * Declaration lookup map by name. Provides O(1) lookup.
+	 */
+	declaration_map = $derived(new Map(this.declarations.map((d) => [d.name, d])));
+
+	constructor(library_json: LibraryJson) {
+		this.library_json = library_json;
+	}
+
+	/**
+	 * Look up a declaration by name.
+	 */
+	lookup_declaration(name: string): Declaration | undefined {
+		return this.declaration_map.get(name);
+	}
+
+	/**
+	 * Check if a declaration exists.
+	 */
+	has_declaration(name: string): boolean {
+		return this.declaration_map.has(name);
+	}
+
+	/**
+	 * Look up a module by its canonical path.
+	 */
+	lookup_module(path: string): Module | undefined {
+		return this.modules.find((m) => m.path === path);
+	}
+
+	/**
+	 * Search declarations by query string with multi-term AND logic.
+	 */
+	search_declarations(query: string): Array<Declaration> {
+		return library_search_declarations(this.declarations, query);
+	}
+}
+
+export const library_context = create_context<Library>();
+
+/**
+ * Search declarations by query string with multi-term AND logic.
+ */
+const library_search_declarations = (
+	declarations: Array<Declaration>,
+	query: string,
+): Array<Declaration> => {
+	if (!query.trim()) return [];
+
+	const terms = query.trim().toLowerCase().split(/\s+/);
+
+	const results = declarations
+		.map((declaration) => {
+			let total_score = 0;
+
+			for (const term of terms) {
+				const name_score = library_score_match(declaration.name, term);
+				const kind_score = library_score_match(declaration.kind, term);
+				const module_score = library_score_match(declaration.module_path, term);
+
+				const term_best = Math.max(name_score, kind_score, module_score);
+
+				if (term_best === 0) {
+					return null;
+				}
+
+				total_score += term_best;
+			}
+
+			return {declaration, score: total_score};
+		})
+		.filter((r) => r !== null)
+		.sort((a, b) => b.score - a.score || a.declaration.name.localeCompare(b.declaration.name))
+		.map((r) => r.declaration);
+
+	return results;
+};
+
+/**
+ * Score a search term match against a field value.
+ */
+const library_score_match = (field_value: string, term: string): number => {
+	const field_lower = field_value.toLowerCase();
+
+	if (field_lower === term) return 100;
+	if (field_lower.startsWith(term)) return 80;
+	if (field_lower.includes(term)) return 60;
+
+	let term_idx = 0;
+	for (const char of field_lower) {
+		if (char === term[term_idx]) {
+			term_idx++;
+			if (term_idx === term.length) {
+				return 40;
+			}
+		}
+	}
+
+	return 0;
+};

package/src/lib/library_gen.ts

@@ -0,0 +1,160 @@
+/**
+ * Library metadata generator helper.
+ *
+ * Generates package_json and source_json with rich metadata:
+ * - JSDoc/TSDoc comments with full tag support
+ * - Full type signatures
+ * - Source code locations
+ * - Parameter information with descriptions and defaults
+ * - Return value documentation
+ * - Usage examples
+ * - Dependency graphs
+ * - Svelte component props
+ *
+ * @see @fuzdev/fuz_util/source_json.js for type definitions
+ * @see src/lib/library_gen_helpers.ts for buildtime-only helpers
+ * @see src/lib/tsdoc_helpers.ts for JSDoc/TSDoc parsing
+ * @see src/lib/ts_helpers.ts for TypeScript analysis
+ * @see src/lib/svelte_helpers.ts for Svelte component analysis
+ */
+
+import type {Gen} from '@ryanatkn/gro';
+import {load_package_json} from '@ryanatkn/gro/package_json.js';
+import type {SourceJson} from '@fuzdev/fuz_util/source_json.js';
+
+import {ts_create_program, type ReExportInfo} from './ts_helpers.js';
+import {module_extract_path, module_is_svelte} from './module_helpers.js';
+import {
+	library_gen_collect_source_files,
+	library_gen_sort_modules,
+	library_gen_validate_no_duplicates,
+	library_gen_generate_ts,
+	library_gen_analyze_svelte_file,
+	library_gen_analyze_typescript_file,
+} from './library_gen_helpers.js';
+
+export interface LibraryGenOptions {
+	filename?: string;
+}
+
+/**
+ * Creates a Gen object for generating library metadata with full TypeScript analysis.
+ *
+ * Usage in a `.gen.ts` file:
+ * ```ts
+ * import {library_gen} from '@ryanatkn/fuz/library_gen.js';
+ * export const gen = library_gen();
+ * ```
+ */
+export const library_gen = (options?: LibraryGenOptions): Gen => {
+	return {
+		generate: async ({log, filer}) => {
+			log.info('generating library metadata with full TypeScript analysis...');
+
+			// Ensure filer is initialized
+			await filer.init();
+
+			// Read package.json
+			const package_json = await load_package_json();
+
+			// Create TypeScript program
+			const program = ts_create_program(log);
+			if (!program) {
+				throw new Error('Failed to create TypeScript program - cannot generate library metadata');
+			}
+
+			const checker = program.getTypeChecker();
+
+			// Collect source files from filer
+			const source_disknodes = library_gen_collect_source_files(filer.files, log);
+
+			// Build source_json with array-based modules
+			// Phase 1: Analyze all modules and collect re-exports
+			const source_json: SourceJson = {
+				name: package_json.name,
+				version: package_json.version,
+				modules: [],
+			};
+
+			// Collect all re-exports: Map<declaration_name, Set<re_exporting_module_path>>
+			// The Set tracks which modules re-export each declaration
+			const all_re_exports: Array<{re_exporting_module: string; re_export: ReExportInfo}> = [];
+
+			for (const disknode of source_disknodes) {
+				const source_id = disknode.id;
+				const module_path = module_extract_path(source_id);
+				const is_svelte = module_is_svelte(module_path);
+
+				// Handle Svelte files separately (before trying to get TypeScript source file)
+				if (is_svelte) {
+					const mod = library_gen_analyze_svelte_file(disknode, module_path, checker);
+					source_json.modules!.push(mod);
+				} else {
+					// For TypeScript/JS files, get the source file from the program
+					const source_file = program.getSourceFile(source_id);
+					if (!source_file) {
+						log.warn(`Could not get source file: ${source_id}`);
+						continue;
+					}
+
+					// May throw, which we want to see
+					const {module: mod, re_exports} = library_gen_analyze_typescript_file(
+						disknode,
+						source_file,
+						module_path,
+						checker,
+					);
+					source_json.modules!.push(mod);
+
+					// Collect re-exports for post-processing
+					for (const re_export of re_exports) {
+						all_re_exports.push({re_exporting_module: module_path, re_export});
+					}
+				}
+			}
+
+			// Phase 2: Build also_exported_from arrays from re-export data
+			// Group re-exports by original module and declaration name
+			const re_export_map: Map<string, Map<string, Array<string>>> = new Map();
+			for (const {re_exporting_module, re_export} of all_re_exports) {
+				const {name, original_module} = re_export;
+				if (!re_export_map.has(original_module)) {
+					re_export_map.set(original_module, new Map());
+				}
+				const module_map = re_export_map.get(original_module)!;
+				if (!module_map.has(name)) {
+					module_map.set(name, []);
+				}
+				module_map.get(name)!.push(re_exporting_module);
+			}
+
+			// Merge into original declarations
+			for (const mod of source_json.modules ?? []) {
+				const module_re_exports = re_export_map.get(mod.path);
+				if (!module_re_exports) continue;
+
+				for (const declaration of mod.declarations ?? []) {
+					const re_exporters = module_re_exports.get(declaration.name);
+					if (re_exporters?.length) {
+						declaration.also_exported_from = re_exporters.sort();
+					}
+				}
+			}
+
+			// Sort modules alphabetically for deterministic output and cleaner diffs
+			source_json.modules = source_json.modules
+				? library_gen_sort_modules(source_json.modules)
+				: undefined;
+
+			// Validate no duplicate declaration names across modules
+			library_gen_validate_no_duplicates(source_json, log);
+
+			log.info('library metadata generation complete');
+
+			return {
+				content: library_gen_generate_ts(package_json, source_json),
+				...(options?.filename && {filename: options.filename}),
+			};
+		},
+	};
+};