@anchrd/intel-ui 0.39.0 → 0.41.0

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

@@ -1,51 +1,62 @@
 import type { BoardTask } from "@anchrd/intel-contract/board";
+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 { 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";
+import {
+  type Drop,
+  dragEndToDrop,
+  dropIsAfter,
+  dropToWrite,
+  neighbourDrop,
+} from "./board-kanban.ts";
 
 function Card({
   card,
   column,
-  row,
   board,
   onMove,
+  onOpen,
+  family,
+  parentColumn,
 }: {
   card: BoardTask;
   column: ColumnWithCards;
-  row: number;
   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
-      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 });
-      }}
+      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
@@ -53,13 +64,20 @@ function Card({
           — 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";
-        }}
+        {...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.
+        className="relative w-full cursor-grab overflow-hidden rounded-md border border-border bg-card p-2 text-left text-sm shadow-xs 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
@@ -70,6 +88,12 @@ function Card({
           // ⚠️ 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"
@@ -88,7 +112,22 @@ function Card({
           onMove(card, drop);
         }}
       >
-        <span className="block">{card.title}</span>
+        <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)}
@@ -99,6 +138,101 @@ function Card({
   );
 }
 
+/**
+ * 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/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);
 }
@@ -117,15 +251,28 @@ 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;
@@ -155,6 +302,9 @@ function Column({
         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)
@@ -165,24 +315,9 @@ function Column({
 
   return (
     <section
+      ref={setDropRef}
       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}
@@ -206,14 +341,32 @@ function Column({
           </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}
+      <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
@@ -258,8 +411,26 @@ function Column({
   );
 }
 
-export function BoardKanban({ board }: { board: BoardHandle }) {
+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>;
@@ -285,11 +456,183 @@ export function BoardKanban({ board }: { board: BoardHandle }) {
     });
   };
 
+  /**
+   * 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 (
-    <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>
+    <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 className="w-64 rounded-md border border-border bg-card 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 });
+}

package/src/board/board-open-task/board-open-task.ts

@@ -0,0 +1,32 @@
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { useCallback } from "react";
+import { openTaskFrom } from "@/router/selection-search.ts";
+
+/**
+ * Which card is open, and the one way to change that.
+ *
+ * ⚠️ **One truth for two places.** The title row and the panel both open cards, and they are
+ * rendered in different subtrees: the row above the content, the panel inside it. Written twice,
+ * one of them would eventually push where the other replaces, and the back button would behave
+ * differently depending on which control was used.
+ */
+export function useOpenTask(): { openId: string | null; open(taskId: string | null): void } {
+  const search = useSearch({ strict: false });
+  const navigate = useNavigate();
+
+  const open = useCallback(
+    (taskId: string | null) =>
+      void navigate({
+        to: ".",
+        // ⚠️ **Closing REPLACES, opening pushes.** Opening a card is a step somebody took and the
+        // back button must undo it; closing is the undo itself. Pushed as well, the history holds
+        // board → card → board, and one press of Back re-opens the card that was just closed.
+        replace: taskId === null,
+        search: (previous: Record<string, unknown>) =>
+          taskId === null ? { ...previous, task: undefined } : { ...previous, task: taskId },
+      }),
+    [navigate],
+  );
+
+  return { openId: openTaskFrom(search), open };
+}