@anchrd/intel-ui 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-ui",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -33,7 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/intel-contract": "^0.22.0",
+    "@anchrd/intel-contract": "^0.23.0",
     "@blocknote/core": "^0.52.1",
     "@blocknote/react": "^0.52.1",
     "@blocknote/shadcn": "^0.52.1",

package/src/app/app-tree/app-tree.tsx

@@ -47,12 +47,17 @@ import { selectedFrom } from "@/router/selection-search.ts";
 /**
  * What the plus can MAKE — derived from `NodeKind`, never written out again (#395).
  *
- * ⚠️ `attachment` is excluded because an attachment is uploaded rather than created, and `flow` is
- * added because a flow shares the tree without being a node (ADR-0004 §1). Both are decisions about
- * this menu; the LIST of node kinds is not, and a copy of it here goes stale in the direction that
- * already bit us — the parked kinds stood in such a union long after nothing could make one.
+ * ⚠️ Three decisions about this MENU, each excluded by name: `attachment` because an attachment is
+ * uploaded rather than created, `task` because a task lives on a board and the API refuses one
+ * filed under a folder, and `flow` added because a flow shares the tree without being a node
+ * (ADR-0004 §1). The LIST of node kinds is not a decision here, and a copy of it would go stale in
+ * the direction that already bit us — the parked kinds stood in such a union long after nothing
+ * could make one.
+ *
+ * ⚠️ `task` was NOT excluded until #661, and the wide form carried it in silence from #647 onward:
+ * a menu entry that could only ever answer with a refusal. It is a type error now.
  */
-type NewKind = Exclude<NodeKind, "attachment"> | "flow";
+type NewKind = Exclude<NodeKind, "attachment" | "task"> | "flow";
 type Creating = { parentId: string | null; kind: NewKind };
 
 // Attachments are inlined as base64, so the browser holds the file twice while it uploads.
@@ -852,7 +857,7 @@ function AddMenu(props: AddMenuProps) {
   const { label, onSelect } = props;
   const variant = props.variant ?? "icon";
   const i18n = useI18n();
-  // ⚠️ Three groups, and the separators are the answer to what the plus promises: four kinds are
+  // ⚠️ Three groups, and the separators are the answer to what the plus promises: five kinds are
   // made here, an upload brings one thing in from the machine, an import brings a whole subtree
   // (#346). The icons come from the one kind-icon map rather than being named again — a second
   // `Folder` beside it is how the tree row and this menu start disagreeing.
@@ -860,6 +865,10 @@ function AddMenu(props: AddMenuProps) {
     { kind: "folder", labelKey: "tree.new.folder", Icon: kindIcons.folder },
     { kind: "document", labelKey: "tree.new.document", Icon: kindIcons.document },
     { kind: "table", labelKey: "tree.new.table", Icon: kindIcons.table },
+    // ⚠️ A board needs nothing else to be usable: an unconfigured one answers with three default
+    // columns (`DEFAULT_COLUMNS`, `packages/api/src/boards/boards.ts`), so unlike a table it has no
+    // second call here. A board with no columns would be a screen with nowhere to put a card.
+    { kind: "board", labelKey: "tree.new.board", Icon: kindIcons.board },
     { kind: "flow", labelKey: "tree.new.flow", Icon: kindIcons.flow },
   ];
   return (

package/src/board/board-data/board-data.ts

@@ -0,0 +1,169 @@
+import type {
+  BoardColumn,
+  BoardTask,
+  BoardTaskCreateInput,
+  BoardTaskFilter,
+  BoardTaskUpdateInput,
+  BoardView,
+} from "@anchrd/intel-contract/board";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import type { BoardHandle, ColumnWithCards } from "./board-data.types.ts";
+
+export const boardKey = (boardId: string) => ["board", boardId] as const;
+
+/**
+ * Whether this filter narrows anything at all.
+ *
+ * ⚠️ **`Object.keys(...).length` is the wrong question**, because clearing a control writes the key
+ * back with `undefined` rather than removing it — `{ status: undefined }` has one key and filters
+ * nothing. Read that as "filtering" and the table says "nothing matches this filter" about a board
+ * nobody is filtering, and a write pays a refetch it does not owe.
+ */
+export function isFiltering(filter: Partial<BoardTaskFilter>): boolean {
+  return Object.values(filter).some((value) => value !== undefined);
+}
+
+/**
+ * Where a card lands when it is dropped between two neighbours.
+ *
+ * ⚠️ **The midpoint, and that is the whole reason `position` is a float.** With integers a drop
+ * would renumber every row below it, two people dropping at once would fight over rows neither
+ * touched, and a retry would move the card again. Here one card is written and nothing else is.
+ *
+ * The two edges are the cases a midpoint cannot express: dropped at the top there is nothing above,
+ * dropped at the bottom nothing below. `1` away from the neighbour keeps room for the next drop on
+ * that side without ever needing to renumber.
+ */
+export function positionBetween(above: number | undefined, below: number | undefined): number {
+  if (above === undefined && below === undefined) return 1;
+  if (above === undefined) return (below ?? 1) - 1;
+  if (below === undefined) return above + 1;
+  return (above + below) / 2;
+}
+
+/**
+ * The board as the views draw it: columns in their configured order, each carrying its own cards
+ * sorted by position.
+ *
+ * ⚠️ **A card whose status names no column is kept, in a column of its own at the end.** Dropping
+ * it would be the quiet failure: somebody renames a column, every card in it stops being drawn, and
+ * the screen looks like the cards were deleted. A visible stray column is ugly and true.
+ */
+export function columnsWithCards(view: BoardView): ColumnWithCards[] {
+  const byStatus = new Map<string, BoardTask[]>();
+  for (const task of view.tasks) {
+    const cards = byStatus.get(task.status);
+    if (cards === undefined) byStatus.set(task.status, [task]);
+    else cards.push(task);
+  }
+  const sorted = (cards: BoardTask[]) => [...cards].sort((a, b) => a.position - b.position);
+  const known: ColumnWithCards[] = view.columns.map((column) => ({
+    column,
+    cards: sorted(byStatus.get(column.id) ?? []),
+  }));
+  const orphaned = [...byStatus.keys()].filter(
+    (status) => !view.columns.some((column) => column.id === status),
+  );
+  const strays: ColumnWithCards[] = orphaned.map((status) => ({
+    column: { id: status, title: status, terminal: false } satisfies BoardColumn,
+    cards: sorted(byStatus.get(status) ?? []),
+    unknown: true,
+  }));
+  return [...known, ...strays];
+}
+
+/**
+ * Everything a board view needs, from one query and three mutations.
+ *
+ * ⚠️ **Every write answers with the whole board, and the answer is written straight into the
+ * cache.** The alternative — patch the cached board from the row that changed — is a second place
+ * that decides what a column contains, and the two drift the first time the server does something
+ * the client did not predict. A move, for instance, also gives the card a new position when none
+ * was sent.
+ */
+export function useBoard(boardId: string, filter: Partial<BoardTaskFilter> = {}): BoardHandle {
+  const { data } = useIntelRouterContext();
+  const client = useQueryClient();
+  const key = boardKey(boardId);
+
+  /**
+   * ⚠️ **The filter belongs in the key, and `includeArchived` is only its most obvious member.**
+   * Without it every filtered view of a board shares one cache entry: switching a filter shows the
+   * previous selection's cards until the fetch returns, which reads as cards appearing and
+   * vanishing on their own.
+   *
+   * ⚠️ **The filter travels; it is not applied here.** A view that fetched everything and hid rows
+   * in the browser looks identical and is a different thing — `board-table.unit.tsx` therefore
+   * asserts the ARGUMENT of the second request, not just that a request happened.
+   */
+  const scoped = [...key, filter] as const;
+  const unfiltered = [...key, {}] as const;
+  const query = useQuery({
+    queryKey: scoped,
+    // `includeArchived` is spelled out because the provider takes the contract's OUTPUT type,
+    // where the default has already been applied and the field is therefore required.
+    queryFn: async () => await data.getBoard({ includeArchived: false, boardId, ...filter }),
+  });
+
+  /**
+   * Where a write's answer goes.
+   *
+   * ⚠️ **A write always answers with the board UNFILTERED, whatever this handle is filtered by.**
+   * All three write paths ask for the view with a fixed `{ boardId, includeArchived: false }`
+   * (`packages/api/src/boards/boards.ts`), and none of the three inputs even carries a filter field.
+   * So the answer belongs in the unfiltered entry — and settling it into the filtered one would put
+   * every card into a view that asked for some of them, with no error, because the write succeeded.
+   *
+   * ⚠️ **The filtered entry is therefore invalidated rather than patched.** This answer cannot say
+   * what the filter now matches: a card that was moved out of it has to disappear, one moved into it
+   * has to appear, and only the server knows which. One extra request per write under a filter, and
+   * an unfiltered board — the ordinary case — still pays none.
+   */
+  const settle = (view: BoardView) => {
+    client.setQueryData(unfiltered, view);
+    if (isFiltering(filter)) void client.invalidateQueries({ queryKey: scoped });
+  };
+
+  const createTask = useMutation({
+    mutationFn: async (input: Omit<BoardTaskCreateInput, "boardId">) =>
+      await data.createBoardTask({ ...input, boardId }),
+    onSuccess: settle,
+  });
+  const updateTask = useMutation({
+    mutationFn: async (input: BoardTaskUpdateInput) => await data.updateBoardTask(boardId, input),
+    onSuccess: settle,
+  });
+  const setColumns = useMutation({
+    mutationFn: async (input: { columns: BoardColumn[]; idempotencyKey: string }) =>
+      await data.updateBoard({ boardId, ...input }),
+    onSuccess: settle,
+  });
+
+  const columns = useMemo(
+    () => (query.data === undefined ? [] : columnsWithCards(query.data)),
+    [query.data],
+  );
+
+  return {
+    boardId,
+    title: query.data?.title ?? "",
+    columns,
+    isPending: query.isPending,
+    isError: query.isError,
+    // ⚠️ One flag for all three writes. A screen that disabled only the button it just pressed
+    // would let a second drag start while the first is in flight, and the second answer would
+    // overwrite the first — with no error, because both succeeded.
+    isWriting: createTask.isPending || updateTask.isPending || setColumns.isPending,
+    createTask: async (input) => {
+      await createTask.mutateAsync(input);
+    },
+    updateTask: async (input) => {
+      await updateTask.mutateAsync(input);
+    },
+    setColumns: async (input) => {
+      await setColumns.mutateAsync(input);
+    },
+  };
+}

package/src/board/board-data/board-data.types.ts

@@ -0,0 +1,29 @@
+import type {
+  BoardColumn,
+  BoardTask,
+  BoardTaskCreateInput,
+  BoardTaskUpdateInput,
+} from "@anchrd/intel-contract/board";
+
+// One column and the cards in it, in the order they are drawn.
+export interface ColumnWithCards {
+  column: BoardColumn;
+  cards: BoardTask[];
+  // ⚠️ Set only on a column the board does not configure — cards whose status names nothing. It is
+  // drawn differently rather than hidden: a card nobody can see is a card somebody will look for.
+  unknown?: boolean;
+}
+
+export interface BoardHandle {
+  boardId: string;
+  title: string;
+  columns: ColumnWithCards[];
+  isPending: boolean;
+  isError: boolean;
+  isWriting: boolean;
+  // `boardId` is supplied by the handle, so a view cannot file a card on the wrong board by
+  // forgetting a field.
+  createTask(input: Omit<BoardTaskCreateInput, "boardId">): Promise<void>;
+  updateTask(input: BoardTaskUpdateInput): Promise<void>;
+  setColumns(input: { columns: BoardColumn[]; idempotencyKey: string }): Promise<void>;
+}

package/src/board/board-kanban/board-kanban.ts

@@ -0,0 +1,108 @@
+import type { BoardTask } from "@anchrd/intel-contract/board";
+import { positionBetween } from "@/board/board-data/board-data.ts";
+import type { ColumnWithCards } from "@/board/board-data/board-data.types.ts";
+
+/**
+ * Where a dragged card was let go.
+ *
+ * ⚠️ **`index` counts into the column AS RENDERED — including the dragged card itself when it
+ * started there.** That is what a drop handler can actually measure: the card stays in the list
+ * while the gesture runs, and the browser reports the gap it hovers over. Reading it as an index
+ * into the list *without* the card is off by one for every downward move inside a column, and the
+ * symptom is a card landing one place short of where it was let go — which looks like a sloppy
+ * animation rather than a bug.
+ */
+export interface Drop {
+  status: string;
+  index: number;
+}
+
+/**
+ * What a drop means as a write — the whole of the drag logic, kept out of the component so it can be
+ * proven without a browser.
+ *
+ * ⚠️ **`null` means "changed nothing", and the caller must not write.** A card let go where it
+ * already sits is the most common drop there is: somebody picks one up, thinks again, and puts it
+ * back. Writing anyway costs a round trip, a re-render, and — because the position would be
+ * recomputed — a card that visibly jumps for no reason.
+ *
+ * ⚠️ **The card itself is removed from the neighbour list first.** Without that, dragging a card
+ * one place down within its own column measures against its OWN old position: the midpoint lands
+ * between the card and its neighbour, which is where it already was. It would look like the drag
+ * did nothing, which is the same symptom as a broken drop handler and reads as one.
+ */
+export function dropToWrite(
+  card: BoardTask,
+  columns: ColumnWithCards[],
+  drop: Drop,
+): { status: string; position: number } | null {
+  const target = columns.find((entry) => entry.column.id === drop.status);
+  if (target === undefined) return null;
+
+  const others = target.cards.filter((entry) => entry.id !== card.id);
+  const wasAt = target.cards.findIndex((entry) => entry.id === card.id);
+
+  // ⚠️ The card is counted out of its own gap. Dropped BELOW where it started, every card it passed
+  // has shifted up by one, so the index into the remaining cards is one lower. Above its start
+  // nothing moved and the index carries over unchanged.
+  const wanted = wasAt >= 0 && drop.index > wasAt ? drop.index - 1 : drop.index;
+  const index = Math.max(0, Math.min(wanted, others.length));
+
+  // Let go in its own gap: nothing moved, and writing anyway would recompute the position and make
+  // the card jump for no reason.
+  if (wasAt >= 0 && index === wasAt) return null;
+
+  return {
+    status: drop.status,
+    position: positionBetween(others[index - 1]?.position, others[index]?.position),
+  };
+}
+
+/**
+ * The card a keyboard move should land on, given the one it starts from.
+ *
+ * ⚠️ Keyboard reachability is part of the first version here, not polish — dragging is a mouse
+ * gesture and a board that can only be operated by dragging is a board half the people cannot use.
+ * Left and right move between columns and keep the row; up and down move within one.
+ */
+export function neighbourDrop(
+  card: BoardTask,
+  columns: ColumnWithCards[],
+  direction: "left" | "right" | "up" | "down",
+): Drop | null {
+  const columnIndex = columns.findIndex((entry) => entry.column.id === card.status);
+  const column = columns[columnIndex];
+  if (column === undefined) return null;
+  const row = column.cards.findIndex((entry) => entry.id === card.id);
+
+  if (direction === "left" || direction === "right") {
+    const next = columns[columnIndex + (direction === "left" ? -1 : 1)];
+    // ⚠️ No wrapping. A card that jumps from the last column to the first because somebody pressed
+    // the arrow once too often is a move nobody asked for, and the one they did ask for is lost.
+    if (next === undefined) return null;
+    return { status: next.column.id, index: Math.min(row, next.cards.length) };
+  }
+  const landing = row + (direction === "up" ? -1 : 1);
+  if (landing < 0 || landing >= column.cards.length) return null;
+  // ⚠️ Down needs one more than the row it lands on. `index` is a GAP in the list AS RENDERED, and
+  // moving down one place means ending up BEHIND the neighbour — that is the gap after it. Naming
+  // the neighbour's own gap names the gap the card already occupies, and `dropToWrite` then
+  // correctly answers "nothing changed" and swallows the move. Upwards the two coincide, which is
+  // why this reads as an asymmetry and is not one.
+  return { status: column.column.id, index: direction === "down" ? landing + 1 : landing };
+}
+
+/**
+ * Which gap a drop ON a card means — the half of the card the pointer is over.
+ *
+ * ⚠️ Without this the column is the only drop target there is, and every drop then means "append":
+ * `dropToWrite` computes a correct midpoint for any gap, but the component never asks it for one
+ * other than the end. On screen the card follows the pointer to the middle of the column and then
+ * jumps to the bottom, which reads as a broken drag rather than as a missing feature.
+ *
+ * The geometry is passed in rather than read here so the decision — upper half means before the
+ * card, lower half means after it — can be proven without a layout engine.
+ */
+export function dropIndexOnCard(row: number, pointerY: number, box: DOMRect): number {
+  return pointerY < box.top + box.height / 2 ? row : row + 1;
+}

package/src/board/board-kanban/board-kanban.tsx

@@ -0,0 +1,295 @@
+import type { BoardTask } from "@anchrd/intel-contract/board";
+import { useState } from "react";
+import type { BoardHandle, ColumnWithCards } from "@/board/board-data/board-data.types.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { type Drop, dropIndexOnCard, dropToWrite, neighbourDrop } from "./board-kanban.ts";
+
+// The id of the card being dragged. `getData` is the payload the browser carries for us; nothing
+// else about the gesture needs to survive a re-render, so there is no state here.
+const CARRIED = "text/plain";
+
+function Card({
+  card,
+  column,
+  row,
+  board,
+  onMove,
+}: {
+  card: BoardTask;
+  column: ColumnWithCards;
+  row: number;
+  board: BoardHandle;
+  onMove(card: BoardTask, drop: Drop): void;
+}) {
+  const i18n = useI18n();
+  const locked = board.isWriting;
+  return (
+    <li
+      onDragOver={(event) => {
+        if (locked) return;
+        event.preventDefault();
+        event.dataTransfer.dropEffect = "move";
+      }}
+      onDrop={(event) => {
+        if (locked) return;
+        event.preventDefault();
+        // ⚠️ The column below is a drop target too, and it means "append". Letting this event reach
+        // it would overwrite the gap just measured with the end of the column — the bug this
+        // handler exists to fix, restored by the bubbling.
+        event.stopPropagation();
+        const dragged = cardById(board, event.dataTransfer.getData(CARRIED));
+        if (dragged === undefined) return;
+        const index = dropIndexOnCard(
+          row,
+          event.clientY,
+          event.currentTarget.getBoundingClientRect(),
+        );
+        onMove(dragged, { status: column.column.id, index });
+      }}
+    >
+      {/* ⚠️ A real button, not an `<li role="button">`. The role override needs two lint
+          suppressions and still leaves a listitem that only *claims* to be operable; a button is
+          focusable, is announced as operable, and — the part that made the override look necessary
+          — may perfectly well be a drag source. */}
+      <button
+        type="button"
+        draggable={!locked}
+        aria-label={i18n.t("board.cardLabel", { title: card.title, column: column.column.title })}
+        className="w-full cursor-grab rounded-md border border-border bg-card p-2 text-left text-sm shadow-xs focus-visible:outline-2 focus-visible:outline-ring"
+        onDragStart={(event) => {
+          event.dataTransfer.setData(CARRIED, card.id);
+          event.dataTransfer.effectAllowed = "move";
+        }}
+        onKeyDown={(event) => {
+          // ⚠️ Not while a write is in flight. Two moves in quick succession both read the same
+          // not-yet-updated `board.columns`, compute a position independently and both write — the
+          // second answer overwrites the first, with no error, because both succeeded. That is the
+          // race `isWriting` was introduced for in #651, and marking the board busy without
+          // refusing the input leaves it exactly as open as before.
+          if (locked) return;
+          // ⚠️ Only with a modifier. The arrows alone belong to whatever the reader is used to —
+          // scrolling the column, moving focus — and taking them would make a board that cannot be
+          // read without moving its cards.
+          if (!event.altKey) return;
+          const direction =
+            event.key === "ArrowLeft"
+              ? "left"
+              : event.key === "ArrowRight"
+                ? "right"
+                : event.key === "ArrowUp"
+                  ? "up"
+                  : event.key === "ArrowDown"
+                    ? "down"
+                    : null;
+          if (direction === null) return;
+          const drop = neighbourDrop(card, board.columns, direction);
+          if (drop === null) return;
+          event.preventDefault();
+          onMove(card, drop);
+        }}
+      >
+        <span className="block">{card.title}</span>
+        {card.dueDate === null ? null : (
+          <span className="mt-1 block text-xs text-muted-foreground">
+            {card.dueDate.slice(0, 10)}
+          </span>
+        )}
+      </button>
+    </li>
+  );
+}
+
+function cardById(board: BoardHandle, id: string): BoardTask | undefined {
+  return board.columns.flatMap((entry) => entry.cards).find((card) => card.id === id);
+}
+
+/**
+ * One column, with the way to add a card to it.
+ *
+ * ⚠️ **`group/column` sits on the section, and that is only safe because columns do not nest.**
+ * A named group compiles to a DESCENDANT selector: put it on something that also holds another
+ * column and hovering one card lights the add row of every column below it — the tree paid for that
+ * with #252, and `packages/ui/CLAUDE.md` carries the rule. Here the sections are siblings, so a
+ * card in one is never a descendant of another. `board-kanban.unit.tsx` asserts exactly that,
+ * structurally, because jsdom computes no hover.
+ */
+function Column({
+  entry,
+  board,
+  onMove,
+}: {
+  entry: ColumnWithCards;
+  board: BoardHandle;
+  onMove(card: BoardTask, drop: Drop): void;
+}) {
+  const i18n = useI18n();
+  const [composing, setComposing] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [failed, setFailed] = useState(false);
+  // ⚠️ A column the board does not configure takes no new card: the server refuses a status that
+  // names no column (`unknown_column`), so offering the control would promise a refusal.
+  const addable = entry.unknown !== true;
+
+  // ⚠️ One way out, and it clears the REFUSAL too. Left standing, the message outlives the attempt
+  // it belongs to: somebody types, is refused, presses Escape — and the column keeps a sentence
+  // about a card nobody is trying to create any more, until the next attempt happens to clear it.
+  const close = () => {
+    setComposing(false);
+    setDraft("");
+    setFailed(false);
+  };
+
+  const create = () => {
+    const title = draft.trim();
+    if (title.length === 0 || board.isWriting) return;
+    setFailed(false);
+    board
+      .createTask({
+        title,
+        status: entry.column.id,
+        // ⚠️ Spelled out because the handle takes the contract's OUTPUT type, where every default
+        // has already been applied and the fields are therefore required. The server decides the
+        // position — the end of this column — and a retry does not move the card again (#648).
+        assigneeId: null,
+        labels: [],
+        startDate: null,
+        dueDate: null,
+        dependsOn: null,
+        idempotencyKey: crypto.randomUUID(),
+      })
+      .then(close)
+      // ⚠️ Reported IN the column. A refusal shown only in a global banner leaves the reader
+      // looking at the column they typed into, which says nothing happened.
+      .catch(() => setFailed(true));
+  };
+
+  return (
+    <section
+      aria-label={entry.column.title}
+      className="group/column flex w-64 shrink-0 flex-col gap-2"
+      onDragOver={(event) => {
+        if (board.isWriting) return;
+        event.preventDefault();
+        event.dataTransfer.dropEffect = "move";
+      }}
+      onDrop={(event) => {
+        if (board.isWriting) return;
+        event.preventDefault();
+        const dragged = cardById(board, event.dataTransfer.getData(CARRIED));
+        // ⚠️ Let go on the column itself rather than on one of its cards: the end of it. A card
+        // drop stops the event before it arrives here, so this is the free area below the last
+        // card — and there, "append" is what the gesture means.
+        if (dragged !== undefined) {
+          onMove(dragged, { status: entry.column.id, index: entry.cards.length });
+        }
+      }}
+    >
+      <h3 className="flex items-baseline gap-2 px-1 text-sm font-medium">
+        {entry.column.title}
+        <span className="text-xs text-muted-foreground tabular-nums">{entry.cards.length}</span>
+        {entry.unknown === true ? (
+          // ⚠️ A column the board does not configure — cards whose status names nothing. Drawn
+          // rather than hidden: a card nobody can see is a card somebody will look for.
+          <span className="text-xs text-muted-foreground">{i18n.t("board.unknownColumn")}</span>
+        ) : null}
+        {addable ? (
+          // ⚠️ The narrow-screen way in, and it is ALWAYS visible: hover is not a gesture a touch
+          // screen has, so the row below would be unreachable there. Above `md` this one steps
+          // aside for it.
+          <button
+            type="button"
+            aria-label={i18n.t("board.addCardIn", { column: entry.column.title })}
+            onClick={() => setComposing(true)}
+            className="ml-auto rounded-md px-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring md:hidden"
+          >
+            +
+          </button>
+        ) : null}
+      </h3>
+      <ul className="flex flex-col gap-2">
+        {entry.cards.map((card, row) => (
+          <Card key={card.id} card={card} column={entry} row={row} board={board} onMove={onMove} />
+        ))}
+      </ul>
+      {entry.cards.length === 0 ? (
+        <p className="px-1 text-xs text-muted-foreground">{i18n.t("board.columnEmpty")}</p>
+      ) : null}
+      {addable ? (
+        composing ? (
+          <input
+            // The field exists because it was just asked for, and making the reader click a second
+            // time is the whole cost of the control.
+            // biome-ignore lint/a11y/noAutofocus: it opens on a deliberate click, never on load
+            autoFocus
+            value={draft}
+            aria-label={i18n.t("board.addCardIn", { column: entry.column.title })}
+            onChange={(event) => setDraft(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === "Enter") {
+                event.preventDefault();
+                create();
+              }
+              if (event.key === "Escape") close();
+            }}
+            onBlur={() => {
+              if (draft.trim().length === 0) close();
+            }}
+            className="rounded-md border bg-background px-2 py-1 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          />
+        ) : (
+          // ⚠️ `md:opacity-0` plus BOTH group states, not `hover` alone: a control that only exists
+          // while a pointer rests on the column does not exist for a keyboard at all. Focus inside
+          // the column brings it back, the same shape the tree uses for its plus.
+          <button
+            type="button"
+            onClick={() => setComposing(true)}
+            className="hidden rounded-md px-2 py-1 text-left text-sm text-muted-foreground outline-none transition-opacity hover:bg-muted focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-ring group-focus-within/column:opacity-100 group-hover/column:opacity-100 md:block md:opacity-0"
+          >
+            {i18n.t("board.addCard")}
+          </button>
+        )
+      ) : null}
+      {failed ? (
+        <p role="alert" className="px-1 text-xs text-destructive">
+          {i18n.t("board.createFailed")}
+        </p>
+      ) : null}
+    </section>
+  );
+}
+
+export function BoardKanban({ board }: { board: BoardHandle }) {
+  const i18n = useI18n();
+
+  if (board.isPending) {
+    return <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  if (board.isError) {
+    return (
+      <p role="alert" className="p-6 text-sm text-destructive">
+        {i18n.t("board.failed")}
+      </p>
+    );
+  }
+
+  const move = (card: BoardTask, drop: Drop) => {
+    const write = dropToWrite(card, board.columns, drop);
+    // ⚠️ `null` means the card is where it already was. Writing anyway would recompute the position
+    // and make it jump — the most common "drop" there is somebody putting a card back.
+    if (write === null) return;
+    void board.updateTask({
+      taskId: card.id,
+      status: write.status,
+      position: write.position,
+      idempotencyKey: `move-${card.id}-${write.status}-${write.position}`,
+    });
+  };
+
+  return (
+    <div className="flex gap-3 overflow-x-auto p-4" aria-busy={board.isWriting}>
+      {board.columns.map((column) => (
+        <Column key={column.column.id} entry={column} board={board} onMove={move} />
+      ))}
+    </div>
+  );
+}