beadcyte 0.4.0

package/src/web/components/ShipTrend.vue

@@ -0,0 +1,510 @@
+<script setup lang="ts">
+// ShipTrend.vue — ships per week over the velocity lookback window.
+//
+// The one thing the summary blocks could not say. The Allocation block
+// reports a flat closes-per-week average; whether that rate is rising or
+// falling is invisible in an average and is the whole question anyone asks
+// of a velocity number. computeVelocity already visits every close in the
+// window, so the series costs nothing beyond keeping it (bp-67g.30).
+//
+// Assembled from the same DDV primitives as BeadsGantt — <DDV> for the
+// wrapper, <CartesianScaler> for the projection, <Axis> for both axes — and
+// a hand-written path for the line. LinePlot is deliberately not used: it
+// strokes at a fixed 1px and defaults to Catmull-Rom, and a curve through
+// integer bucket counts draws ships that did not happen.
+
+import { computed, onBeforeUnmount, onMounted, reactive, ref } from "vue";
+import { Axis, CartesianScaler, DDV, fromRange } from "@incytestudios/ddv";
+import type { Layout, MouseState, Value } from "@incytestudios/ddv";
+import "@incytestudios/ddv/style.css";
+import type { ShipTrend } from "../insights";
+
+const props = defineProps<{ trend: ShipTrend }>();
+
+// left holds <Axis>'s self-reserved label width — plotMarginPx +
+// tickLengthPx + 4 + the widest tick label — with slack for a four-digit
+// count; right holds the endpoint's direct label; bottom holds the date row.
+const PAD = { top: 14, right: 40, bottom: 24, left: 42 };
+const HEIGHT = 168;
+
+// Below this the plot is narrower than its own axis labels, so the chart is
+// dropped for the table instead of rendering a smear.
+const MIN_PLOT_WIDTH = 140;
+
+const hostEl = ref<HTMLElement | null>(null);
+const elementWidth = ref(0);
+
+let ro: ResizeObserver | null = null;
+onMounted(() => {
+  if (!hostEl.value) return;
+  const measure = () => {
+    if (hostEl.value) {
+      elementWidth.value = hostEl.value.getBoundingClientRect().width;
+    }
+  };
+  measure();
+  ro = new ResizeObserver(measure);
+  ro.observe(hostEl.value);
+});
+onBeforeUnmount(() => ro?.disconnect());
+
+const weeks = computed(() => props.trend.weeks);
+
+const layout = computed<Layout>(() => ({
+  plotWidth: Math.max(0, elementWidth.value - PAD.left - PAD.right),
+  plotHeight: HEIGHT - PAD.top - PAD.bottom,
+  elementWidth: elementWidth.value,
+  elementHeight: HEIGHT,
+  computedHeight: HEIGHT,
+  margins: { ...PAD },
+}));
+
+/**
+ * A repo with no ship records at all would plot a flat line along zero,
+ * which looks like a measurement rather than an absence — and it is the
+ * common case, because a ship here means recorded evidence — an MR URL or a
+ * commit SHA — and plenty of projects close beads carrying neither. Say so
+ * instead.
+ */
+const hasShips = computed(() => props.trend.total > 0);
+
+const canDraw = computed(
+  () =>
+    hasShips.value &&
+    weeks.value.length > 1 &&
+    layout.value.plotWidth >= MIN_PLOT_WIDTH,
+);
+
+// DDV's primitives read flags off a MouseState for styling; the scaler and
+// the axes don't need live coordinates, and the hover below is our own.
+const mouseState = reactive<MouseState>({
+  mouse: { x: 0, y: 0 },
+  normalizedMouse: { x: 0, y: 0 },
+  globalMouse: { x: 0, y: 0 },
+  isHovered: false,
+  isPlotHovered: false,
+});
+
+/**
+ * Week INDEX on x, not the date. A Date domain makes DDV pick its own tick
+ * unit, which lands on days for an eight-week window and crowds the axis.
+ * The points are weekly buckets, so the index is the natural unit and the
+ * formatter puts the date back.
+ */
+const xDomain = computed(() => ({
+  min: 0,
+  max: Math.max(1, weeks.value.length - 1),
+}));
+
+/** Headroom above the peak so the line isn't welded to the top edge. */
+const yDomain = computed(() => {
+  const peak = Math.max(1, ...weeks.value.map((w) => w.count));
+  return { min: 0, max: Math.ceil(peak * 1.15) };
+});
+
+const xScreen = computed(() => fromRange(layout.value.plotWidth || 1));
+const yScreen = computed(() => fromRange(layout.value.plotHeight || 1));
+
+const fmtWeek = (d: Date) =>
+  d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+
+/**
+ * Blank for a fractional tick. <Axis> solves ticks over a continuous domain,
+ * so a week-index axis gets values like 3.5 once the plot is wide enough to
+ * fit more ticks than there are weeks — and rounding those to the nearest
+ * week prints the same date twice in a row. There is no discrete tick mode
+ * to ask for instead (filed upstream as bp-67g.22), so the label is dropped
+ * and the tick mark left standing.
+ */
+function weekLabel(i: number): string {
+  if (!Number.isInteger(i)) return "";
+  const w = weeks.value[i];
+  return w ? fmtWeek(w.weekStart) : "";
+}
+
+const deltaLabel = computed(() => {
+  const d = props.trend.vsMean;
+  // One shipping week is not a baseline, so say what IS true — how much of
+  // the window has any history in it — rather than a percentage against a
+  // mean derived from the single week being described.
+  if (d === null) {
+    const a = props.trend.activeWeeks;
+    if (a === 0) return null;
+    return `first ${a === 1 ? "week" : `${a} weeks`} of history — no baseline yet`;
+  }
+  const pct = Math.round(d * 100);
+  if (pct === 0) return "on its average";
+  return `${pct > 0 ? "+" : ""}${pct}% vs average`;
+});
+
+// ── hover ─────────────────────────────────────────────────────────────────
+// The hit area is the whole plot, so reading a middle week doesn't require
+// landing on a 3px point.
+
+const hoverIndex = ref<number | null>(null);
+
+function onMove(e: MouseEvent) {
+  const rect = (e.currentTarget as SVGRectElement).getBoundingClientRect();
+  const frac = (e.clientX - rect.left) / Math.max(1, rect.width);
+  hoverIndex.value = Math.max(
+    0,
+    Math.min(weeks.value.length - 1, Math.round(frac * (weeks.value.length - 1))),
+  );
+}
+</script>
+
+<template>
+  <section class="stat-block trend-block">
+    <h2>
+      Ships per week
+      <span class="hint">last {{ weeks.length }} weeks</span>
+    </h2>
+
+    <div v-if="hasShips" class="trend-head">
+      <span class="trend-value">{{ trend.total }}</span>
+      <span class="trend-sub">
+        {{ trend.perWeek.toFixed(1) }}/wk average ·
+        {{ trend.last }} this week<template v-if="deltaLabel">,
+        {{ deltaLabel }}</template>
+      </span>
+    </div>
+
+    <div ref="hostEl" class="trend-host">
+      <DDV
+        v-if="canDraw"
+        :layout="layout"
+        :mouse-state="mouseState"
+        class="trend-ddv"
+      >
+        <template #default>
+          <!-- reverse-y-axis, because SVG's y grows DOWNWARD. Without it the
+               scaler maps count 0 to y 0 (the top) and the whole plot renders
+               upside down: the axis reads 0 at the top and the peak week sits
+               at the bottom. Easy to miss, because a monotonically falling
+               line is a perfectly plausible chart. BeadsGantt does NOT set
+               this and is right not to — its y axis is row index, where 0
+               belongs at the top. -->
+          <CartesianScaler
+            :x-source="xDomain"
+            :y-source="yDomain"
+            :x-target="xScreen"
+            :y-target="yScreen"
+            reverse-y-axis
+          >
+            <template #default="{ xScaler, yScaler }">
+              <!-- ONE translated group for the axes and the marks alike.
+                   <Axis> positions itself relative to wherever it is
+                   mounted: a vertical axis draws at `-reservedWidth` and a
+                   horizontal one at `+plotHeight`, expecting to sit inside a
+                   coordinate system already shifted by the plot margins. Left
+                   at the SVG origin it puts its y labels at negative x, where
+                   svg.outer's overflow:hidden clips them away entirely, and
+                   shifts the x labels out of line with the data. -->
+              <g
+                v-if="xScaler && yScaler"
+                :transform="`translate(${PAD.left} ${PAD.top})`"
+              >
+                <Axis
+                  :layout="layout"
+                  :scaler="yScaler"
+                  :domain="yDomain"
+                  is-vertical
+                  draw-grid-lines
+                  tick-frequency="36px"
+                  :tick-length-px="3"
+                  :plot-margin-px="0"
+                />
+                <Axis
+                  :layout="layout"
+                  :scaler="xScaler"
+                  :domain="xDomain"
+                  tick-frequency="88px"
+                  :tick-length-px="3"
+                  :plot-margin-px="0"
+                  :axis-tick-formatter="(v: Value) => weekLabel(Number(v))"
+                />
+
+                <g>
+                  <!-- A single series reads as a quantity, so it gets a
+                       wash under it. 10% keeps it a wash, not a block. -->
+                  <path
+                    class="trend-area"
+                    :d="
+                      `M ${xScaler.scale(0)} ${yScaler.scale(0)} ` +
+                      weeks
+                        .map((w, i) => `L ${xScaler.scale(i)} ${yScaler.scale(w.count)}`)
+                        .join(' ') +
+                      ` L ${xScaler.scale(weeks.length - 1)} ${yScaler.scale(0)} Z`
+                    "
+                  />
+                  <path
+                    class="trend-line"
+                    :d="
+                      weeks
+                        .map(
+                          (w, i) =>
+                            `${i ? 'L' : 'M'} ${xScaler.scale(i)} ${yScaler.scale(w.count)}`,
+                        )
+                        .join(' ')
+                    "
+                  />
+
+                  <!-- Only the endpoint is direct-labelled; the axis and the
+                       hover carry the rest. -->
+                  <circle
+                    class="trend-end"
+                    :cx="xScaler.scale(weeks.length - 1)"
+                    :cy="yScaler.scale(trend.last)"
+                    r="3.5"
+                  />
+                  <text
+                    class="trend-end-label"
+                    :x="xScaler.scale(weeks.length - 1) + 7"
+                    :y="yScaler.scale(trend.last) + 4"
+                  >{{ trend.last }}</text>
+
+                  <g v-if="hoverIndex !== null" class="trend-hover">
+                    <line
+                      :x1="xScaler.scale(hoverIndex)"
+                      :x2="xScaler.scale(hoverIndex)"
+                      :y1="0"
+                      :y2="layout.plotHeight"
+                    />
+                    <circle
+                      :cx="xScaler.scale(hoverIndex)"
+                      :cy="yScaler.scale(weeks[hoverIndex].count)"
+                      r="3.5"
+                    />
+                    <text
+                      :x="xScaler.scale(hoverIndex)"
+                      :y="-3"
+                      :text-anchor="
+                        hoverIndex > (weeks.length - 1) / 2 ? 'end' : 'start'
+                      "
+                    >
+                      {{ fmtWeek(weeks[hoverIndex].weekStart) }} ·
+                      {{ weeks[hoverIndex].count }}
+                    </text>
+                  </g>
+                  <rect
+                    class="trend-hit"
+                    :width="layout.plotWidth"
+                    :height="layout.plotHeight"
+                    @mousemove="onMove"
+                    @mouseleave="hoverIndex = null"
+                  />
+                </g>
+              </g>
+            </template>
+          </CartesianScaler>
+        </template>
+      </DDV>
+      <p v-if="!hasShips" class="trend-empty">
+        No ships recorded in the last {{ weeks.length }} weeks. A ship is a
+        closed bead carrying <code>metadata.ship.mr_url</code> or
+        <code>metadata.ship.commit</code>; closes with neither aren't counted,
+        here or in the calibrated caps.
+      </p>
+    </div>
+
+    <!-- Every value reachable without hovering. -->
+    <details v-if="hasShips" class="table-view">
+      <summary>Table</summary>
+      <table>
+        <thead>
+          <tr>
+            <th>week of</th>
+            <th class="num">ships</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="w in weeks" :key="w.weekStart.toISOString()">
+            <td>{{ fmtWeek(w.weekStart) }}</td>
+            <td class="num">{{ w.count }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </details>
+  </section>
+</template>
+
+<style scoped>
+.trend-block h2 .hint {
+  text-transform: none;
+  letter-spacing: 0;
+  font-weight: 400;
+  color: var(--c-dim);
+  margin-left: 6px;
+}
+
+.trend-head {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  flex-wrap: wrap;
+  margin-bottom: 6px;
+}
+
+/* Proportional figures, not tabular: equal-width digits read loose at this
+   size. tabular-nums belongs in the table below, where they align. */
+.trend-value {
+  font-size: 24px;
+  font-weight: 600;
+  line-height: 1.1;
+  color: var(--c-text);
+}
+
+.trend-sub {
+  font-size: 11px;
+  color: var(--c-dim);
+}
+
+.trend-host {
+  /* DDV's inner svg.outer caps at min-height 250px unless --minHeight says
+     otherwise, and --aspectRatio must be auto or it resizes to whatever
+     ratio the wrapper happened to start at. */
+  --minHeight: 168px;
+  --aspectRatio: auto;
+  width: 100%;
+  min-height: 168px;
+}
+
+.trend-empty {
+  color: var(--c-dim);
+  font-size: 12px;
+  line-height: 1.5;
+  margin: 8px 0 0;
+  max-width: 62ch;
+}
+
+.trend-empty code {
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+}
+
+/* No chart, no reserved chart height. */
+.trend-block:has(.trend-empty) .trend-host {
+  --minHeight: 0;
+  min-height: 0;
+}
+
+.table-view {
+  margin-top: 10px;
+  font-size: 11px;
+}
+
+.table-view summary {
+  cursor: pointer;
+  color: var(--c-dim);
+  padding: 2px 0;
+}
+
+.table-view table {
+  border-collapse: collapse;
+  margin-top: 6px;
+  width: 100%;
+}
+
+.table-view th,
+.table-view td {
+  text-align: left;
+  padding: 2px 8px 2px 0;
+  border-bottom: 1px solid var(--c-border);
+}
+
+.table-view thead th {
+  color: var(--c-dim);
+  font-size: 10px;
+  font-weight: 600;
+}
+
+.table-view .num {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+</style>
+
+<style>
+/* Unscoped: these marks live inside DDV's own SVG subtree, which a scoped
+   style does not reach.
+   `shipped` is the encoding token for a real ship, so a trend OF ships
+   wears it rather than inventing a colour — nothing new to register in
+   style-audit. */
+.trend-ddv {
+  display: block;
+  width: 100%;
+}
+
+/* DDV's axis and grid defaults are authored for a light theme and vanish on
+   our dark ground. Same overrides BeadsGantt applies. */
+.trend-block .trend-host {
+  --axisTickFontColor: var(--c-dim);
+  --axisLabelColor: var(--c-dim);
+  --axisTickFontFamily: var(--font-body);
+  --axisTickFontSize: 10px;
+  --axisTickFontWeight: 400;
+  --boundaryStroke: var(--c-border-strong);
+  --boundaryStrokeWidth: 1;
+  --tickStroke: var(--c-border-strong);
+  --tickStrokeWidth: 1;
+  --subTickStroke: var(--c-border);
+  --subTickStrokeWidth: 0.5;
+  --gridStroke: var(--c-border);
+  --gridStrokeWidth: 0.5;
+  --subGridStroke: var(--c-border);
+  --subGridStrokeWidth: 0.5;
+  --gridStrokeDashArray: none;
+  --plotSurface: transparent;
+  --chartSurface: transparent;
+}
+
+.trend-ddv .trend-line {
+  fill: none;
+  stroke: var(--c-shipped);
+  stroke-width: 2;
+  stroke-linejoin: round;
+  stroke-linecap: round;
+}
+
+.trend-ddv .trend-area {
+  fill: var(--c-shipped);
+  fill-opacity: 0.1;
+  stroke: none;
+}
+
+/* A 2px ring in the surface colour keeps the marker legible where it
+   crosses the line or the axis. */
+.trend-ddv .trend-end {
+  fill: var(--c-shipped);
+  stroke: var(--c-panel);
+  stroke-width: 2;
+}
+
+.trend-ddv .trend-end-label {
+  fill: var(--c-text);
+  font-size: 11px;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+.trend-ddv .trend-hit {
+  fill: transparent;
+}
+
+.trend-ddv .trend-hover line {
+  stroke: var(--c-border-strong);
+  stroke-width: 1;
+}
+
+.trend-ddv .trend-hover circle {
+  fill: var(--c-shipped);
+  stroke: var(--c-panel);
+  stroke-width: 2;
+}
+
+.trend-ddv .trend-hover text {
+  fill: var(--c-text);
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+}
+</style>

package/src/web/components/ShortcutsOverlay.vue

@@ -0,0 +1,164 @@
+<script setup lang="ts">
+// ShortcutsOverlay.vue — the ? overlay (bp-67g.45), generated from
+// keybindings.ts so it cannot drift from what the keys do. Opens on ? and
+// from the options menu; closes on Escape (through the same table), ?,
+// the close button or a click on the backdrop.
+
+import { computed } from "vue";
+import { X } from "@lucide/vue";
+import { useBeadsStore } from "../store";
+import { bindingsByGroup, chordsToShow, formatChord, KEY_CONVENTION } from "../keybindings";
+
+const store = useBeadsStore();
+const mac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
+const groups = computed(() => bindingsByGroup());
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="store.helpOpen"
+      class="shortcuts-overlay"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Keyboard shortcuts"
+      @click.self="store.closeHelp()"
+    >
+      <div class="shortcuts-panel">
+        <header>
+          <h2>Keyboard shortcuts</h2>
+          <button type="button" class="close" title="Close (Esc)" aria-label="Close" @click="store.closeHelp()">
+            <X class="icon" />
+          </button>
+        </header>
+        <p class="convention">{{ KEY_CONVENTION }}</p>
+        <div class="groups">
+          <section v-for="g in groups" :key="g.group">
+            <h3>{{ g.group }}</h3>
+            <dl>
+              <template v-for="b in g.bindings" :key="b.action">
+                <dt>
+                  <kbd v-for="c in chordsToShow(b, mac)" :key="c.key + (c.ctrl ? 'c' : '') + (c.meta ? 'm' : '')">{{ formatChord(c, mac) }}</kbd>
+                </dt>
+                <dd>{{ b.label }}</dd>
+              </template>
+            </dl>
+          </section>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style>
+.shortcuts-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 950;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 8vh 16px;
+  background: color-mix(in oklab, var(--c-bg) 70%, transparent);
+}
+
+.shortcuts-panel {
+  width: min(880px, 100%);
+  max-height: 84vh;
+  overflow: auto;
+  background: var(--c-panel);
+  color: var(--c-text);
+  border: 1px solid var(--c-border-strong);
+  border-radius: 8px;
+  box-shadow: var(--shadow-pop);
+  padding: 16px 20px 20px;
+}
+
+.shortcuts-panel header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 6px;
+}
+
+.shortcuts-panel h2 {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.shortcuts-panel .close {
+  all: unset;
+  cursor: pointer;
+  color: var(--c-dim);
+  display: inline-flex;
+  padding: 4px;
+  border-radius: 4px;
+}
+
+.shortcuts-panel .close:hover {
+  color: var(--c-text);
+  background: var(--c-lift);
+}
+
+.shortcuts-panel .close .icon {
+  width: 16px;
+  height: 16px;
+}
+
+.shortcuts-panel .convention {
+  margin: 0 0 14px;
+  font-size: 12px;
+  color: var(--c-dim);
+  line-height: 1.5;
+}
+
+.shortcuts-panel .groups {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 14px 28px;
+}
+
+.shortcuts-panel h3 {
+  margin: 0 0 6px;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--c-dim);
+}
+
+.shortcuts-panel dl {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 4px 12px;
+  margin: 0;
+  font-size: 12px;
+}
+
+.shortcuts-panel dt {
+  display: flex;
+  gap: 4px;
+  align-items: center;
+}
+
+.shortcuts-panel dd {
+  margin: 0;
+  color: var(--c-text);
+}
+
+.shortcuts-panel kbd {
+  display: inline-block;
+  min-width: 18px;
+  padding: 1px 6px;
+  border: 1px solid var(--c-border-strong);
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  background: var(--c-lift);
+  color: var(--c-text);
+  font-family: ui-monospace, monospace;
+  font-size: 11px;
+  line-height: 1.5;
+  text-align: center;
+}
+</style>