@fuzdev/fuz_ui 0.206.8 → 0.207.0

package/dist/sparkline.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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;
+}
+/**
+ * Computes the rendering geometry for a sparkline of `values`.
+ *
+ * Returns `null` when `values` has fewer than 2 points, which cannot form a line.
+ */
+export declare const sparkline_geometry: (values: Array<number>, options: SparklineOptions) => SparklineGeometry | null;
+//# sourceMappingURL=sparkline.d.ts.map

package/dist/sparkline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparkline.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/sparkline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACnB;AAID;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,KAAK,CAAC,MAAM,CAAC,EACrB,SAAS,gBAAgB,KACvB,iBAAiB,GAAG,IA8DtB,CAAC"}

package/dist/sparkline.js

@@ -0,0 +1,63 @@
+/**
+ * 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
+ */
+const round = (n) => 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, options) => {
+    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) => pad + (index * (width - 2 * pad)) / (values.length - 1);
+    const y_coord = (value) => {
+        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) => 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 = [];
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.206.8",
+  "version": "0.207.0",
   "description": "Svelte UI library",
   "tagline": "friendly user zystem",
   "glyph": "🧶",
@@ -81,7 +81,7 @@
     "jsdom": "^29.1.1",
     "svelte": "^5.56.4",
     "svelte-check": "^4.7.2",
-    "svelte-docinfo": "^0.5.4",
+    "svelte-docinfo": "^0.6.0",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.60.0",

package/src/lib/declaration.svelte.ts

@@ -5,7 +5,8 @@ import type {
 	ParameterJsonInput,
 	ComponentPropJsonInput,
 	OverloadJsonInput,
-	Reactivity
+	Reactivity,
+	TypeJson
 } from 'svelte-docinfo/types.js';
 import { generateImport, getDisplayName } from 'svelte-docinfo/declaration-helpers.js';
 import { EMPTY_ARRAY } from '@fuzdev/fuz_util/array.ts';
@@ -122,6 +123,23 @@ export class Declaration {
 		return this.declaration_json.typeSignature;
 	}
 
+	/**
+	 * Structured type tree beside `type_signature`, absent when the flat string
+	 * is the whole story. Present on `variable` and `type` kinds only.
+	 */
+	get type_info(): TypeJson | undefined {
+		return field<TypeJson>(this.declaration_json, 'typeInfo');
+	}
+
+	/**
+	 * Default value documented via `@default`; the authoritative initializer
+	 * (when human-readable) is in `type_signature`. Present on `variable` kind
+	 * only — parameters, props, and members carry their own.
+	 */
+	get default_value(): string | undefined {
+		return field<string>(this.declaration_json, 'defaultValue');
+	}
+
 	get doc_comment(): string | undefined {
 		return this.declaration_json.docComment;
 	}
@@ -142,6 +160,14 @@ export class Declaration {
 		return field<string>(this.declaration_json, 'returnType');
 	}
 
+	/**
+	 * Structured return type beside `return_type`, absent when the flat string
+	 * is the whole story. Present on `function` kind only.
+	 */
+	get return_type_info(): TypeJson | undefined {
+		return field<TypeJson>(this.declaration_json, 'returnTypeInfo');
+	}
+
 	get return_description(): string | undefined {
 		return field<string>(this.declaration_json, 'returnDescription');
 	}
@@ -150,8 +176,8 @@ export class Declaration {
 		return this.declaration_json.genericParams ?? EMPTY_ARRAY;
 	}
 
-	get extends_type(): string | Array<string> | undefined {
-		return field<string | Array<string>>(this.declaration_json, 'extends');
+	get extends_types(): Array<string> | undefined {
+		return field<Array<string>>(this.declaration_json, 'extends');
 	}
 
 	get implements_types(): Array<string> | undefined {
@@ -182,11 +208,15 @@ export class Declaration {
 	}
 
 	/**
-	 * Intersection types whose properties are external (filtered out of props/members).
-	 * Present on `component` and `type` kinds.
+	 * External types whose contributions are filtered out of props/members —
+	 * the attribute bags a component forwards, however the author composed
+	 * them (intersection, heritage clause, bare or indexed-access reference).
+	 * On `interface`/`class` kinds it records the external reach of the
+	 * heritage chain, whose contributions members (own-only) never enumerate.
+	 * Present on `component`, `type`, `interface`, and `class` kinds.
 	 */
-	get intersects(): Array<string> | undefined {
-		return field<Array<string>>(this.declaration_json, 'intersects');
+	get external_types(): Array<string> | undefined {
+		return field<Array<string>>(this.declaration_json, 'externalTypes');
 	}
 
 	/**

package/src/lib/project_stats.ts

@@ -0,0 +1,220 @@
+/**
+ * Types and pure helpers for project commit-activity stats.
+ *
+ * The committed dataset (`project_stats_data.ts`, written by the
+ * `project_stats_update` task) stores daily commit counts per project as the
+ * master granularity; coarser scopes like monthly are derived at runtime by
+ * rebucketing. All date handling is UTC — `YYYY-MM-DD` strings and "epoch
+ * days" (days since the Unix epoch) — so results are deterministic across
+ * machines.
+ *
+ * @module
+ */
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Daily commit counts for one project.
+ */
+export interface ProjectCommitStats {
+	/**
+	 * Project name, matching `project_items`.
+	 */
+	name: string;
+	/**
+	 * UTC date (`YYYY-MM-DD`) of the first day bucket, the day of the first commit.
+	 */
+	start_date: string;
+	/**
+	 * Commits per UTC day from `start_date` through the snapshot's `end_date`, inclusive.
+	 */
+	daily_counts: Array<number>;
+}
+
+/**
+ * A snapshot of commit stats across projects, sharing a single `end_date`.
+ */
+export interface ProjectStatsSnapshot {
+	/**
+	 * ISO datetime when the snapshot was collected.
+	 */
+	generated_at: string;
+	/**
+	 * UTC date (`YYYY-MM-DD`) of the final day bucket, shared by every project.
+	 */
+	end_date: string;
+	projects: Array<ProjectCommitStats>;
+}
+
+/**
+ * A derived series of bucketed counts for one project.
+ */
+export interface ProjectStatsSeries {
+	name: string;
+	counts: Array<number>;
+}
+
+/**
+ * Converts a UTC `YYYY-MM-DD` date to days since the Unix epoch.
+ */
+export const epoch_day_from_date = (date: string): number => {
+	const [year, month, day] = date.split('-').map(Number);
+	return Date.UTC(year!, month! - 1, day) / DAY_MS;
+};
+
+/**
+ * Converts days since the Unix epoch to a UTC `YYYY-MM-DD` date.
+ */
+export const date_from_epoch_day = (epoch_day: number): string =>
+	new Date(epoch_day * DAY_MS).toISOString().slice(0, 10);
+
+/**
+ * Buckets commit timestamps into daily counts from the earliest commit's UTC
+ * day through `end_date`, inclusive.
+ *
+ * @param timestamps - commit times as Unix epoch seconds
+ * @param end_date - UTC date (`YYYY-MM-DD`) of the final bucket; later timestamps clamp into it
+ * @returns the start date and daily counts, or `null` if `timestamps` is empty
+ */
+export const daily_counts_from_timestamps = (
+	timestamps: Array<number>,
+	end_date: string
+): { start_date: string; daily_counts: Array<number> } | null => {
+	if (timestamps.length === 0) return null;
+	const days = timestamps.map((t) => Math.floor((t * 1000) / DAY_MS));
+	const end_day = epoch_day_from_date(end_date);
+	let start_day = end_day;
+	for (const day of days) {
+		if (day < start_day) start_day = day;
+	}
+	const daily_counts: Array<number> = new Array(end_day - start_day + 1).fill(0);
+	for (const day of days) {
+		daily_counts[Math.min(day, end_day) - start_day]! += 1;
+	}
+	return { start_date: date_from_epoch_day(start_day), daily_counts };
+};
+
+/**
+ * Pads `daily_counts` with leading zeros so the series starts at
+ * `padded_start_date` instead of `start_date`.
+ *
+ * Returns the input array unchanged when `padded_start_date` is not earlier
+ * than `start_date`.
+ */
+export const daily_counts_pad_start = (
+	daily_counts: Array<number>,
+	start_date: string,
+	padded_start_date: string
+): Array<number> => {
+	const pad = epoch_day_from_date(start_date) - epoch_day_from_date(padded_start_date);
+	if (pad <= 0) return daily_counts;
+	return (new Array(pad).fill(0) as Array<number>).concat(daily_counts);
+};
+
+/**
+ * Rebuckets daily counts into calendar-month (UTC) counts.
+ *
+ * The first and last buckets may cover partial months.
+ */
+export const monthly_counts_from_daily = (
+	daily_counts: Array<number>,
+	start_date: string
+): Array<number> => {
+	const start_day = epoch_day_from_date(start_date);
+	const counts: Array<number> = [];
+	let current_month_key: number | null = null;
+	for (let i = 0; i < daily_counts.length; i++) {
+		const date = new Date((start_day + i) * DAY_MS);
+		const month_key = date.getUTCFullYear() * 12 + date.getUTCMonth();
+		if (month_key !== current_month_key) {
+			current_month_key = month_key;
+			counts.push(0);
+		}
+		counts[counts.length - 1]! += daily_counts[i]!;
+	}
+	return counts;
+};
+
+/**
+ * Rebuckets daily counts into 7-day counts, anchored at the end of the series
+ * so the newest bucket always covers a full 7 days.
+ *
+ * The first bucket may cover fewer days when the length isn't a multiple of 7.
+ */
+export const weekly_counts_from_daily = (daily_counts: Array<number>): Array<number> => {
+	const counts: Array<number> = [];
+	for (let end = daily_counts.length; end > 0; end -= 7) {
+		let sum = 0;
+		for (let i = Math.max(0, end - 7); i < end; i++) {
+			sum += daily_counts[i]!;
+		}
+		counts.push(sum);
+	}
+	return counts.reverse();
+};
+
+const to_aligned_series = (
+	snapshot: ProjectStatsSnapshot,
+	rebucket: (daily_counts: Array<number>, start_date: string) => Array<number>
+): { series: Array<ProjectStatsSeries>; max: number } => {
+	if (snapshot.projects.length === 0) return { series: [], max: 0 };
+	let shared_start = snapshot.projects[0]!.start_date;
+	for (const project of snapshot.projects) {
+		if (project.start_date < shared_start) shared_start = project.start_date;
+	}
+	let max = 0;
+	const series = snapshot.projects.map((project) => {
+		const daily = daily_counts_pad_start(project.daily_counts, project.start_date, shared_start);
+		const counts = rebucket(daily, shared_start);
+		for (const count of counts) {
+			if (count > max) max = count;
+		}
+		return { name: project.name, counts };
+	});
+	return { series, max };
+};
+
+/**
+ * Derives aligned monthly series for every project in `snapshot`, sharing one
+ * time window and one scale.
+ *
+ * Each series spans from the earliest project's `start_date` through the
+ * snapshot's `end_date` (younger projects are zero-padded at the front), so
+ * all series have the same length and bucket boundaries. `max` is the largest
+ * monthly count across all projects, for rendering every series at the same
+ * vertical scale.
+ */
+export const project_stats_to_monthly_series = (
+	snapshot: ProjectStatsSnapshot
+): { series: Array<ProjectStatsSeries>; max: number } =>
+	to_aligned_series(snapshot, monthly_counts_from_daily);
+
+/**
+ * Derives aligned weekly series for every project in `snapshot`, sharing one
+ * time window and one scale — the weekly sibling of
+ * `project_stats_to_monthly_series`.
+ */
+export const project_stats_to_weekly_series = (
+	snapshot: ProjectStatsSnapshot
+): { series: Array<ProjectStatsSeries>; max: number } =>
+	to_aligned_series(snapshot, weekly_counts_from_daily);
+
+const start_date_formatter = new Intl.DateTimeFormat('en-US', {
+	month: 'long',
+	day: 'numeric',
+	year: 'numeric',
+	timeZone: 'UTC'
+});
+
+/**
+ * Formats a one-line human-readable summary of a project's commit stats,
+ * e.g. `"gro — 2,386 commits since August 7, 2019"`. Used for accessible
+ * labels and tooltips.
+ */
+export const project_stats_label = (project: ProjectCommitStats): string => {
+	let total = 0;
+	for (const count of project.daily_counts) {
+		total += count;
+	}
+	return `${project.name} — ${total.toLocaleString('en-US')} commits since ${start_date_formatter.format(new Date(project.start_date))}`;
+};