@fuzdev/fuz_ui 0.169.0

package/dist/tsdoc_helpers.js

@@ -0,0 +1,221 @@
+/**
+ * TSDoc/JSDoc parsing helpers using the TypeScript Compiler API.
+ *
+ * Provides `tsdoc_parse()` for extracting JSDoc/TSDoc from TypeScript nodes.
+ * Primarily designed for build-time code generation but can be used at runtime.
+ *
+ * ## Design
+ *
+ * Pure extraction approach: extracts documentation as-is with minimal transformation,
+ * preserving source intent. Works around TypeScript Compiler API quirks where needed.
+ *
+ * Supports both regular TypeScript and Svelte components (via svelte2tsx output).
+ *
+ * ## Tag support
+ *
+ * Supports a subset of standard TSDoc tags:
+ * `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@nodocs`.
+ *
+ * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
+ * The declaration is still exported and usable, just not documented.
+ *
+ * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
+ * Use format: `@mutates paramName - description of mutation`.
+ *
+ * Only `@returns` is supported (not `@return`).
+ *
+ * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
+ * Relative/absolute path support in `@see` is TBD.
+ *
+ * ## Behavioral notes
+ *
+ * Due to TS Compiler API limitations:
+ * - Preserves dash separator in `@param` descriptions: `@param x desc` → `"- desc"`
+ * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
+ * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
+ *
+ * All functions are prefixed with `tsdoc_` for clarity.
+ */
+import ts from 'typescript';
+/**
+ * Convert TSDoc link syntax to mdz-compatible format.
+ *
+ * Conversions:
+ * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link https://...}` → `https://...` (bare URL)
+ * - `{@link identifier}` → `` `identifier` `` (backticks)
+ * - `@see` variants follow same rules
+ *
+ * @param content The @see tag content to convert
+ */
+const tsdoc_convert_link_to_mdz = (content) => {
+    // Check for {@link ...} or {@see ...} syntax
+    const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(content.trim());
+    if (link_match) {
+        const inner = link_match[1].trim();
+        // Check for pipe separator (custom display text)
+        const pipe_index = inner.indexOf('|');
+        if (pipe_index !== -1) {
+            const reference = inner.slice(0, pipe_index).trim();
+            const display_text = inner.slice(pipe_index + 1).trim();
+            // Convert to markdown link: [text](url)
+            return `[${display_text}](${reference})`;
+        }
+        // No pipe - check if it's a URL or declaration
+        if (inner.startsWith('https://') || inner.startsWith('http://')) {
+            // Bare URL - return as-is
+            return inner;
+        }
+        else {
+            // Declaration or module - wrap in backticks
+            return `\`${inner}\``;
+        }
+    }
+    // No {@link} or {@see} syntax - check if it's a bare URL or declaration
+    const trimmed = content.trim();
+    if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
+        // Already a bare URL - return as-is
+        return trimmed;
+    }
+    else {
+        // Declaration or module - wrap in backticks
+        return `\`${trimmed}\``;
+    }
+};
+/**
+ * Parse JSDoc comment from a TypeScript node.
+ *
+ * Extracts and parses all JSDoc tags including:
+ *
+ * - `@param` - parameter descriptions
+ * - `@returns` - return value description
+ * - `@throws` - error documentation
+ * - `@example` - code examples
+ * - `@deprecated` - deprecation warnings
+ * - `@see` - related references
+ * - `@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)
+ */
+export const tsdoc_parse = (node, source_file) => {
+    const tsdoc_comments = ts.getJSDocCommentsAndTags(node);
+    if (tsdoc_comments.length === 0)
+        return undefined;
+    let full_text = '';
+    const params = new Map();
+    let returns;
+    const throws = [];
+    const examples = [];
+    let deprecated_message;
+    const see_also = [];
+    let since;
+    const mutates = [];
+    let nodocs = false;
+    // Extract main comment text
+    for (const comment of tsdoc_comments) {
+        if (ts.isJSDoc(comment) && comment.comment) {
+            const text = typeof comment.comment === 'string'
+                ? comment.comment
+                : comment.comment.map((c) => c.text).join('');
+            full_text += text + '\n';
+        }
+    }
+    // Extract tags
+    const tags = ts.getJSDocTags(node);
+    for (const tag of tags) {
+        const tag_text = typeof tag.comment === 'string' ? tag.comment : tag.comment?.map((c) => c.text).join('');
+        const tag_name = tag.tagName.text;
+        if (tag_name === 'param' && ts.isJSDocParameterTag(tag)) {
+            // Extract parameter name and description
+            const param_name = ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText();
+            if (param_name && tag_text) {
+                params.set(param_name, tag_text.trim());
+            }
+        }
+        else if (tag_name === 'returns' && tag_text) {
+            returns = tag_text.trim();
+        }
+        else if (tag_name === 'throws' && tag_text) {
+            // Try to extract error type and description
+            const match = /^\{?(\w+)\}?\s+(.+)/.exec(tag_text);
+            if (match) {
+                throws.push({ type: match[1], description: match[2].trim() });
+            }
+            else {
+                throws.push({ description: tag_text.trim() });
+            }
+        }
+        else if (tag_name === 'example' && tag_text) {
+            examples.push(tag_text.trim());
+        }
+        else if (tag_name === 'deprecated' && tag_text) {
+            deprecated_message = tag_text.trim();
+        }
+        else if (tag_name === 'see') {
+            // The TS API strips 'https' from URLs in @see tags, so get full text from source
+            const full_tag_text = tag.getText(source_file);
+            // Extract content after @see, handling JSDoc formatting artifacts
+            const see_content = full_tag_text
+                .replace(/^@see\s+/, '') // remove @see prefix
+                .replace(/\n\s*\*\s*/g, ' ') // remove JSDoc line continuations
+                .trim();
+            if (see_content) {
+                // Convert TSDoc link syntax to mdz-compatible format
+                see_also.push(tsdoc_convert_link_to_mdz(see_content));
+            }
+        }
+        else if (tag_name === 'since' && tag_text) {
+            since = tag_text.trim();
+        }
+        else if (tag_name === 'mutates' && tag_text) {
+            mutates.push(tag_text.trim());
+        }
+        else if (tag_name === 'nodocs') {
+            nodocs = true;
+        }
+    }
+    full_text = full_text.trim();
+    return {
+        text: full_text,
+        params,
+        returns,
+        ...(throws.length && { throws }),
+        ...(examples.length && { examples }),
+        deprecated_message,
+        ...(see_also.length && { see_also }),
+        since,
+        ...(mutates.length && { mutates }),
+        ...(nodocs && { nodocs }),
+    };
+};
+/**
+ * Apply parsed TSDoc metadata to a declaration.
+ *
+ * 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)
+ * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
+ */
+export const tsdoc_apply_to_declaration = (declaration, tsdoc) => {
+    if (!tsdoc)
+        return;
+    declaration.doc_comment = tsdoc.text;
+    declaration.deprecated_message = tsdoc.deprecated_message;
+    // Only assign arrays if they have content
+    if (tsdoc.examples?.length) {
+        declaration.examples = tsdoc.examples;
+    }
+    if (tsdoc.see_also?.length) {
+        declaration.see_also = tsdoc.see_also;
+    }
+    if (tsdoc.throws?.length) {
+        declaration.throws = tsdoc.throws;
+    }
+    if (tsdoc.since) {
+        declaration.since = tsdoc.since;
+    }
+};

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@fuzdev/fuz_ui",
+  "version": "0.169.0",
+  "description": "Svelte UI library",
+  "motto": "friendly user zystem",
+  "glyph": "🧶",
+  "logo": "logo.svg",
+  "logo_alt": "a friendly brown spider facing you",
+  "public": true,
+  "license": "MIT",
+  "homepage": "https://www.fuz.dev/",
+  "author": {
+    "name": "Ryan Atkinson",
+    "email": "mail@ryanatkn.com",
+    "url": "https://www.ryanatkn.com/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanatkn/fuz.git"
+  },
+  "bugs": "https://github.com/ryanatkn/fuz/issues",
+  "funding": "https://www.ryanatkn.com/funding",
+  "scripts": {
+    "start": "gro dev",
+    "dev": "gro dev",
+    "build": "gro build",
+    "check": "gro check",
+    "test": "gro test",
+    "preview": "vite preview",
+    "deploy": "gro deploy"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.15"
+  },
+  "peerDependencies": {
+    "@fuzdev/fuz_code": ">=0.37.0",
+    "@fuzdev/fuz_css": ">=0.40.0",
+    "@fuzdev/fuz_util": ">=0.42.0",
+    "@ryanatkn/gro": ">=0.180.0",
+    "@sveltejs/kit": "^2.47.3",
+    "esm-env": "^1",
+    "svelte": "^5",
+    "svelte2tsx": "^0.7.45",
+    "zod": "^4.1.12"
+  },
+  "peerDependenciesMeta": {
+    "@fuzdev/fuz_code": {
+      "optional": true
+    },
+    "@ryanatkn/gro": {
+      "optional": true
+    },
+    "esm-env": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/changelog-git": "^0.2.1",
+    "@fuzdev/fuz_code": "^0.37.0",
+    "@fuzdev/fuz_css": "^0.40.0",
+    "@fuzdev/fuz_util": "^0.42.0",
+    "@ryanatkn/belt": "^0.41.1",
+    "@ryanatkn/eslint-config": "^0.9.0",
+    "@ryanatkn/gro": "^0.180.0",
+    "@sveltejs/adapter-static": "^3.0.10",
+    "@sveltejs/kit": "^2.49.0",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-svelte": "^3.13.0",
+    "esm-env": "^1.2.2",
+    "jsdom": "^27.2.0",
+    "prettier": "^3.6.2",
+    "prettier-plugin-svelte": "^3.4.0",
+    "svelte": "^5.45.2",
+    "svelte-check": "^4.3.4",
+    "svelte2tsx": "^0.7.45",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.0.14",
+    "zod": "^4.1.13"
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-svelte"
+    ],
+    "useTabs": true,
+    "printWidth": 100,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "overrides": [
+      {
+        "files": "package.json",
+        "options": {
+          "useTabs": false
+        }
+      }
+    ]
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src/lib/**/*.ts",
+    "!src/lib/**/*.test.*",
+    "!dist/**/*.test.*"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.ts": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.svelte": {
+      "types": "./dist/*.svelte.d.ts",
+      "svelte": "./dist/*.svelte",
+      "default": "./dist/*.svelte"
+    }
+  }
+}

package/src/lib/alert.ts

@@ -0,0 +1,14 @@
+// TODO move to module context?
+
+export type AlertStatus = 'inform' | 'help' | 'error';
+
+export interface AlertStatusOptions {
+	color: string;
+	icon: string | null;
+}
+
+export const alert_status_options: Record<AlertStatus, AlertStatusOptions> = {
+	inform: {color: 'var(--text_color_3)', icon: '✻'},
+	help: {color: 'var(--color_b_5)', icon: '➺'},
+	error: {color: 'var(--color_c_5)', icon: '!?'},
+};

package/src/lib/api_search.svelte.ts

@@ -0,0 +1,85 @@
+import type {Declaration} from './declaration.svelte.js';
+import type {Library} from './library.svelte.js';
+
+export interface DeclarationSearchState {
+	query: string;
+	all: Array<Declaration>;
+	filtered: Array<Declaration>;
+}
+
+/**
+ * Creates search state for the API index page (all declarations across all modules).
+ */
+export const create_declaration_search = (library: Library): DeclarationSearchState => {
+	let query = $state('');
+
+	const all = $derived(library.declarations);
+
+	const filtered = $derived.by(() => {
+		const items = query.trim() ? library.search_declarations(query) : all;
+		return items.sort((a, b) => a.name.localeCompare(b.name));
+	});
+
+	return {
+		get query() {
+			return query;
+		},
+		set query(v: string) {
+			query = v;
+		},
+		get all() {
+			return all;
+		},
+		get filtered() {
+			return filtered;
+		},
+	};
+};
+
+/**
+ * Creates search state for module-specific declaration lists.
+ */
+export const create_module_declaration_search = (
+	declarations: Array<Declaration>,
+): DeclarationSearchState => {
+	let query = $state('');
+
+	const all = $derived(declarations);
+
+	const filtered = $derived.by(() => {
+		const trimmed_query = query.trim();
+		if (!trimmed_query) return all.sort((a, b) => a.name.localeCompare(b.name));
+
+		const terms = trimmed_query.toLowerCase().split(/\s+/);
+
+		const items = all.filter((d) => {
+			const name_lower = d.name.toLowerCase();
+			const kind_lower = d.kind.toLowerCase();
+			const module_path_lower = d.module_path.toLowerCase();
+
+			return terms.every(
+				(term) =>
+					name_lower.includes(term) ||
+					kind_lower.includes(term) ||
+					module_path_lower.includes(term),
+			);
+		});
+
+		return items.sort((a, b) => a.name.localeCompare(b.name));
+	});
+
+	return {
+		get query() {
+			return query;
+		},
+		set query(v: string) {
+			query = v;
+		},
+		get all() {
+			return all;
+		},
+		get filtered() {
+			return filtered;
+		},
+	};
+};

package/src/lib/constants.ts

@@ -0,0 +1,3 @@
+// TODO the 60px is a hack, need `--docs_primary_nav_height` exported or :root values from Fuz -- the --space_lg also needs to be kept in sync
+// see also the same issue in Moss
+export const MAIN_HEADER_MARGIN_TOP = 'calc(60px + var(--space_lg))';

package/src/lib/context_helpers.ts

@@ -0,0 +1,47 @@
+import {getContext, setContext} from 'svelte';
+
+// This uses a function instead of a class because of the overloaded type signatures.
+// It could be implemented internally with a class like `SvelteContext`
+// but this is less code and seems a bit simpler.
+// The memory gains of a class appear minimal given the expected usage patterns.
+// See https://github.com/ryanatkn/fuz/pull/56 for more.
+
+// TODO maybe remove `error_message`?
+
+/**
+ * Wraps Svelte's `setContext` and `getContext` for better ergonomics.
+ * When no value is set in the context,
+ * `get` throws an error and `get_maybe` returns `undefined`.
+ * If a `fallback` is provided, the `value` argument to `set` is optional
+ * and `get_maybe` is omitted from the type.
+ */
+export function create_context<T>(fallback: () => T): {
+	get: () => T;
+	set: (value?: T) => T;
+};
+export function create_context<T>(): {
+	get: (error_message?: string) => T;
+	get_maybe: () => T | undefined;
+	set: (value: T) => T;
+};
+export function create_context<T>(fallback?: () => T): {
+	get: (error_message?: string) => T;
+	get_maybe: () => T | undefined;
+	set: (value?: T) => T;
+} {
+	const key = Symbol();
+	const get_maybe = () => {
+		const value: T | undefined = getContext(key); // treat `null` as a valid value - the `typescript-eslint` rule below is bugged because `??` would clobber nulls, see issue https://github.com/typescript-eslint/typescript-eslint/issues/7842
+		return value === undefined ? fallback?.() : value;
+	};
+	return {
+		get: (error_message?: string) => {
+			const value = get_maybe();
+			if (value === undefined) throw Error(error_message ?? 'context value is not set');
+			return value;
+		},
+		get_maybe,
+		// this is typesafe, so no runtime check:
+		set: (value: T | undefined = fallback?.()) => setContext(key, value)!,
+	};
+}

package/src/lib/contextmenu_helpers.ts

@@ -0,0 +1,63 @@
+import {is_editable, swallow, inside_editable} from '@fuzdev/fuz_util/dom.js';
+
+import type {ContextmenuState} from './contextmenu_state.svelte.js';
+
+// Constants for default prop values
+export const CONTEXTMENU_DEFAULT_OPEN_OFFSET_X = -2;
+export const CONTEXTMENU_DEFAULT_OPEN_OFFSET_Y = -2;
+export const CONTEXTMENU_DEFAULT_BYPASS_WINDOW = 750;
+export const CONTEXTMENU_DEFAULT_BYPASS_MOVE_TOLERANCE = 11;
+export const CONTEXTMENU_DEFAULT_LONGPRESS_DURATION = 633;
+export const CONTEXTMENU_DEFAULT_LONGPRESS_MOVE_TOLERANCE = 21;
+
+/**
+ * Returns true if valid and narrows the type to HTMLElement | SVGElement.
+ */
+export const contextmenu_is_valid_target = (
+	target: EventTarget | null,
+	shiftKey: boolean,
+): target is HTMLElement | SVGElement =>
+	!shiftKey &&
+	(target instanceof HTMLElement || target instanceof SVGElement) &&
+	!is_editable(target) &&
+	!inside_editable(target);
+
+// TODO maybe bind these to the contextmenu instance instead of including the function wrapper
+// TODO customize
+export const contextmenu_create_keyboard_handlers = (
+	contextmenu: ContextmenuState,
+): Map<string, () => void> =>
+	new Map([
+		['Escape', () => contextmenu.close()],
+		['ArrowLeft', () => contextmenu.collapse_selected()],
+		['ArrowRight', () => contextmenu.expand_selected()],
+		['ArrowDown', () => contextmenu.select_next()],
+		['ArrowUp', () => contextmenu.select_previous()],
+		['Home', () => contextmenu.select_first()],
+		['End', () => contextmenu.select_last()],
+		[' ', () => contextmenu.activate_selected()],
+		['Enter', () => contextmenu.activate_selected()],
+	]);
+
+export const contextmenu_create_keydown_handler = (
+	keyboard_handlers: Map<string, () => void>,
+): ((e: KeyboardEvent) => void) => {
+	return (e: KeyboardEvent): void => {
+		const handler = keyboard_handlers.get(e.key);
+		if (!handler || is_editable(e.target)) return;
+		swallow(e);
+		handler();
+	};
+};
+
+export const contextmenu_calculate_constrained_x = (
+	menu_x: number,
+	menu_width: number,
+	layout_width: number,
+): number => menu_x + Math.min(0, layout_width - (menu_x + menu_width));
+
+export const contextmenu_calculate_constrained_y = (
+	menu_y: number,
+	menu_height: number,
+	layout_height: number,
+): number => menu_y + Math.min(0, layout_height - (menu_y + menu_height));