k0-board 0.1.2 → 0.3.0

package/web/changelog.js

@@ -0,0 +1,298 @@
+import { render } from '/md.js'
+
+// ── The ChangeLog ────────────────────────────────────────────────────────────
+// k0's third page. The board says what is happening; this says what happened.
+//
+// It is built in two passes on purpose. The facts come back from the server straight away and
+// are on screen before you have finished reading the heading; the words take a model half a
+// minute, and arrive into a page that was already worth looking at. A summary that shows a
+// spinner over an empty sheet is a summary you close.
+
+const $ = (s) => document.querySelector(s)
+
+const api = async (url, opts) => {
+  const r = await fetch(url, { headers: { 'content-type': 'application/json' }, ...opts })
+  if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error || r.statusText)
+  return r.json()
+}
+
+const DAY = 24 * 60 * 60 * 1000
+
+// Something to read while the model reads. They are not jokes exactly — they say what is
+// actually going on, which is the only reason a waiting message is ever worth having.
+const PHRASES = [
+  'Reading the commits…',
+  'Working out what actually shipped…',
+  'Translating git into human…',
+  'Looking for what you left half-done…',
+  'Checking what never made it out of here…',
+  'Putting the day in order…',
+]
+
+let period = 'last'
+let facts = null
+let poll = null
+let phrases = null
+const put = new Set() // repositories folded away by hand, this visit only
+
+// ── Painting ─────────────────────────────────────────────────────────────────
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+
+const day = (t) => new Date(t).toLocaleDateString(undefined, { day: 'numeric', month: 'long' })
+
+/** Which stretch of time is on screen, said the way you would say it. */
+function whenLabel(data) {
+  const single = data.to - data.from <= DAY
+  if (!single) return `${day(data.from)} – ${day(data.to - 1)}`
+  const today = new Date()
+  today.setHours(0, 0, 0, 0)
+  if (data.from === today.getTime()) return 'Today'
+  if (data.from === today.getTime() - DAY) return 'Yesterday'
+  return day(data.from)
+}
+
+/**
+ * The written summary comes back as one piece of Markdown with a `## name` per repository.
+ * It is cut back apart here so each repository's words can sit with its own facts — and so
+ * that folding a repository away takes its paragraph with it.
+ *
+ * The headings themselves are dropped: the block already carries the name, and this way a
+ * repository is always called what k0 calls it. Anything that matches no repository is kept
+ * and shown at the top rather than quietly lost.
+ */
+function sectionise(html) {
+  const holder = document.createElement('div')
+  holder.innerHTML = html
+  const loose = []
+  const map = new Map()
+  let current = null
+  for (const node of [...holder.childNodes]) {
+    if (node.nodeType === 1 && node.tagName === 'H2') {
+      current = node.textContent.trim().toLowerCase()
+      map.set(current, [])
+      continue
+    }
+    if (current) map.get(current).push(node)
+    else loose.push(node)
+  }
+  return { loose, map }
+}
+
+function commitList(r) {
+  const ul = document.createElement('ul')
+  ul.className = 'commits'
+  for (const c of r.commits) {
+    const li = document.createElement('li')
+    const dot = document.createElement('i')
+    dot.className = c.online === false ? 'local' : 'online'
+    dot.title = c.online === false ? 'Still on this machine' : 'Online'
+    li.append(dot, document.createTextNode(c.subject))
+    ul.append(li)
+  }
+  return ul
+}
+
+/** What is still outstanding here — and only for repositories you actually touched. */
+function pending(r) {
+  const lines = []
+  if (r.unpushedTotal) lines.push(`${plural(r.unpushedTotal, 'commit')} still on this machine`)
+  if (r.dirtyTotal) lines.push(`${plural(r.dirtyTotal, 'file')} changed and never committed`)
+  if (r.unreleased) lines.push(`${plural(r.unreleased.filter((l) => l.startsWith('-')).length, 'changelog line')} not yet released`)
+  const open = r.cards.filter((c) => !c.done)
+  if (open.length) lines.push(`${plural(open.length, 'card')} still open`)
+  if (!lines.length) return null
+  const p = document.createElement('p')
+  p.className = 'pending'
+  p.textContent = lines.join(' · ')
+  return p
+}
+
+function factsBlock(r) {
+  const d = document.createElement('details')
+  d.className = 'facts'
+  const s = document.createElement('summary')
+  const local = r.commits.filter((c) => c.online === false).length
+  const bits = []
+  if (r.commits.length) bits.push(plural(r.commits.length, 'commit'))
+  if (local) bits.push(`${local} not out yet`)
+  if (r.dirty.length) bits.push(plural(r.dirty.length, 'file touched', 'files touched'))
+  if (r.cards.length) bits.push(plural(r.cards.length, 'card'))
+  s.textContent = bits.join(' · ') || 'nothing recorded'
+  d.append(s)
+  if (r.commits.length) d.append(commitList(r))
+  const p = pending(r)
+  if (p) d.append(p)
+  return d
+}
+
+function repoBlock(r, nodes) {
+  const sec = document.createElement('section')
+  sec.className = 'repo'
+  const h = document.createElement('h2')
+  h.textContent = r.name
+  sec.append(h)
+  if (nodes?.length) {
+    const prose = document.createElement('div')
+    prose.className = 'prose'
+    prose.append(...nodes)
+    sec.append(prose)
+  }
+  sec.append(factsBlock(r))
+  return sec
+}
+
+function paintChips(data) {
+  const box = $('#chips')
+  box.textContent = ''
+  box.hidden = data.repos.length < 2
+  for (const r of data.repos) {
+    const b = document.createElement('button')
+    b.type = 'button'
+    b.textContent = r.name
+    b.setAttribute('aria-pressed', String(!put.has(r.name)))
+    b.onclick = () => {
+      if (put.has(r.name)) put.delete(r.name)
+      else put.add(r.name)
+      paint()
+    }
+    box.append(b)
+  }
+}
+
+/** Draws whatever is known right now: the facts always, the words if they have arrived. */
+function paint(text = null) {
+  const data = facts
+  if (!data) return
+  const { loose, map } = text ? sectionise(render(text)) : { loose: [], map: new Map() }
+
+  const intro = $('#intro')
+  intro.textContent = ''
+  if (loose.length) intro.append(...loose)
+
+  const box = $('#repos')
+  box.textContent = ''
+  const mine = new Set(data.repos.map((r) => r.name.toLowerCase()))
+  for (const r of data.repos) {
+    if (put.has(r.name)) continue
+    box.append(repoBlock(r, map.get(r.name.toLowerCase())))
+  }
+  // A heading that matches no repository — a name written differently, a paragraph the model
+  // decided to group under something of its own. It goes at the top rather than nowhere: losing
+  // a piece of the summary without telling anybody is the one failure that would not show.
+  for (const [name, nodes] of map) if (!mine.has(name)) intro.append(...nodes)
+  paintChips(data)
+}
+
+function say(message, kind = 'note') {
+  const intro = $('#intro')
+  intro.textContent = ''
+  const p = document.createElement('p')
+  p.className = kind
+  p.textContent = message
+  intro.append(p)
+}
+
+// ── Waiting ──────────────────────────────────────────────────────────────────
+function waiting(on) {
+  $('#waiting').hidden = !on
+  clearInterval(phrases)
+  if (!on) return
+  let i = 0
+  $('#phrase').textContent = PHRASES[0]
+  phrases = setInterval(() => {
+    i = (i + 1) % PHRASES.length
+    $('#phrase').textContent = PHRASES[i]
+  }, 2600)
+}
+
+function stop() {
+  clearInterval(poll)
+  poll = null
+  waiting(false)
+}
+
+function arrived(state) {
+  if (state.text) {
+    stop()
+    paint(state.text)
+    return true
+  }
+  if (state.error) {
+    stop()
+    say(state.error, 'note')
+    return true
+  }
+  return false
+}
+
+async function writeUp() {
+  waiting(true)
+  try {
+    if (arrived(await api(`/api/changelog/write?period=${period}`, { method: 'POST' }))) return
+  } catch (err) {
+    stop()
+    say(String(err.message || err), 'note')
+    return
+  }
+  poll = setInterval(async () => {
+    try {
+      arrived(await api(`/api/changelog/write?period=${period}`))
+    } catch {
+      /* the server is restarting: the next round will find it */
+    }
+  }, 1000)
+}
+
+// ── Loading ──────────────────────────────────────────────────────────────────
+/**
+ * Which of the four is lit. The page opens on none of them — it opens on the last day that had
+ * anything in it — but when that day turns out to be today or yesterday, lighting the button
+ * says so more clearly than the date does.
+ */
+function markPeriod(data) {
+  let lit = period
+  if (period === 'last' && data && data.to - data.from <= DAY) {
+    const today = new Date()
+    today.setHours(0, 0, 0, 0)
+    if (data.from === today.getTime()) lit = 'today'
+    else if (data.from === today.getTime() - DAY) lit = 'yesterday'
+  }
+  for (const b of document.querySelectorAll('#periods button')) {
+    b.setAttribute('aria-checked', String(b.dataset.period === lit))
+  }
+}
+
+async function load(p) {
+  period = p
+  stop()
+  markPeriod(null)
+
+  facts = await api(`/api/changelog?period=${p}`)
+  markPeriod(facts)
+  $('#when').textContent = whenLabel(facts)
+  $('#blank').hidden = true
+  paint()
+
+  if (!facts.repos.length) {
+    // Nothing happened. Say it in a line and stop there — no model, nothing to pad out.
+    $('#intro').textContent = ''
+    $('#chips').hidden = true
+    $('#blank').hidden = false
+    $('#blank').textContent =
+      p === 'last' ? 'Nothing in the last thirty days.' : `Nothing in ${whenLabel(facts).toLowerCase()}.`
+    return
+  }
+
+  if (!facts.writer.can) {
+    say(`${facts.writer.why} The facts are all here.`)
+    return
+  }
+  writeUp()
+}
+
+$('#periods').onclick = (e) => {
+  const b = e.target.closest('button[data-period]')
+  if (b && b.dataset.period !== period) load(b.dataset.period)
+}
+
+load('last')

package/web/index.html

@@ -13,6 +13,12 @@
     <button class="new" id="new-card" title="New card" aria-label="New card">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
     </button>
+    <!-- Next to the plus, because they are the two ends of the same thing: one starts a piece
+         of work, the other tells you how the ones before it went. A plain link, and a quiet
+         one — no dot, no badge. It is there when you want it. -->
+    <a class="log" href="/changelog.html" title="What you have been doing" aria-label="What you have been doing">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7h16M4 12h11M4 17h7"/></svg>
+    </a>
     <div class="filters" id="filters"></div>
 
     <!-- How the computer is doing. Always visible; clicking it switches off the weights on the cards. -->
@@ -46,11 +52,11 @@
     <div class="edges" id="edges" aria-hidden="true"><i class="l"></i><i class="r"></i><i class="t"></i><i class="b"></i></div>
 
     <div class="zoom" id="zoom">
-      <button type="button" id="z-out" title="Zoom out" aria-label="Zoom out">
+      <button type="button" id="z-out" title="Zoom out, ten per cent at a time" aria-label="Zoom out">
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M5 12h14"/></svg>
       </button>
       <button type="button" id="z-level" title="Back to 100%">100%</button>
-      <button type="button" id="z-in" title="Zoom in" aria-label="Zoom in">
+      <button type="button" id="z-in" title="Zoom in, ten per cent at a time" aria-label="Zoom in">
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
       </button>
       <button type="button" id="z-fit" title="Fit the whole board on screen" aria-label="Fit to screen">

package/web/recency.js

@@ -0,0 +1,86 @@
+// ── Which repositories are still warm ──────────────────────────────
+// With a dozen repositories open the board is wider than the screen, and the three or four you
+// are actually on today sit scattered among all the others. This decides which columns stay
+// open and which fold away into `Old`, and it is here rather than in board.js for the reason
+// docs/testing.md gives: what is worth proving comes out of the browser files into one of its
+// own. Nothing in here touches the DOM.
+
+export const DAY = 24 * 60 * 60 * 1000
+
+/**
+ * The statuses that hold a column on the board whatever its age: something is happening in there
+ * right now, or something is on screen waiting for you. Hiding the one that is waiting for you is
+ * the exact opposite of what the board is for.
+ *
+ * `IDLE` is deliberately not one of them, and it is the only debatable line in this file. It
+ * means "your turn", so it looks like it belongs — but it is also the resting state of every
+ * terminal you have left open, and on a real board nearly every live card is sitting in it. Let
+ * it hold a column and nothing ever folds: a session you finished with three weeks ago and never
+ * closed would keep its column at full width for ever. So `IDLE` gets the same treatment as
+ * everything else — recent, and it stays; a fortnight old, and it goes to `Old`, where it is one
+ * click away. Nothing is closed either way: the terminal is still open, and the card is still
+ * exactly where you left it.
+ */
+const DEMANDING = new Set(['ASK', 'PLANNED', 'WORKING', 'PLANNING'])
+
+/** The last time each repository was touched: the freshest of its cards. */
+export function lastTouched(cards) {
+  const map = new Map()
+  for (const c of cards) {
+    const t = Number(c.updated_at) || 0
+    if (t > (map.get(c.project_path) ?? 0)) map.set(c.project_path, t)
+  }
+  return map
+}
+
+/** The repositories with something going on in them right now. */
+export function busy(cards) {
+  const set = new Set()
+  for (const c of cards) if (DEMANDING.has(c.status)) set.add(c.project_path)
+  return set
+}
+
+/**
+ * The line between recent and old. It is **not** "now minus a day": it is a day back from the
+ * most recent thing on the whole board.
+ *
+ * That one difference is what makes it survive a weekend. Anchored to the clock, a Monday
+ * morning would find every column older than a day and fold the lot — you would open k0 to an
+ * empty board on the one morning you most need to see where you left off. Anchored to the work,
+ * Monday shows you Friday, and the moment you start something the line moves with you.
+ */
+export function cutoff(touched) {
+  let newest = 0
+  for (const t of touched.values()) if (t > newest) newest = t
+  return newest ? newest - DAY : 0
+}
+
+/**
+ * Which columns stay open, and which fold into `Old`. Four rules, in this order:
+ *
+ * 1. a repository with something going on in it is always open — see DEMANDING above, and note
+ *    this beats a fold you did by hand: something in there woke up and wants you;
+ * 2. one you opened by hand during this visit stays open;
+ * 3. one you put away by hand stays away;
+ * 4. otherwise, open if it was touched after the cutoff.
+ *
+ * `held` carries the fifth rule, which lives in the caller: within one visit the set of open
+ * columns only ever grows. A column does not fold out from under you while you are working —
+ * it folds the next time the page loads. It is the same reason the columns only reorder
+ * themselves in driving mode.
+ *
+ * The order of `paths` is kept: whoever asked has already sorted them.
+ */
+export function split({ paths, cards, folded = new Set(), held = new Set() }) {
+  const touched = lastTouched(cards)
+  const line = cutoff(touched)
+  const alive = busy(cards)
+  const open = []
+  const old = []
+  for (const p of paths) {
+    const stays =
+      alive.has(p) || held.has(p) || (!folded.has(p) && (touched.get(p) ?? 0) >= line)
+    ;(stays ? open : old).push(p)
+  }
+  return { open, old, touched, alive }
+}

package/web/view.js

@@ -9,7 +9,9 @@ const $ = (s) => document.querySelector(s)
 
 const EDGE = 96 // the sensitive band along each edge, in px
 const SPEED = 1200 // px per second right at the edge; inside the band it accelerates
-const STEPS = [0.3, 0.4, 0.5, 0.65, 0.8, 1, 1.25, 1.5, 2]
+// The ladder is even on purpose: every click of + or − is ten points, so where the next one lands
+// is something you can predict rather than discover.
+const STEPS = [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2]
 
 let vp, board, edges, level