@heyramzi/ui 2.14.0 → 2.15.0

package/dist/charts/smoothing.js

@@ -1,13 +1,18 @@
 /** The tooltip's name for a drawn point, beside its date. */
-export const ROLLING_LABEL = "7-day average";
+export const averageLabel = (days) => `${days}-day average`;
+export const ROLLING_LABEL = averageLabel(7);
 export const weekOf = (start) => `Week of ${start}`;
-export const averageTo = (end) => `${ROLLING_LABEL} to ${end}`;
+export const averageTo = (end, days = 7) => `${averageLabel(days)} to ${end}`;
+/** What a point the collector never measured reads as, where a number would claim a 0. */
+export const NO_DATA = "No data";
 const DAY = 864e5;
-const WINDOW = 7;
+const WEEK = 7;
+/** A year at 7 days still drew one-day spikes as humps; 28 days keeps the growth and drops the spikes. */
+const LONG_WINDOW = 28;
 // =========================
 // FUNCTIONS
 // =========================
-/** About 30 to 60 marks across a chart: raw to a week, a 7-day average to a quarter, whole weeks past it. */
+/** About 30 to 60 marks across a chart: raw to a fortnight, a daily average to a quarter, weekly past it. */
 export function smoothMode(rangeDays) {
 	if (rangeDays <= 14) return "raw";
 	if (rangeDays <= 120) return "rolling";
@@ -16,70 +21,105 @@ export function smoothMode(rangeDays) {
 function timeOf(value) {
 	return value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
 }
+/** Null, undefined or not a number: a day nobody measured. An absent row still counts as 0. */
+function measured(value) {
+	if (value == null) return null;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : null;
+}
 /** The bucket's start in the same form the series uses, so the axis and the formatter see no change. */
 function sameForm(sample, time) {
 	if (sample instanceof Date) return new Date(time);
 	const iso = new Date(time).toISOString();
 	return String(sample).length === 10 ? iso.slice(0, 10) : iso;
 }
+const daysBetween = (from, to) => Math.round((to - from) / DAY);
+/**
+* A trailing mean over `window` days, drawn on the days `keep` picks.
+*
+* A missing value is skipped, never averaged in as 0, and a window with fewer measured days than
+* missing ones draws a gap: one partial day after a 12-day outage is not a week. Days before a
+* series' first measured value are not tracked yet, so they neither draw nor count as missing.
+*/
+function trailingMean(data, times, yKeys, window, keep) {
+	const firstSeen = Object.fromEntries(yKeys.map((k) => [k, times[data.findIndex((d) => measured(d[k]) !== null)] ?? Infinity]));
+	const out = [];
+	data.forEach((d, i) => {
+		if (!keep(i)) return;
+		const row = { ...d };
+		for (const k of yKeys) {
+			if (times[i] < firstSeen[k]) {
+				row[k] = null;
+				continue;
+			}
+			let sum = 0;
+			let missing = 0;
+			for (let j = i; j >= 0 && times[i] - times[j] < window * DAY; j--) {
+				const value = measured(data[j][k]);
+				if (value === null) missing += times[j] >= firstSeen[k] ? 1 : 0;
+				else sum += value;
+			}
+			// Divided by the tracked days in the window, so a row absent from a sparse series counts as 0.
+			const days = Math.min(window, daysBetween(Math.max(times[0], firstSeen[k]), times[i]) + 1);
+			const seen = days - missing;
+			row[k] = seen > 0 && seen * 2 >= days ? sum / seen : null;
+		}
+		out.push(row);
+	});
+	return out;
+}
 /**
-* The line a chart draws: a trailing 7-day mean, or 7-day buckets counted back from the last day.
-* Totals stay the caller's raw sums; this only moves the drawn points.
+* The line a chart draws. Up to a quarter, a trailing 7-day mean per day. Past it, a trailing
+* 28-day mean read once a week from the last day, so the axis stays in per-day units at every
+* range; a level reads its last value each week instead. A missing value (null) is a gap in the
+* line, never a 0. Totals stay the caller's raw sums; this only moves the drawn points.
 */
 export function smoothSeries(data, xKey, yKeys, { rangeDays, kind = "count" }) {
 	const mode = smoothMode(rangeDays);
-	if (mode === "raw" || data.length < WINDOW) return {
+	if (mode === "raw" || data.length < WEEK) return {
 		points: data,
-		mode: "raw"
+		mode: "raw",
+		window: 1
 	};
 	const times = data.map((d) => timeOf(d[xKey]));
-	if (mode === "rolling") {
-		// A level has no daily noise to average, and a mean draws slopes between its steps.
-		if (kind === "level") return {
-			points: data,
-			mode: "raw"
-		};
-		let from = 0;
-		const sums = Object.fromEntries(yKeys.map((k) => [k, 0]));
-		const points = data.map((d, i) => {
-			for (const k of yKeys) sums[k] += Number(d[k] ?? 0);
-			while (times[i] - times[from] >= WINDOW * DAY) {
-				for (const k of yKeys) sums[k] -= Number(data[from][k] ?? 0);
-				from += 1;
-			}
-			// Divided by the days in the window, so a missing day counts as zero, not skipped.
-			const days = Math.min(WINDOW, Math.round((times[i] - times[0]) / DAY) + 1);
-			const row = { ...d };
-			for (const k of yKeys) row[k] = sums[k] / days;
-			return row;
-		});
+	const last = times[times.length - 1];
+	if (kind === "count") {
+		const window = mode === "rolling" ? WEEK : LONG_WINDOW;
+		const keep = mode === "rolling" ? () => true : (i) => daysBetween(times[i], last) % WEEK === 0;
 		return {
-			points,
-			mode
+			points: trailingMean(data, times, yKeys, window, keep),
+			mode: "rolling",
+			window
 		};
 	}
-	// Weeks end on the last day, so only the oldest can be partial, and a partial week is dropped:
-	// a 3-day sum would draw a dip that never happened.
-	const last = times[times.length - 1];
+	// A level has no daily noise to average, and a mean draws slopes between its steps.
+	if (mode === "rolling") return {
+		points: data,
+		mode: "raw",
+		window: 1
+	};
+	// Weeks end on the last day, so only the oldest can be partial, and a partial week is dropped.
 	const buckets = new Map();
 	data.forEach((d, i) => {
-		const index = Math.floor(Math.round((last - times[i]) / DAY) / WINDOW);
+		const index = Math.floor(daysBetween(times[i], last) / WEEK);
 		buckets.set(index, [...buckets.get(index) ?? [], d]);
 	});
 	const oldest = Math.max(...buckets.keys());
-	const oldestStart = last - (oldest * WINDOW + WINDOW - 1) * DAY;
+	const oldestStart = last - (oldest * WEEK + WEEK - 1) * DAY;
 	if (times[0] > oldestStart && buckets.size > 1) buckets.delete(oldest);
 	const points = [...buckets.entries()].toSorted(([a], [b]) => b - a).map(([index, rows]) => {
 		const row = { ...rows[rows.length - 1] };
-		row[xKey] = sameForm(data[0][xKey], last - (index * WINDOW + WINDOW - 1) * DAY);
+		row[xKey] = sameForm(data[0][xKey], last - (index * WEEK + WEEK - 1) * DAY);
 		for (const k of yKeys) {
-			row[k] = kind === "level" ? Number(rows[rows.length - 1][k] ?? 0) : rows.reduce((sum, r) => sum + Number(r[k] ?? 0), 0);
+			const readings = rows.map((r) => measured(r[k])).filter((v) => v !== null);
+			row[k] = readings.length > 0 ? readings[readings.length - 1] : null;
 		}
 		return row;
 	});
 	return {
 		points,
-		mode
+		mode,
+		window: WEEK
 	};
 }
 /** Labels at least `spacing` pixels apart, the way a time axis reads at any width. */

package/dist/work/kanban-board-state.svelte.js

@@ -0,0 +1,205 @@
+import { untrack } from "svelte";
+import { SvelteSet } from "svelte/reactivity";
+import { prefersReducedMotion } from "svelte/motion";
+import { cubicOut } from "svelte/easing";
+import { durationMs } from "../lib/motion.js";
+import { createKanbanDnd } from "./use-kanban-dnd.svelte.js";
+import { createKanbanRailState } from "./kanban-rail-state.svelte.js";
+import { createCardKeyDown } from "./kanban-keyboard.js";
+/**
+* A board's state: sort, the per-column fold and cap, and the drag wiring. The hidden rail
+* lives in `rail`, the keyboard move in `onCardKeyDown`.
+* Call it during component init, since it registers an effect. `input` is read on every use.
+*/
+export function createKanbanBoardState(input) {
+	// The drop slot takes the held card's height, so the column doesn't jump when it lands.
+	let slotHeight = $state(0);
+	let slotMotion = $derived({
+		duration: prefersReducedMotion.current ? 0 : durationMs("quick"),
+		easing: cubicOut
+	});
+	let internalExpanded = $state([]);
+	let expandedIds = $derived(input().expanded ?? internalExpanded);
+	function compare(a, b) {
+		const { sortKey, manualTiebreak, boardOrder, sortKeys } = input();
+		if (sortKey === "manual") {
+			const tie = manualTiebreak?.(a, b) ?? 0;
+			if (!boardOrder) return tie;
+			const ao = boardOrder(a);
+			const bo = boardOrder(b);
+			if (ao == null && bo == null) return tie;
+			if (ao == null) return 1;
+			if (bo == null) return -1;
+			return ao < bo ? -1 : ao > bo ? 1 : tie;
+		}
+		const key = sortKeys.find((entry) => entry.id === sortKey);
+		return key ? key.compare(a, b) : 0;
+	}
+	function sortedByColumn(columnId) {
+		const { items, getColumn } = input();
+		return items.filter((item) => getColumn(item) === columnId).slice().sort(compare);
+	}
+	function idAt(list, index) {
+		const item = list[index];
+		return item === undefined ? null : input().getId(item);
+	}
+	function capOf(columnId) {
+		const { limit } = input();
+		return typeof limit === "function" ? limit(columnId) : limit;
+	}
+	/** The column holds more cards than its cap, so it gets a fold. */
+	function isFoldable(columnId, total) {
+		const cap = capOf(columnId);
+		return cap !== undefined && total > cap;
+	}
+	// Open from this board's "Show N more", on top of the header caret's `expanded`.
+	const laneOpen = new SvelteSet();
+	function isOpen(columnId) {
+		return expandedIds.includes(columnId) || laneOpen.has(columnId);
+	}
+	/** The fold is shut, so the tail is out of sight. */
+	function isCapped(columnId, total) {
+		return isFoldable(columnId, total) && !isOpen(columnId);
+	}
+	// A card moved into a folded column stays in view, wherever its sort puts it.
+	const pinned = new SvelteSet();
+	// The caret folding a column shuts this board's own fold of it too, so every lane lands on the cap.
+	let previousExpanded = [];
+	$effect(() => {
+		const now = expandedIds;
+		untrack(() => {
+			for (const id of previousExpanded) if (!now.includes(id)) shut(id);
+		});
+		previousExpanded = [...now];
+	});
+	function moveAndPin(id, move) {
+		pinned.add(id);
+		return input().onMove(id, move);
+	}
+	function canDrop(columnId) {
+		const { isDroppable, columns } = input();
+		return isDroppable?.(columnId) ?? columns.find((c) => c.id === columnId)?.droppable ?? true;
+	}
+	function setExpanded(next) {
+		internalExpanded = next;
+		input().onExpandedChange?.(next);
+	}
+	// Shutting drops the column's pins, so the fold closes to exactly its cap.
+	function shut(columnId) {
+		laneOpen.delete(columnId);
+		for (const item of sortedByColumn(columnId)) pinned.delete(input().getId(item));
+	}
+	/** "Show N more": opens this board's cell only. */
+	function expand(columnId) {
+		laneOpen.add(columnId);
+	}
+	/** "Show less": shuts this board's cell, and lifts the caret's open if it was the caret's. */
+	function collapse(columnId) {
+		shut(columnId);
+		if (expandedIds.includes(columnId)) setExpanded(expandedIds.filter((id) => id !== columnId));
+	}
+	/** The header caret: the whole column, in every board that shares `expanded`. */
+	function toggleColumn(columnId) {
+		if (expandedIds.includes(columnId)) collapse(columnId);
+		else setExpanded([...expandedIds, columnId]);
+	}
+	const dnd = createKanbanDnd({
+		items: () => input().items,
+		getId: (item) => input().getId(item),
+		getColumn: (item) => input().getColumn(item),
+		getColumnItems: sortedByColumn,
+		getSortKey: () => input().sortKey,
+		boardOrder: (item) => input().boardOrder?.(item),
+		onMove: moveAndPin,
+		dropAtTop: (columnId) => input().dropAtTop?.(columnId) ?? isCapped(columnId, sortedByColumn(columnId).length),
+		isDroppable: canDrop
+	});
+	const rail = createKanbanRailState({
+		hidden: () => input().hidden,
+		onHiddenChange: () => input().onHiddenChange,
+		canDrop,
+		dnd
+	});
+	const onCardKeyDown = createCardKeyDown({
+		input,
+		canDrop,
+		isHidden: (columnId) => rail.hiddenSet.has(columnId),
+		sortedByColumn,
+		isCapped,
+		moveAndPin
+	});
+	let view = $derived(input().columns.map((column) => {
+		const all = sortedByColumn(column.id);
+		const cap = capOf(column.id);
+		const foldable = isFoldable(column.id, all.length);
+		const open = foldable && isOpen(column.id);
+		if (!foldable || cap === undefined) {
+			return {
+				column,
+				all,
+				head: all,
+				tail: [],
+				foldable,
+				open,
+				capped: false
+			};
+		}
+		// Head: the first `cap` cards plus any pinned ones, in sort order. The fold holds the rest.
+		const head = [];
+		const tail = [];
+		all.forEach((item, index) => {
+			(index < cap || pinned.has(input().getId(item)) ? head : tail).push(item);
+		});
+		return {
+			column,
+			all,
+			head,
+			tail,
+			foldable,
+			open,
+			capped: !open && tail.length > 0
+		};
+	}));
+	let hiddenColumns = $derived(input().columns.filter((column) => rail.hiddenSet.has(column.id)));
+	function contextOf(entry, active) {
+		const { column, all, head, capped } = entry;
+		return {
+			count: all.length,
+			active,
+			shown: capped ? head.length : all.length,
+			capped,
+			hide: () => rail.hide(column.id),
+			expand: () => expand(column.id),
+			collapse: () => collapse(column.id)
+		};
+	}
+	return {
+		get slotHeight() {
+			return slotHeight;
+		},
+		set slotHeight(value) {
+			slotHeight = value;
+		},
+		get slotMotion() {
+			return slotMotion;
+		},
+		get expandedIds() {
+			return expandedIds;
+		},
+		get view() {
+			return view;
+		},
+		get hiddenColumns() {
+			return hiddenColumns;
+		},
+		dnd,
+		rail,
+		sortedByColumn,
+		idAt,
+		expand,
+		collapse,
+		toggleColumn,
+		onCardKeyDown,
+		contextOf
+	};
+}

package/dist/work/kanban-keyboard.js

@@ -0,0 +1,45 @@
+import { boardOrderAt } from "./board-order.js";
+/** The card's keydown handler: Enter or Space selects, Alt + arrow moves. */
+export function createCardKeyDown(config) {
+	const { input, canDrop, isHidden, sortedByColumn, isCapped, moveAndPin } = config;
+	/**
+	* Alt + ArrowLeft/Right moves the focused card to the next droppable column, so
+	* keyboard and screen-reader users get drag's onMove contract.
+	*/
+	return function onCardKeyDown(e, id) {
+		const { onSelect, items, getId, getColumn, columns, sortKey, dropAtTop, boardOrder } = input();
+		if (onSelect && e.target === e.currentTarget && (e.key === "Enter" || e.key === " ")) {
+			e.preventDefault();
+			onSelect(id);
+			return;
+		}
+		if (!e.altKey || e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+		const item = items.find((entry) => getId(entry) === id);
+		if (!item) return;
+		const current = getColumn(item);
+		const at = columns.findIndex((c) => c.id === current);
+		if (at === -1) return;
+		const dir = e.key === "ArrowRight" ? 1 : -1;
+		for (let i = at + dir; i >= 0 && i < columns.length; i += dir) {
+			const target = columns[i];
+			if (!canDrop(target.id) || isHidden(target.id) || target.id === current) continue;
+			e.preventDefault();
+			if (sortKey === "manual") {
+				const column = sortedByColumn(target.id).filter((entry) => getId(entry) !== id);
+				const atTop = dropAtTop?.(target.id) ?? isCapped(target.id, column.length + 1);
+				const index = atTop ? 0 : column.length;
+				const before = column[index - 1];
+				const after = column[index];
+				void moveAndPin(id, {
+					columnId: target.id,
+					...boardOrder ? { boardOrder: boardOrderAt(column, index, (entry) => boardOrder(entry)) } : {},
+					beforeId: before === undefined ? null : getId(before),
+					afterId: after === undefined ? null : getId(after)
+				});
+			} else {
+				void moveAndPin(id, { columnId: target.id });
+			}
+			return;
+		}
+	};
+}

package/dist/work/kanban-rail-state.svelte.js

@@ -0,0 +1,85 @@
+import { SvelteSet } from "svelte/reactivity";
+/** The rail of hidden columns: which are folded, the fold and unfold timing, and drops onto it. */
+export function createKanbanRailState(config) {
+	const { canDrop, dnd } = config;
+	let internalHidden = $state([]);
+	let hiddenIds = $derived(config.hidden() ?? internalHidden);
+	let hiddenSet = $derived(new Set(hiddenIds));
+	let railOpen = $state(true);
+	let dragOverHidden = $state(null);
+	const collapsing = new SvelteSet();
+	const expanding = new SvelteSet();
+	const leaving = new SvelteSet();
+	function setHidden(next) {
+		internalHidden = next;
+		config.onHiddenChange()?.(next);
+	}
+	// Fold: the column fades out first, then leaves the row and joins the rail.
+	function hide(columnId) {
+		if (hiddenSet.has(columnId) || collapsing.has(columnId)) return;
+		collapsing.add(columnId);
+		setTimeout(() => {
+			setHidden([...hiddenIds, columnId]);
+			collapsing.delete(columnId);
+		}, 300);
+	}
+	// Unfold: the rail entry leaves, then the column grows back in.
+	function show(columnId) {
+		leaving.add(columnId);
+		setTimeout(() => {
+			leaving.delete(columnId);
+			expanding.add(columnId);
+			setHidden(hiddenIds.filter((id) => id !== columnId));
+			setTimeout(() => expanding.delete(columnId), 350);
+		}, 200);
+	}
+	function showAll() {
+		for (const id of hiddenIds) leaving.add(id);
+		setTimeout(() => {
+			leaving.clear();
+			setHidden([]);
+		}, 200);
+	}
+	function onHiddenDragOver(e, columnId) {
+		if (!canDrop(columnId)) return;
+		e.preventDefault();
+		if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+		if (dragOverHidden !== columnId) dragOverHidden = columnId;
+		dnd.clearDragOver();
+	}
+	function onHiddenDragLeave(e) {
+		if (!e.currentTarget.contains(e.relatedTarget)) dragOverHidden = null;
+	}
+	// A card dropped on a folded column brings the column back and lands in it.
+	function onHiddenDrop(e, columnId) {
+		dragOverHidden = null;
+		dnd.onDrop(e, columnId);
+		show(columnId);
+	}
+	return {
+		get hiddenSet() {
+			return hiddenSet;
+		},
+		get railOpen() {
+			return railOpen;
+		},
+		set railOpen(value) {
+			railOpen = value;
+		},
+		get dragOverHidden() {
+			return dragOverHidden;
+		},
+		set dragOverHidden(value) {
+			dragOverHidden = value;
+		},
+		collapsing,
+		expanding,
+		leaving,
+		hide,
+		show,
+		showAll,
+		onHiddenDragOver,
+		onHiddenDragLeave,
+		onHiddenDrop
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Svelte 5 UI for apps: primitives, effects and animations, plus work (tasks and docs), charts, slides, an editor, onboarding and a canvas as subpaths.",
   "homepage": "https://ui.heyramzi.com",
   "license": "MIT",

package/src/charts/area-chart.svelte

@@ -14,7 +14,8 @@
 	import Reveal from "./reveal.svelte";
 	import ReferenceLine, { type ChartReference } from "./reference-line.svelte";
 	import {
-		ROLLING_LABEL,
+		NO_DATA,
+		averageLabel as averageName,
 		averageTo,
 		smoothSeries,
 		weekOf,
@@ -97,10 +98,15 @@
 		return pointLabel(d);
 	}
 
-	/** What a drawn point is: a day, the week it opens, or the end of a 7-day average. */
+	/** What a drawn point is: a day, the week it opens, or the end of a 7 or 28-day average. */
 	function pointLabel(d: TData): string {
 		const x = formatX(d[xKey]);
-		return mode === "weekly" ? weekOf(x) : mode === "rolling" ? averageTo(x) : x;
+		return mode === "weekly" ? weekOf(x) : mode === "rolling" ? averageTo(x, smoothed.window) : x;
+	}
+
+	/** A missing point reads "No data", never the 0 Number(null) would claim. */
+	function shown(value: unknown): string {
+		return value == null ? NO_DATA : formatValue(Number(value));
 	}
 
 	// =========================
@@ -126,12 +132,12 @@
 					series.map((s) => s.key),
 					smoothing,
 				)
-			: { points: input, mode: "raw" as const },
+			: { points: input, mode: "raw" as const, window: 1 },
 	);
 	const data = $derived(smoothed.points);
 	const mode = $derived(smoothed.mode);
-	// The series label in the readout, unless the point is an average of the week before it.
-	const averageLabel = $derived(mode === "rolling" ? ROLLING_LABEL : null);
+	// The series label in the readout, unless the point is an average of the days before it.
+	const averageLabel = $derived(mode === "rolling" ? averageName(smoothed.window) : null);
 	const dataMax = $derived.by(() => {
 		if (stacked) {
 			return Math.max(0, ...data.map((d) => series.reduce((s, k) => s + Number(d[k.key] ?? 0), 0)));
@@ -182,6 +188,8 @@
 			format={formatValue}
 			size="md"
 		/>
+	{:else if display && series.every((s) => display[s.key] == null)}
+		<Figure value={NO_DATA} eyebrow={pointLabel(display)} size="md" />
 	{:else if figureRows && display}
 		<Figure series={figureRows} eyebrow={pointLabel(display)} format={formatValue} size="md" />
 	{:else}
@@ -246,7 +254,7 @@
 							{#each series as s (s.key)}
 								<Tooltip.Item
 									label={averageLabel ?? s.label}
-									value={formatValue(Number(d[s.key]))}
+									value={shown(d[s.key])}
 									color={s.color}
 								/>
 							{/each}

package/src/charts/index.ts

@@ -36,4 +36,5 @@ export {
   type Smoothing,
   type SeriesKind,
   type SmoothMode,
+  type Smoothed,
 } from "./smoothing.js";

package/src/charts/smoothing.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vite-plus/test";
+import { averageTo, smoothSeries } from "./smoothing.js";
+
+type Row = { date: string; value: number | null };
+
+/** `values.length` days ending 2026-10-31, oldest first. */
+function days(values: (number | null)[]): Row[] {
+  const end = Date.UTC(2026, 9, 31);
+  return values.map((value, i) => ({
+    date: new Date(end - (values.length - 1 - i) * 86_400_000).toISOString().slice(0, 10),
+    value,
+  }));
+}
+
+const smooth = (rows: Row[], rangeDays: number, kind: "count" | "level" = "count") =>
+  smoothSeries(rows, "date", ["value"], { rangeDays, kind });
+
+describe("smoothSeries, a missing day", () => {
+  it("is left out of the 7-day average, not counted as 0", () => {
+    const rows = days([10, 10, 10, 10, null, 10, 10, 10, 10, 10]);
+    const values = smooth(rows, 90).points.map((p) => p.value);
+    expect(values.every((v) => v === 10)).toBe(true);
+  });
+
+  it("draws a gap where most of the window was never measured", () => {
+    // A 12-day outage, then one partial day: the partial day alone is not a week's average.
+    const rows = days([100, 100, 100, 100, 100, 100, 100, ...Array(12).fill(null), 5, 100, 100]);
+    const values = smooth(rows, 90).points.map((p) => p.value);
+    expect(values.slice(12, 19)).toEqual(Array(7).fill(null));
+    expect(values.some((v) => v === 0)).toBe(false);
+  });
+
+  it("before a series' first measured day is a gap that drags nothing down", () => {
+    const rows = days([null, null, null, null, null, 40, 40, 40, 40, 40]);
+    const values = smooth(rows, 90).points.map((p) => p.value);
+    expect(values.slice(0, 5)).toEqual([null, null, null, null, null]);
+    expect(values.slice(5)).toEqual([40, 40, 40, 40, 40]);
+  });
+
+  it("still counts a row absent from a sparse series as 0", () => {
+    const rows = days(Array(20).fill(7)).filter((_, i) => i % 2 === 0);
+    const tail = smooth(rows, 90).points.at(-1)?.value;
+    // Four sales of 7 in the 7 days to the last row: 28 over 7 days, not over the 4 rows.
+    expect(tail).toBe(4);
+  });
+
+  it("is a gap in a level's weekly reading, never a 0", () => {
+    const rows = days([...Array(14).fill(500), ...Array(7).fill(null)]);
+    const values = smooth(rows, 365, "level").points.map((p) => p.value);
+    expect(values).toEqual([500, 500, null]);
+  });
+});
+
+describe("smoothSeries over a year", () => {
+  it("draws a 28-day average per day, one point a week ending on the last day", () => {
+    const rows = days(Array(70).fill(50));
+    const { points, mode, window } = smooth(rows, 365);
+    expect(mode).toBe("rolling");
+    expect(window).toBe(28);
+    expect(points.at(-1)?.date).toBe("2026-10-31");
+    expect(points.map((p) => p.date)).toHaveLength(10);
+    expect(points.every((p) => p.value === 50)).toBe(true);
+  });
+
+  it("flattens a one-day spike into a small bump", () => {
+    // The 2 Mar 2026 shape: 1,225 visitors on a day that ran about 60.
+    const rows = days([...Array(40).fill(60), 1225, ...Array(29).fill(60)]);
+    const peak = Math.max(...smooth(rows, 365).points.map((p) => Number(p.value)));
+    expect(peak).toBeLessThan(60 + (1225 - 60) / 28 + 1);
+  });
+
+  it("keeps a real climb", () => {
+    const climb = Array.from({ length: 112 }, (_, i) => 100 + i * 2);
+    const values = smooth(days(climb), 365).points.map((p) => Number(p.value));
+    for (let i = 1; i < values.length; i++) expect(values[i]).toBeGreaterThan(values[i - 1]);
+  });
+
+  it("names a point by its window", () => {
+    expect(averageTo("Oct 31", 28)).toBe("28-day average to Oct 31");
+    expect(averageTo("Oct 31")).toBe("7-day average to Oct 31");
+  });
+});