@anchrd/intel 0.59.0

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

@@ -0,0 +1,680 @@
+import type { BoardTask } from "@contract/board.ts";
+import {
+  closestCorners,
+  DndContext,
+  type DragEndEvent,
+  DragOverlay,
+  MouseSensor,
+  TouchSensor,
+  useDroppable,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import { SortableContext, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { useState } from "react";
+import type { BoardHandle, ColumnWithCards } from "@/board/board-data/board-data.types.ts";
+import { type Family, familiesOf } from "@/board/board-stripes/board-stripes.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { cn } from "@/lib/utils";
+import {
+  type Drop,
+  dragEndToDrop,
+  dropIsAfter,
+  dropToWrite,
+  neighbourDrop,
+} from "./board-kanban.ts";
+
+function Card({
+  card,
+  column,
+  board,
+  onMove,
+  onOpen,
+  family,
+  parentColumn,
+}: {
+  card: BoardTask;
+  column: ColumnWithCards;
+  board: BoardHandle;
+  onMove(card: BoardTask, drop: Drop): void;
+  onOpen(taskId: string): void;
+  family: Family;
+  /** The title of the column the parent card sits in, or `undefined` when there is none here. */
+  parentColumn: string | undefined;
+}) {
+  const i18n = useI18n();
+  const locked = board.isWriting;
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: card.id,
+    disabled: locked,
+  });
+
+  return (
+    <li
+      ref={setNodeRef}
+      style={{ transform: CSS.Translate.toString(transform), transition }}
+      // ⚠️ The card keeps its place in the list while it is carried, and only fades. Removing it
+      // would collapse the gap it came from, every card below would jump up by one, and the drop
+      // target the pointer is over would change underneath the gesture.
+      className={isDragging ? "opacity-40" : undefined}
+    >
+      {/* ⚠️ 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"
+        {...attributes}
+        {...listeners}
+        // ⚠️ After the spread, deliberately. `attributes` carries `aria-roledescription="sortable"`,
+        // which announces a gesture this board does not offer from the keyboard.
+        aria-roledescription={undefined}
+        // ⚠️ The name carries everything this card cannot say any other way: that it OPENS (#671),
+        // how it moves without a pointer, and how DEEP it sits (#366). The stripes on the right are
+        // `aria-hidden` — a button's children are presentational, so no label inside one is ever
+        // announced, and the depth would exist in colour alone.
+        aria-label={labelOf(i18n, card, column, family, parentColumn)}
+        onClick={() => onOpen(card.id)}
+        // `relative` and `overflow-hidden` are for the depth pattern: it is positioned against this
+        // card, and nothing of it may spill past the rounded edge.
+        /* ⚠️ A quiet grey FIELD, not a box (#748). It carried `bg-card` plus `border-border` plus
+             `shadow-xs` — three means saying the same thing ("this is a card"), and on a white board
+             the three together read as a container rather than a surface. `bg-muted` is 0.97 against
+             a 1.0 ground in light and 0.269 against 0.145 in dark, so the card stands off its column
+             in both without a line around it.
+             ⚠️ The hover is what replaces the border: a surface still has to answer the pointer, and
+             without a line there is nothing else left to do it. */
+        className="relative w-full cursor-grab overflow-hidden rounded-md bg-muted p-2 text-left text-sm transition-colors hover:bg-muted/70 focus-visible:outline-2 focus-visible:outline-ring"
+        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.
+          //
+          // ⚠️ This is kept INSTEAD of `dnd-kit`'s own keyboard sensor. That sensor lifts a card
+          // with the space bar and then steers it by collision detection, which needs measured
+          // geometry — a board whose columns are off screen to the right cannot be reached without
+          // scrolling first, and jsdom measures nothing at all, so the whole path would leave the
+          // suite. Alt and an arrow names the neighbour directly and is proven without a layout.
+          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);
+        }}
+      >
+        <Stripes family={family} label={depthOf(i18n, family, parentColumn)} />
+        {/* ⚠️ The room on the right follows the STRIPES, not the level. A fixed `pr-6` holds four
+            stripes and the title runs under the fifth; but reserving room for the real level once
+            the pattern caps takes width from the title for stripes that are not drawn — at level 20
+            that is 76 px of a 240 px card, given away for nothing. */}
+        <span
+          className="block"
+          // ⚠️ `STRIPE_WIDTH`, not a number written twice. The reserve followed the OLD grid of
+          // 3px plus a 2px gap; since the stripes sit flush and 4px wide, `* 5` reserved up to 14px
+          // the title never needed, while the comment above claimed the reserve follows them.
+          style={{
+            paddingRight: `${8 + Math.min(family.level, MAX_STRIPES) * STRIPE_WIDTH}px`,
+          }}
+        >
+          {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>
+  );
+}
+
+/**
+ * The depth pattern on the right edge of a card.
+ *
+ * ⚠️ **Right, where no text stands.** Jack's decision 2026-08-08: an indent costs width exactly
+ * where the title is, and by the third level the card is a strip. The stripes cost nothing a reader
+ * was using.
+ *
+ * ⚠️ **`aria-hidden`, and the words live on the BUTTON.** A `role="img"` with a label inside a
+ * `<button>` reaches nobody: a button's children are presentational in ARIA, and the button already
+ * carries a name of its own, which wins. The mark was drawn, the test was green, and the sentence
+ * existed for no one — see `labelOf` and `packages/intel/ui/CLAUDE.md`.
+ */
+function Stripes({ family, label }: { family: Family; label: string }) {
+  if (family.level === 0) return null;
+  return (
+    <span
+      aria-hidden="true"
+      // ⚠️ A tooltip BESIDE the accessible name, not instead of it: the name serves whoever cannot
+      // see the stripes, the tooltip whoever sees them and wonders what they mean.
+      //
+      // ⚠️ And therefore NOT `pointer-events-none`. A native `title` hangs on hover, and an element
+      // that is not a hit target never gets one — the attribute would sit there, the test would find
+      // it, and the tooltip would never appear once. The class is not needed either: this span lies
+      // inside the button, so a click reaches it anyway.
+      title={label}
+      // ⚠️ Flush and gapless, top to bottom. Inset from the edge and spaced apart, the stripes read
+      // as decoration somebody added; against the edge and touching, they read as one mark with a
+      // countable number of parts, which is what they are.
+      className="absolute inset-y-0 right-0 flex"
+    >
+      {levels(family.level).map((level) => (
+        <span
+          key={`${family.rootId}-${level}`}
+          // ⚠️ Each level a fainter step of the SAME tone, not a different tone. The hue answers
+          // "which family", the count answers "how deep" — one channel per question.
+          //
+          // ⚠️ Clamped, and the clamp survives its own reason. It was added because an unclamped
+          // ramp went negative — CSS pins that to zero and the deepest stripes are simply not drawn.
+          // Since the pattern caps at six the lowest raw value is 0.25, so the clamp no longer
+          // fires; it stays because it is the guard, not the arithmetic, that must hold if the cap
+          // ever moves.
+          // ⚠️ No rounding. A rounded stripe at full height leaves a light wedge at each end, and
+          // two of them beside one another look like a gap that is not there.
+          // ⚠️ The width as an inline STYLE, not a class. `w-[${…}px]` is a name Tailwind never
+          // sees — it reads class names statically, so the stripes would have no width in the build
+          // and be perfectly fine in the tests. An inline value is also the only way one number can
+          // rule both the mark and the room reserved for it.
+          className={toneClasses[family.tone - 1]}
+          style={{ width: `${STRIPE_WIDTH}px`, opacity: Math.max(0.3, 1 - (level - 1) * 0.15) }}
+        />
+      ))}
+    </span>
+  );
+}
+
+/**
+ * ⚠️ **The pattern caps at six, the NAME does not.** Seven stripes are twenty pixels, and nobody
+ * counts them — past that the mark stops being a count and becomes texture. The accessible name
+ * keeps saying the real level, so nothing is lost, only unread pixels.
+ */
+const MAX_STRIPES = 6;
+
+/**
+ * How wide one stripe is, in pixels.
+ *
+ * ⚠️ **One number, read by both the mark and the room reserved for it.** Written twice they drift,
+ * and the drift is silent: the title keeps its distance from stripes that are no longer that wide,
+ * or runs under ones that grew.
+ */
+const STRIPE_WIDTH = 4;
+
+/**
+ * `[1, 2, … min(depth, MAX_STRIPES)]` — the level each stripe stands for.
+ *
+ * ⚠️ The level, not the index. Both are the same number here, and the rule against index keys is
+ * about lists whose order can change; this one cannot, because stripe two is always level two.
+ */
+function levels(depth: number): number[] {
+  return Array.from({ length: Math.min(depth, MAX_STRIPES) }, (_, step) => step + 1);
+}
+
+/**
+ * ⚠️ Written out rather than built from a template string. Tailwind reads class names statically,
+ * and `bg-board-family-${n}` is a name it never sees — the stripes would be invisible in the build
+ * and perfectly fine in the tests.
+ */
+const toneClasses = [
+  "bg-board-family-1",
+  "bg-board-family-2",
+  "bg-board-family-3",
+  "bg-board-family-4",
+  "bg-board-family-5",
+  "bg-board-family-6",
+] as const;
+
+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/intel/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,
+  onOpen,
+  families,
+  columnOf,
+}: {
+  entry: ColumnWithCards;
+  board: BoardHandle;
+  onMove(card: BoardTask, drop: Drop): void;
+  onOpen(taskId: string): void;
+  families: Map<string, Family>;
+  columnOf: Map<string, string>;
+}) {
+  const i18n = useI18n();
+  const [composing, setComposing] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [failed, setFailed] = useState(false);
+  // ⚠️ The column is a drop target in its OWN right, and it means "append": the free area below
+  // the last card. Without it a board could never take a card into an empty column — there would be
+  // no card there to let go on.
+  const { setNodeRef: setDropRef } = useDroppable({
+    id: entry.column.id,
+    disabled: board.isWriting,
+  });
+  // ⚠️ 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,
+        // A card made in a column sits on the board itself. Making a SUBTASK is the same call with
+        // the parent named — that is the detail view's business (#671), not the column's.
+        parentTaskId: 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
+      ref={setDropRef}
+      aria-label={entry.column.title}
+      className="group/column flex w-64 shrink-0 flex-col gap-2"
+    >
+      <h3 className="flex items-center gap-2 px-1 text-sm font-medium">
+        {/* ⚠️ The dot is DECORATION and says so (#725). The column's name is right beside it in
+            words, so announcing the colour would repeat the name in a form nobody can act on — and
+            for somebody who cannot see it, a second announcement of "Backlog" is noise, not help.
+            ⚠️ An inline style, not a class: the value is chosen by a person at runtime, and Tailwind
+            only ships classes its scanner saw in the source. */}
+        <ColumnDot color={entry.column.color} />
+        {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>
+      <SortableContext
+        items={entry.cards.map((card) => card.id)}
+        strategy={verticalListSortingStrategy}
+      >
+        <ul className="flex flex-col gap-2">
+          {entry.cards.map((card) => (
+            <Card
+              key={card.id}
+              card={card}
+              column={entry}
+              board={board}
+              onMove={onMove}
+              onOpen={onOpen}
+              family={families.get(card.id) ?? noFamily}
+              parentColumn={
+                card.parentTaskId === null ? undefined : columnOf.get(card.parentTaskId)
+              }
+            />
+          ))}
+        </ul>
+      </SortableContext>
+      {/* ⚠️ **Nothing at all under an empty column.** The sentence said what the emptiness already
+          says, and the surface I first put in its place was an invention with a false reason: the
+          column is a drop target through `setDropRef` on the section above, with or without
+          anything drawn in it — `dragEndToDrop` answers `{ status, index: 0 }` for a column with no
+          cards, and `neighbourDrop` reaches one by index alone. */}
+      {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,
+  onOpen,
+}: {
+  board: BoardHandle;
+  onOpen(taskId: string): void;
+}) {
+  const i18n = useI18n();
+  // The card under the pointer, for the preview. Nothing else about the gesture is state.
+  const [carried, setCarried] = useState<string | null>(null);
+
+  /**
+   * ⚠️ **A distance before the drag starts, or the card stops being a button.** Without it every
+   * press is a gesture: `dnd-kit` swallows the click that follows, and opening a card by clicking
+   * it — the thing the card is mostly for — silently stops working.
+   */
+  const sensors = useSensors(
+    useSensor(MouseSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(TouchSensor, { activationConstraint: { delay: 200, tolerance: 6 } }),
+  );
+
+  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}`,
+    });
+  };
+
+  /**
+   * What a finished gesture means as a write, or `null` for "nothing changed".
+   *
+   * ⚠️ Shared by the handler and the announcement on purpose. Computed twice they would drift, and
+   * the drift would be invisible: the screen reader would report a move nobody made, or stay quiet
+   * about one that happened.
+   *
+   * ⚠️ **The lock belongs HERE, not in the caller.** With it one level up, a write starting
+   * underneath a running gesture stopped the handler and left the announcement saying "moved to
+   * Offen" over zero writes — the drift the paragraph above claims to rule out, restored by the
+   * one line that was not shared.
+   */
+  const resolve = (event: Pick<DragEndEvent, "active" | "over">) => {
+    if (board.isWriting) return null;
+    const dragged = cardById(board, String(event.active.id));
+    if (dragged === undefined) return null;
+    const drop = dragEndToDrop(
+      String(event.active.id),
+      event.over === null ? null : String(event.over.id),
+      board.columns,
+      dropIsAfter(event.active.rect.current.translated, event.over?.rect),
+    );
+    return drop === null ? null : dropToWrite(dragged, board.columns, drop);
+  };
+
+  /**
+   * ⚠️ **ONE derivation for the whole board, not one per card** — and that has to include the
+   * lookup the LABEL needs, not only the families. `dnd-kit` re-renders on every pointer move while
+   * a card is carried, so anything per-card that scans the board is quadratic: measured at 800
+   * cards it was 36 ms per render before, and a `find` left in the label put the same shape back
+   * at 5 ms per 1600 cards.
+   */
+  const families = familiesOf(board.columns.flatMap((entry) => entry.cards));
+  const columnOf = new Map(
+    board.columns.flatMap((entry) => entry.cards.map((card) => [card.id, entry.column.title])),
+  );
+
+  const carriedCard = carried === null ? undefined : cardById(board, carried);
+
+  return (
+    <DndContext
+      sensors={sensors}
+      // ⚠️ Corners, not centres. A card is far taller than the gap between two cards, so the closest
+      // CENTRE stays the same card across most of a column and the gesture feels stuck; the closest
+      // corner changes at the boundary the reader is aiming at.
+      collisionDetection={closestCorners}
+      // ⚠️ `dnd-kit`'s own wording announces the space bar, and no keyboard sensor is registered —
+      // pressing it does nothing. Announcing a gesture that is not there is worse than announcing
+      // none: the reader tries it, nothing happens, and the one that works is never mentioned.
+      accessibility={{
+        screenReaderInstructions: { draggable: i18n.t("board.dragInstructions") },
+        // ⚠️ `dnd-kit`'s own announcements read out the raw ids — "Draggable item a was moved over
+        // droppable area a" — and report a drop even when nothing was written. Both are replaced:
+        // the card is named by its TITLE, the move-over is silent because there is nothing about a
+        // position this code could say honestly, and the end says what actually happened.
+        announcements: {
+          onDragStart: ({ active }) => {
+            const card = cardById(board, String(active.id));
+            return card === undefined
+              ? undefined
+              : i18n.t("board.drag.lifted", { card: card.title });
+          },
+          onDragOver: () => undefined,
+          onDragMove: () => undefined,
+          onDragEnd: (event) => {
+            const write = resolve(event);
+            const card = cardById(board, String(event.active.id));
+            // ⚠️ Silence, not a sentence without a subject. A card that vanished mid-gesture — an
+            // answer arrived, somebody else archived it — has no name left to announce, and
+            // " put back" read out on its own says less than nothing.
+            if (card === undefined) return undefined;
+            if (write === null) return i18n.t("board.drag.putBack", { card: card.title });
+            return i18n.t("board.drag.moved", {
+              card: card.title,
+              column:
+                board.columns.find((entry) => entry.column.id === write.status)?.column.title ??
+                write.status,
+            });
+          },
+          onDragCancel: ({ active }) => {
+            const card = cardById(board, String(active.id));
+            return card === undefined
+              ? undefined
+              : i18n.t("board.drag.putBack", { card: card.title });
+          },
+        },
+      }}
+      onDragStart={(event) => setCarried(String(event.active.id))}
+      onDragCancel={() => setCarried(null)}
+      onDragEnd={(event) => {
+        setCarried(null);
+        // ⚠️ The SECOND lock lives inside `resolve`, so the announcement obeys it too — see there.
+        const write = resolve(event);
+        if (write === null) return;
+        void board.updateTask({
+          taskId: String(event.active.id),
+          status: write.status,
+          position: write.position,
+          idempotencyKey: `move-${event.active.id}-${write.status}-${write.position}`,
+        });
+      }}
+    >
+      {/* ⚠️ **`min-h-0 flex-1`, or the scrollbar sits in the middle of the screen.** A box with no
+          height shrinks to its content, and the horizontal bar clings to the bottom of the tallest
+          column: on a board with few cards that looks broken. The panel above already offers the
+          full height; this is where it is taken.
+
+          ⚠️ **And NO `items-start` with it.** A stretched column paints nothing — the section
+          carries neither background nor border — but the rectangle it stretches to is what
+          `useDroppable` measures and `closestCorners` reckons against. Held to its content instead,
+          an empty column shrinks to its heading, and the area a card can be dropped into shrinks
+          with it. */}
+      <div className="flex min-h-0 flex-1 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}
+            onOpen={onOpen}
+            families={families}
+            columnOf={columnOf}
+          />
+        ))}
+      </div>
+      {/* ⚠️ The preview is what a drag looks like. Without it the card stays put and only the
+          cursor moves, and there is nothing on screen saying the gesture was picked up at all. */}
+      <DragOverlay>
+        {carriedCard === undefined ? null : (
+          <div /* ⚠️ The same surface as the card it stands for (#748), plus the shadow that is the ONE
+              thing this element says beyond it: this one is lifted. A card that changed colour on
+              being picked up would read as a different card. */
+            className="w-64 rounded-md bg-muted p-2 text-left text-sm shadow-lg"
+          >
+            {carriedCard.title}
+          </div>
+        )}
+      </DragOverlay>
+    </DndContext>
+  );
+}
+
+/** A card that belongs to no family — the answer when the board has not been read yet. */
+const noFamily: Family = { level: 0, tone: 0, rootId: null };
+
+/**
+ * What the card's button is CALLED.
+ *
+ * ⚠️ **This is where the depth becomes readable, and the only place it can be.** The stripes are
+ * `aria-hidden` because a button's children are presentational: a `role="img"` with a label inside
+ * one is never announced, and the button's own name wins in any case. The board already spends a
+ * colour axis on the status, so the family may not be a second one — a reader who does not see the
+ * difference has to be able to read it.
+ */
+function labelOf(
+  i18n: ReturnType<typeof useI18n>,
+  card: BoardTask,
+  column: ColumnWithCards,
+  family: Family,
+  parentColumn: string | undefined,
+): string {
+  const name = i18n.t("board.cardLabel", { title: card.title, column: column.column.title });
+  if (family.level === 0) return name;
+  // ⚠️ Handed IN, not looked up. A `find` over the board here runs once per card on every render,
+  // and puts back the quadratic shape the one derivation above exists to remove.
+  return `${name} ${depthOf(i18n, family, parentColumn)}`;
+}
+
+/**
+ * What the depth pattern says, in words.
+ *
+ * ⚠️ Always the REAL level, even where the stripes have capped. The mark stops counting at six; the
+ * sentence does not, because it is the channel somebody relies on when they cannot count stripes.
+ */
+function depthOf(
+  i18n: ReturnType<typeof useI18n>,
+  family: Family,
+  parentColumn: string | undefined,
+): string {
+  if (family.level === 0) return "";
+  return parentColumn === undefined
+    ? i18n.t("board.stripes.root", { level: family.level })
+    : i18n.t("board.stripes.under", { level: family.level, column: parentColumn });
+}
+
+/**
+ * The colour of a column, as a dot (#725).
+ *
+ * ⚠️ **One component for two places.** The kanban head draws it and so does a linked task in the
+ * open card; written twice they drift, and a dot that means one thing here and another there is
+ * worse than no dot.
+ *
+ * ⚠️ **Absent is a real state, not a missing value.** A board configured before colours existed has
+ * none, and painting it grey-by-default would claim somebody chose grey. The reader's own muted
+ * tone says "no colour set" without pretending otherwise.
+ */
+export function ColumnDot({ color }: { color?: string | undefined }) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "size-2 shrink-0 rounded-full",
+        color === undefined && "bg-muted-foreground/40",
+      )}
+      {...(color === undefined ? {} : { style: { backgroundColor: color } })}
+    />
+  );
+}