@fuzdev/fuz_ui 0.206.7 → 0.206.9

package/src/lib/sparkline.ts

@@ -0,0 +1,173 @@
+/**
+ * Pure geometry helpers behind `Sparkline` and `ProjectActivityChart`.
+ *
+ * Computes polyline points, alpha-fade gradient stops, and the end-dot
+ * position for a series of values, so components stay thin and the math is
+ * testable and reusable outside Svelte.
+ *
+ * @module
+ */
+
+/**
+ * Vertical scale for a sparkline's geometry. The nonlinear options compress
+ * the top of the range so small values stay legible under a large shared
+ * max — increasingly so from `'sqrt'` to smaller power exponents (a number
+ * in `(0, 1]`, where `1` is linear and `1 / 3` is cube root) to `'log'`.
+ */
+export type SparklineScale = 'linear' | 'sqrt' | 'log' | number;
+
+export interface SparklineOptions {
+	/**
+	 * Width of the drawing area in px.
+	 */
+	width: number;
+	/**
+	 * Height of the drawing area in px.
+	 */
+	height: number;
+	/**
+	 * The value rendered at full height and full alpha.
+	 * Pass a shared max across sparklines for comparable scales.
+	 * Defaults to the local max of the values.
+	 */
+	max?: number;
+	/**
+	 * Vertical scale for the line's geometry. The alpha fade always tracks
+	 * the linear ratio regardless of `scale`.
+	 *
+	 * @default 'linear'
+	 */
+	scale?: SparklineScale;
+	/**
+	 * @default 2
+	 */
+	stroke_width?: number;
+	/**
+	 * Alpha at a value of 0, scaling linearly to 1 at the max.
+	 *
+	 * @default 0.4
+	 */
+	alpha_floor?: number;
+	/**
+	 * Reserve padding for an end dot of radius `stroke_width` at the final point.
+	 *
+	 * @default false
+	 */
+	end_dot?: boolean;
+}
+
+/**
+ * A gradient stop for the per-point alpha fade.
+ */
+export interface SparklineStop {
+	/**
+	 * Gradient offset in `[0, 1]`.
+	 */
+	offset: number;
+	/**
+	 * Stop opacity in `[alpha_floor, 1]`.
+	 */
+	opacity: number;
+}
+
+export interface SparklineGeometry {
+	/**
+	 * SVG polyline `points` string.
+	 */
+	points: string;
+	/**
+	 * Alpha-fade gradient stops, thinned to runs' boundaries so long flat
+	 * stretches (like all-zero history) cost a constant number of stops.
+	 */
+	stops: Array<SparklineStop>;
+	/**
+	 * X coordinate of the final point.
+	 */
+	end_x: number;
+	/**
+	 * Y coordinate of the final point.
+	 */
+	end_y: number;
+	/**
+	 * Alpha of the final point.
+	 */
+	end_alpha: number;
+	/**
+	 * Radius for an end dot, equal to the stroke width.
+	 */
+	dot_radius: number;
+}
+
+const round = (n: number): number => Math.round(n * 100) / 100;
+
+/**
+ * Computes the rendering geometry for a sparkline of `values`.
+ *
+ * Returns `null` when `values` has fewer than 2 points, which cannot form a line.
+ */
+export const sparkline_geometry = (
+	values: Array<number>,
+	options: SparklineOptions
+): SparklineGeometry | null => {
+	if (values.length < 2) return null;
+	const {
+		width,
+		height,
+		max,
+		scale = 'linear',
+		stroke_width = 2,
+		alpha_floor = 0.4,
+		end_dot = false
+	} = options;
+	const local_max = max ?? Math.max(0, ...values);
+	const scale_max = local_max > 0 ? local_max : 1;
+	const dot_radius = stroke_width;
+	// inset by half the stroke (or the dot radius) so the extremes aren't clipped
+	const pad = end_dot ? Math.max(stroke_width / 2, dot_radius) : stroke_width / 2;
+	const x_coord = (index: number): number =>
+		pad + (index * (width - 2 * pad)) / (values.length - 1);
+	const y_coord = (value: number): number => {
+		const clamped = Math.min(value, scale_max);
+		const ratio = clamped / scale_max;
+		const scaled =
+			scale === 'linear'
+				? ratio
+				: scale === 'sqrt'
+					? Math.sqrt(ratio)
+					: scale === 'log'
+						? Math.log1p(clamped) / Math.log1p(scale_max)
+						: ratio ** scale;
+		return height - pad - scaled * (height - 2 * pad);
+	};
+	const alpha = (value: number): number =>
+		alpha_floor + (1 - alpha_floor) * (Math.min(value, scale_max) / scale_max);
+
+	const points = values
+		.map((value, index) => `${round(x_coord(index))},${round(y_coord(value))}`)
+		.join(' ');
+
+	const opacities = values.map((value) => round(alpha(value)));
+	const stops: Array<SparklineStop> = [];
+	for (let i = 0; i < values.length; i++) {
+		const opacity = opacities[i]!;
+		// keep the first and last stops and each run's boundaries; drop run interiors
+		if (
+			i > 0 &&
+			i < values.length - 1 &&
+			opacity === opacities[i - 1] &&
+			opacity === opacities[i + 1]
+		) {
+			continue;
+		}
+		stops.push({ offset: round(x_coord(i) / width), opacity });
+	}
+
+	return {
+		points,
+		stops,
+		end_x: round(x_coord(values.length - 1)),
+		end_y: round(y_coord(values[values.length - 1]!)),
+		end_alpha: opacities[values.length - 1]!,
+		dot_radius
+	};
+};

package/src/lib/storage.ts

@@ -1,4 +1,4 @@
-import {BROWSER} from 'esm-env';
+import { BROWSER } from 'esm-env';
 
 // TODO more than just localStorage, maybe rework the module
 
@@ -26,7 +26,7 @@ export const save_to_storage = (key: string, value: any, is_json = false): void
 export const load_from_storage = <T>(
 	key: string,
 	is_json = false,
-	parse_fn?: (value: unknown) => T | null,
+	parse_fn?: (value: unknown) => T | null
 ): T | null => {
 	if (!BROWSER) return null;
 	try {

package/src/lib/style_variable_helpers.svelte.ts

@@ -1,6 +1,6 @@
-import type {StyleVariable} from '@fuzdev/fuz_css/variable.ts';
+import type { StyleVariable } from '@fuzdev/fuz_css/variable.ts';
 
-import {create_context} from './context_helpers.ts';
+import { create_context } from './context_helpers.ts';
 
 export const selected_variable_context = create_context(() => new SelectedStyleVariable(null));
 

package/src/lib/svg.ts

@@ -1,4 +1,4 @@
-import type {SvelteHTMLElements} from 'svelte/elements';
+import type { SvelteHTMLElements } from 'svelte/elements';
 
 /**
  * A structured icon definition rendered by `Svg.svelte`. Rendering is purely
@@ -11,7 +11,7 @@ export interface SvgData {
 	 * List of svg `path` attribute objects, spread onto each `path` element. The
 	 * `d` attribute is required; a per-path `fill` overrides the resolved `fill`.
 	 */
-	paths?: Array<{d: string} & SvelteHTMLElements['path']> | null;
+	paths?: Array<{ d: string } & SvelteHTMLElements['path']> | null;
 	/**
 	 * Inline `style` applied to the root `svg` element, merged with any `style`
 	 * passed as a component prop. Travels with the icon definition - per-instance

package/src/lib/theme_state.svelte.ts

@@ -1,9 +1,9 @@
-import {color_schemes, type ColorScheme, type Theme} from '@fuzdev/fuz_css/theme.ts';
-import {default_themes} from '@fuzdev/fuz_css/themes.ts';
-import {BROWSER} from 'esm-env';
+import { color_schemes, type ColorScheme, type Theme } from '@fuzdev/fuz_css/theme.ts';
+import { default_themes } from '@fuzdev/fuz_css/themes.ts';
+import { BROWSER } from 'esm-env';
 
-import {create_context} from './context_helpers.ts';
-import {load_from_storage, save_to_storage} from './storage.ts';
+import { create_context } from './context_helpers.ts';
+import { load_from_storage, save_to_storage } from './storage.ts';
 
 export interface ThemeStateJson {
 	theme: Theme;
@@ -29,7 +29,7 @@ export class ThemeState {
 	toJSON(): ThemeStateJson {
 		return {
 			theme: this.theme,
-			color_scheme: this.color_scheme,
+			color_scheme: this.color_scheme
 		};
 	}
 }
@@ -49,14 +49,14 @@ export const THEME_STORAGE_KEY = 'fuz:theme';
 
 export const save_color_scheme = (
 	color_scheme: ColorScheme | null,
-	key = COLOR_SCHEME_STORAGE_KEY,
+	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,
+	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 => {

package/src/lib/tome.ts

@@ -1,10 +1,10 @@
-import {resolve} from '$app/paths';
-import type {Component} from 'svelte';
-import {z} from 'zod';
-import {ensure_start} from '@fuzdev/fuz_util/string.ts';
+import { resolve } from '$app/paths';
+import type { Component } from 'svelte';
+import { z } from 'zod';
+import { ensure_start } from '@fuzdev/fuz_util/string.ts';
 
-import {create_context} from './context_helpers.ts';
-import {DOCS_PATH_DEFAULT} from './docs_helpers.svelte.ts';
+import { create_context } from './context_helpers.ts';
+import { DOCS_PATH_DEFAULT } from './docs_helpers.svelte.ts';
 
 export const tomes_context = create_context<() => Map<string, Tome>>();
 
@@ -29,7 +29,7 @@ export const Tome = z.object({
 	Component: z.custom<Component<any, any>>(),
 	related_tomes: z.array(z.string()),
 	related_modules: z.array(z.string()),
-	related_declarations: z.array(z.string()),
+	related_declarations: z.array(z.string())
 });
 export type Tome = z.infer<typeof Tome>;
 
@@ -39,7 +39,7 @@ export type Tome = z.infer<typeof Tome>;
 export const tome_to_pathname = (
 	item: Tome | string,
 	docs_path = DOCS_PATH_DEFAULT,
-	hash?: string,
+	hash?: string
 ): string => {
 	const slug = typeof item === 'string' ? item : item.slug;
 	const path = docs_path + '/' + slug;

package/src/lib/vite_plugin_pkg_json.ts

@@ -44,11 +44,11 @@
  * @module
  */
 
-import {readFileSync} from 'node:fs';
-import {join} from 'node:path';
-import type {Plugin, Rollup} from 'vite';
-import type {PackageJson} from '@fuzdev/fuz_util/package_json.ts';
-import {pkg_json_from_package_json, pkg_json_keys} from '@fuzdev/fuz_util/pkg_json.ts';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Plugin, Rollup } from 'vite';
+import type { PackageJson } from '@fuzdev/fuz_util/package_json.ts';
+import { pkg_json_from_package_json, pkg_json_keys } from '@fuzdev/fuz_util/pkg_json.ts';
 
 const VIRTUAL_ID = 'virtual:pkg.json';
 /**
@@ -81,7 +81,7 @@ export interface VitePluginPkgJsonOptions {
  * the publish-safe field set defaults to `pkg_json_keys`; widen it via `keys`.
  */
 export const vite_plugin_pkg_json = (options: VitePluginPkgJsonOptions = {}): Plugin => {
-	const {keys = pkg_json_keys} = options;
+	const { keys = pkg_json_keys } = options;
 	let root = '';
 	let is_dev = false;
 	/** Curated JSON cached for build; left `null` in dev so `load` re-reads. */
@@ -106,7 +106,7 @@ export const vite_plugin_pkg_json = (options: VitePluginPkgJsonOptions = {}): Pl
 			return ctx.error(
 				`vite_plugin_pkg_json: failed to read or parse ${package_json_path}: ${
 					(err as Error).message
-				}`,
+				}`
 			);
 		}
 		if (raw.name === undefined) {
@@ -139,6 +139,6 @@ export const vite_plugin_pkg_json = (options: VitePluginPkgJsonOptions = {}): Pl
 		load(id) {
 			if (id !== RESOLVED_VIRTUAL_ID) return undefined;
 			return cached ?? read_curated(this);
-		},
+		}
 	};
 };