@seanmars/tospec 0.23.0 → 0.24.0

package/assets/dashboard/index.html

@@ -1,34 +1,43 @@
 <!doctype html>
-<html lang="en">
+<html lang="zh-Hant-TW">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>tospec dashboard</title>
+    <meta name="color-scheme" content="light dark" />
+    <title>tospec</title>
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='7.5' fill='%23262b30'/%3E%3Ccircle cx='8' cy='8' r='3.6' fill='none' stroke='%23fff' stroke-width='2.4'/%3E%3C/svg%3E" />
     <link rel="stylesheet" href="/assets/style.css" />
   </head>
   <body>
-    <header class="topbar">
-      <div class="topbar-left">
-        <h1 class="brand">tospec <span class="muted">dashboard</span></h1>
-        <nav class="tabs">
-          <a href="#/" class="tab" data-tab="overview">Overview</a>
-          <a href="#/decisions" class="tab" data-tab="decisions">Decisions</a>
-        </nav>
-        <span id="root-path" class="root-path mono"></span>
-      </div>
-      <div class="topbar-right">
-        <span id="conn-status" class="conn"></span>
-        <select id="theme-select" title="Theme">
-          <option value="system">System</option>
-          <option value="light">Light</option>
-          <option value="dark">Dark</option>
-          <option value="dracula">Dracula</option>
-        </select>
-        <button id="refresh-btn" type="button" title="Refresh">&#x21bb; Refresh</button>
+    <header class="signbar" id="signbar">
+      <button id="nav-toggle" type="button" class="sign-control sign-button nav-toggle" aria-controls="sidebar" aria-expanded="false" title="Projects"></button>
+      <a class="wordmark" href="#/" aria-label="tospec 總覽">tospec</a>
+      <nav class="crumbs-nav" aria-label="目前位置">
+        <ol id="crumbs" class="crumbs"></ol>
+        <a id="crumb-back" class="crumb-back" hidden></a>
+      </nav>
+      <div class="signbar-tools">
+        <span id="hub-status" class="hub-status" role="status"></span>
+        <label class="theme-field">
+          <span class="sr-only">主題</span>
+          <select id="theme-select" class="sign-control">
+            <option value="system">跟隨系統</option>
+            <option value="light">淺色</option>
+            <option value="dark">深色</option>
+            <option value="dracula">Dracula</option>
+          </select>
+        </label>
+        <button id="notify-btn" type="button" class="sign-control sign-button" aria-pressed="false"></button>
+        <button id="refresh-btn" type="button" class="sign-control sign-button" title="向連線中的 session 要求新快照">重新整理</button>
       </div>
     </header>
-    <main id="view" class="view"></main>
-    <script src="/assets/chart.umd.js"></script>
+    <div class="shell">
+      <aside id="sidebar" class="sidebar" aria-label="Projects"></aside>
+      <main id="view" class="view" tabindex="-1"></main>
+    </div>
+    <div id="nav-scrim" class="nav-scrim" hidden></div>
+    <aside id="session-panel" class="session-panel" hidden></aside>
+    <div id="toasts" class="toasts" aria-live="polite"></div>
     <script type="module" src="/assets/app.js"></script>
   </body>
 </html>

package/assets/dashboard/lib/charts.js

@@ -0,0 +1,355 @@
+// The project page's four charts, drawn as SVG at the container's real pixel
+// width (redrawn on resize) so text stays at its set size instead of scaling
+// with a viewBox. Colours are CSS classes reading theme variables, so a theme
+// switch restyles a drawn chart without redrawing it.
+
+import { el, svg, icon } from './dom.js';
+import { parseLooseDate, formatDate, weeklyArchiveCounts, relTime } from './derive.js';
+import { routes } from './routes.js';
+
+const DAY_MS = 86400000;
+const observers = new Set();
+
+/** Called before every route render: charts from the previous view stop observing. */
+export function releaseCharts() {
+  for (const ro of observers) ro.disconnect();
+  observers.clear();
+}
+
+function figure({ title, summary, draw, table, legend }) {
+  const plot = el('div', { class: 'chart-plot' });
+  const tip = el('div', { class: 'chart-tip', role: 'status' });
+  tip.hidden = true;
+  const fig = el('figure', { class: 'chart' }, [
+    el('figcaption', { class: 'chart-caption' }, [el('h3', { class: 'chart-title', text: title }), summary ? el('p', { class: 'chart-summary', text: summary }) : null]),
+    plot,
+    legend || null,
+    tip,
+    table ? el('details', { class: 'chart-table' }, [el('summary', {}, [icon('chevron', 14), '以表格檢視']), table]) : null,
+  ]);
+  if (draw) {
+    let lastWidth = 0;
+    const redraw = () => {
+      const width = Math.floor(plot.clientWidth);
+      if (!width || width === lastWidth) return;
+      lastWidth = width;
+      plot.replaceChildren(draw(width));
+    };
+    if (typeof ResizeObserver !== 'undefined') {
+      const ro = new ResizeObserver(() => redraw());
+      ro.observe(plot);
+      observers.add(ro);
+    }
+    wireTooltip(fig, plot, tip);
+  }
+  return fig;
+}
+
+/** Marks carry `data-tip`; one tooltip per chart follows the pointer. */
+function wireTooltip(fig, plot, tip) {
+  plot.addEventListener('pointermove', (event) => {
+    const mark = event.target.closest && event.target.closest('[data-tip]');
+    if (!mark) {
+      tip.hidden = true;
+      return;
+    }
+    tip.textContent = mark.getAttribute('data-tip');
+    tip.hidden = false;
+    const box = fig.getBoundingClientRect();
+    const x = event.clientX - box.left;
+    const flip = x > box.width - 220;
+    tip.style.setProperty('left', (flip ? x - 12 : x + 12) + 'px');
+    tip.style.setProperty('top', event.clientY - box.top + 12 + 'px');
+    tip.classList.toggle('is-flipped', flip);
+  });
+  plot.addEventListener('pointerleave', () => {
+    tip.hidden = true;
+  });
+}
+
+function dataTable(headers, rows) {
+  return el('table', { class: 'data-table' }, [
+    el('thead', {}, [el('tr', {}, headers.map((h) => el('th', { scope: 'col', text: h })))]),
+    el('tbody', {}, rows.map((r) => el('tr', {}, r.map((c) => el('td', { text: String(c) }))))),
+  ]);
+}
+
+function emptyFigure(title, text) {
+  return el('figure', { class: 'chart chart-empty' }, [
+    el('figcaption', { class: 'chart-caption' }, [el('h3', { class: 'chart-title', text: title })]),
+    el('p', { class: 'note', text }),
+  ]);
+}
+
+/** Truncates an ASCII-ish label to roughly `px` at 12px; the full text rides in the tooltip and table. */
+function fit(text, px) {
+  const max = Math.max(4, Math.floor(px / 6.8));
+  return text.length > max ? text.slice(0, max - 1) + '…' : text;
+}
+
+/** Column/bar with a 4px rounded data end and a square baseline end. */
+function barPath(x, y, w, h, horizontal) {
+  const r = Math.min(4, horizontal ? w / 2 : h / 2, horizontal ? h / 2 : w / 2);
+  if (horizontal) {
+    return `M${x},${y}H${x + w - r}Q${x + w},${y} ${x + w},${y + r}V${y + h - r}Q${x + w},${y + h} ${x + w - r},${y + h}H${x}Z`;
+  }
+  return `M${x},${y + h}V${y + r}Q${x},${y} ${x + r},${y}H${x + w - r}Q${x + w},${y} ${x + w},${y + r}V${y + h}Z`;
+}
+
+function niceMax(value) {
+  if (value <= 4) return Math.max(1, value);
+  const step = Math.pow(10, Math.floor(Math.log10(value)));
+  return Math.ceil(value / step) * step;
+}
+
+const md = (d) => `${d.getMonth() + 1}/${d.getDate()}`;
+
+// --- 1. in transit -------------------------------------------------------------
+
+/**
+ * Each active change's journey: departed (`created`) to last seen
+ * (`lastModified`) as a thick run in the line colour, then dashed idle time up
+ * to today. A last-seen dot left of the threshold line means the change has
+ * gone stale.
+ */
+export function transitChart(changes, staleDays, now) {
+  const title = 'change 存在天數';
+  if (!changes.length) return emptyFigure(title, '沒有進行中的 change.');
+  const rows = changes
+    .map((c) => ({ name: c.name, created: parseLooseDate(c.created), seen: parseLooseDate(c.lastModified) }))
+    .filter((r) => r.seen)
+    .sort((a, b) => a.seen - b.seen);
+  const stale = rows.filter((r) => now - r.seen.getTime() > staleDays * DAY_MS).length;
+  const summary = stale
+    ? `${rows.length} 個進行中的 change, ${stale} 個超過 ${staleDays} 天沒有更新.`
+    : `${rows.length} 個進行中的 change, 都在 ${staleDays} 天內有更新.`;
+  const threshold = now - staleDays * DAY_MS;
+  let tMin = Math.min(threshold - 2 * DAY_MS, ...rows.map((r) => (r.created ? r.created.getTime() : r.seen.getTime())));
+  tMin -= (now - tMin) * 0.03;
+
+  const draw = (width) => {
+    const labelW = Math.min(180, Math.round(width * 0.32));
+    const x0 = labelW + 12;
+    const x1 = width - 12;
+    const top = 26;
+    const rowH = 30;
+    const height = top + rows.length * rowH + 26;
+    const x = (t) => x0 + ((t - tMin) / (now - tMin)) * (x1 - x0);
+    const g = svg('svg', { class: 'chart-svg', width, height, viewBox: `0 0 ${width} ${height}`, role: 'img', 'aria-label': summary });
+
+    // Axis first so marks sit over it.
+    const axisY = top + rows.length * rowH + 4;
+    g.append(svg('line', { class: 'axis', x1: x0, x2: x1, y1: axisY, y2: axisY }));
+    const ticks = 4;
+    for (let i = 0; i <= ticks; i++) {
+      const t = tMin + ((now - tMin) * i) / ticks;
+      const tx = x(t);
+      g.append(svg('line', { class: 'grid', x1: tx, x2: tx, y1: top - 6, y2: axisY }));
+      g.append(svg('text', { class: 'tick', x: tx, y: axisY + 16, 'text-anchor': i === 0 ? 'start' : i === ticks ? 'end' : 'middle', text: i === ticks ? '今天' : md(new Date(t)) }));
+    }
+    const tx = x(threshold);
+    g.append(svg('line', { class: 'threshold', x1: tx, x2: tx, y1: top - 10, y2: axisY }));
+    g.append(svg('text', { class: 'threshold-label', x: tx - 4, y: top - 14, 'text-anchor': 'end', text: `閒置門檻 ${staleDays} 天` }));
+
+    rows.forEach((r, i) => {
+      const y = top + i * rowH + rowH / 2;
+      const isStale = now - r.seen.getTime() > staleDays * DAY_MS;
+      const idle = Math.floor((now - r.seen.getTime()) / DAY_MS);
+      const age = r.created ? Math.floor((now - r.created.getTime()) / DAY_MS) : null;
+      const tipText = `${r.name} · ${age == null ? '未記錄 created' : '存在 ' + age + ' 天'} · 最後更新 ${relTime(r.seen, now)}`;
+      const row = svg('g', { class: 'transit-row' + (isStale ? ' is-stale' : ''), 'data-tip': tipText });
+      row.append(svg('rect', { class: 'hit', x: 0, y: y - rowH / 2, width, height: rowH }));
+      row.append(svg('text', { class: 'row-label', x: 0, y: y + 4, text: fit(r.name, labelW) }));
+      if (r.created && r.created <= r.seen) {
+        row.append(svg('line', { class: 'run', x1: x(r.created.getTime()), x2: x(r.seen.getTime()), y1: y, y2: y }));
+      }
+      row.append(svg('line', { class: 'idle', x1: x(r.seen.getTime()), x2: x1, y1: y, y2: y }));
+      row.append(svg('circle', { class: 'seen', cx: x(r.seen.getTime()), cy: y, r: 4.5 }));
+      g.append(row);
+    });
+    return g;
+  };
+
+  const table = dataTable(
+    ['change', 'created', '最後更新', '閒置天數'],
+    rows.map((r) => [r.name, r.created ? formatDate(r.created) : '未記錄', formatDate(r.seen), Math.floor((now - r.seen.getTime()) / DAY_MS)])
+  );
+  return figure({ title, summary, draw, table });
+}
+
+// --- 2. weekly archives --------------------------------------------------------
+
+export function archiveRateChart(archivedChanges, now) {
+  const title = '每週歸檔數';
+  const buckets = weeklyArchiveCounts(archivedChanges, now, 12);
+  const total = buckets.reduce((n, b) => n + b.count, 0);
+  const peak = Math.max(...buckets.map((b) => b.count));
+  if (total === 0) return emptyFigure(title, '近 12 週沒有歸檔任何 change.');
+  const summary = `近 12 週歸檔 ${total} 個 change, 單週最多 ${peak} 個.`;
+  const top = niceMax(peak);
+  const latest = buckets.length - 1;
+  // Label sparingly: the first peak week and the current week, nothing else;
+  // the axis and the tooltip carry the rest.
+  const labelled = new Set([buckets.findIndex((b) => b.count === peak)]);
+  if (buckets[latest].count > 0) labelled.add(latest);
+
+  const draw = (width) => {
+    const x0 = 28;
+    const x1 = width - 8;
+    const y0 = 18;
+    const y1 = 150;
+    const height = y1 + 26;
+    const slot = (x1 - x0) / buckets.length;
+    const barW = Math.min(24, slot * 0.6);
+    const y = (v) => y1 - (v / top) * (y1 - y0);
+    const g = svg('svg', { class: 'chart-svg', width, height, viewBox: `0 0 ${width} ${height}`, role: 'img', 'aria-label': summary });
+    const tickValues = top >= 4 ? [0, top / 2, top] : [0, top];
+    for (const v of tickValues) {
+      g.append(svg('line', { class: v === 0 ? 'axis' : 'grid', x1: x0, x2: x1, y1: y(v), y2: y(v) }));
+      g.append(svg('text', { class: 'tick', x: x0 - 8, y: y(v) + 4, 'text-anchor': 'end', text: String(v) }));
+    }
+    buckets.forEach((b, i) => {
+      const cx = x0 + (i + 0.5) * slot;
+      const col = svg('g', { class: 'column', 'data-tip': `${md(b.start)} 起的那週: ${b.count} 個` });
+      col.append(svg('rect', { class: 'hit', x: cx - slot / 2, y: y0 - 10, width: slot, height: y1 - y0 + 10 }));
+      if (b.count > 0) {
+        col.append(svg('path', { class: 'bar', d: barPath(cx - barW / 2, y(b.count), barW, y1 - y(b.count), false) }));
+        if (labelled.has(i)) {
+          col.append(svg('text', { class: 'value', x: cx, y: y(b.count) - 6, 'text-anchor': 'middle', text: String(b.count) }));
+        }
+      }
+      if (i % 3 === 0 || i === latest) {
+        col.append(svg('text', { class: 'tick', x: cx, y: y1 + 16, 'text-anchor': 'middle', text: i === latest ? '本週' : md(b.start) }));
+      }
+      g.append(col);
+    });
+    return g;
+  };
+
+  const table = dataTable(['週起始', '歸檔數'], buckets.map((b) => [formatDate(b.start), b.count]));
+  return figure({ title, summary, draw, table });
+}
+
+// --- 3. decision timeline ------------------------------------------------------
+
+const ADR_SHAPES = ['accepted', 'proposed', 'superseded'];
+
+function adrMark(status, cx, cy) {
+  if (status === 'accepted') return svg('circle', { class: 'adr adr-accepted', cx, cy, r: 5 });
+  if (status === 'proposed') return svg('circle', { class: 'adr adr-proposed', cx, cy, r: 4.5 });
+  if (status === 'superseded') {
+    return svg('path', { class: 'adr adr-superseded', d: `M${cx - 3.5},${cy - 3.5}L${cx + 3.5},${cy + 3.5}M${cx + 3.5},${cy - 3.5}L${cx - 3.5},${cy + 3.5}` });
+  }
+  return svg('path', { class: 'adr adr-other', d: `M${cx},${cy - 5}L${cx + 5},${cy}L${cx},${cy + 5}L${cx - 5},${cy}Z` });
+}
+
+function legendSwatch(status) {
+  return svg('svg', { width: 14, height: 14, viewBox: '0 0 14 14', 'aria-hidden': 'true', class: 'legend-swatch' }, [adrMark(status, 7, 7)]);
+}
+
+export function decisionTimeline(key, decisions, now) {
+  const title = 'ADR 時間軸';
+  if (!decisions || !decisions.length) return emptyFigure(title, '這個 project 還沒有決策記錄.');
+  const items = decisions
+    .map((d) => ({ ...d, when: parseLooseDate(d.date) }))
+    .filter((d) => d.when)
+    .sort((a, b) => a.when - b.when);
+  const counts = {};
+  for (const d of decisions) counts[d.status] = (counts[d.status] || 0) + 1;
+  const open = counts.proposed || 0;
+  const summary = `${decisions.length} 筆決策` + (open ? `, ${open} 筆仍是 proposed.` : ', 沒有懸而未決的 proposed.');
+  let tMin = items.length ? items[0].when.getTime() : now - 30 * DAY_MS;
+  tMin = Math.min(tMin, now - 30 * DAY_MS);
+  tMin -= (now - tMin) * 0.03;
+
+  const draw = (width) => {
+    const x0 = 10;
+    const x1 = width - 10;
+    const x = (t) => x0 + ((t - tMin) / (now - tMin)) * (x1 - x0);
+    const levels = [];
+    const placed = items.map((d) => {
+      const px = x(d.when.getTime());
+      let level = 0;
+      while (levels.some((p) => p.level === level && Math.abs(p.x - px) < 11)) level++;
+      levels.push({ x: px, level });
+      return { d, px, level };
+    });
+    const maxLevel = Math.max(0, ...placed.map((p) => p.level));
+    const base = 18 + maxLevel * 13 + 8;
+    const height = base + 30;
+    const g = svg('svg', { class: 'chart-svg', width, height, viewBox: `0 0 ${width} ${height}`, role: 'img', 'aria-label': summary });
+    g.append(svg('line', { class: 'axis', x1: x0, x2: x1, y1: base + 8, y2: base + 8 }));
+    // Month starts as ticks, thinned to keep labels apart; evenly spaced
+    // ticks over a short range repeated the same month.
+    const todayX = x(now);
+    let lastX = -Infinity;
+    const month = new Date(tMin);
+    month.setDate(1);
+    month.setHours(0, 0, 0, 0);
+    for (month.setMonth(month.getMonth() + 1); month.getTime() < now; month.setMonth(month.getMonth() + 1)) {
+      const mx = x(month.getTime());
+      if (mx - lastX < 64 || todayX - mx < 52) continue;
+      g.append(svg('line', { class: 'grid', x1: mx, x2: mx, y1: base + 4, y2: base + 12 }));
+      g.append(svg('text', { class: 'tick', x: mx, y: base + 26, 'text-anchor': 'middle', text: formatDate(month).slice(0, 7) }));
+      lastX = mx;
+    }
+    g.append(svg('text', { class: 'tick', x: todayX, y: base + 26, 'text-anchor': 'end', text: '今天' }));
+    for (const { d, px, level } of placed) {
+      const cy = base - level * 13;
+      const link = svg('a', { href: routes.decisions(key, d.file), 'data-tip': `${formatDate(d.when)} · ${d.status} · ${d.title}`, 'aria-label': `${d.title} (${d.status})` }, [
+        svg('rect', { class: 'hit', x: px - 6, y: cy - 6, width: 12, height: 12 }),
+        adrMark(d.status, px, cy),
+      ]);
+      g.append(link);
+    }
+    return g;
+  };
+
+  const statuses = [...ADR_SHAPES.filter((s) => counts[s]), ...Object.keys(counts).filter((s) => !ADR_SHAPES.includes(s))];
+  const legend = el('ul', { class: 'chart-legend' }, statuses.map((s) => el('li', {}, [legendSwatch(s), el('span', { text: `${s} ${counts[s]}` })])));
+  const table = dataTable(['日期', '標題', 'status'], items.slice().reverse().map((d) => [formatDate(d.when), d.title, d.status]));
+  return figure({ title, summary, draw, table, legend });
+}
+
+// --- 4. spec size ----------------------------------------------------------------
+
+export function specSizeChart(key, specs) {
+  const title = 'Spec 規模';
+  if (!specs.length) return emptyFigure(title, '還沒有任何 spec. change 歸檔時, 它的 delta spec 會合併進 tospec/specs/.');
+  const sorted = specs.slice().sort((a, b) => b.requirementCount - a.requirementCount || a.id.localeCompare(b.id));
+  const total = sorted.reduce((n, s) => n + s.requirementCount, 0);
+  const summary = `${specs.length} 個 spec, 共 ${total} 條 requirement.`;
+  const LIMIT = 10;
+  const shown = sorted.slice(0, LIMIT);
+  const rest = sorted.slice(LIMIT);
+  const rows = shown.map((s) => ({ label: s.id, value: s.requirementCount, href: routes.spec(key, s.id) }));
+  if (rest.length) rows.push({ label: `其他 ${rest.length} 個 spec`, value: rest.reduce((n, s) => n + s.requirementCount, 0), other: true });
+  const max = Math.max(1, ...rows.map((r) => r.value));
+
+  const draw = (width) => {
+    const labelW = Math.min(200, Math.round(width * 0.38));
+    const x0 = labelW + 10;
+    const x1 = width - 36;
+    const rowH = 26;
+    const barH = 12;
+    const height = rows.length * rowH + 6;
+    const g = svg('svg', { class: 'chart-svg', width, height, viewBox: `0 0 ${width} ${height}`, role: 'img', 'aria-label': summary });
+    g.append(svg('line', { class: 'axis', x1: x0, x2: x0, y1: 0, y2: height - 4 }));
+    rows.forEach((r, i) => {
+      const cy = i * rowH + rowH / 2 + 2;
+      const w = (r.value / max) * (x1 - x0);
+      const parts = [
+        svg('rect', { class: 'hit', x: 0, y: cy - rowH / 2, width, height: rowH }),
+        svg('text', { class: 'row-label', x: labelW, y: cy + 4, 'text-anchor': 'end', text: fit(r.label, labelW) }),
+        w > 0 ? svg('path', { class: 'bar' + (r.other ? ' is-other' : ''), d: barPath(x0, cy - barH / 2, Math.max(w, 2), barH, true) }) : null,
+        svg('text', { class: 'value', x: x0 + w + 6, y: cy + 4, text: String(r.value) }),
+      ];
+      const tipText = `${r.label}: ${r.value} 條 requirement`;
+      g.append(r.href ? svg('a', { href: r.href, 'data-tip': tipText }, parts) : svg('g', { 'data-tip': tipText }, parts));
+    });
+    return g;
+  };
+
+  const table = dataTable(['spec', 'requirement'], sorted.map((s) => [s.id, s.requirementCount]));
+  return figure({ title, summary, draw, table });
+}