@heyramzi/ui 2.13.0 → 2.15.0

package/src/charts/smoothing.ts

@@ -10,19 +10,33 @@ export interface Smoothing {
   kind?: SeriesKind;
 }
 
+/** Raw days, a trailing average, or a level read once a week. */
 export type SmoothMode = "raw" | "rolling" | "weekly";
 
+export interface Smoothed<TData> {
+  points: TData[];
+  mode: SmoothMode;
+  /** How many days a rolling point averages: 7 up to a quarter, 28 past it. */
+  window: number;
+}
+
 /** The tooltip's name for a drawn point, beside its date. */
-export const ROLLING_LABEL = "7-day average";
+export const averageLabel = (days: number) => `${days}-day average`;
+export const ROLLING_LABEL = averageLabel(7);
 export const weekOf = (start: string) => `Week of ${start}`;
+export const averageTo = (end: string, 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 = 86_400_000;
-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: number): SmoothMode {
   if (rangeDays <= 14) return "raw";
   if (rangeDays <= 120) return "rolling";
@@ -33,6 +47,13 @@ function timeOf(value: unknown): number {
   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: unknown): number | null {
+  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: unknown, time: number): unknown {
   if (sample instanceof Date) return new Date(time);
@@ -40,66 +61,100 @@ function sameForm(sample: unknown, time: number): unknown {
   return String(sample).length === 10 ? iso.slice(0, 10) : iso;
 }
 
+const daysBetween = (from: number, to: number) => 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<TData extends Record<string, unknown>>(
+  data: TData[],
+  times: number[],
+  yKeys: string[],
+  window: number,
+  keep: (i: number) => boolean,
+): TData[] {
+  const firstSeen = Object.fromEntries(
+    yKeys.map((k) => [k, times[data.findIndex((d) => measured(d[k]) !== null)] ?? Infinity]),
+  );
+  const out: TData[] = [];
+  data.forEach((d, i) => {
+    if (!keep(i)) return;
+    const row: Record<string, unknown> = { ...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 as TData);
+  });
+  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<TData extends Record<string, unknown>>(
   data: TData[],
   xKey: keyof TData & string,
   yKeys: (keyof TData & string)[],
   { rangeDays, kind = "count" }: Smoothing,
-): { points: TData[]; mode: SmoothMode } {
+): Smoothed<TData> {
   const mode = smoothMode(rangeDays);
-  if (mode === "raw" || data.length < WINDOW) return { points: data, mode: "raw" };
+  if (mode === "raw" || data.length < WEEK) return { points: data, mode: "raw", window: 1 };
   const times = data.map((d) => timeOf(d[xKey]));
+  const last = times[times.length - 1];
 
-  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])) as Record<string, number>;
-    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: Record<string, unknown> = { ...d };
-      for (const k of yKeys) row[k] = sums[k] / days;
-      return row as TData;
-    });
-    return { points, mode };
+  if (kind === "count") {
+    const window = mode === "rolling" ? WEEK : LONG_WINDOW;
+    const keep =
+      mode === "rolling" ? () => true : (i: number) => daysBetween(times[i], last) % WEEK === 0;
+    return { 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<number, TData[]>();
   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: Record<string, unknown> = { ...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 as TData;
     });
-  return { points, mode };
+  return { points, mode, window: WEEK };
 }
 
 /** Labels at least `spacing` pixels apart, the way a time axis reads at any width. */

package/src/charts/sparkline.svelte

@@ -6,7 +6,14 @@
 	import { Area, Chart, Highlight, LinearGradient, Points, Spline, Svg, Tooltip } from "layerchart";
 	import { curveMonotoneX } from "d3-shape";
 	import Reveal from "./reveal.svelte";
-	import { ROLLING_LABEL, smoothSeries, weekOf, type Smoothing } from "./smoothing.js";
+	import {
+		NO_DATA,
+		averageLabel,
+		averageTo,
+		smoothSeries,
+		weekOf,
+		type Smoothing,
+	} from "./smoothing.js";
 
 	// =========================
 	// TYPES
@@ -71,7 +78,7 @@
 			active = d;
 		});
 		const x = formatX(d[xKey]);
-		return mode === "weekly" ? weekOf(x) : x;
+		return mode === "weekly" ? weekOf(x) : mode === "rolling" ? averageTo(x, smoothed.window) : x;
 	}
 
 	// =========================
@@ -81,13 +88,14 @@
 	const smoothed = $derived(
 		smoothing
 			? smoothSeries(input, xKey, [yKey], 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);
-	const valueLabel = $derived(mode === "rolling" ? ROLLING_LABEL : String(yKey));
+	const valueLabel = $derived(mode === "rolling" ? averageLabel(smoothed.window) : String(yKey));
 	const curve = $derived(smooth ? curveMonotoneX : undefined);
-	const last = $derived(data.length > 0 ? data[data.length - 1] : null);
+	// The newest measured point: a gap at the end has no height for the dot to sit at.
+	const last = $derived(data.findLast((d) => d[yKey] != null) ?? null);
 	const display = $derived(active ?? last);
 	const dot = $derived(endCap && !bare);
 	// Bare runs to the edges: the fill reaches the bottom of the box and the line keeps three pixels of head so its stroke is not cut at the series
@@ -144,7 +152,10 @@
 						{#snippet children({ data: d })}
 							<Tooltip.Header value={trackActive(d as TData)} />
 							<Tooltip.List>
-								<Tooltip.Item label={valueLabel} value={formatValue(Number(d[yKey]))} />
+								<Tooltip.Item
+									label={valueLabel}
+									value={d[yKey] == null ? NO_DATA : formatValue(Number(d[yKey]))}
+								/>
 							</Tooltip.List>
 						{/snippet}
 					</Tooltip.Root>

package/src/work/README.md

@@ -81,15 +81,15 @@ isn't a drop target (an Overdue lane, say).
 | `manualTiebreak` | `(a: T, b: T) => number`                               | Settles two cards with the same manual key, or none.        |
 | `getLabel`      | `(item: T) => string`                                   | The screen-reader name of a card. Defaults to a keyboard hint. |
 | `onSelect`      | `(id: string) => void`                                  | Enter or Space on a focused card.                           |
-| `columnFooter`  | `Snippet<[Column, KanbanColumnContext]>`                | Under a column's cards: a "Show all" or an add button.      |
+| `columnFooter`  | `Snippet<[Column, KanbanColumnContext]>`                | Under a column's cards and its fold button, e.g. an add button. |
 | `wrapColumn`    | `Snippet<[Column, Snippet<[props]>]>`                   | Wraps a whole column, for a context menu. Render the inner snippet once with the props you are handed. |
-| `limit`         | `(columnId: string) => number \| undefined`             | Cards a column shows before the rest fold. `expanded` and `onExpandedChange` lift it per column. |
+| `limit`         | `number \| ((columnId: string) => number \| undefined)` | Cards a column shows before the rest fold, 5 by default; `Infinity` for none. A "Show N more" button opens the fold and "Show less" shuts it, both animated. `moreLabel`, `lessLabel`, `expanded` and `onExpandedChange` go with it. A card moved into a shut column stays in view. |
 | `hidden`        | `string[]`                                              | Columns folded into a rail on the right. Fold and unfold animate, and a card dropped on a rail entry brings the column back. `onHiddenChange`, `hiddenLabel`, `showAllLabel` and `hiddenItem` go with it. |
 
 `columns` can be your own type, as long as it extends `KanbanColumn`: the
 header, footer and wrap snippets get it back as you passed it, so a column can
 carry a status or a stage for your own markup. The header and footer context is
-`{ count, active, shown, capped, hide, expand }`.
+`{ count, active, shown, capped, hide, expand, collapse }`.
 
 `onMove` gives `{ columnId, boardOrder?, beforeId?, afterId? }`. On a manual
 drop `beforeId` and `afterId` name the cards above and below the new slot (null

package/src/work/kanban-board-state.svelte.ts

@@ -0,0 +1,265 @@
+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";
+import type {
+  KanbanColumn as KanbanColumnDef,
+  KanbanColumnContext,
+  KanbanMove,
+  KanbanSortKey,
+} from "./kanban-types.js";
+
+/** The board props the state reads, with the board's defaults already applied. */
+export type KanbanBoardInput<T, C extends KanbanColumnDef> = {
+  columns: C[];
+  items: T[];
+  getId: (item: T) => string;
+  getColumn: (item: T) => string;
+  onMove: (id: string, move: KanbanMove) => void | Promise<void>;
+  boardOrder?: (item: T) => string | null | undefined;
+  manualTiebreak?: (a: T, b: T) => number;
+  sortKeys: KanbanSortKey<T>[];
+  sortKey: string;
+  onSelect?: (id: string) => void;
+  limit: number | ((columnId: string) => number | undefined);
+  expanded?: string[];
+  onExpandedChange?: (ids: string[]) => void;
+  hidden?: string[];
+  onHiddenChange?: (ids: string[]) => void;
+  dropAtTop?: (columnId: string) => boolean;
+  isDroppable?: (columnId: string) => boolean;
+};
+
+/** One column as the board renders it: every card, the head over the fold and the tail in it. */
+export type KanbanColumnView<T, C extends KanbanColumnDef> = {
+  column: C;
+  all: T[];
+  head: T[];
+  tail: T[];
+  foldable: boolean;
+  open: boolean;
+  capped: boolean;
+};
+
+/**
+ * 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<T, C extends KanbanColumnDef>(
+  input: () => KanbanBoardInput<T, C>,
+) {
+  // 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<string[]>([]);
+  let expandedIds = $derived(input().expanded ?? internalExpanded);
+
+  function compare(a: T, b: T): number {
+    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: string): T[] {
+    const { items, getColumn } = input();
+    return items
+      .filter((item) => getColumn(item) === columnId)
+      .slice()
+      .sort(compare);
+  }
+
+  function idAt(list: T[], index: number): string | null {
+    const item = list[index];
+    return item === undefined ? null : input().getId(item);
+  }
+
+  function capOf(columnId: string): number | undefined {
+    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: string, total: number): boolean {
+    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<string>();
+
+  function isOpen(columnId: string): boolean {
+    return expandedIds.includes(columnId) || laneOpen.has(columnId);
+  }
+
+  /** The fold is shut, so the tail is out of sight. */
+  function isCapped(columnId: string, total: number): boolean {
+    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<string>();
+
+  // The caret folding a column shuts this board's own fold of it too, so every lane lands on the cap.
+  let previousExpanded: string[] = [];
+  $effect(() => {
+    const now = expandedIds;
+    untrack(() => {
+      for (const id of previousExpanded) if (!now.includes(id)) shut(id);
+    });
+    previousExpanded = [...now];
+  });
+
+  function moveAndPin(id: string, move: KanbanMove): void | Promise<void> {
+    pinned.add(id);
+    return input().onMove(id, move);
+  }
+
+  function canDrop(columnId: string): boolean {
+    const { isDroppable, columns } = input();
+    return isDroppable?.(columnId) ?? columns.find((c) => c.id === columnId)?.droppable ?? true;
+  }
+
+  function setExpanded(next: string[]): void {
+    internalExpanded = next;
+    input().onExpandedChange?.(next);
+  }
+
+  // Shutting drops the column's pins, so the fold closes to exactly its cap.
+  function shut(columnId: string): void {
+    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: string): void {
+    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: string): void {
+    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: string): void {
+    if (expandedIds.includes(columnId)) collapse(columnId);
+    else setExpanded([...expandedIds, columnId]);
+  }
+
+  const dnd = createKanbanDnd<T>({
+    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<T, C>({
+    input,
+    canDrop,
+    isHidden: (columnId) => rail.hiddenSet.has(columnId),
+    sortedByColumn,
+    isCapped,
+    moveAndPin,
+  });
+
+  let view = $derived(
+    input().columns.map((column): KanbanColumnView<T, C> => {
+      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: [] as T[], foldable, open, capped: false };
+      }
+      // Head: the first `cap` cards plus any pinned ones, in sort order. The fold holds the rest.
+      const head: T[] = [];
+      const tail: T[] = [];
+      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: KanbanColumnView<T, C>, active: boolean): KanbanColumnContext {
+    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: number) {
+      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,
+  };
+}
+
+export type KanbanBoardState<T, C extends KanbanColumnDef> = ReturnType<
+  typeof createKanbanBoardState<T, C>
+>;