@fuzdev/fuz_ui 0.201.0 → 0.203.0

package/src/lib/library.svelte.ts

@@ -15,7 +15,49 @@ import {
 	url_npm_package,
 } from '@fuzdev/fuz_util/package_helpers.js';
 
-export const library_context = create_context<Library>();
+/**
+ * Holds a getter to the active `Library` for the current subtree.
+ *
+ * The getter form keeps consumers reactive when the library changes without
+ * requiring a remount — set it with a closure over reactive state, e.g.
+ * `library_context.set(() => library)`. Components that accept a `library`
+ * prop (`LibraryDetail`, `ApiIndex`, `ApiModule`) project the prop into this
+ * context for their subtree, so descendants like `ModuleLink`,
+ * `DeclarationLink`, and TSDoc-rendered `DocsLink` resolve against the same
+ * library — including when an aggregator renders a foreign library that
+ * differs from the site-level context.
+ */
+export const library_context = create_context<() => Library>();
+
+/**
+ * Sets `library_context` for the component's subtree to a getter that prefers
+ * the component's `library` prop and falls back to the ancestor's value,
+ * returning the resolved getter.
+ *
+ * Pass `get_library_prop` as a getter (not a snapshot) so prop changes remain
+ * reactive. The ancestor lookup happens once at component init, before the
+ * projection — the fallback sees the parent value, not the projection.
+ *
+ * @param get_library_prop - Getter for the component's `library` prop. A thunk so the prop stays reactive.
+ * @param component_name - Used in the error when neither the prop nor the context provides a library.
+ * @returns getter for the resolved library; read it lazily, e.g. `$derived(get_library())`
+ * @initializes
+ */
+export const set_library_context_with_fallback = (
+	get_library_prop: () => Library | undefined,
+	component_name: string,
+): (() => Library) => {
+	const get_outer = library_context.get_maybe();
+	const get_library = (): Library => {
+		const value = get_library_prop() ?? get_outer?.();
+		if (!value) {
+			throw Error(`${component_name} requires a \`library\` prop or a set \`library_context\``);
+		}
+		return value;
+	};
+	library_context.set(get_library);
+	return get_library;
+};
 
 /**
  * Normalizes a URL prefix: ensures leading `/`, strips trailing `/`, returns `''` for falsy and non-string values.

package/src/lib/logos.ts

@@ -73,7 +73,7 @@ export const logo_fuz_css = {
 	label: 'a fuzzy tuft of green moss',
 	fill: '#3db33d',
 	paths: logo_fuz.paths,
-	attrs: {style: 'transform: scaleX(-1) rotate(180deg)'},
+	style: 'transform: scaleX(-1) rotate(180deg)',
 } satisfies SvgData;
 
 export const logo_fuz_ui = {

package/src/lib/module.svelte.ts

@@ -1,9 +1,34 @@
-import type {ModuleJsonInput} from 'svelte-docinfo/types.js';
+import type {
+	ModuleJsonInput,
+	ReExportJsonInput,
+	ExternalReExportJsonInput,
+} from 'svelte-docinfo/types.js';
 
 import {Declaration} from './declaration.svelte.js';
 import type {Library} from './library.svelte.js';
 import {url_github_file} from '@fuzdev/fuz_util/package_helpers.js';
 
+/**
+ * Groups entries by a string key, with groups sorted by key. Entries within
+ * each group keep their input order.
+ */
+const group_sorted = <T>(
+	entries: Array<T>,
+	get_key: (entry: T) => string,
+): Map<string, Array<T>> => {
+	const by_key: Map<string, Array<T>> = new Map();
+	for (const entry of entries) {
+		const key = get_key(entry);
+		let group = by_key.get(key);
+		if (!group) {
+			group = [];
+			by_key.set(key, group);
+		}
+		group.push(entry);
+	}
+	return new Map([...by_key].sort(([a], [b]) => a.localeCompare(b)));
+};
+
 /**
  * Rich runtime representation of a module with computed properties.
  *
@@ -76,7 +101,11 @@ export class Module {
 			: undefined,
 	);
 
-	has_declarations: boolean = $derived((this.module_json.declarations?.length ?? 0) > 0);
+	/**
+	 * Whether the module has renderable declarations (after the default-export
+	 * filter in `declarations`).
+	 */
+	has_declarations: boolean = $derived(this.declarations.length > 0);
 
 	has_module_comment: boolean = $derived(!!this.module_comment);
 
@@ -94,6 +123,72 @@ export class Module {
 
 	has_dependents: boolean = $derived(this.dependents.length > 0);
 
+	/**
+	 * Same-name re-export edges in this module's source (`ModuleJson.reExports`)
+	 * — the forward view of declarations' `alsoExportedFrom`, sorted by name
+	 * then module. Renamed re-exports appear as declarations with `aliasOf`
+	 * instead, and star exports in `star_exports`.
+	 */
+	re_exports = $derived(this.module_json.reExports ?? []);
+
+	has_re_exports: boolean = $derived(this.re_exports.length > 0);
+
+	/**
+	 * Modules fully re-exported via `export * from './module'`
+	 * (`ModuleJson.starExports`), in source order. Star-projected symbols are
+	 * not materialized as declarations or `re_exports` edges — this is their
+	 * sole encoding.
+	 */
+	star_exports = $derived(this.module_json.starExports ?? []);
+
+	has_star_exports: boolean = $derived(this.star_exports.length > 0);
+
+	/**
+	 * Re-export edges grouped by canonical module path, groups sorted by path.
+	 * Entries within each group keep their name-sorted serialized order.
+	 */
+	re_exports_by_module: Map<string, Array<ReExportJsonInput>> = $derived(
+		group_sorted(this.re_exports, (entry) => entry.module),
+	);
+
+	/**
+	 * Re-exports whose immediate target is an external package
+	 * (`ModuleJson.externalReExports`) — `export {x} from 'pkg'` and
+	 * `export * as ns from 'pkg'` forms, sorted by name then specifier.
+	 */
+	external_re_exports = $derived(this.module_json.externalReExports ?? []);
+
+	has_external_re_exports: boolean = $derived(this.external_re_exports.length > 0);
+
+	/**
+	 * External re-exports grouped by package specifier, groups sorted by
+	 * specifier. Entries within each group keep their name-sorted serialized
+	 * order.
+	 */
+	external_re_exports_by_specifier: Map<string, Array<ExternalReExportJsonInput>> = $derived(
+		group_sorted(this.external_re_exports, (entry) => entry.specifier),
+	);
+
+	/**
+	 * External packages fully re-exported via `export * from 'pkg'`
+	 * (`ModuleJson.externalStarExports`), in source order. The projected
+	 * names are unknown — the package isn't analyzed.
+	 */
+	external_star_exports = $derived(this.module_json.externalStarExports ?? []);
+
+	has_external_star_exports: boolean = $derived(this.external_star_exports.length > 0);
+
+	/**
+	 * Whether the module re-exports anything in any form — same-name edges,
+	 * star exports, or the external variants of both.
+	 */
+	has_any_re_exports: boolean = $derived(
+		this.has_re_exports ||
+			this.has_star_exports ||
+			this.has_external_re_exports ||
+			this.has_external_star_exports,
+	);
+
 	constructor(library: Library, module_json: ModuleJsonInput) {
 		this.library = library;
 		this.module_json = module_json;

package/src/lib/svg.ts

@@ -1,23 +1,84 @@
 import type {SvelteHTMLElements} from 'svelte/elements';
 
+/**
+ * A structured icon definition rendered by `Svg.svelte`. Rendering is purely
+ * structural - typed fields, never raw markup - so untrusted data cannot
+ * introduce script execution or navigation. See `Svg.svelte` for the full
+ * security notes, including the residual `style` `url(...)` caveat.
+ */
 export interface SvgData {
 	/**
-	 * Raw svg markup string that's inserted unsafely as a child of the `svg` element.
-	 * This is an escape hatch for non-`path` markup -
-	 * generally, you should instead use the `paths` property to avoid security/CSP implications.
+	 * List of svg `path` attribute objects, spread onto each `path` element. The
+	 * `d` attribute is required; a per-path `fill` overrides the resolved `fill`.
 	 */
-	raw?: string | null;
+	paths?: Array<{d: string} & SvelteHTMLElements['path']> | null;
 	/**
-	 * List of svg `path` attribute objects. The `d` attribute is required.
+	 * Inline `style` applied to the root `svg` element, merged with any `style`
+	 * passed as a component prop. Travels with the icon definition - per-instance
+	 * svg attributes belong on the `Svg` component itself.
+	 */
+	style?: string | null;
+	/**
+	 * Default `fill` for every `path`, falling back to `var(--text_color, #000)`.
+	 * Overridden by the component's `fill` prop, and per-path by a path's own `fill`.
 	 */
-	paths?: Array<{d: string} & SvelteHTMLElements['path']> | null;
-	attrs?: SvelteHTMLElements['svg'] | null;
 	fill?: string | null;
-	width?: string | null;
-	height?: string | null;
+	/**
+	 * Accessible name, applied as `aria-label`. Overridden by the component's `label` prop.
+	 */
 	label?: string | null;
 	/**
 	 * Defaults to `"0 0 100 100"`.
 	 */
 	viewBox?: string | null;
+	/**
+	 * Gradient definitions rendered into the svg's `<defs>` block. This is the
+	 * structured replacement for raw markup - reference a gradient from a
+	 * path/shape `fill` or `stroke` with `url(#id)`. Most svgs need only `paths`.
+	 */
+	gradients?: Array<SvgGradient> | null;
+}
+
+/**
+ * A gradient definition rendered into the svg's `<defs>` block. Reference it
+ * from a path/shape `fill` or `stroke` with `url(#id)`.
+ */
+export interface SvgGradient {
+	/**
+	 * Whether to render a `linearGradient` or `radialGradient` element.
+	 */
+	type: 'linear' | 'radial';
+	/**
+	 * The `id` referenced by a `fill`/`stroke` like `url(#id)`. Inline svgs share
+	 * the document's id namespace, so pick a value unique to the icon - icons
+	 * with colliding ids all resolve to whichever element renders first.
+	 */
+	id: string;
+	/**
+	 * The gradient's color stops.
+	 */
+	stops: Array<SvgGradientStop>;
+	/**
+	 * Additional attributes on the gradient element, e.g. `gradientUnits`,
+	 * `gradientTransform`, `cx`/`cy`/`r` (radial), or `x1`/`y1`/`x2`/`y2` (linear).
+	 */
+	attrs?: (SvelteHTMLElements['radialGradient'] & SvelteHTMLElements['linearGradient']) | null;
+}
+
+/**
+ * A single color stop of an `SvgGradient`.
+ */
+export interface SvgGradientStop {
+	/**
+	 * The stop's position along the gradient, e.g. `0.5` or `"50%"`.
+	 */
+	offset: string | number;
+	/**
+	 * The stop's color, applied as the `stop-color` attribute.
+	 */
+	color: string;
+	/**
+	 * The stop's opacity, applied as the `stop-opacity` attribute.
+	 */
+	opacity?: string | number | null;
 }