@rebasepro/plugin-insights 0.23.0 → 0.24.0

package/dist/index.es.js

@@ -1,66 +1,111 @@
-import React, { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { getIcon, useAuthController } from "@rebasepro/app";
-import { cls, defaultBorderMixin } from "@rebasepro/ui";
-//#region src/engine/InsightsCache.ts
+import { getIcon, useAuthController, useTranslation } from "@rebasepro/app";
+import { Tooltip, Typography, cls, defaultBorderMixin } from "@rebasepro/ui";
+var DAY_MS = 864e5;
+/** The current and previous windows of `days` days, ending at `to`. */
+function resolvePeriod(days, to) {
+	const from = /* @__PURE__ */ new Date(to.getTime() - days * DAY_MS);
+	return {
+		days,
+		from,
+		to,
+		previousFrom: /* @__PURE__ */ new Date(from.getTime() - days * DAY_MS)
+	};
+}
 /**
-* The cache key for one insight, in one scope, for one user.
+* The cache key for one source, for one user.
 *
-* The cache lives at the root of the app and outlives a sign-out, and a figure
+* The engine lives at the root of the app and outlives a sign-out, and a figure
 * is computed under the permissions and row-level security of whoever asked
-* for it. A key without the user served the previous account's numbers to the
-* next one that signed in on the same tab, until the TTL ran out.
+* for it. A key without the user would serve the previous account's numbers to
+* the next one that signs in on the same tab, until the TTL ran out.
 */
-function insightCacheKey(definitionId, context, userId) {
-	return JSON.stringify([
-		userId,
-		definitionId,
-		context.path ?? context.collectionSlug ?? "global"
-	]);
+function sourceCacheKey(sourceId, userId) {
+	return JSON.stringify([userId, sourceId]);
 }
 /**
-* In-memory cache for insight query results.
-* Supports TTL-based expiry and inflight request deduplication
-* to prevent redundant network requests when multiple widgets
-* share the same query.
+* Fetches and caches the plugin's sources.
+*
+* Every insight that reads a source shares one fetch of it: concurrent reads
+* join the request in flight, later ones read the cache until the TTL passes.
+* That is what keeps a figure shown on the home page and in a collection view
+* the same number.
 */
-var InsightsCache = class {
+var InsightsEngine = class {
+	sources;
+	periodDays;
 	ttl;
+	now;
 	cache = /* @__PURE__ */ new Map();
 	inflight = /* @__PURE__ */ new Map();
-	constructor(ttl = 6e4) {
+	anchor = null;
+	constructor(sources, periodDays = 30, ttl = 6e4, now = Date.now) {
+		this.sources = sources;
+		this.periodDays = periodDays;
 		this.ttl = ttl;
+		this.now = now;
 	}
-	get(key) {
-		const entry = this.cache.get(key);
-		if (!entry) return null;
-		if (Date.now() - entry.timestamp > this.ttl) {
-			this.cache.delete(key);
-			return null;
-		}
-		return entry.data;
-	}
-	set(key, data) {
-		this.cache.set(key, {
-			data,
-			timestamp: Date.now()
-		});
-		this.inflight.delete(key);
+	/**
+	* The period a fetch starting now is asked for. Its end is fixed by the
+	* first fetch and kept until the TTL passes, so sources fetched for the
+	* same screen describe the same window.
+	*/
+	period() {
+		const now = this.now();
+		if (!this.anchor || now - this.anchor.at > this.ttl) this.anchor = {
+			period: resolvePeriod(this.periodDays, new Date(now)),
+			at: now
+		};
+		return this.anchor.period;
 	}
-	getInflight(key) {
-		return this.inflight.get(key) ?? null;
+	/** The cached result for this source and user, if it is still fresh. */
+	peek(sourceId, userId) {
+		const entry = this.cache.get(sourceCacheKey(sourceId, userId));
+		if (!entry || this.now() - entry.at > this.ttl) return null;
+		return entry.result;
 	}
-	setInflight(key, promise) {
+	/** The source's record for this user: from the cache, the fetch in flight, or a new fetch. */
+	load(sourceId, userId) {
+		const cached = this.peek(sourceId, userId);
+		if (cached) return Promise.resolve(cached);
+		const key = sourceCacheKey(sourceId, userId);
+		const pending = this.inflight.get(key);
+		if (pending) return pending;
+		const source = this.sources[sourceId];
+		if (!source) return Promise.reject(/* @__PURE__ */ new Error(`No insights source is named "${sourceId}".`));
+		const period = this.period();
+		let fetched;
+		try {
+			fetched = Promise.resolve(source({ period }));
+		} catch (error) {
+			fetched = Promise.reject(error);
+		}
+		const promise = fetched.then((row) => {
+			const result = {
+				row,
+				period
+			};
+			if (this.inflight.get(key) === promise) {
+				this.inflight.delete(key);
+				this.cache.set(key, {
+					result,
+					at: this.now()
+				});
+			}
+			return result;
+		}, (error) => {
+			if (this.inflight.get(key) === promise) this.inflight.delete(key);
+			throw error;
+		});
 		this.inflight.set(key, promise);
+		return promise;
 	}
-	invalidate(key) {
-		if (key) {
-			this.cache.delete(key);
-			this.inflight.delete(key);
-		} else {
-			this.cache.clear();
-			this.inflight.clear();
-		}
+	/** Drops every cached result and fetch in flight, and re-anchors the period on the next fetch. */
+	invalidate() {
+		this.cache.clear();
+		this.inflight.clear();
+		this.anchor = null;
 	}
 };
 //#endregion
@@ -70,19 +115,21 @@ var InsightsContext = createContext(null);
 * Root-level provider for the insights data engine.
 * Injected automatically by the plugin via `providers: [{ scope: "root" }]`.
 *
-* Manages a single `InsightsCache` instance shared by all insight widgets
-* for TTL-based caching and inflight request deduplication.
+* Holds the one `InsightsEngine` every insight widget reads its source from.
 */
-function InsightsProvider({ cacheTTL, children }) {
-	const cache = useMemo(() => new InsightsCache(cacheTTL), [cacheTTL]);
-	const value = useMemo(() => ({ cache }), [cache]);
+function InsightsProvider({ sources, periodDays, cacheTTL, children }) {
+	const engine = useMemo(() => new InsightsEngine(sources, periodDays, cacheTTL), [
+		sources,
+		periodDays,
+		cacheTTL
+	]);
 	return /* @__PURE__ */ jsx(InsightsContext.Provider, {
-		value,
+		value: engine,
 		children
 	});
 }
 /**
-* Access the insights cache (for advanced usage).
+* The insights engine (for advanced usage).
 * Returns null when called outside of an `InsightsProvider`
 * (e.g. during auth-loading phase before plugin providers mount).
 */
@@ -90,82 +137,84 @@ function useInsightsEngine() {
 	return useContext(InsightsContext);
 }
 //#endregion
-//#region src/engine/useInsightsData.ts
+//#region src/validateConfig.ts
 /**
-* Hook that fetches and caches data for a single insight definition.
-*
-* Calls the definition's own `data()` callback and manages:
-* - TTL-based caching via InsightsCache
-* - Inflight request deduplication (multiple mounts of the same widget)
-* - Loading and error state management
+* Refuses a config whose insights read a source it does not declare, or whose
+* period is not a whole number of days. Both would otherwise surface as an
+* error tile per insight, on whichever screen a user opened first.
+*/
+function assertValidConfig(config) {
+	const days = config.period?.days ?? 30;
+	if (!Number.isInteger(days) || days < 1) throw new Error(`Insights period.days must be a whole number of days, at least 1; got ${days}.`);
+	const declared = Object.keys(config.sources);
+	const definitions = [...config.insights.home ?? [], ...Object.values(config.insights.collections ?? {}).flat()];
+	for (const definition of definitions) if (!Object.hasOwn(config.sources, definition.source)) throw new Error(`Insight "${definition.id}" reads source "${definition.source}", which is not in \`sources\` (declared: ${declared.length > 0 ? declared.join(", ") : "none"}).`);
+}
+//#endregion
+//#region src/engine/useInsightSource.ts
+/**
+* Reads one source for the signed-in user.
 *
-* @param definition - The insight to fetch data for
-* @param context - The collection scope; with the signed-in user, it scopes the cache key
+* Waits for auth to settle: a source runs under the caller's permissions, so
+* fetching before the user is known would compute the figures for nobody.
 */
-function useInsightsData(definition, context) {
-	const cache = useInsightsEngine()?.cache ?? null;
+function useInsightSource(sourceId) {
+	const engine = useInsightsEngine();
 	const { initialLoading, authLoading, user, loginSkipped } = useAuthController();
 	const authReady = !initialLoading && !authLoading && (Boolean(user) || loginSkipped);
-	const [data, setData] = useState(null);
-	const [loading, setLoading] = useState(true);
-	const [error, setError] = useState(null);
-	const cacheKey = insightCacheKey(definition.id, context, user?.uid ?? null);
+	const userId = user?.uid ?? null;
+	const key = sourceCacheKey(sourceId, userId);
+	const [settled, setSettled] = useState(null);
 	useEffect(() => {
-		if (!authReady || !cache) return;
+		if (!authReady || !engine) return;
 		let cancelled = false;
-		const cached = cache.get(cacheKey);
-		if (cached) {
-			setData(cached);
-			setLoading(false);
-			return;
-		}
-		const inflight = cache.getInflight(cacheKey);
-		if (inflight) {
-			setLoading(true);
-			inflight.then((result) => {
-				if (!cancelled) setData(result);
-			}).catch((err) => {
-				if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
-			}).finally(() => {
-				if (!cancelled) setLoading(false);
+		engine.load(sourceId, userId).then((result) => {
+			if (!cancelled) setSettled({
+				key,
+				result,
+				error: null
+			});
+		}, (error) => {
+			if (!cancelled) setSettled({
+				key,
+				result: null,
+				error: error instanceof Error ? error : new Error(String(error))
 			});
-			return;
-		}
-		setLoading(true);
-		setError(null);
-		const promise = definition.data(context);
-		cache.setInflight(cacheKey, promise);
-		promise.then((result) => {
-			cache.set(cacheKey, result);
-			if (!cancelled) setData(result);
-		}).catch((err) => {
-			cache.invalidate(cacheKey);
-			if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
-		}).finally(() => {
-			if (!cancelled) setLoading(false);
 		});
 		return () => {
 			cancelled = true;
 		};
 	}, [
-		definition.id,
-		definition.data,
-		context.path,
-		context.collectionSlug,
-		cacheKey,
-		cache,
+		engine,
+		sourceId,
+		userId,
+		key,
 		authReady
 	]);
+	const current = settled?.key === key ? settled : null;
+	const cached = !current && authReady && engine ? engine.peek(sourceId, userId) : null;
 	return {
-		data,
-		loading,
-		error
+		result: current?.result ?? cached,
+		loading: !current && !cached,
+		error: current?.error ?? null
 	};
 }
 //#endregion
-//#region src/components/InsightsScorecardView.tsx
-function formatNumber(value, format) {
-	if (value === null || value === void 0) return "N/A";
+//#region src/format.ts
+/**
+* A number formatter in the given language, falling back to the browser's
+* when the language is not a tag `Intl` accepts (i18next's `cimode`, a custom
+* bundle name).
+*/
+function numberFormat(locale, options) {
+	try {
+		return new Intl.NumberFormat(locale, options);
+	} catch {
+		return new Intl.NumberFormat(void 0, options);
+	}
+}
+/** Writes a value the way its insight asks, in the admin panel's language. */
+function formatValue(value, format, locale) {
 	const options = {
 		style: format?.style ?? "decimal",
 		notation: format?.notation ?? "standard"
@@ -175,337 +224,239 @@ function formatNumber(value, format) {
 		options.minimumFractionDigits = format.decimals;
 	}
 	if (format?.style === "currency") options.currency = format.currency ?? "USD";
-	let formatted = new Intl.NumberFormat("en-US", options).format(value);
-	if (format?.showSign && value > 0) formatted = "+" + formatted;
-	return formatted;
+	return numberFormat(locale, options).format(value);
 }
 /**
-* Scorecard widget for the Rebase design system.
+* The change from `previous` to `current`, written as the comparison asks.
 *
-* Renders a single KPI metric with optional comparison value and icon.
-* Uses Tailwind `dark:` classes — no JS dark mode detection.
-* Icons are resolved via `getIcon` from `@rebasepro/app`.
+* A percentage needs a previous figure to be a percentage of, so a change
+* from zero is written as the difference instead. Under 10% keeps one
+* decimal (`0.2%`), above it none (`42%`): the decimal stops carrying
+* information once the change is that large.
 */
-function InsightsScorecardView({ config, data, title, compact = false, embedded = false, fixedHeight }) {
-	const containerRef = useRef(null);
-	const [containerWidth, setContainerWidth] = useState(null);
-	React.useLayoutEffect(() => {
-		if (!containerRef.current) return;
-		setContainerWidth(containerRef.current.offsetWidth);
-		const observer = new ResizeObserver((entries) => {
-			for (const entry of entries) setContainerWidth(entry.contentRect.width);
-		});
-		observer.observe(containerRef.current);
-		return () => observer.disconnect();
-	}, []);
-	const mainValue = data[config.value.field];
-	const formattedValue = typeof mainValue === "number" ? formatNumber(mainValue, config.value.format) : String(mainValue ?? "N/A");
-	let comparisonElement = null;
-	if (config.comparison) {
-		const comparisonValue = data[config.comparison.field];
-		if (typeof comparisonValue === "number") {
-			const formattedComparison = formatNumber(comparisonValue, config.comparison.format);
-			const isPositive = comparisonValue > 0;
-			const isNegative = comparisonValue < 0;
-			let colorClass = "text-surface-500 dark:text-surface-400";
-			if (config.comparison.intent === "increase_is_good") {
-				if (isPositive) colorClass = "text-emerald-500";
-				if (isNegative) colorClass = "text-red-500";
-			} else if (config.comparison.intent === "decrease_is_good") {
-				if (isPositive) colorClass = "text-red-500";
-				if (isNegative) colorClass = "text-emerald-500";
-			}
-			comparisonElement = /* @__PURE__ */ jsx("span", {
-				className: `font-mono tabular-nums font-medium ${compact ? "text-[10px]" : "text-xs"} ${colorClass}`,
-				children: formattedComparison
-			});
-		}
+function formatChange(current, previous, comparison, format, locale) {
+	const delta = current - previous;
+	const direction = delta > 0 ? "up" : delta < 0 ? "down" : "flat";
+	if (comparison.show !== "absolute" && previous !== 0) {
+		const ratio = Math.abs(delta / previous);
+		const decimals = ratio < .1 ? 1 : 0;
+		return {
+			direction,
+			magnitude: numberFormat(locale, {
+				style: "percent",
+				minimumFractionDigits: decimals,
+				maximumFractionDigits: decimals
+			}).format(ratio)
+		};
 	}
-	const isSmall = compact || containerWidth !== null && containerWidth < 200;
-	const iconElement = config.icon ? getIcon(config.icon, "text-text-secondary dark:text-text-secondary-dark", void 0, 14) : null;
-	if (compact) return /* @__PURE__ */ jsxs("div", {
-		className: "flex items-baseline gap-1.5 min-w-0",
-		children: [/* @__PURE__ */ jsx("span", {
-			className: "text-[10px] uppercase tracking-wider text-surface-400 dark:text-surface-500 truncate",
-			children: title
-		}), /* @__PURE__ */ jsxs("div", {
-			className: "flex items-baseline gap-1.5",
-			children: [/* @__PURE__ */ jsx("span", {
-				className: "text-sm font-semibold tabular-nums text-surface-800 dark:text-surface-100",
-				children: formattedValue
-			}), comparisonElement]
-		})]
-	});
-	return /* @__PURE__ */ jsxs("div", {
-		ref: containerRef,
-		className: embedded ? `flex flex-col min-w-0 h-full ${isSmall ? "px-3.5 py-3" : "px-5 py-4"}` : cls("rounded-xl flex flex-col min-w-0 bg-surface-card border", defaultBorderMixin, isSmall ? "px-3.5 py-3" : "px-5 py-4"),
-		style: embedded ? void 0 : fixedHeight ? { height: fixedHeight } : { minHeight: isSmall ? 68 : 92 },
-		children: [
-			/* @__PURE__ */ jsxs("div", {
-				className: `flex flex-col min-w-0 ${isSmall ? "mb-1" : "mb-2.5"}`,
-				children: [/* @__PURE__ */ jsxs("div", {
-					className: "flex items-center gap-1.5 min-w-0",
-					children: [iconElement && /* @__PURE__ */ jsx("span", {
-						className: "shrink-0 flex items-center text-text-secondary dark:text-text-secondary-dark [&>svg]:size-3.5",
-						children: iconElement
-					}), /* @__PURE__ */ jsx("span", {
-						className: "typography-micro truncate text-surface-400 dark:text-surface-400",
-						children: title
-					})]
-				}), config.dateRange && !isSmall && /* @__PURE__ */ jsx("span", {
-					className: "font-mono tabular-nums text-[10px] text-surface-400 dark:text-surface-500 truncate mt-1",
-					children: config.dateRange
-				})]
-			}),
-			/* @__PURE__ */ jsx("div", {
-				className: `font-headers font-semibold leading-tight tracking-display tabular-nums break-all text-text-primary dark:text-text-primary-dark ${isSmall ? "text-lg" : containerWidth !== null && containerWidth < 300 ? "text-xl" : "text-2xl"}`,
-				children: formattedValue
-			}),
-			comparisonElement && /* @__PURE__ */ jsx("div", {
-				className: isSmall ? "mt-0.5" : "mt-1",
-				children: comparisonElement
-			})
-		]
-	});
+	return {
+		direction,
+		magnitude: formatValue(Math.abs(delta), format, locale)
+	};
+}
+/** Whether a change in this direction is good news for this insight. */
+function changeTone(direction, intent) {
+	if (direction === "flat") return "neutral";
+	return direction === (intent === "increase_is_good" ? "up" : "down") ? "positive" : "negative";
 }
-InsightsScorecardView.displayName = "InsightsScorecardView";
 //#endregion
-//#region src/components/InsightWidgetSkeleton.tsx
+//#region src/components/InsightsScorecardView.tsx
+var toneClasses = {
+	positive: "text-emerald-700 dark:text-emerald-400",
+	negative: "text-red-600 dark:text-red-500",
+	neutral: "text-text-secondary dark:text-text-secondary-dark"
+};
+/** A pulsing bar standing in for a figure that has not arrived, sized by its line box. */
+function Placeholder({ className }) {
+	return /* @__PURE__ */ jsx("span", { className: cls("inline-block align-middle rounded-sm bg-surface-200 dark:bg-surface-700 animate-pulse", className) });
+}
+function displayValue(row, definition, locale) {
+	const value = row?.[definition.value.field];
+	if (typeof value === "number") return formatValue(value, definition.value.format, locale);
+	if (typeof value === "string" && value !== "") return value;
+	return "—";
+}
 /**
-* Skeleton loader for scorecard insight widgets — displays animated
-* shimmer placeholders that exactly match the final rendered layout
-* of InsightsScorecardView for a given config, preventing layout shift.
-*
-* The skeleton receives the scorecard config so it can conditionally
-* render placeholder lines for comparison, dateRange, and icon —
-* only when the loaded view will also render them.
-*
-* The standard skeleton mirrors InsightsScorecardView's responsive
-* container-width breakpoints (ResizeObserver → isSmall / isMedium)
-* and uses placeholder heights that exactly match the **computed**
-* Tailwind line-heights (accounting for `leading-*` overrides).
-* This guarantees a pixel-perfect skeleton → loaded transition.
+* The change against the previous period: an arrow and its size, coloured by
+* whether it is good news. The arrow is what carries the direction, so it
+* reads without the colour.
 */
-function InsightWidgetSkeleton({ config, compact = false, embedded = false, fixedHeight }) {
-	const hasComparison = Boolean(config.comparison);
-	const hasIcon = Boolean(config.icon);
-	const hasDateRange = Boolean(config.dateRange);
-	if (compact) return /* @__PURE__ */ jsxs("div", {
-		className: cls("animate-pulse", embedded ? "h-full px-2.5 py-2" : "flex flex-col gap-0.5 rounded-md bg-transparent border min-w-0 px-2.5 py-2", !embedded && defaultBorderMixin),
-		children: [/* @__PURE__ */ jsx("div", {
-			className: "bg-surface-200 dark:bg-surface-700 rounded-sm",
-			style: {
-				height: 14,
-				width: 48
-			}
-		}), /* @__PURE__ */ jsxs("div", {
-			className: "flex items-baseline gap-1.5",
-			children: [/* @__PURE__ */ jsx("div", {
-				className: "bg-surface-200 dark:bg-surface-700 rounded-sm",
-				style: {
-					height: 20,
-					width: 40
-				}
-			}), hasComparison && /* @__PURE__ */ jsx("div", {
-				className: "bg-surface-200/60 dark:bg-surface-700/60 rounded-sm",
-				style: {
-					height: 14,
-					width: 28
-				}
-			})]
-		})]
+function InsightChange({ definition, row, period, locale, tooltip }) {
+	const { t } = useTranslation();
+	const comparison = definition.comparison;
+	if (!comparison) return null;
+	const current = row[definition.value.field];
+	const previous = row[comparison.previous];
+	if (typeof current !== "number" || typeof previous !== "number") return null;
+	const change = formatChange(current, previous, comparison, definition.value.format, locale);
+	const arrow = change.direction === "up" ? "↑" : change.direction === "down" ? "↓" : null;
+	const spoken = change.direction === "up" ? t("insights_change_up", { change: change.magnitude }) : change.direction === "down" ? t("insights_change_down", { change: change.magnitude }) : t("insights_change_none");
+	const previousLabel = t("insights_previous_period_value", {
+		count: period.days,
+		value: formatValue(previous, definition.value.format, locale)
 	});
-	return /* @__PURE__ */ jsx(StandardSkeleton, {
-		hasComparison,
-		hasIcon,
-		hasDateRange,
-		embedded,
-		fixedHeight
+	const label = /* @__PURE__ */ jsxs("span", {
+		className: cls("typography-mono text-xs font-medium whitespace-nowrap", toneClasses[changeTone(change.direction, comparison.intent)]),
+		children: [/* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			children: arrow ? `${arrow} ${change.magnitude}` : change.magnitude
+		}), /* @__PURE__ */ jsx("span", {
+			className: "sr-only",
+			children: `${spoken}. ${previousLabel}`
+		})]
 	});
+	return tooltip ? /* @__PURE__ */ jsx(Tooltip, {
+		title: previousLabel,
+		children: label
+	}) : label;
 }
 /**
-* Inner component for the standard scorecard skeleton.
+* One insight: its label, its value and its change on the previous period.
 *
-* Mirrors InsightsScorecardView's layout by:
-* 1. Using the same ResizeObserver + containerWidth pattern for
-*    responsive breakpoints (isSmall < 200px, isMedium < 300px).
-* 2. Using placeholder heights derived from the exact computed
-*    Tailwind line-heights that InsightsScorecardView renders.
-* 3. Matching all container classes, margins, paddings, and flex
-*    layout properties identically.
+* The label and icon are known before the figures are, so they render while
+* the source loads and only the figures pulse. Loading, loaded and failed
+* share one shell, so nothing moves when the data arrives.
+*
+* `compact` is the inline readout on a home-page card; the default is a tile.
 */
-function StandardSkeleton({ hasComparison, hasIcon, hasDateRange, embedded, fixedHeight }) {
-	const containerRef = useRef(null);
-	const [containerWidth, setContainerWidth] = useState(null);
-	React.useLayoutEffect(() => {
-		if (!containerRef.current) return;
-		setContainerWidth(containerRef.current.offsetWidth);
-		const observer = new ResizeObserver((entries) => {
-			for (const entry of entries) setContainerWidth(entry.contentRect.width);
-		});
-		observer.observe(containerRef.current);
-		return () => observer.disconnect();
-	}, []);
-	const isSmall = containerWidth !== null && containerWidth < 200;
-	const titleHeight = isSmall ? 15 : 16.5;
-	const valueHeight = isSmall ? 22.5 : containerWidth !== null && containerWidth < 300 ? 25 : 30;
-	const comparisonHeight = 16;
-	const iconSize = isSmall ? 14 : 18;
-	return /* @__PURE__ */ jsxs("div", {
-		ref: containerRef,
-		className: cls("animate-pulse", embedded ? `flex flex-col min-w-0 h-full ${isSmall ? "px-3.5 py-3" : "px-5 py-4"}` : cls("rounded-lg flex flex-col min-w-0 bg-transparent border", defaultBorderMixin, isSmall ? "px-3.5 py-3" : "px-5 py-4")),
-		style: embedded ? void 0 : fixedHeight ? { height: fixedHeight } : { minHeight: isSmall ? 68 : 92 },
+function InsightsScorecardView({ definition, result, loading = false, error = null, compact = false }) {
+	const { i18n } = useTranslation();
+	const locale = i18n.language;
+	const row = result?.row;
+	const value = displayValue(row, definition, locale);
+	if (compact) return /* @__PURE__ */ jsxs("div", {
+		className: "flex items-baseline gap-1.5 min-w-0",
+		title: error?.message,
 		children: [
-			/* @__PURE__ */ jsxs("div", {
-				className: `flex items-center justify-between ${isSmall ? "mb-1" : "mb-2"}`,
-				children: [/* @__PURE__ */ jsxs("div", {
-					className: "flex flex-col min-w-0",
-					children: [/* @__PURE__ */ jsx("div", {
-						className: "bg-surface-200 dark:bg-surface-700 rounded",
-						style: {
-							height: titleHeight,
-							width: "60%"
-						}
-					}), hasDateRange && !isSmall && /* @__PURE__ */ jsx("div", {
-						className: "bg-surface-200/60 dark:bg-surface-700/60 rounded mt-0.5",
-						style: {
-							height: 14,
-							width: "40%"
-						}
-					})]
-				}), hasIcon && /* @__PURE__ */ jsx("span", {
-					className: "ml-2 shrink-0",
-					children: /* @__PURE__ */ jsx("div", {
-						className: "bg-surface-200 dark:bg-surface-700 rounded",
-						style: {
-							height: iconSize,
-							width: iconSize
-						}
-					})
-				})]
+			/* @__PURE__ */ jsx(Typography, {
+				variant: "micro",
+				color: "secondary",
+				className: "truncate",
+				children: definition.title
 			}),
-			/* @__PURE__ */ jsx("div", {
-				className: "bg-surface-200 dark:bg-surface-700 rounded",
-				style: {
-					height: valueHeight,
-					width: "40%"
-				}
+			loading ? /* @__PURE__ */ jsx(Placeholder, { className: "h-3 w-8" }) : /* @__PURE__ */ jsx("span", {
+				className: "text-sm font-semibold tabular-nums text-text-primary dark:text-text-primary-dark",
+				children: value
 			}),
-			hasComparison && /* @__PURE__ */ jsx("div", {
-				className: isSmall ? "mt-0.5" : "mt-1",
-				children: /* @__PURE__ */ jsx("div", {
-					className: "bg-surface-200/60 dark:bg-surface-700/60 rounded",
-					style: {
-						height: comparisonHeight,
-						width: "25%"
-					}
-				})
+			!loading && row && result && /* @__PURE__ */ jsx(InsightChange, {
+				definition,
+				row,
+				period: result.period,
+				locale,
+				tooltip: false
 			})
 		]
 	});
+	const icon = definition.icon ? getIcon(definition.icon, "text-text-secondary dark:text-text-secondary-dark", void 0, 14) : null;
+	return /* @__PURE__ */ jsx("div", {
+		className: cls("@container rounded-xl bg-surface-card border min-w-0", defaultBorderMixin),
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "flex flex-col min-w-0 h-full px-5 py-4 @max-[200px]:px-3.5 @max-[200px]:py-3",
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "flex items-center gap-1.5 min-w-0 mb-2.5 @max-[200px]:mb-1",
+					children: [icon && /* @__PURE__ */ jsx("span", {
+						className: "shrink-0 flex items-center text-text-secondary dark:text-text-secondary-dark [&>svg]:size-3.5",
+						children: icon
+					}), /* @__PURE__ */ jsx(Typography, {
+						variant: "micro",
+						color: "secondary",
+						className: "truncate",
+						children: definition.title
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					className: "typography-stat leading-tight break-all text-text-primary dark:text-text-primary-dark @max-[200px]:text-xl",
+					children: loading ? /* @__PURE__ */ jsx(Placeholder, { className: "h-[0.8em] w-24" }) : value
+				}),
+				error ? /* @__PURE__ */ jsx(Typography, {
+					variant: "caption",
+					color: "error",
+					className: "block mt-1 truncate",
+					title: error.message,
+					children: error.message
+				}) : definition.comparison && /* @__PURE__ */ jsx("div", {
+					className: "mt-1 leading-4",
+					children: loading || !row || !result ? /* @__PURE__ */ jsx(Placeholder, { className: "h-3 w-12" }) : /* @__PURE__ */ jsx(InsightChange, {
+						definition,
+						row,
+						period: result.period,
+						locale,
+						tooltip: true
+					})
+				})
+			]
+		})
+	});
 }
-InsightWidgetSkeleton.displayName = "InsightWidgetSkeleton";
+InsightsScorecardView.displayName = "InsightsScorecardView";
 //#endregion
 //#region src/components/InsightWidget.tsx
-/**
-* Compute a deterministic fixed height for a standard scorecard based
-* on which optional elements the config declares.  This eliminates
-* layout shift between skeleton and loaded states.
-*
-* Breakdown (non-compact, non-small):
-*   py-4 padding:     16 + 16 = 32
-*   title row:        16.5  (text-xs leading-snug)
-*   mb-2 margin:      8
-*   value:            30    (text-2xl leading-tight)
-*   ---
-*   base:             86.5
-*   + dateRange:      +16   (14px text + 2px mt-0.5)
-*   + comparison:     +20   (16px text + 4px mt-1)
-*/
-function computeFixedHeight(config) {
-	let h = 86.5;
-	if (config.dateRange) h += 16;
-	if (config.comparison) h += 20;
-	return Math.ceil(h);
-}
-/**
-* Single insight widget orchestrator.
-*
-* Wraps skeleton and loaded states in a fixed-height container
-* (computed from the scorecard config) to prevent layout shift.
-*
-* All theme-awareness is handled via Tailwind `dark:` classes.
-*/
-function InsightWidget({ definition, collectionSlug, path, parentCollectionSlugs, parentEntityIds, compact = false, embedded = false }) {
-	const { data, loading, error } = useInsightsData(definition, {
-		path,
-		collectionSlug,
-		parentCollectionSlugs
-	});
-	const fixedHeight = !compact && !embedded ? computeFixedHeight(definition.scorecard) : void 0;
-	if (loading) return /* @__PURE__ */ jsx(InsightWidgetSkeleton, {
-		config: definition.scorecard,
-		compact,
-		embedded,
-		fixedHeight
-	});
-	if (error) return /* @__PURE__ */ jsxs("div", {
-		className: `text-red-500/70 dark:text-red-400/70 text-[0.8125rem] ${embedded ? "px-5 py-4 h-full" : `rounded-lg bg-red-500/5 dark:bg-red-400/5 border border-red-500/10 dark:border-red-400/10 ${compact ? "px-3.5 py-3" : "px-5 py-4"}`}`,
-		style: fixedHeight ? { height: fixedHeight } : void 0,
-		children: [/* @__PURE__ */ jsx("div", {
-			className: "font-semibold mb-1",
-			children: definition.title
-		}), /* @__PURE__ */ jsx("div", { children: error.message })]
-	});
-	if (!data || data.rows.length === 0) return /* @__PURE__ */ jsxs("div", {
-		className: `text-surface-400 dark:text-surface-500 text-[0.8125rem] ${embedded ? "px-5 py-4 h-full" : `rounded-lg bg-surface-100 dark:bg-surface-800 border border-surface-200 dark:border-surface-700 ${compact ? "px-3.5 py-3" : "px-5 py-4"}`}`,
-		style: fixedHeight ? { height: fixedHeight } : void 0,
-		children: [definition.title, " — No data"]
-	});
+/** One insight, reading its source through the shared engine. */
+function InsightWidget({ definition, compact = false }) {
+	const { result, loading, error } = useInsightSource(definition.source);
 	return /* @__PURE__ */ jsx(InsightsScorecardView, {
-		config: definition.scorecard,
-		data: data.rows[0],
-		title: definition.title,
-		compact,
-		embedded,
-		fixedHeight
+		definition,
+		result,
+		loading,
+		error,
+		compact
 	});
 }
 InsightWidget.displayName = "InsightWidget";
 //#endregion
 //#region src/components/HomeCardInsightSlot.tsx
 /**
-* Renders compact insight widgets inline within a home page collection card.
+* Renders compact insight readouts inside a home page collection card.
 * Injected via the `home.card.widget` slot.
-*
-* Uses a horizontal flex layout so multiple cards sit side by side.
 */
-function HomeCardInsightSlot({ slug, insights }) {
+function HomeCardInsightSlot({ insights }) {
 	if (!insights || insights.length === 0) return null;
 	return /* @__PURE__ */ jsx("div", {
 		className: "flex flex-wrap items-baseline gap-x-4 gap-y-1 mt-1.5",
-		children: insights.map((def) => /* @__PURE__ */ jsx(InsightWidget, {
-			definition: def,
-			collectionSlug: slug,
+		children: insights.map((definition) => /* @__PURE__ */ jsx(InsightWidget, {
+			definition,
 			compact: true
-		}, def.id))
+		}, definition.id))
 	});
 }
 HomeCardInsightSlot.displayName = "HomeCardInsightSlot";
 //#endregion
+//#region src/components/InsightsRow.tsx
+/**
+* A row of insight tiles. When any of them compares with the previous period,
+* the row says which period once, above the tiles, rather than on each.
+*/
+function InsightsRow({ insights, className }) {
+	const { t } = useTranslation();
+	const days = useInsightsEngine()?.periodDays ?? 30;
+	const compares = insights.some((definition) => definition.comparison);
+	return /* @__PURE__ */ jsxs("section", {
+		className: cls("w-full", className),
+		children: [compares && /* @__PURE__ */ jsx(Typography, {
+			variant: "micro",
+			color: "secondary",
+			component: "h2",
+			className: "block py-1 mb-4",
+			children: t("insights_period_last_days", { count: days })
+		}), /* @__PURE__ */ jsx("div", {
+			className: "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-4",
+			children: insights.map((definition) => /* @__PURE__ */ jsx(InsightWidget, { definition }, definition.id))
+		})]
+	});
+}
+InsightsRow.displayName = "InsightsRow";
+//#endregion
 //#region src/components/HomeInsightsSlot.tsx
 /**
 * Scorecard insights panel rendered at the top of the home page.
 * Injected via the `home.children.start` slot.
-*
-* Renders scorecards in a responsive grid (up to 4 columns).
 */
 function HomeInsightsSlot({ insights }) {
 	if (!insights || insights.length === 0) return null;
-	return /* @__PURE__ */ jsx("div", {
-		className: "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3 pb-6",
-		style: { minHeight: 92 },
-		children: insights.map((def) => /* @__PURE__ */ jsx(InsightWidget, { definition: def }, def.id))
+	return /* @__PURE__ */ jsx(InsightsRow, {
+		insights,
+		className: "mt-6 pb-2"
 	});
 }
 HomeInsightsSlot.displayName = "HomeInsightsSlot";
@@ -517,16 +468,11 @@ HomeInsightsSlot.displayName = "HomeInsightsSlot";
 *
 * Injected via the `collection.widgets` slot.
 */
-function CollectionInsightsInline({ insights, path, parentCollectionSlugs, parentEntityIds }) {
+function CollectionInsightsInline({ insights }) {
 	if (!insights || insights.length === 0) return null;
-	return /* @__PURE__ */ jsx("div", {
-		className: "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3 pb-4",
-		children: insights.map((def) => /* @__PURE__ */ jsx(InsightWidget, {
-			definition: def,
-			path,
-			parentCollectionSlugs,
-			parentEntityIds
-		}, def.id))
+	return /* @__PURE__ */ jsx(InsightsRow, {
+		insights,
+		className: "pb-4"
 	});
 }
 CollectionInsightsInline.displayName = "CollectionInsightsInline";
@@ -538,46 +484,60 @@ CollectionInsightsInline.displayName = "CollectionInsightsInline";
 * This plugin injects scorecard widgets into key UI locations:
 * - **Home page header**: KPI overview via `home.children.start` slot
 * - **Collection list view**: Scorecards inline (below title, above list) via `collection.widgets` slot
-* - **Home page cards**: Compact scorecard metrics auto-extracted from collection insights via `home.card.widget` slot
+* - **Home page cards**: Compact readouts of the collection's insights via `home.card.widget` slot
 *
-* Collection-level insights (`collections.<slug>`) are the single source of truth:
-* scorecards render in the collection list view and are automatically extracted
-* to show as compact widgets on the corresponding home page card.
+* Figures come from named `sources`, each fetched once per user however many
+* insights read it: a value shown on the home page and in a collection view
+* is the same number. Every source is handed the comparison period, so the
+* query and the label above the tiles describe the same window.
 *
-* Each insight owns its own `data()` callback — use the Rebase client SDK,
-* call a custom function, or hit any external API. Full flexibility, zero new endpoints.
+* Pass a memoized config: a new `sources` object starts a new cache.
 *
 * @example
 * ```typescript
 * import { useInsightsPlugin } from "@rebasepro/plugin-insights";
 *
-* const insightsPlugin = useInsightsPlugin({
-*     cacheTTL: 120_000,
+* const insightsPlugin = useInsightsPlugin(useMemo(() => ({
+*     period: { days: 30 },
+*     sources: {
+*         orders: ({ period }) => fetchOrderStats(period.from, period.to, period.previousFrom)
+*     },
 *     insights: {
-*         home: [
-*             { id: "revenue", title: "Revenue", data: async () => ..., scorecard: { ... } },
-*         ],
+*         home: [{
+*             id: "revenue",
+*             title: "Revenue",
+*             source: "orders",
+*             value: { field: "revenue", format: { style: "currency", currency: "USD" } },
+*             comparison: { previous: "previousRevenue", intent: "increase_is_good" }
+*         }],
 *         collections: {
-*             orders: [
-*                 { id: "total", title: "Total Orders", data: async () => ..., scorecard: { ... } },
-*             ],
-*         },
-*     },
-* });
+*             orders: [{
+*                 id: "shipped",
+*                 title: "Shipped",
+*                 source: "orders",
+*                 value: { field: "shipped" },
+*                 comparison: { previous: "previousShipped", intent: "increase_is_good", show: "absolute" }
+*             }]
+*         }
+*     }
+* }), []));
 * ```
 */
 function useInsightsPlugin(config) {
-	const { insights, cacheTTL } = config;
+	const { insights, sources, period, cacheTTL } = config;
+	const periodDays = period?.days ?? 30;
 	return React.useMemo(() => {
+		assertValidConfig({
+			insights,
+			sources,
+			period: { days: periodDays }
+		});
 		const slots = [];
 		if (insights.home && insights.home.length > 0) {
 			const homeInsights = insights.home;
 			slots.push({
 				slot: "home.children.start",
-				Component: (props) => /* @__PURE__ */ jsx(HomeInsightsSlot, {
-					...props,
-					insights: homeInsights
-				}),
+				Component: () => /* @__PURE__ */ jsx(HomeInsightsSlot, { insights: homeInsights }),
 				order: 10
 			});
 		}
@@ -589,10 +549,7 @@ function useInsightsPlugin(config) {
 				Component: (props) => {
 					if ((props.path?.split("/").filter(Boolean).pop() ?? "") !== slug) return null;
 					if (props.parentEntityIds && props.parentEntityIds.length > 0) return null;
-					return /* @__PURE__ */ jsx(CollectionInsightsInline, {
-						...props,
-						insights: collectionInsights
-					});
+					return /* @__PURE__ */ jsx(CollectionInsightsInline, { insights: collectionInsights });
 				},
 				order: 10
 			});
@@ -600,10 +557,7 @@ function useInsightsPlugin(config) {
 				slot: "home.card.widget",
 				Component: (props) => {
 					if (props.slug !== slug) return null;
-					return /* @__PURE__ */ jsx(HomeCardInsightSlot, {
-						...props,
-						insights: collectionInsights
-					});
+					return /* @__PURE__ */ jsx(HomeCardInsightSlot, { insights: collectionInsights });
 				},
 				order: 10
 			});
@@ -614,12 +568,21 @@ function useInsightsPlugin(config) {
 			providers: [{
 				scope: "root",
 				Component: InsightsProvider,
-				props: { cacheTTL }
+				props: {
+					sources,
+					periodDays,
+					cacheTTL
+				}
 			}]
 		};
-	}, [insights, cacheTTL]);
+	}, [
+		insights,
+		sources,
+		periodDays,
+		cacheTTL
+	]);
 }
 //#endregion
-export { InsightWidget, InsightWidgetSkeleton, InsightsCache, InsightsProvider, InsightsScorecardView, useInsightsData, useInsightsEngine, useInsightsPlugin };
+export { InsightWidget, InsightsEngine, InsightsProvider, InsightsRow, InsightsScorecardView, resolvePeriod, useInsightSource, useInsightsEngine, useInsightsPlugin };
 
 //# sourceMappingURL=index.es.js.map