syndes 0.3.3 → 0.4.0

package/dashboard/web/app.js

@@ -1,15 +1,25 @@
 /**
  * The shell: unlock, top bar, page head, rail, and the router.
  *
- * The range lives here rather than in a view, because it is shared — moving
- * from Overview to Habits must not silently reset the window you are reading.
+ * The window lives here rather than in a view, because it is shared — moving
+ * from Overview to Habits must not silently reset what you are reading.
+ *
+ * It is two pieces of state, not one. `scope` is how wide a window you want and
+ * is remembered between sessions; `day` is which day you are on and is NOT, so
+ * opening the dashboard tomorrow shows tomorrow rather than silently serving a
+ * stale Tuesday that a stored range would have pinned you to.
+ *
+ * The default is a single day, because that is the question people actually
+ * arrive with: what happened today. A seven-day average hides the day you came
+ * to look at, and a shared pool averaged over a week says nothing about whether
+ * the two of you are in each other's way right now.
  *
  * Views are imported lazily, so the first paint does not wait on the Ledger
  * view's table code and a view that fails to load takes only itself down.
  */
 
 import { api, ApiError, onBusy } from './api.js';
-import { h, replace, mount, icon, dropdown } from './ui.js';
+import { h, replace, mount, icon, dropdown, daypicker, todayISO, dayLabel } from './ui.js';
 
 const ROUTES = [
   { id: 'overview', label: 'Overview', title: 'Overview', load: () => import('./views/overview.js') },
@@ -22,20 +32,38 @@ const ROUTES = [
   { id: 'settings', label: 'Settings', title: 'Settings', rail: true, noRange: true, load: () => import('./views/settings.js') },
 ];
 
-const RANGES = [
-  { id: 'today', label: 'Today' },
+/**
+ * How wide a window. `day` is not a span — it defers to `state.day`, which is
+ * what the stepper beside this control moves.
+ */
+const SCOPES = [
+  { id: 'day', label: 'One day', hint: 'the day picker chooses which' },
   { id: '7d', label: '7 days' },
   { id: '30d', label: '30 days' },
   { id: '90d', label: '90 days' },
   { id: 'all', label: 'All time' },
 ];
 
+const SCOPE_KEY = 'syndes.scope';
+
 const state = {
-  range: localStorage.getItem('syndes.range') ?? '7d',
+  scope: SCOPES.some((scope) => scope.id === storedScope()) ? storedScope() : 'day',
+  day: todayISO(),
   route: 'overview',
   status: null,
+  /** The day index behind the picker, fetched once and refreshed on reload. */
+  days: [],
 };
 
+function storedScope() {
+  return localStorage.getItem(SCOPE_KEY);
+}
+
+/** The one spec every endpoint is asked with. A single day is its literal date. */
+function rangeSpec() {
+  return state.scope === 'day' ? state.day : state.scope;
+}
+
 const root = document.getElementById('root');
 let outlet;
 let titleNode;
@@ -145,16 +173,16 @@ function renderApp() {
 
     h('div.pagehead', {}, [
       h('div', {}, [titleNode, subNode]),
-      // The range filter is hidden where it would be a lie: nothing on Settings
-      // is scoped to a time window.
-      h('div.filters', { id: 'filters' }, [rangeFilter()]),
+      // Hidden where it would be a lie: nothing on Settings is scoped to a
+      // time window.
+      h('div.filters', { id: 'filters' }, filters()),
     ]),
 
     h('div.body', {}, [
       h('aside.rail', {}, [
-        railButton('refresh', 'Reload this view', () => render()),
+        railButton('refresh', 'Reload this view', () => { loadDays(); render(); }),
         railButton('verify', 'Check the chain', () => go('ledger')),
-        railButton('download', 'Export everything as CSV', () => { window.location.href = api.exportUrl('csv', state.range); }),
+        railButton('download', 'Export everything as CSV', () => { window.location.href = api.exportUrl('csv', rangeSpec()); }),
         railButton('settings', 'Settings', () => go('settings'), 'settings'),
       ]),
       outlet,
@@ -165,6 +193,23 @@ function renderApp() {
   window.addEventListener('hashchange', () => go(routeFromHash(), { push: false }));
   go(routeFromHash(), { push: false });
   refreshStatus();
+  loadDays();
+}
+
+/**
+ * What the page head says the numbers cover.
+ *
+ * A single day gets its full name. "2026-09-10" is a string a machine chose;
+ * "Thursday, 10 September" is the thing a person came to look at, and the
+ * distinction matters most on the view that is now the default.
+ */
+function windowLabel() {
+  if (state.scope !== 'day') return SCOPES.find((scope) => scope.id === state.scope)?.label ?? state.scope;
+  const named = dayLabel(state.day, { long: true });
+  const full = new Date(`${state.day}T12:00`).toLocaleDateString(undefined, {
+    weekday: 'long', day: 'numeric', month: 'long',
+  });
+  return named === full ? full : `${named} \u00b7 ${full}`;
 }
 
 function railButton(name, label, onClick, routeId = null) {
@@ -174,21 +219,67 @@ function railButton(name, label, onClick, routeId = null) {
   }, [icon(name)]);
 }
 
-function rangeFilter() {
-  return dropdown({
-    label: 'Range',
-    value: state.range,
-    options: RANGES.map((range) => ({ id: range.id, label: range.label })),
-    onChange: setRange,
-  });
+/**
+ * Scope, and — when the scope is one day — which day.
+ *
+ * The stepper only exists in day scope. Leaving a day control visible beside
+ * "30 days" would invite somebody to set a day that the view then ignores, which
+ * is worse than not offering it.
+ */
+function filters() {
+  return [
+    dropdown({
+      label: 'Window',
+      value: state.scope,
+      options: SCOPES.map((scope) => ({ id: scope.id, label: scope.label, hint: scope.hint })),
+      onChange: setScope,
+    }),
+    state.scope === 'day'
+      ? daypicker({ day: state.day, days: state.days, onChange: setDay })
+      : null,
+  ].filter(Boolean);
+}
+
+function repaintFilters() {
+  const node = document.getElementById('filters');
+  if (node) replace(node, filters());
 }
 
-function setRange(id) {
-  state.range = id;
-  localStorage.setItem('syndes.range', id);
+function setScope(id) {
+  state.scope = id;
+  localStorage.setItem(SCOPE_KEY, id);
+  // Landing on day scope lands on today, never on whichever day was last open
+  // before you went to look at a month.
+  if (id === 'day') state.day = todayISO();
+  repaintFilters();
   render();
 }
 
+function setDay(day) {
+  state.scope = 'day';
+  state.day = day;
+  localStorage.setItem(SCOPE_KEY, 'day');
+  repaintFilters();
+  render();
+}
+
+/**
+ * The day index behind the picker.
+ *
+ * Failure is silent and leaves the list empty: the picker still steps with its
+ * arrows, so a dashboard whose rollup cache is mid-rebuild loses the hints and
+ * nothing else.
+ */
+async function loadDays() {
+  try {
+    const { days } = await api.days();
+    state.days = days ?? [];
+    repaintFilters();
+  } catch {
+    state.days = [];
+  }
+}
+
 function routeFromHash() {
   const id = location.hash.replace(/^#\/?/, '').split('/')[0];
   return ROUTES.some((route) => route.id === id) ? id : 'overview';
@@ -209,16 +300,26 @@ function go(id, { push = true } = {}) {
 async function render() {
   const route = ROUTES.find((candidate) => candidate.id === state.route);
   titleNode.textContent = route.title;
-  subNode.textContent = route.noRange ? 'Stored on this machine only' : (RANGES.find((range) => range.id === state.range)?.label ?? state.range);
-  const filters = document.getElementById('filters');
-  if (filters) filters.hidden = Boolean(route.noRange);
+  subNode.textContent = route.noRange ? 'Stored on this machine only' : windowLabel();
+  const filterBar = document.getElementById('filters');
+  if (filterBar) filterBar.hidden = Boolean(route.noRange);
 
+  const spec = rangeSpec();
   mount(outlet, skeleton());
   try {
     const module = await route.load();
-    const node = await module.render({ range: state.range, status: state.status, go });
-    // A range switch mid-load must not paint the answer to the previous question.
-    if (state.route === route.id) mount(outlet, node);
+    const node = await module.render({
+      range: spec,
+      scope: state.scope,
+      day: state.day,
+      days: state.days,
+      status: state.status,
+      go,
+      setDay,
+      setScope,
+    });
+    // A window switch mid-load must not paint the answer to the previous question.
+    if (state.route === route.id && spec === rangeSpec()) mount(outlet, node);
   } catch (error) {
     if (error instanceof ApiError && error.status === 401) return renderUnlock();
     mount(outlet, notice(`Could not load ${route.label}`, error.message));

package/dashboard/web/charts.js

@@ -169,27 +169,40 @@ export function dualLine(seriesA, seriesB, { height = 96, label = 'trend' } = {}
 }
 
 /**
- * A row of day capsules. Compact activity: one capsule per day, height by
- * volume, so a gap in the week is visible as an empty slot rather than absent.
+ * A row of capsules over an ordered axis: one per day across a week, or one per
+ * hour across a single day. Height is volume, so a gap is visible as an empty
+ * slot rather than as an absence.
+ *
+ * `labelEvery` exists because twenty-four hour labels do not fit where seven day
+ * labels do. Labelling every third hour keeps the axis readable instead of
+ * letting the text overlap into a smear, and the full value is always on the
+ * hover title so nothing is only available by squinting.
  */
-export function dayStrip(days, { height = 74, label = 'activity by day' } = {}) {
+export function dayStrip(slots, { height = 74, label = 'activity', labelEvery = null, format = String } = {}) {
   const width = 640;
-  const max = Math.max(...days.map((day) => day.value), 1);
-  const slot = width / Math.max(days.length, 1);
-  const capWidth = Math.min(30, slot * 0.55);
+  const max = Math.max(...slots.map((slot) => slot.value), 1);
+  const slotWidth = width / Math.max(slots.length, 1);
+  const capWidth = Math.min(30, slotWidth * 0.55);
   const floor = height - 20;
+  const every = labelEvery ?? (slots.length <= 8 ? 1 : null);
 
   const nodes = [];
-  days.forEach((day, index) => {
-    const cx = index * slot + slot / 2;
-    const h = day.value === 0 ? capWidth * 0.5 : Math.max(capWidth, (day.value / max) * (floor - 8));
-    nodes.push(el('rect', {
-      class: day.value === 0 ? '' : TONE[day.tone] ?? TONE.lime,
-      fill: day.value === 0 ? 'var(--track)' : null,
-      x: cx - capWidth / 2, y: floor - h, width: capWidth, height: h, rx: capWidth / 2,
-    }));
-    if (index === 0 || index === days.length - 1 || days.length <= 8) {
-      nodes.push(el('text', { x: cx, y: height - 4, 'text-anchor': 'middle' }, [txt(day.label)]));
+  slots.forEach((slot, index) => {
+    const cx = index * slotWidth + slotWidth / 2;
+    const barHeight = slot.value === 0 ? capWidth * 0.5 : Math.max(capWidth, (slot.value / max) * (floor - 8));
+    const bar = el('rect', {
+      class: slot.value === 0 ? '' : TONE[slot.tone] ?? TONE.lime,
+      fill: slot.value === 0 ? 'var(--track)' : null,
+      x: cx - capWidth / 2, y: floor - barHeight, width: capWidth, height: barHeight, rx: capWidth / 2,
+    });
+    bar.appendChild(el('title', {}, [txt(slot.title ?? `${slot.label}: ${format(slot.value)}`)]));
+    nodes.push(bar);
+
+    const labelled = every
+      ? index % every === 0
+      : index === 0 || index === slots.length - 1;
+    if (labelled) {
+      nodes.push(el('text', { x: cx, y: height - 4, 'text-anchor': 'middle' }, [txt(slot.label)]));
     }
   });
   return frame(width, height, label, nodes);
@@ -352,6 +365,90 @@ export function dotMatrix(grid, { label = 'when each of you worked', dayLabel =
   return frame(width, height, label, nodes);
 }
 
+/**
+ * The one-day contention chart: a lane per person across the twenty-four hours.
+ *
+ * The days × bands matrix is the right picture for a week and the wrong one for a
+ * day — one day at three-hour bands is eight dots in a single column, which
+ * throws away the only axis a day has. So a single selected day is drawn
+ * transposed: hours run across, people run down, and the dot on each person's
+ * lane is how much they did in that hour.
+ *
+ * Colour keeps the meaning it has everywhere else. A dot is orange when somebody
+ * ELSE was also working that hour, which is the question this chart exists to
+ * answer: not "was the pool busy" but "was I sharing the window, and with whom".
+ * A top summary lane carries the pool, so the overlap reads at a glance before
+ * any single name does.
+ *
+ * @param {object} grid  from analytics/team.mjs — needs `cells`, `people`, `peak`
+ */
+export function hourMatrix(grid, { label = 'who worked when today' } = {}) {
+  const hours = 24;
+  const cell = 24;
+  const left = 92;
+  const top = 8;
+  const rowGap = 6;
+  const rows = [{ deviceId: null, name: 'Everyone', initials: null, isMe: false }, ...grid.people];
+  const width = left + hours * cell + 10;
+  const height = top + rows.length * (cell + rowGap) + 18;
+  const maxRadius = cell * 0.44;
+  const peak = Math.max(grid.peak, 1);
+
+  const byBand = new Map(grid.cells.map((item) => [item.band, item]));
+  const nodes = [];
+
+  rows.forEach((person, index) => {
+    const cy = top + index * (cell + rowGap) + cell / 2;
+
+    nodes.push(el('text', {
+      x: left - 12, y: cy, 'text-anchor': 'end', 'dominant-baseline': 'middle',
+      style: person.isMe ? 'fill:var(--ink)' : null,
+    }, [txt(clipName(person.isMe ? `${person.name} (you)` : person.name))]));
+
+    for (let hour = 0; hour < hours; hour += 1) {
+      const item = byBand.get(hour);
+      const cx = left + hour * cell + cell / 2;
+
+      // The pool lane is the hour's total; a person's lane is only their own.
+      const value = person.deviceId === null
+        ? item?.total ?? 0
+        : item?.byDevice?.[person.deviceId] ?? 0;
+
+      if (!value) {
+        nodes.push(el('circle', { cx, cy, r: 2, fill: 'var(--track)' }));
+        continue;
+      }
+
+      // Shared means: somebody other than this lane's person also worked here.
+      const shared = person.deviceId === null
+        ? (item?.people ?? 0) > 1
+        : Object.keys(item?.byDevice ?? {}).some((id) => id !== person.deviceId);
+
+      // Square root, because the eye compares a dot's AREA. Scaling the radius
+      // linearly makes a busy hour look four times worse than it is.
+      const radius = Math.max(3, Math.sqrt(value / peak) * maxRadius);
+      const dot = el('circle', { class: shared ? TONE.orange : TONE.lime, cx, cy, r: radius });
+      dot.appendChild(el('title', {}, [txt(
+        `${person.deviceId === null ? 'Everyone' : person.name} \u00b7 ${String(hour).padStart(2, '0')}:00 \u00b7 ` +
+        `${value} events${shared ? ' \u00b7 shared with someone else' : ' \u00b7 had the window alone'}`,
+      )]));
+      nodes.push(dot);
+    }
+  });
+
+  for (let hour = 0; hour < hours; hour += 3) {
+    nodes.push(el('text', {
+      x: left + hour * cell + cell / 2, y: height - 5, 'text-anchor': 'middle',
+    }, [txt(String(hour).padStart(2, '0'))]));
+  }
+
+  return frame(width, height, label, nodes);
+}
+
+function clipName(name) {
+  return name.length > 14 ? `${name.slice(0, 13)}\u2026` : name;
+}
+
 /**
  * One row per day, split into a capsule per person — the reference's timeline,
  * answering "who took the day".

package/dashboard/web/ui.js

@@ -45,6 +45,8 @@ const ICONS = {
     'M15 8a2 2 0 1 0 4 0 2 2 0 0 0-4 0', 'M8 16a2 2 0 1 0 4 0 2 2 0 0 0-4 0',
   ],
   chevron: ['M6.5 9.5 12 15l5.5-5.5'],
+  left: ['M14.5 5.5 8 12l6.5 6.5'],
+  right: ['M9.5 5.5 16 12l-6.5 6.5'],
   tick: ['M5 12.5 9.5 17 19 7.5'],
 };
 
@@ -188,6 +190,77 @@ export function dropdown({ value, options, onChange, label = null, onCard = fals
   return trigger;
 }
 
+/**
+ * The day picker: step back a day, pick one from a list, step forward.
+ *
+ * Two ways in, because they answer different questions. The arrows are for
+ * "what about the day before this one", which is the move somebody makes five
+ * times in a row and must not cost five menu openings. The list is for "take me
+ * to last Tuesday", and it carries each day's volume so a quiet day is visible
+ * before it is opened rather than after.
+ *
+ * Forward is disabled on today rather than hidden. A control that disappears
+ * makes the row reflow under the pointer, and the disabled state is what says
+ * "this is the edge" instead of leaving someone to wonder where the button went.
+ *
+ * @param {string}   day      the selected day, YYYY-MM-DD
+ * @param {object[]} days     [{ day, records, activeMs, tokens }], newest first
+ * @param {Function} onChange called with the newly selected day
+ */
+export function daypicker({ day, days = [], onChange }) {
+  const today = todayISO();
+  const known = new Map(days.map((entry) => [entry.day, entry]));
+
+  // The listed days, plus the selected one if it is outside what the server
+  // returned — a day you are looking at must always appear in the list that
+  // claims to be showing which day you are looking at.
+  const listed = known.has(day) ? [...days] : [{ day, records: null }, ...days];
+
+  const step = (delta) => {
+    const next = shiftISO(day, delta);
+    if (next > today) return;
+    onChange(next);
+  };
+
+  const arrow = (name, label, delta, disabled) => h('button.stepper__btn', {
+    type: 'button',
+    title: label,
+    'aria-label': label,
+    disabled,
+    onclick: () => step(delta),
+  }, [icon(name, { size: 16 })]);
+
+  return h('div.stepper', {}, [
+    arrow('left', 'The day before', -1, false),
+    dropdown({
+      label: 'Day',
+      value: day,
+      onChange,
+      options: listed.slice(0, 120).map((entry) => ({
+        id: entry.day,
+        label: dayLabel(entry.day),
+        hint: dayHint(entry),
+      })),
+    }),
+    arrow('right', 'The day after', 1, day >= today),
+  ]);
+}
+
+/**
+ * What a day looks like before you open it.
+ *
+ * `records: null` means the rollup cache has not folded that day yet, which is
+ * not the same as a day with nothing in it — so it says so rather than claiming
+ * a zero it has not measured.
+ */
+function dayHint(entry) {
+  if (entry.records === null || entry.records === undefined) return 'not counted yet';
+  if (!entry.records) return 'nothing recorded';
+  const parts = [`${compact(entry.records)} records`];
+  if (entry.activeMs) parts.push(duration(entry.activeMs));
+  return parts.join(' \u00b7 ');
+}
+
 export function replace(node, ...children) {
   node.replaceChildren(...children.flat().filter(Boolean));
   return node;
@@ -212,11 +285,6 @@ export function compact(value) {
   return String(Math.round(value));
 }
 
-export function usd(value) {
-  if (value === null || value === undefined) return DASH;
-  return value >= 1000 ? `$${Math.round(value).toLocaleString()}` : `$${value.toFixed(2)}`;
-}
-
 export function duration(ms) {
   if (!ms || ms < 0) return '0m';
   const minutes = Math.round(ms / 60_000);
@@ -226,6 +294,24 @@ export function duration(ms) {
   return rest ? `${hours}h ${rest}m` : `${hours}h`;
 }
 
+/**
+ * A per-hour rate. `compact` does the magnitude; this only adds the unit, so a
+ * burn rate and a token count never disagree about what "1.2M" means.
+ *
+ * Null is an em dash, not 0 — a rate we could not measure must not read as a
+ * rate of nothing. See analytics/metrics/window.mjs.
+ */
+export function perHour(value) {
+  if (value === null || value === undefined || Number.isNaN(value)) return DASH;
+  return `${compact(value)}/h`;
+}
+
+/** A ratio printed as a multiplier: 63.6 → "64×". */
+export function times(value, digits = 0) {
+  if (value === null || value === undefined || Number.isNaN(value)) return DASH;
+  return `${value.toFixed(digits)}×`;
+}
+
 export function percent(fraction, digits = 0) {
   if (fraction === null || fraction === undefined || Number.isNaN(fraction)) return DASH;
   return `${(fraction * 100).toFixed(digits)}%`;
@@ -243,6 +329,36 @@ export const when = (ts) => (ts ? new Date(ts).toLocaleString(undefined, { month
 export const clock = (ts) => new Date(ts).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
 export const dayName = (iso) => new Date(`${iso}T12:00`).toLocaleDateString(undefined, { weekday: 'short' });
 
+/** Today's local date as YYYY-MM-DD — the same shape analytics/ranges.mjs speaks. */
+export function todayISO(now = new Date()) {
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+
+export function shiftISO(iso, delta) {
+  const [year, month, date] = iso.split('-').map(Number);
+  // Noon, so a DST boundary cannot push the result onto the wrong calendar day.
+  return todayISO(new Date(year, month - 1, date + delta, 12));
+}
+
+/**
+ * A day, named the way a person would say it.
+ *
+ * "Today" and "Yesterday" beat a date for the two days somebody is nearly always
+ * looking at, and a date beats a weekday for everything older — "Tuesday" is
+ * ambiguous the moment more than one Tuesday is on offer.
+ */
+export function dayLabel(iso, { long = false } = {}) {
+  const today = todayISO();
+  if (iso === today) return 'Today';
+  if (iso === shiftISO(today, -1)) return 'Yesterday';
+  const date = new Date(`${iso}T12:00`);
+  return date.toLocaleDateString(undefined, long
+    ? { weekday: 'long', day: 'numeric', month: 'long' }
+    : { weekday: 'short', day: 'numeric', month: 'short' });
+}
+
 // ── Components ─────────────────────────────────────────────────────────────
 
 export function card(title, body, { note = null, actions = null, className = '' } = {}) {