@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/board/view/card.ts

@@ -0,0 +1,229 @@
+/**
+ * One card's face: the title, the facts a reader acts on, and the two marks that say
+ * where they have been.
+ *
+ * It is a fragment of the client bundle like `team.ts` and `dialog.ts`, and it reads the
+ * helpers the renderer publishes — the element builder, the chip, the age, the count's
+ * wording, and the reason rule spliced in from `lib/board/reason.ts` — so no rule about a
+ * card is stated twice.
+ *
+ * Two of the face's facts are longer than it can draw: the hints past its third path, the
+ * reason sentence, and the cards it is holding up. Each is on a hover title for the
+ * pointer, and each is named by the title button's `aria-describedby` for the keyboard,
+ * because `j`/`k` walks cards by focusing that button and never hovers anything.
+ *
+ * Every value arrives as `textContent`, never as markup: a title is model-written and a
+ * note is anything a person typed.
+ */
+
+export const BOARD_CARD_JS = String.raw`(function () {
+  "use strict";
+  var board = window.bfBoard || (window.bfBoard = {});
+  var el = board.el;
+  var chip = board.chip;
+  var ago = board.ago;
+  var plural = board.plural;
+  var reasonFor = board.reasonFor;
+  var reasonTone = board.reasonTone;
+
+  /** Path chips a lane card shows before it counts the rest. */
+  var PATH_CHIPS = 3;
+  /**
+   * The class that draws each tone, in the page kit's own words.
+   *
+   * A tone is a colour and the class is named after it, so the reason line for a missing
+   * contract, an approval nobody gave, and a spot-check nobody did are three kinds drawn in
+   * one tone — instead of three kinds sharing a class named after the first of them.
+   */
+  var TONE_CLASS = {
+    muted: N.cardReasonMuted,
+    dim: N.cardReasonDim,
+    warn: N.cardReasonWarn,
+    accent: N.cardReasonAccent,
+    danger: N.cardReasonDanger,
+    success: N.cardReasonSuccess,
+  };
+
+  /** "3h", "just now" — the age a stamp is drawn with, read against the reader's clock. */
+  function sentence(wording, age) {
+    return wording.replace("{age}", age === "now" ? "just now" : age + " ago");
+  }
+
+  /**
+   * An age the ticker can keep honest: the stamp it was painted from, and the sentence
+   * saying which fact it is, which the ticker fills from the same stamp a second later.
+   *
+   * The wording is the stamp's rather than the ticker's because a card now carries two
+   * ages — when it was written to, and when its last note was filed — and a ticker that
+   * assumed "updated" would relabel one of them within a minute.
+   */
+  function stamp(at, wording) {
+    var node = el("span", "", ago(at));
+    node.setAttribute("data-at", String(at));
+    node.setAttribute("data-at-title", wording);
+    node.title = sentence(wording, ago(at));
+    return node;
+  }
+
+  /** The one line under a card's meta: why it sits where it does. */
+  function reasonOf(card) {
+    // An order is the strongest reason a card is not being worked on, and the one a
+    // reader cannot see from the lane. The sentence is the snapshot's, so this line and
+    // the tool's refusal name one list.
+    if (card.waits !== undefined) return { text: "waits on " + card.waits, kind: "waiting" };
+    return reasonFor(card, ago);
+  }
+
+  /**
+   * A path hint, or the +N chip that points at the rest.
+   *
+   * The hints past the third are the ones a reader needs before opening anything, so they
+   * are not dropped: the chip carries them on its hover one per line, and the list holds
+   * them again as text a screen reader reads, which is the whole of what the chip counts.
+   */
+  function paths(card, limit) {
+    var list = el("ul", N.cardPaths);
+    list.id = "card-paths-" + card.id;
+    var shown = card.paths.slice(0, limit);
+    for (var i = 0; i < shown.length; i++) {
+      var item = el("li", "");
+      var hint = chip(shown[i]);
+      // A path longer than the card elides, and the whole of it is on the hover title: the
+      // card is often the only place its hints are read before opening the record.
+      hint.title = shown[i];
+      item.appendChild(hint);
+      list.appendChild(item);
+    }
+    if (card.paths.length > limit) {
+      var beyond = card.paths.slice(limit);
+      var rest = el("li", "");
+      var more = chip("+" + beyond.length);
+      more.title = beyond.join("\n");
+      // The count is a shape, not a word: what it counts is in the list below it, and a
+      // reader is owed the hints rather than "+3".
+      more.setAttribute("aria-hidden", "true");
+      rest.appendChild(more);
+      list.appendChild(rest);
+      for (var j = 0; j < beyond.length; j++) list.appendChild(el("li", "sr-only", beyond[j]));
+    }
+    return list;
+  }
+
+  /** Whether the reader is dragging a selection, which a click at the end of it would clear. */
+  function textSelected() {
+    var selection = window.getSelection ? window.getSelection() : null;
+    return selection !== null && String(selection) !== "";
+  }
+
+  /** One card in its lane. */
+  function cardNode(card) {
+    var item = el("li", N.card);
+    item.setAttribute("data-card", card.id);
+    item.setAttribute("data-lane", card.lane);
+    item.setAttribute("data-rev", String(card.rev));
+
+    var head = el("p", N.cardHead);
+    head.appendChild(el("span", N.cardId, "#" + card.id));
+    // The title is the page's only focusable thing inside a card, so Enter and the focus
+    // ring have one home; the card around it is the larger target for a pointer. A native
+    // button's Enter and Space arrive as a click that bubbles to the card, so the card is
+    // the one handler and the button needs none.
+    var title = el("button", N.cardTitle, card.title);
+    title.type = "button";
+    head.appendChild(title);
+    item.appendChild(head);
+    item.addEventListener("click", function () {
+      // A drag that ends on a card is a reader selecting a title to copy, not opening it.
+      if (textSelected()) return;
+      board.openCard(card.id);
+    });
+
+    /** The face's clipped text, by id: what the title button describes. */
+    var described = [];
+
+    var meta = el("p", N.cardMeta);
+    meta.appendChild(card.owner ? chip(card.owner.label, "accent") : el("span", "", "unassigned"));
+    // The order inside a lane is the priority, so an urgent card says so: an order
+    // nobody can see reads as an accident. The lane's colour stays the card's own.
+    if (card.priority !== "normal") meta.appendChild(chip(card.priority, "outline"));
+    // The stamp, so the clock can keep the age honest between frames: a board can be
+    // quiet for ten minutes while the page still says "live".
+    meta.appendChild(stamp(card.updatedAt, "updated {age}"));
+    // A card with ten notes and a card with none drew the same face, and the notes are the
+    // card's history: the count says how much is there. The last note's own age earns a place
+    // only when it reads differently from the stamp beside it — a note is itself a write, so
+    // usually the two are one moment and the meta line printed the same bare number twice.
+    if (card.notes.length > 0) {
+      var last = card.notes[card.notes.length - 1];
+      var notes = el("span", N.cardNotes, plural(card.notes.length, "note"));
+      if (ago(last.at) !== ago(card.updatedAt)) {
+        notes.appendChild(document.createTextNode(" \u00b7 "));
+        notes.appendChild(stamp(last.at, "last note {age} by " + last.by));
+      }
+      meta.appendChild(notes);
+    }
+    item.appendChild(meta);
+
+    if (card.paths.length > 0) {
+      item.appendChild(paths(card, PATH_CHIPS));
+      // Only a truncated list is described: the hints a reader can already see are read in
+      // order with the card, and the ones behind the chip have nowhere else to be read.
+      if (card.paths.length > PATH_CHIPS) described.push("card-paths-" + card.id);
+    }
+
+    var reason = reasonOf(card);
+    if (reason) {
+      // The tone is a lookup, not a suffix: a name assembled from a prefix is a name no
+      // test can compare with the stylesheet.
+      var line = el("p", N.cardReason + " " + TONE_CLASS[reasonTone(reason.kind)], reason.text);
+      line.id = "card-reason-" + card.id;
+      // It clamps on the card, so the full sentence is the tooltip.
+      line.title = reason.text;
+      item.appendChild(line);
+      described.push(line.id);
+    }
+
+    // The other side of a link, on the face: what leaving this card undone holds up. It was
+    // dialog-only, so a card three others were waiting on looked like any other card.
+    if (card.dependents !== undefined) {
+      var holds = el("p", N.cardHolds, "holds up " + card.dependents);
+      holds.id = "card-holds-" + card.id;
+      holds.title = "holds up " + card.dependents;
+      item.appendChild(holds);
+      described.push(holds.id);
+    }
+
+    // The reason and the hints are drawn below the title, and a keyboard reader never
+    // hovers: describing the button with them is what makes a clamped line readable from
+    // j/k and from a screen reader alike.
+    if (described.length > 0) title.setAttribute("aria-describedby", described.join(" "));
+
+    return item;
+  }
+
+  board.cardNode = cardNode;
+  board.sentence = sentence;
+
+  /** Set a mark on a card, or drop it, so one that lost it does not keep it. */
+  function marked(node, name, on) {
+    if (on) node.setAttribute(name, "true");
+    else node.removeAttribute(name);
+  }
+
+  /**
+   * Paint the card the reader is on and the cards they have already read.
+   *
+   * j/k walks the drawn cards and wraps, so walking a lane and coming back looked
+   * exactly like arriving for the first time. The two ids are the client's own — never
+   * sent anywhere — and this runs after every frame as well as on a focus and an open,
+   * because a lane is rebuilt whole when its cards move.
+   */
+  board.markCards = function () {
+    var nodes = document.querySelectorAll(".board-card");
+    for (var i = 0; i < nodes.length; i++) {
+      var id = nodes[i].getAttribute("data-card");
+      marked(nodes[i], "data-current", board.current !== undefined && String(board.current) === id);
+      marked(nodes[i], "data-visited", board.visited !== undefined && board.visited[id] === true);
+    }
+  };
+})();`;

package/extensions/board/view/client.ts

@@ -6,37 +6,55 @@
  * Served as one string, because a page that opens six requests before it can paint
  * is a page that looks broken for a moment. Nothing here is typed — no compiler sees
  * a template string — so the split is by job and the class-contract test reads the
- * result: `render.ts` paints, `team.ts` draws the round, `dialog.ts` opens one card,
- * `keys.ts` binds, and `live.ts` owns the tabs and the stream.
+ * result: `render.ts` paints a whole frame, `card.ts` draws one card's face, `team.ts`
+ * draws the round, `dialog.ts` opens one card, `keys.ts` binds, and `live.ts` owns the
+ * tabs and the stream.
  *
- * Load order is a dependency: `team` takes helpers from `render`, and `live` starts
- * last, after every `board.*` handler it wires exists.
+ * Load order is a dependency: `card` and `team` take helpers from `render`, and `live`
+ * starts last, after every `board.*` handler it wires exists.
  */
 
 import { MATCHES_QUERY_JS } from "../../../lib/board/card.ts";
-import { CLIENT_BASE_JS, CLIENT_RUNTIME_JS } from "../../../lib/web/index.ts";
-import { PLURAL_JS } from "../../../lib/board/round-text.ts";
+import { REASON_FOR_JS } from "../../../lib/board/reason.ts";
+import { DECISION_RANK_JS, DECISION_TONE_JS, REASON_TONE_JS } from "../../../lib/board/tone.ts";
+import { LANES } from "../../../lib/board/lanes.ts";
+import {
+	CLIENT_BASE_JS,
+	CLIENT_RUNTIME_JS,
+	dialogScript,
+	INLINE_MARKDOWN_JS,
+	keysDialogScript,
+	namesScript,
+	TAB_TITLE_JS,
+	THEME_TOGGLE_JS,
+} from "../../../lib/web/index.ts";
+import { PLURAL_JS, HISTORY_LINE_JS, HISTORY_OWNER_JS } from "../../../lib/board/round-text.ts";
+import { skippedText } from "../../../lib/board/skipped.ts";
 import { FORMAT_AGE_JS } from "../../../lib/format.ts";
-import { namesScript, TAB_TITLE_JS, THEME_TOGGLE_JS, dialogScript, keysDialogScript } from "../../../lib/web/index.ts";
+import { BOARD_CARD_JS } from "./card.ts";
 import { BOARD_CLASS } from "./names.ts";
-import { BOARD_DIALOG_JS } from "./dialog.ts";
+import { BOARD_EMPTY_JS } from "./empty.ts";
+import { dialogJs } from "./dialog.ts";
 import { BOARD_KEYS_JS } from "./keys.ts";
 import { BOARD_LIVE_JS } from "./live.ts";
 import { renderJs } from "./render.ts";
-import { BOARD_TEAM_JS } from "./team.ts";
+import { teamJs } from "./team.ts";
 
 /**
  * The whole client, in load order: paint, round, the card dialog, keys, wiring, start.
  *
- * Four rules cross the boundary as source — the count's wording, the tab title's
- * shape, what a `query` matches, and how an age reads: the browser has no import graph,
- * and a second copy of any of them is exactly what this bundle is not allowed to hold.
+ * Seven rules cross the boundary as source — the count's wording, the tab title's
+ * shape, what a `query` matches, why a card sits where it does, how an age reads, which
+ * owners a round may state once, and how that one line reads: the browser has no import
+ * graph, and a second copy of any of them is exactly what this bundle is not allowed to hold.
  */
 export const BOARD_CLIENT_JS = `${CLIENT_BASE_JS}
 ${namesScript(BOARD_CLASS)}
-${renderJs({ plural: PLURAL_JS, tabTitle: TAB_TITLE_JS, matches: MATCHES_QUERY_JS, age: FORMAT_AGE_JS, runtime: CLIENT_RUNTIME_JS })}
-${BOARD_TEAM_JS}
-${BOARD_DIALOG_JS}
+${renderJs({ plural: PLURAL_JS, tabTitle: TAB_TITLE_JS, matches: MATCHES_QUERY_JS, reason: REASON_FOR_JS, age: FORMAT_AGE_JS, lanes: String(LANES.length), skipped: String(skippedText), decisions: DECISION_RANK_JS, decisionTones: DECISION_TONE_JS, reasonTones: REASON_TONE_JS, runtime: CLIENT_RUNTIME_JS })}
+${teamJs({ historyOwner: HISTORY_OWNER_JS, historyLine: HISTORY_LINE_JS })}
+${BOARD_CARD_JS}
+${BOARD_EMPTY_JS}
+${dialogJs({ inlineMarkdown: INLINE_MARKDOWN_JS })}
 ${BOARD_KEYS_JS}
 ${BOARD_LIVE_JS}
 ${THEME_TOGGLE_JS}

package/extensions/board/view/dialog.ts

@@ -1,19 +1,177 @@
 /**
  * The card dialog: one card, whole, as a read view.
  *
- * Opening, closing, and forgetting which card is open is the whole of it. The page
- * cannot change a card, so this module has no request, no confirmation, no banner and
- * no footer actions — the dialogs it used to fill are gone from the document, and the
- * only way a card changes is a tool.
+ * Filling it, opening it, and forgetting which card is open is the whole of it. `render.ts`
+ * paints the board and hands each frame to {@link syncDialog}, which keeps an open record
+ * current and closes it when its card has left the board. The page cannot change a card, so
+ * this module has no request, no confirmation, no banner and no footer actions — the dialogs
+ * it used to fill are gone from the document, and the only way a card changes is a tool.
+ *
+ * A note is the one field that is not a `textContent` write: its prose is Markdown, read by
+ * the kit's one inline renderer (`lib/web/markdown.ts`), which appends text nodes and the
+ * four inline atoms and never parses markup. That renderer is spliced into this fragment
+ * rather than the bundle's top level — it is only ever read here, and inside this closure it
+ * resolves `el` to `board.el` instead of making the page's builder a `window` global.
+ * Everything else here is set as text, like the rest of the page.
  *
  * The one thing it must not do is leave a stale panel behind: a dialog the kit closed —
  * `Esc`, a backdrop click, its own close button — forgets `openId`, so the next frame
  * stops filling something nobody can see.
  */
 
-export const BOARD_DIALOG_JS = String.raw`(function () {
+/**
+ * The dialog fragment, with the inline Markdown renderer a note is read through spliced in.
+ *
+ * The source crosses the boundary as text, because `lib/web/markdown.ts` is JavaScript and a
+ * page's bundle has no import graph; `__INLINE_MARKDOWN__` is a rule a served script must
+ * never carry, and `pages.test` fails an unfilled one.
+ */
+export function dialogJs(rules: { inlineMarkdown: string }): string {
+	return dialogTemplate.replace("__INLINE_MARKDOWN__", rules.inlineMarkdown);
+}
+
+const dialogTemplate = String.raw`(function () {
   "use strict";
   var board = window.bfBoard || (window.bfBoard = {});
+  var el = board.el;
+  var chip = board.chip;
+  var ago = board.ago;
+
+__INLINE_MARKDOWN__
+
+  /** Fill the dialog's contents from a card, without opening or closing it. */
+  function fillDialog(card, view) {
+    document.getElementById("card-dialog-title").textContent = card.title;
+    document.getElementById("card-dialog-id").textContent = "#" + card.id;
+    // The lane is a status of its own, not a word inside a sentence: the same dot and
+    // label a lane head wears, so the dialog and the board speak the same vocabulary.
+    var state = document.getElementById("card-dialog-state");
+    var lane = board.laneOf(view, card.lane);
+    state.setAttribute("data-lane", card.lane);
+    state.textContent = lane === undefined ? card.lane : lane.label;
+
+    // One fact per row of the ladder, so a reader can pick out a value instead of
+    // hunting for it in a sentence. A row with nothing to say takes its label with it:
+    // an empty cell under a heading reads as a missing value, not as an absence.
+    var pair = function (name, shown) {
+      var dt = document.getElementById("card-dialog-" + name + "-label");
+      var dd = document.getElementById("card-dialog-" + name);
+      if (dt) dt.hidden = !shown;
+      if (dd) dd.hidden = !shown;
+      return dd;
+    };
+    var setRow = function (name, shown, value, full) {
+      var dd = pair(name, shown);
+      dd.textContent = shown ? value : "";
+      if (full === undefined) dd.removeAttribute("title");
+      else dd.setAttribute("title", full);
+    };
+
+    var owner = document.getElementById("card-dialog-owner");
+    owner.textContent = "";
+    owner.appendChild(card.owner ? chip(card.owner.label, "accent") : document.createTextNode("unassigned"));
+    pair("owner", true);
+
+    var priority = pair("priority", card.priority !== "normal");
+    priority.textContent = "";
+    if (card.priority !== "normal") priority.appendChild(chip(card.priority, "outline"));
+
+    setRow("updated", true, ago(card.updatedAt));
+    // How long the card has been in the lane it is in now, which updatedAt cannot say:
+    // a note filed against a blocked card moves that stamp without moving the card. Absent
+    // for a card written before the log existed, so the row takes its label with it.
+    setRow("lane", card.since !== undefined, card.lane + " \u00b7 " + ago(card.since));
+    setRow("by", true, card.by);
+    setRow("landed", card.landed !== undefined, card.landed ? card.landed.commit : "", card.landed ? card.landed.commit : undefined);
+
+    // The dialog and the card face say one thing, from one field: the ids it was linked
+    // to are the storage, and a reader is owed the lanes that make them a decision.
+    setRow("depends", card.waits !== undefined, card.waits || "", card.waits);
+    // The other side of the same link: what leaving this card undone is holding up, which
+    // is the one thing a card's own row cannot say.
+    setRow("dependents", card.dependents !== undefined, card.dependents || "", card.dependents);
+
+    // A long plan path elides on one line, and the whole of it is on the hover title and
+    // in the text, so it stays copyable: the reason to open a card is often its plan.
+    setRow("plan", Boolean(card.planPath), card.planPath || "", card.planPath || undefined);
+
+    // The contract is three lines and a signature, and each is its own rung: a reader
+    // comparing what was promised with what was done reads them one at a time, and the
+    // approval's age is the fact that says whether anybody has looked.
+    var contract = card.contract;
+    setRow("goal", Boolean(contract), contract ? contract.goal : "", contract ? contract.goal : undefined);
+    setRow("acceptance", Boolean(contract), contract ? contract.acceptance : "", contract ? contract.acceptance : undefined);
+    setRow("scope-out", Boolean(contract), contract ? contract.scopeOut : "", contract ? contract.scopeOut : undefined);
+    var approved = contract && contract.approved;
+    setRow("approved", Boolean(approved), approved ? approved.by + " \u00b7 " + ago(approved.at) : "");
+    setRow("reviewed", card.review !== undefined, card.review ? card.review.by + " \u00b7 " + ago(card.review.at) : "");
+
+    pair("paths", card.paths.length > 0);
+    var pathList = document.getElementById("card-dialog-path-list");
+    pathList.textContent = "";
+    for (var i = 0; i < card.paths.length; i++) {
+      var item = el("li", "");
+      var hint = chip(card.paths[i]);
+      hint.className += " " + N.dialogPath;
+      hint.title = card.paths[i];
+      item.appendChild(hint);
+      pathList.appendChild(item);
+    }
+
+    var notes = document.getElementById("card-dialog-notes");
+    notes.textContent = "";
+    for (var j = 0; j < card.notes.length; j++) {
+      var note = card.notes[j];
+      // The prose is the record and reads at body size; who wrote it and when is its
+      // footnote, so it follows the sentence instead of standing over it.
+      var row = el("li", N.dialogNote);
+      // A note is Markdown, read by the kit's one inline renderer: a backtick, a bold word,
+      // or an ordinary URL reads as what it says, a target the policy refuses stays text,
+      // and nothing a person typed can become markup.
+      var text = el("p", N.dialogNoteText);
+      renderInline(text, note.text);
+      row.appendChild(text);
+      var foot = el("p", N.dialogNoteFoot);
+      foot.appendChild(el("span", N.dialogNoteBy, note.by));
+      foot.appendChild(el("span", N.dialogNoteAt, ago(note.at)));
+      row.appendChild(foot);
+      notes.appendChild(row);
+    }
+    var count = document.getElementById("card-dialog-note-count");
+    if (count) count.textContent = card.notes.length === 0 ? " \u00b7 none" : " \u00b7 " + card.notes.length;
+    var earlier = document.getElementById("card-dialog-earlier");
+    earlier.hidden = card.notesDropped === 0;
+    earlier.textContent = card.notesDropped === 0 ? "" : card.notesDropped + " earlier notes dropped";
+
+    // A modal whose title changes is not announced, so walking with j/k says where it
+    // landed: the position is counted over the cards as they are drawn, not as stored, so
+    // a filter or a folded lane cannot make the number disagree with the screen.
+    var where = document.getElementById("card-dialog-where");
+    if (where) {
+      var drawn = board.drawnCards();
+      var at = 0;
+      for (var k = 0; k < drawn.length; k++) {
+        if (drawn[k].getAttribute("data-card") === String(card.id)) at = k + 1;
+      }
+      // Opened from the Team tab there is no drawn board to count along, so the line
+      // names the card instead of claiming a position it cannot know.
+      where.textContent = drawn.length === 0 ? card.title : "card " + at + " of " + drawn.length + ": " + card.title;
+    }
+  }
+
+  /**
+   * Keep an open record current: fill it from the frame, or close it when its card left.
+   *
+   * The frame owns this rather than the open handler: a peer's note moves the card's
+   * revision, and a panel left showing the record it was opened with is a page that lies
+   * for as long as the tab stays open.
+   */
+  board.syncDialog = function (view) {
+    if (board.openId === undefined) return;
+    var card = board.findCard(view, board.openId);
+    if (card) fillDialog(card, view);
+    else board.closeCard();
+  };
 
   /** Fill and open the card dialog. */
   board.openCard = function (id) {
@@ -22,7 +180,12 @@ export const BOARD_DIALOG_JS = String.raw`(function () {
     var card = board.findCard(view, id);
     if (!card || !window.bfCard) return;
     board.openId = id;
-    board.fillDialog(card, view);
+    // A card a reader opened is one they have read, and it is where they are: the board
+    // paints both marks from these two fields, so closing the record leaves the place.
+    board.visited[id] = true;
+    board.current = id;
+    fillDialog(card, view);
+    board.markCards();
     window.bfCard.open();
   };
 

package/extensions/board/view/empty.ts

@@ -0,0 +1,47 @@
+/**
+ * The board's two empty states: no cards at all, and a filter that matches none.
+ *
+ * Both reuse the one block the document already carries (`#board-no-cards`), because the
+ * difference between them is a sentence and one button, not a second layout. They live in
+ * their own fragment so the renderer stays the painter of cards and lanes: an empty board is
+ * a statement about the whole board, and it is the one part of the page that says a thing
+ * instead of drawing one.
+ *
+ * Same rule as the rest of the client: every value arrives as `textContent`, and the query
+ * the reader typed is one of them.
+ */
+
+export const BOARD_EMPTY_JS = String.raw`(function () {
+  "use strict";
+  var board = window.bfBoard || (window.bfBoard = {});
+
+  /**
+   * What the board says when there is nothing to read.
+   *
+   * Two different emptinesses. No cards at all is the board's own state, and it teaches the
+   * verb that fills it. A filter that matches none of them is the reader's own query: the
+   * lanes go, because five trays saying "no match" read as a board with no work, and the way
+   * back is one button rather than a key a reader has to remember.
+   */
+  board.renderEmpty = function (view, query, shownTotal) {
+    var block = document.getElementById("board-no-cards");
+    if (!block) return;
+    var lanes = document.getElementById("board-lanes");
+    var noCards = view.total === 0;
+    var noMatch = !noCards && query !== "" && shownTotal === 0;
+    block.hidden = !noCards && !noMatch;
+    if (lanes) lanes.hidden = noCards || noMatch;
+    var title = document.getElementById("board-no-cards-title");
+    var sub = document.getElementById("board-no-cards-sub");
+    var hint = document.getElementById("board-no-cards-hint");
+    var clear = document.getElementById("board-no-match-clear");
+    if (title) title.textContent = noMatch ? "No card matches \u201c" + query + "\u201d" : "No cards yet";
+    if (sub) {
+      sub.textContent = noMatch
+        ? "The filter reads a title, its owner, a path, a plan, and the notes."
+        : "One card per feature: what it delivers, who holds it, and where to start.";
+    }
+    if (hint) hint.hidden = noMatch;
+    if (clear) clear.hidden = !noMatch;
+  };
+})();`;

package/extensions/board/view/keys.ts

@@ -65,7 +65,12 @@ export const BOARD_KEYS_JS = String.raw`(function () {
     if (walk(delta)) return;
     var drawn = cards();
     if (drawn.length === 0) return;
-    var at = drawn.indexOf(document.activeElement);
+    // Focus sits on a card's title button, not on the card, so the step reads the card that
+    // holds it: an index of -1 for every card made j from one land on the first card in the
+    // lane instead of the next — which is the place a reader lost when they came back.
+    var here = document.activeElement;
+    var card = here && here.closest ? here.closest(".board-card") : null;
+    var at = card === null ? -1 : drawn.indexOf(card);
     var next = at < 0 ? (delta > 0 ? 0 : drawn.length - 1) : (at + delta + drawn.length) % drawn.length;
     var button = drawn[next].querySelector(".board-card__title");
     if (button) button.focus();
@@ -75,7 +80,11 @@ export const BOARD_KEYS_JS = String.raw`(function () {
     doc.addEventListener("keydown", function (event) {
       if (event.metaKey || event.ctrlKey || event.altKey) return;
       var target = event.target;
-      if (event.key === "?" && !typing(target)) {
+      // A dialog is modal for the pointer and for the keyboard alike: "/", "t", and "?"
+      // reach the page behind the scrim from nowhere else, so a modal keeps them and the
+      // keys that move inside it -- j, k, Enter, Esc -- are the ones still read.
+      var modal = (board.dialogOpen && board.dialogOpen()) || (board.keysOpen && board.keysOpen());
+      if (event.key === "?" && !typing(target) && !modal) {
         event.preventDefault();
         board.openKeys();
         return;
@@ -108,6 +117,7 @@ export const BOARD_KEYS_JS = String.raw`(function () {
         return;
       }
       if (event.key === "/") {
+        if (modal) return;
         event.preventDefault();
         board.focusFilter();
       } else if (event.key === "j") {
@@ -117,6 +127,7 @@ export const BOARD_KEYS_JS = String.raw`(function () {
         event.preventDefault();
         step(-1);
       } else if (event.key === "t") {
+        if (modal) return;
         event.preventDefault();
         board.showView(board.viewName() === "team" ? "board" : "team");
       }