@fuzdev/fuz_ui 0.169.0

package/src/lib/mdz_components.ts

@@ -0,0 +1,34 @@
+import type {Component} from 'svelte';
+
+import {create_context} from './context_helpers.js';
+
+/**
+ * Component registry for custom Svelte components that can be used in mdz content.
+ *
+ * For example, registering 'Alert' allows using `<Alert>...</Alert>` in mdz content.
+ *
+ * The Map values are the Svelte component constructors.
+ */
+export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
+
+/**
+ * Element registry for HTML elements that can be used in mdz content.
+ *
+ * For example, registering 'div' allows using `<div>...</div>` in mdz content.
+ *
+ * The Map values are boolean placeholders for future configuration options.
+ */
+export type MdzElements = Map<string, boolean>;
+
+/**
+ * Context for providing custom mdz components.
+ * Must be set by the application using mdz.
+ */
+export const mdz_components_context = create_context<MdzComponents>();
+
+/**
+ * Context for providing allowed HTML elements.
+ * Must be set by the application using mdz.
+ * By default, no HTML elements are allowed.
+ */
+export const mdz_elements_context = create_context<MdzElements>();

package/src/lib/module.svelte.ts

@@ -0,0 +1,78 @@
+import type {ModuleJson} from '@fuzdev/fuz_util/source_json.js';
+
+import {Declaration} from './declaration.svelte.js';
+import type {Library} from './library.svelte.js';
+import {url_github_file} from './library_helpers.js';
+
+/**
+ * Rich runtime representation of a module with computed properties.
+ */
+export class Module {
+	readonly library: Library = $state.raw()!;
+	readonly module_json: ModuleJson = $state.raw()!;
+
+	/**
+	 * Canonical module path (e.g., 'Alert.ts', 'helpers/foo.ts').
+	 */
+	path = $derived(this.module_json.path);
+
+	/**
+	 * Import-style path with ./ prefix.
+	 */
+	path_import = $derived('./' + this.path);
+
+	module_comment = $derived(this.module_json.module_comment);
+
+	/**
+	 * Array of Declaration instances. Filters out default exports.
+	 */
+	declarations = $derived(
+		this.module_json.declarations
+			? this.module_json.declarations
+					.filter((declaration_json) => declaration_json.name !== 'default')
+					.map((declaration_json) => new Declaration(this, declaration_json))
+			: [],
+	);
+
+	/**
+	 * API documentation URL for this module.
+	 */
+	url_api = $derived(`/docs/api/${this.path}`);
+
+	/**
+	 * GitHub source URL.
+	 */
+	url_github = $derived(
+		this.library.repo_url
+			? url_github_file(this.library.repo_url, `src/lib/${this.path}`)
+			: undefined,
+	);
+
+	has_declarations: boolean = $derived(
+		!!(this.module_json.declarations && this.module_json.declarations.length > 0),
+	);
+
+	has_module_comment: boolean = $derived(!!this.module_json.module_comment);
+
+	/**
+	 * Modules this imports (paths relative to src/lib).
+	 */
+	dependencies = $derived(this.module_json.dependencies);
+
+	/**
+	 * Modules that import this (paths relative to src/lib).
+	 */
+	dependents = $derived(this.module_json.dependents);
+
+	constructor(library: Library, module_json: ModuleJson) {
+		this.library = library;
+		this.module_json = module_json;
+	}
+
+	/**
+	 * Look up a declaration by name within this module.
+	 */
+	get_declaration_by_name(name: string): Declaration | undefined {
+		return this.declarations.find((d) => d.name === name);
+	}
+}

package/src/lib/module_contextmenu.ts

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

package/src/lib/module_helpers.ts

@@ -0,0 +1,113 @@
+/**
+ * Module path and metadata helpers.
+ *
+ * Provides utilities for working with source module paths, file types,
+ * and import relationships in the package generation system.
+ *
+ * All functions are prefixed with `module_` for clarity.
+ */
+
+/**
+ * Configuration for module source detection.
+ *
+ * Allows customizing which paths are considered source modules,
+ * useful for projects with non-standard directory structures.
+ */
+export interface ModuleSourceOptions {
+	/** Source directory paths to include. @default ['/src/lib/'] */
+	source_paths?: Array<string>;
+	/** File extensions to analyze. @default ['.ts', '.js', '.svelte'] */
+	extensions?: Array<string>;
+	/** Patterns to exclude (matched against full path). @default [/\.test\.ts$/] */
+	exclude_patterns?: Array<RegExp>;
+}
+
+/**
+ * Default options for module source detection.
+ */
+export const MODULE_SOURCE_DEFAULTS: Required<ModuleSourceOptions> = {
+	source_paths: ['/src/lib/'],
+	extensions: ['.ts', '.js', '.svelte'],
+	exclude_patterns: [/\.test\.ts$/],
+};
+
+/**
+ * Extract module path relative to src/lib from absolute source ID.
+ *
+ * @example
+ * module_extract_path('/home/user/project/src/lib/foo.ts') // => 'foo.ts'
+ * module_extract_path('/home/user/project/src/lib/nested/bar.svelte') // => 'nested/bar.svelte'
+ */
+export const module_extract_path = (source_id: string): string => {
+	const lib_index = source_id.indexOf('/src/lib/');
+	return lib_index !== -1 ? source_id.substring(lib_index + 9) : source_id;
+};
+
+/**
+ * Extract component name from a Svelte module path.
+ *
+ * @example
+ * module_get_component_name('Alert.svelte') // => 'Alert'
+ * module_get_component_name('components/Button.svelte') // => 'Button'
+ */
+export const module_get_component_name = (module_path: string): string =>
+	module_path.replace(/^.*\//, '').replace(/\.svelte$/, '');
+
+/**
+ * Convert module path to module key format (with ./ prefix).
+ *
+ * @example
+ * module_get_key('foo.ts') // => './foo.ts'
+ */
+export const module_get_key = (module_path: string): string => `./${module_path}`;
+
+export const module_is_typescript = (path: string): boolean =>
+	path.endsWith('.ts') || path.endsWith('.js'); // hackyy but fine?
+
+export const module_is_svelte = (path: string): boolean => path.endsWith('.svelte');
+
+export const module_is_css = (path: string): boolean => path.endsWith('.css');
+
+export const module_is_json = (path: string): boolean => path.endsWith('.json');
+
+export const module_is_test = (path: string): boolean => path.endsWith('.test.ts');
+
+/**
+ * Check if a path matches source criteria.
+ *
+ * Checks source directory paths, file extensions, and exclusion patterns.
+ * Uses defaults if no options provided.
+ *
+ * Rejects nested repo paths by ensuring the first `/src/` leads to the source directory
+ * (e.g. rejects `/src/fixtures/repos/foo/src/lib/index.ts` because `/src/fixtures/` ≠ `/src/lib/`).
+ *
+ * @param path Full path to check
+ * @param options Configuration options (uses defaults if not provided)
+ * @returns True if the path matches all criteria
+ */
+export const module_matches_source = (path: string, options?: ModuleSourceOptions): boolean => {
+	const opts = {...MODULE_SOURCE_DEFAULTS, ...options};
+
+	// Check if path is in one of the source directories
+	// The first /src/ in the path must lead directly to the source directory
+	// This rejects nested repos like /src/fixtures/repos/foo/src/lib/
+	const in_source_dir = opts.source_paths.some((source_path) => {
+		if (!path.includes(source_path)) return false;
+		// Find the first /src/ and verify it's part of the source_path
+		const first_src_index = path.indexOf('/src/');
+		if (first_src_index === -1) return false;
+		// The source_path should start at that position
+		return path.substring(first_src_index).startsWith(source_path);
+	});
+	if (!in_source_dir) return false;
+
+	// Check if extension matches
+	const has_valid_extension = opts.extensions.some((ext) => path.endsWith(ext));
+	if (!has_valid_extension) return false;
+
+	// Check exclusion patterns
+	const is_excluded = opts.exclude_patterns.some((pattern) => pattern.test(path));
+	if (is_excluded) return false;
+
+	return true;
+};

package/src/lib/rune_helpers.svelte.ts

@@ -0,0 +1,10 @@
+/**
+ * Runs `fn` in an `$effect`, passing `true` as the `skip` argument for the first `count` runs.
+ * Calls `fn` even when skipping so callers can read any dependent signals.
+ */
+export const effect_with_count = (fn: (count: number) => void, initial = 0): void => {
+	let count = initial;
+	$effect(() => {
+		fn(++count);
+	});
+};

package/src/lib/storage.ts

@@ -0,0 +1,48 @@
+import {BROWSER} from 'esm-env';
+
+// TODO more than just localStorage, maybe rework the module
+
+/**
+ * Utility function to save a value to `localStorage`.
+ */
+export const save_to_storage = (key: string, value: any, is_json = false): void => {
+	if (!BROWSER) return;
+	if (value !== null) {
+		try {
+			localStorage.setItem(key, is_json ? JSON.stringify(value) : value);
+			return;
+		} catch (_) {}
+	}
+	localStorage.removeItem(key); // remove if null or error
+};
+
+/**
+ * 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
+ */
+export const load_from_storage = <T>(
+	key: string,
+	is_json = false,
+	parse_fn?: (value: unknown) => T | null,
+): T | null => {
+	if (!BROWSER) return null;
+	try {
+		const loaded = localStorage.getItem(key);
+		if (loaded === null) return null;
+
+		// First handle JSON parsing if requested
+		const value = is_json ? JSON.parse(loaded) : loaded;
+
+		// Then apply the custom parse function if provided
+		if (parse_fn) {
+			return parse_fn(value);
+		}
+
+		return value as unknown as T;
+	} catch (_) {
+		return null;
+	}
+};

package/src/lib/svelte_helpers.ts

@@ -0,0 +1,303 @@
+/**
+ * Svelte component analysis helpers.
+ *
+ * Extracts metadata from Svelte components using svelte2tsx transformations:
+ *
+ * - Component props with types and JSDoc
+ * - Component-level documentation
+ * - Type information
+ *
+ * Workflow: Transform Svelte to TypeScript via svelte2tsx, parse the transformed
+ * TypeScript with the TS Compiler API, extract component-level JSDoc from original source.
+ *
+ * All functions are prefixed with `svelte_` for clarity.
+ */
+
+import ts from 'typescript';
+import {readFileSync} from 'node:fs';
+import {svelte2tsx} from 'svelte2tsx';
+import type {DeclarationJson, ComponentPropInfo} from '@fuzdev/fuz_util/source_json.js';
+
+import {tsdoc_parse, tsdoc_apply_to_declaration} from './tsdoc_helpers.js';
+import {module_get_component_name} from './module_helpers.js';
+
+/**
+ * Analyze a Svelte component from its svelte2tsx transformation.
+ */
+export const svelte_analyze_component = (
+	ts_code: string,
+	source_file: ts.SourceFile,
+	checker: ts.TypeChecker,
+	component_name: string,
+): DeclarationJson => {
+	const result: DeclarationJson = {
+		name: component_name,
+		kind: 'component',
+	};
+
+	try {
+		// Create a virtual source file from the svelte2tsx output
+		// svelte2tsx generates plain TypeScript (not TSX/JSX)
+		const virtual_source = ts.createSourceFile(
+			source_file.fileName + '.ts',
+			ts_code,
+			ts.ScriptTarget.Latest,
+			true,
+			ts.ScriptKind.TS,
+		);
+
+		// Extract component-level TSDoc from svelte2tsx transformed output
+		const component_tsdoc = svelte_extract_component_tsdoc(virtual_source);
+		tsdoc_apply_to_declaration(result, component_tsdoc);
+
+		// Extract props from svelte2tsx transformed output
+		const props = svelte_extract_props(virtual_source, checker);
+		if (props.length > 0) {
+			result.props = props;
+		}
+
+		// Extract source line from original file
+		const start_pos = source_file.getLineAndCharacterOfPosition(0);
+		result.source_line = start_pos.line + 1;
+	} catch (error) {
+		// If analysis fails, return basic component info
+		// eslint-disable-next-line no-console
+		console.error(`Error analyzing Svelte component ${component_name}:`, error);
+	}
+
+	return result;
+};
+
+/**
+ * Extract component-level TSDoc comment from svelte2tsx transformed output.
+ *
+ * svelte2tsx places component-level JSDoc inside the $$render() function,
+ * attached to a variable statement (usually before the props destructuring).
+ * This function searches the AST recursively to find it.
+ */
+const svelte_extract_component_tsdoc = (
+	source_file: ts.SourceFile,
+): ReturnType<typeof tsdoc_parse> => {
+	let found_tsdoc: ReturnType<typeof tsdoc_parse> = undefined;
+
+	// Recursively search for component-level JSDoc
+	function visit(node: ts.Node) {
+		if (found_tsdoc) return; // Already found, stop searching
+
+		// Skip PropertySignature nodes - those are prop-level JSDoc, not component-level
+		if (ts.isPropertySignature(node)) {
+			return; // Don't recurse into property signatures
+		}
+
+		// Check for JSDoc on VariableStatement or VariableDeclaration
+		// Component-level JSDoc is attached to these node types
+		if (ts.isVariableStatement(node) || ts.isVariableDeclaration(node)) {
+			const tsdoc = tsdoc_parse(node, source_file);
+			if (tsdoc) {
+				found_tsdoc = tsdoc;
+				return;
+			}
+		}
+
+		// Continue searching child nodes
+		ts.forEachChild(node, visit);
+	}
+
+	visit(source_file);
+	return found_tsdoc;
+};
+
+/**
+ * Helper to extract prop info from a property signature member.
+ */
+const svelte_extract_prop_from_member = (
+	member: ts.PropertySignature,
+	source_file: ts.SourceFile,
+	checker: ts.TypeChecker,
+): ComponentPropInfo | undefined => {
+	if (!ts.isIdentifier(member.name)) return undefined;
+
+	const prop_name = member.name.text;
+	const optional = !!member.questionToken;
+
+	// Get type string
+	let type_string = 'any';
+	if (member.type) {
+		type_string = member.type.getText(source_file);
+	} else {
+		// Try to get type from type checker
+		try {
+			const prop_type = checker.getTypeAtLocation(member);
+			type_string = checker.typeToString(prop_type);
+		} catch {
+			// Fallback to 'any'
+		}
+	}
+
+	// Extract TSDoc description
+	let description: string | undefined;
+	const tsdoc = tsdoc_parse(member, source_file);
+	if (tsdoc) {
+		description = tsdoc.text;
+	}
+
+	// Extract default value (if available in TSDoc or initializer)
+	let default_value: string | undefined;
+	const default_match = description?.match(/@default\s+(.+)/);
+	if (default_match) {
+		default_value = default_match[1]!.trim();
+	}
+
+	return {
+		name: prop_name,
+		type: type_string,
+		...(optional && {optional}),
+		description,
+		default_value,
+	};
+};
+
+/**
+ * Extract bindable prop names from svelte2tsx transformed output.
+ *
+ * svelte2tsx marks bindable props with `__sveltets_$$bindings('prop1', 'prop2', ...)`.
+ * This function extracts those prop names.
+ */
+const svelte_extract_bindable_props = (virtual_source: ts.SourceFile): Set<string> => {
+	const bindable_props: Set<string> = new Set();
+
+	// Search for __sveltets_$$bindings call
+	function visit(node: ts.Node) {
+		if (ts.isCallExpression(node)) {
+			const expr = node.expression;
+			if (ts.isIdentifier(expr) && expr.text === '__sveltets_$$bindings') {
+				// Extract string literal arguments
+				for (const arg of node.arguments) {
+					if (ts.isStringLiteral(arg)) {
+						bindable_props.add(arg.text);
+					}
+				}
+			}
+		}
+		ts.forEachChild(node, visit);
+	}
+
+	visit(virtual_source);
+	return bindable_props;
+};
+
+/**
+ * Extract props from a type node (handles type literals and intersection types).
+ *
+ * @mutates props - adds extracted prop info to the array
+ */
+const svelte_extract_props_from_type = (
+	type_node: ts.TypeNode,
+	virtual_source: ts.SourceFile,
+	checker: ts.TypeChecker,
+	bindable_props: Set<string>,
+	props: Array<ComponentPropInfo>,
+): void => {
+	if (ts.isTypeLiteralNode(type_node)) {
+		// Handle direct type literal: { prop1: type1, prop2: type2 }
+		for (const member of type_node.members) {
+			if (ts.isPropertySignature(member)) {
+				const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker);
+				if (prop_info) {
+					// Mark as bindable if found in bindings
+					if (bindable_props.has(prop_info.name)) {
+						prop_info.bindable = true;
+					}
+					props.push(prop_info);
+				}
+			}
+		}
+	} else if (ts.isIntersectionTypeNode(type_node)) {
+		// Handle intersection type: TypeA & TypeB & { prop: type }
+		for (const type_part of type_node.types) {
+			svelte_extract_props_from_type(type_part, virtual_source, checker, bindable_props, props);
+		}
+	}
+	// Skip other type references like SvelteHTMLElements['details'] since we can't easily resolve them
+};
+
+/**
+ * Extract props from svelte2tsx transformed output.
+ *
+ * svelte2tsx generates a `$$ComponentProps` type alias containing the component props.
+ * This function extracts prop metadata from that type.
+ */
+const svelte_extract_props = (
+	virtual_source: ts.SourceFile,
+	checker: ts.TypeChecker,
+): Array<ComponentPropInfo> => {
+	const props: Array<ComponentPropInfo> = [];
+	const bindable_props = svelte_extract_bindable_props(virtual_source);
+
+	// Look for $$ComponentProps type alias or Props interface
+	ts.forEachChild(virtual_source, (node) => {
+		// Check for type alias ($$ComponentProps)
+		if (ts.isTypeAliasDeclaration(node) && node.name.text === '$$ComponentProps') {
+			svelte_extract_props_from_type(node.type, virtual_source, checker, bindable_props, props);
+		}
+		// Also check for Props interface (fallback/older format)
+		else if (ts.isInterfaceDeclaration(node) && node.name.text === 'Props') {
+			for (const member of node.members) {
+				if (ts.isPropertySignature(member)) {
+					const prop_info = svelte_extract_prop_from_member(member, virtual_source, checker);
+					if (prop_info) {
+						// Mark as bindable if found in bindings
+						if (bindable_props.has(prop_info.name)) {
+							prop_info.bindable = true;
+						}
+						props.push(prop_info);
+					}
+				}
+			}
+		}
+	});
+
+	return props;
+};
+
+/**
+ * Analyze a Svelte component file from disk.
+ *
+ * This is a high-level function that handles the complete workflow:
+ * 1. Read the Svelte source from disk
+ * 2. Transform to TypeScript via svelte2tsx
+ * 3. Extract component metadata (props, documentation)
+ *
+ * Suitable for use in documentation generators, build tools, and analysis.
+ *
+ * @param file_path Absolute path to the .svelte file
+ * @param module_path Module path relative to src/lib (e.g., 'Alert.svelte')
+ * @param checker TypeScript type checker for type resolution
+ * @returns Complete declaration metadata for the component
+ */
+export const svelte_analyze_file = (
+	file_path: string,
+	module_path: string,
+	checker: ts.TypeChecker,
+): DeclarationJson => {
+	const svelte_source = readFileSync(file_path, 'utf-8');
+
+	// Check if component uses TypeScript
+	const is_ts_file = svelte_source.includes('lang="ts"');
+
+	// Transform Svelte to TS
+	const ts_result = svelte2tsx(svelte_source, {
+		filename: file_path,
+		isTsFile: is_ts_file,
+		emitOnTemplateError: true, // Handle malformed templates gracefully
+	});
+
+	// Get component name from filename
+	const component_name = module_get_component_name(module_path);
+
+	// Create a temporary source file from the original Svelte content for JSDoc extraction
+	const temp_source = ts.createSourceFile(file_path, svelte_source, ts.ScriptTarget.Latest, true);
+
+	// Analyze the component using the existing lower-level function
+	return svelte_analyze_component(ts_result.code, temp_source, checker, component_name);
+};

package/src/lib/themer.svelte.ts

@@ -0,0 +1,68 @@
+import {color_schemes, type ColorScheme, type Theme} from '@fuzdev/fuz_css/theme.js';
+import {default_themes} from '@fuzdev/fuz_css/themes.js';
+import {BROWSER} from 'esm-env';
+
+import {create_context} from './context_helpers.js';
+import {load_from_storage, save_to_storage} from './storage.js';
+
+export class Themer {
+	theme: Theme = $state()!;
+	color_scheme: ColorScheme = $state()!;
+
+	constructor(theme: Theme = default_themes[0]!, color_scheme: ColorScheme = 'auto') {
+		if (parse_color_scheme(color_scheme) === null) {
+			throw Error('unknown color scheme: ' + color_scheme);
+		}
+		this.theme = theme;
+		this.color_scheme = color_scheme; // TODO `resolved_color_scheme` if auto? users could then do different things based on the final value - would not be added to `ThemerJson`
+	}
+
+	toJSON(): ThemerJson {
+		return {
+			theme: this.theme,
+			color_scheme: this.color_scheme,
+		};
+	}
+}
+
+export interface ThemerJson {
+	theme: Theme;
+	color_scheme: ColorScheme;
+}
+
+export const themer_context = create_context<Themer>();
+
+export const sync_color_scheme = (color_scheme: ColorScheme | null): void => {
+	if (!BROWSER) return;
+	const dark =
+		color_scheme === 'dark' ||
+		(color_scheme !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches);
+	document.documentElement.classList.add(dark ? 'dark' : 'light');
+	document.documentElement.classList.remove(dark ? 'light' : 'dark');
+};
+
+export const COLOR_SCHEME_STORAGE_KEY = 'fuz:color-scheme';
+export const THEME_STORAGE_KEY = 'fuz:theme';
+
+export const save_color_scheme = (
+	color_scheme: ColorScheme | null,
+	key = COLOR_SCHEME_STORAGE_KEY,
+): void => {
+	save_to_storage(key, color_scheme);
+};
+
+export const load_color_scheme = (
+	fallback: ColorScheme = 'auto',
+	key = COLOR_SCHEME_STORAGE_KEY,
+): ColorScheme => load_from_storage(key, false, parse_color_scheme) ?? fallback;
+
+export const save_theme = (theme: Theme | null, key = THEME_STORAGE_KEY): void => {
+	save_to_storage(key, theme, true);
+};
+
+export const load_theme = (fallback: Theme = default_themes[0]!, key = THEME_STORAGE_KEY): Theme =>
+	load_from_storage<Theme>(key, true) ?? fallback; // TODO use `parse_theme` from moss
+
+// TODO move to moss
+const parse_color_scheme = (value: unknown): ColorScheme | null =>
+	color_schemes.includes(value as any) ? (value as ColorScheme) : null;