@multiplatform.one/components 6.1.0 → 6.3.0

package/src/views/kanbanDnd.ts

@@ -0,0 +1,323 @@
+/**
+ * Pure drag-and-drop math and keyboard state machine for the Kanban board.
+ *
+ * Everything here is platform-agnostic and side-effect free so web
+ * (`Kanban.tsx`) and native (`Kanban.native.tsx`) share one source of truth
+ * and the logic stays unit-testable without a DOM.
+ *
+ * Coordinate vocabulary:
+ * - "original index": a card's index in its column's `items` array (the
+ *   dragged card still occupies its slot — data is never mutated mid-drag).
+ * - "without-dragged index" (wd): index in the list with the dragged card
+ *   removed. Insertion targets (`KanbanDropTarget.index`) always use wd
+ *   coordinates, so a target equals the final position after the drop.
+ *
+ * All displacement is expressed as transform translate offsets (never layout
+ * props) so the same math is native-driver safe (A-GESTURE / Axiom 4).
+ */
+
+// ── Types ─────────────────────────────────────────────────────
+
+/** Where the dragged card would land if dropped now. */
+export interface KanbanDropTarget {
+  columnId: string;
+  /** Insertion index in without-dragged coordinates (0..wdCount). */
+  index: number;
+}
+
+/** Minimal board snapshot for the keyboard machine. */
+export interface KanbanBoardColumnSnapshot {
+  id: string;
+  title: string;
+  /** Item count with the dragged card still in place. */
+  count: number;
+}
+
+/** Active keyboard drag session (source never changes while lifted). */
+export interface KanbanKeyboardDrag {
+  sourceColumnId: string;
+  /** Original index of the lifted card in its source column. */
+  sourceIndex: number;
+  target: KanbanDropTarget;
+}
+
+export type KanbanMoveDirection = "up" | "down" | "left" | "right";
+
+// ── Displacement (FLIP make-room) ─────────────────────────────
+
+export interface SiblingOffsetOptions {
+  /** Card's original index in its column. */
+  index: number;
+  /** Dragged card's original index when this column is the source, else null. */
+  sourceIndex: number | null;
+  /** Insertion index (wd coords) when this column is the drop target, else null. */
+  gapIndex: number | null;
+  /** Dragged slot size in px (wrapper height including its gap padding). */
+  size: number;
+}
+
+/**
+ * Transform offset (px) a sibling card translates by so the board makes room
+ * for the insertion gap. Values are always -size, 0, or +size, so siblings
+ * move with pure transforms and spring back cleanly on cancel.
+ */
+export function siblingOffset({
+  index,
+  sourceIndex,
+  gapIndex,
+  size,
+}: SiblingOffsetOptions): number {
+  if (sourceIndex != null) {
+    if (index === sourceIndex) return 0; // the dragged card itself is handled as the ghost
+    const wdIndex = index > sourceIndex ? index - 1 : index;
+    const closeOrigin = index > sourceIndex ? -size : 0;
+    const openGap = gapIndex != null && wdIndex >= gapIndex ? size : 0;
+    return closeOrigin + openGap;
+  }
+  return gapIndex != null && index >= gapIndex ? size : 0;
+}
+
+export interface GapPositionOptions {
+  /** Insertion index in wd coordinates. */
+  gapIndex: number;
+  /** Dragged card's original index when this column is the source, else null. */
+  sourceIndex: number | null;
+  /** Total item count of the column (dragged card included when source). */
+  count: number;
+  /** Dragged slot size in px. */
+  size: number;
+  /** Column content total size in px (virtualizer total). */
+  totalSize: number;
+  /** Start offset (px) of the card at an original index. */
+  getStart: (index: number) => number;
+}
+
+/** Top offset (px) of the insertion gap inside the column's content. */
+export function gapPosition({
+  gapIndex,
+  sourceIndex,
+  count,
+  size,
+  totalSize,
+  getStart,
+}: GapPositionOptions): number {
+  if (sourceIndex == null) {
+    return gapIndex < count ? getStart(gapIndex) : totalSize;
+  }
+  if (gapIndex < sourceIndex) return getStart(gapIndex);
+  if (gapIndex + 1 <= count - 1) return getStart(gapIndex + 1) - size;
+  return totalSize - size;
+}
+
+// ── Insertion index from a pointer position ───────────────────
+
+export interface RenderedCardMeasurement {
+  /** Original index in the column. */
+  index: number;
+  /** Start offset in px (column content coordinates). */
+  start: number;
+  /** Measured size in px. */
+  size: number;
+}
+
+export interface InsertionIndexOptions {
+  /** Pointer y in column content coordinates (client y − content top + scrollTop). */
+  localY: number;
+  /** Rendered (virtualized) card measurements sorted by index. */
+  items: RenderedCardMeasurement[];
+  /** Dragged card's original index when this column is the source, else null. */
+  sourceIndex: number | null;
+  /** Total item count of the column (dragged card included when source). */
+  count: number;
+  /** Dragged slot size in px. */
+  size: number;
+}
+
+/**
+ * Insertion index (wd coordinates) for a pointer at `localY`. Uses the
+ * midpoint rule (Trello/dnd-kit consensus): the gap lands after every card
+ * whose without-dragged midpoint sits above the pointer.
+ */
+export function insertionIndexForY({
+  localY,
+  items,
+  sourceIndex,
+  count,
+  size,
+}: InsertionIndexOptions): number {
+  const wdCount = count - (sourceIndex != null ? 1 : 0);
+  const rendered = items.filter((it) => it.index !== sourceIndex);
+  if (rendered.length === 0 || wdCount <= 0) return 0;
+  const first = rendered[0];
+  const base = first.index - (sourceIndex != null && first.index > sourceIndex ? 1 : 0);
+  let passed = 0;
+  for (const it of rendered) {
+    const wdStart = it.start - (sourceIndex != null && it.index > sourceIndex ? size : 0);
+    if (localY > wdStart + it.size / 2) passed += 1;
+  }
+  const index = base + passed;
+  return index < 0 ? 0 : index > wdCount ? wdCount : index;
+}
+
+/**
+ * Closed-form insertion index for uniform card sizes (native path — FlashList
+ * does not expose per-item measurements). Equivalent to the midpoint rule.
+ */
+export function uniformInsertionIndex(localY: number, size: number, wdCount: number): number {
+  if (size <= 0 || wdCount <= 0) return 0;
+  const index = Math.floor(localY / size + 0.5);
+  return index < 0 ? 0 : index > wdCount ? wdCount : index;
+}
+
+// ── Auto-scroll ───────────────────────────────────────────────
+
+export interface AutoScrollOptions {
+  /** Pointer position along the scroll axis (client coords). */
+  pos: number;
+  /** Viewport start edge (client coords). */
+  start: number;
+  /** Viewport end edge (client coords). */
+  end: number;
+  /** Edge activation zone in px. */
+  edge: number;
+  /** Max scroll speed in px per frame. */
+  maxSpeed: number;
+}
+
+/**
+ * Signed scroll velocity (px/frame) for edge auto-scroll. Speed ramps
+ * linearly with proximity to the edge and saturates at `maxSpeed` when the
+ * pointer reaches or passes it.
+ */
+export function autoScrollVelocity({ pos, start, end, edge, maxSpeed }: AutoScrollOptions): number {
+  const span = end - start;
+  if (span <= 0) return 0;
+  const effEdge = Math.min(edge, span / 3);
+  if (effEdge <= 0) return 0;
+  const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+  const dStart = pos - start;
+  if (dStart < effEdge) return -maxSpeed * (1 - clamp01(dStart / effEdge));
+  const dEnd = end - pos;
+  if (dEnd < effEdge) return maxSpeed * (1 - clamp01(dEnd / effEdge));
+  return 0;
+}
+
+// ── Keyboard drag state machine (WAI-ARIA drag pattern) ───────
+
+/** Max insertion index for a column (wd coordinates). */
+export function maxInsertionIndex(
+  board: KanbanBoardColumnSnapshot[],
+  drag: Pick<KanbanKeyboardDrag, "sourceColumnId">,
+  columnId: string,
+): number {
+  const column = board.find((c) => c.id === columnId);
+  if (!column) return 0;
+  return column.id === drag.sourceColumnId ? Math.max(column.count - 1, 0) : column.count;
+}
+
+/** Begin a keyboard drag session. Returns null when the card does not exist. */
+export function keyboardLift(
+  board: KanbanBoardColumnSnapshot[],
+  columnId: string,
+  index: number,
+): KanbanKeyboardDrag | null {
+  const column = board.find((c) => c.id === columnId);
+  if (!column || index < 0 || index >= column.count) return null;
+  return {
+    sourceColumnId: columnId,
+    sourceIndex: index,
+    target: { columnId, index },
+  };
+}
+
+/**
+ * Move the drop target one step. Returns the same session object when the
+ * move hits a boundary so callers can detect no-ops by identity.
+ */
+export function keyboardMove(
+  drag: KanbanKeyboardDrag,
+  board: KanbanBoardColumnSnapshot[],
+  direction: KanbanMoveDirection,
+): KanbanKeyboardDrag {
+  const { target } = drag;
+  if (direction === "up") {
+    if (target.index <= 0) return drag;
+    return { ...drag, target: { ...target, index: target.index - 1 } };
+  }
+  if (direction === "down") {
+    const max = maxInsertionIndex(board, drag, target.columnId);
+    if (target.index >= max) return drag;
+    return { ...drag, target: { ...target, index: target.index + 1 } };
+  }
+  const colIndex = board.findIndex((c) => c.id === target.columnId);
+  if (colIndex < 0) return drag;
+  const nextIndex = direction === "left" ? colIndex - 1 : colIndex + 1;
+  if (nextIndex < 0 || nextIndex >= board.length) return drag;
+  const nextColumn = board[nextIndex];
+  const max = maxInsertionIndex(board, drag, nextColumn.id);
+  return {
+    ...drag,
+    target: {
+      columnId: nextColumn.id,
+      index: target.index > max ? max : target.index,
+    },
+  };
+}
+
+export interface KanbanDropResult {
+  /** False when the card lands exactly where it started. */
+  commit: boolean;
+  from: { columnId: string; index: number };
+  to: KanbanDropTarget;
+}
+
+/** Resolve a drop for the current target (keyboard and pointer share this). */
+export function resolveDrop(
+  drag: Pick<KanbanKeyboardDrag, "sourceColumnId" | "sourceIndex" | "target">,
+): KanbanDropResult {
+  const { sourceColumnId, sourceIndex, target } = drag;
+  return {
+    commit: target.columnId !== sourceColumnId || target.index !== sourceIndex,
+    from: { columnId: sourceColumnId, index: sourceIndex },
+    to: target,
+  };
+}
+
+// ── Screen-reader announcements ───────────────────────────────
+
+export type KanbanAnnouncement =
+  | { type: "lift"; card: string; column: string; position: number; count: number }
+  | { type: "move"; card: string; column: string; position: number; count: number }
+  | { type: "drop"; card: string; column: string; position: number; count: number }
+  | { type: "cancel"; card: string; column: string };
+
+/**
+ * Structured announcement payload for the aria-live region. Positions are
+ * 1-based and `count` is the column's size after the pending drop, matching
+ * the "position 2 of 3" phrasing of the WAI-ARIA drag pattern.
+ */
+export function describeDragState(
+  type: "lift" | "move" | "drop",
+  drag: Pick<KanbanKeyboardDrag, "sourceColumnId" | "sourceIndex" | "target">,
+  board: KanbanBoardColumnSnapshot[],
+  card: string,
+): KanbanAnnouncement {
+  const column = board.find((c) => c.id === drag.target.columnId);
+  const max = maxInsertionIndex(board, drag, drag.target.columnId);
+  return {
+    type,
+    card,
+    column: column?.title ?? drag.target.columnId,
+    position: drag.target.index + 1,
+    count: max + 1,
+  };
+}
+
+export function describeCancel(
+  drag: Pick<KanbanKeyboardDrag, "sourceColumnId">,
+  board: KanbanBoardColumnSnapshot[],
+  card: string,
+): KanbanAnnouncement {
+  const column = board.find((c) => c.id === drag.sourceColumnId);
+  return { type: "cancel", card, column: column?.title ?? drag.sourceColumnId };
+}

package/src/views/treeViewDnd.spec.ts

@@ -0,0 +1,353 @@
+import { describe, expect, it } from "vitest";
+import {
+  applyTreeMove,
+  childrenOf,
+  describeTreeCancel,
+  describeTreeDragState,
+  flattenDndRows,
+  indicatorForTarget,
+  locateNode,
+  resolveTreeDrop,
+  subtreeIds,
+  toWdIndex,
+  treeDropTargetForY,
+  treeKeyboardLift,
+  treeKeyboardMove,
+  wdChildCount,
+  type DndTreeNode,
+} from "./treeViewDnd";
+
+const H = 36;
+const getHeight = () => H;
+
+// src/
+//   components/
+//     button
+//     input
+//   hooks/          (collapsed in most probes)
+//     use-form
+//   index
+// readme
+const tree: DndTreeNode[] = [
+  {
+    id: "src",
+    label: "src",
+    children: [
+      {
+        id: "components",
+        label: "components",
+        children: [
+          { id: "button", label: "Button.tsx" },
+          { id: "input", label: "Input.tsx" },
+        ],
+      },
+      { id: "hooks", label: "hooks", children: [{ id: "use-form", label: "useForm.ts" }] },
+      { id: "index", label: "index.ts" },
+    ],
+  },
+  { id: "readme", label: "README.md" },
+];
+
+const allExpanded = new Set(["src", "components", "hooks"]);
+
+describe("structure lookups", () => {
+  it("locates nodes with parent + index", () => {
+    expect(locateNode(tree, "src")).toMatchObject({ parentId: null, index: 0 });
+    expect(locateNode(tree, "input")).toMatchObject({ parentId: "components", index: 1 });
+    expect(locateNode(tree, "readme")).toMatchObject({ parentId: null, index: 1 });
+    expect(locateNode(tree, "missing")).toBeNull();
+  });
+
+  it("resolves children of a parent (null = roots)", () => {
+    expect(childrenOf(tree, null).map((n) => n.id)).toEqual(["src", "readme"]);
+    expect(childrenOf(tree, "components").map((n) => n.id)).toEqual(["button", "input"]);
+    expect(childrenOf(tree, "button")).toEqual([]);
+  });
+
+  it("collects the dragged subtree", () => {
+    expect([...subtreeIds(tree, "src")].sort()).toEqual(
+      ["components", "button", "hooks", "index", "input", "src", "use-form"].sort(),
+    );
+    expect([...subtreeIds(tree, "readme")]).toEqual(["readme"]);
+  });
+
+  it("flattens visible rows with depth and expansion", () => {
+    const rows = flattenDndRows(tree, new Set(["src"]));
+    expect(rows.map((r) => r.id)).toEqual(["src", "components", "hooks", "index", "readme"]);
+    expect(rows[1]).toMatchObject({ parentId: "src", childIndex: 0, depth: 1, isExpanded: false });
+  });
+
+  it("computes wd counts and indexes around the dragged node", () => {
+    const session = { nodeId: "components", sourceParentId: "src", sourceIndex: 0 };
+    expect(wdChildCount(tree, session, "src")).toBe(2);
+    expect(wdChildCount(tree, session, null)).toBe(2);
+    expect(toWdIndex(session, "src", 2)).toBe(1); // index after the dragged slot shifts down
+    expect(toWdIndex(session, "src", 0)).toBe(0);
+    expect(toWdIndex(session, null, 1)).toBe(1); // other parents unaffected
+  });
+});
+
+describe("keyboard drag state machine", () => {
+  it("lifts a node at its own position (identity target)", () => {
+    const session = treeKeyboardLift(tree, "input");
+    expect(session).toEqual({
+      nodeId: "input",
+      sourceParentId: "components",
+      sourceIndex: 1,
+      target: { parentId: "components", index: 1 },
+    });
+  });
+
+  it("rejects lifting a node that does not exist", () => {
+    expect(treeKeyboardLift(tree, "missing")).toBeNull();
+  });
+
+  it("moves up/down within the parent and clamps at boundaries", () => {
+    let session = treeKeyboardLift(tree, "input")!;
+    session = treeKeyboardMove(session, tree, "up");
+    expect(session.target).toEqual({ parentId: "components", index: 0 });
+    const clamped = treeKeyboardMove(session, tree, "up");
+    expect(clamped).toBe(session); // boundary no-op returns the same session
+    session = treeKeyboardMove(session, tree, "down");
+    expect(session.target).toEqual({ parentId: "components", index: 1 });
+    // components holds 2 children; dragging one leaves wd max = 1
+    expect(treeKeyboardMove(session, tree, "down")).toBe(session);
+  });
+
+  it("right nests into the previous sibling as its last child", () => {
+    // index (child 2 of src) lifted; position above it is hooks
+    let session = treeKeyboardLift(tree, "index")!;
+    session = treeKeyboardMove(session, tree, "right");
+    expect(session.target).toEqual({ parentId: "hooks", index: 1 }); // hooks has 1 child
+  });
+
+  it("right at index 0 is a no-op", () => {
+    const session = treeKeyboardLift(tree, "components")!; // index 0 in src
+    expect(treeKeyboardMove(session, tree, "right")).toBe(session);
+  });
+
+  it("left un-nests to after the current parent", () => {
+    let session = treeKeyboardLift(tree, "input")!;
+    session = treeKeyboardMove(session, tree, "left");
+    // components is child 0 of src → insert after it
+    expect(session.target).toEqual({ parentId: "src", index: 1 });
+    session = treeKeyboardMove(session, tree, "left");
+    // src is root 0 → insert after it at top level
+    expect(session.target).toEqual({ parentId: null, index: 1 });
+    expect(treeKeyboardMove(session, tree, "left")).toBe(session); // top level → no-op
+  });
+
+  it("un-nest converts the parent's index to wd coordinates", () => {
+    // Drag hooks (child 1 of src); un-nest from inside hooks' own parent chain:
+    // lift hooks, nest right into components? components is above it.
+    let session = treeKeyboardLift(tree, "hooks")!;
+    session = treeKeyboardMove(session, tree, "right"); // into components (index 1 → prev sibling)
+    expect(session.target).toEqual({ parentId: "components", index: 2 });
+    session = treeKeyboardMove(session, tree, "left"); // back out: after components in src
+    // components is child 0 of src; hooks (dragged) was child 1 → wd index of components = 0
+    expect(session.target).toEqual({ parentId: "src", index: 1 });
+  });
+
+  it("resolves drops: no-op at origin, commit elsewhere", () => {
+    const home = treeKeyboardLift(tree, "input")!;
+    expect(resolveTreeDrop(home).commit).toBe(false);
+    const moved = treeKeyboardMove(home, tree, "up");
+    const result = resolveTreeDrop(moved);
+    expect(result.commit).toBe(true);
+    expect(result.from).toEqual({ parentId: "components", index: 1 });
+    expect(result.to).toEqual({ parentId: "components", index: 0 });
+  });
+});
+
+describe("treeDropTargetForY (pointer band model)", () => {
+  // Fully expanded flat order: src, components, button, input, hooks, use-form, index, readme
+  const rows = flattenDndRows(tree, allExpanded);
+  const session = { nodeId: "readme", sourceParentId: null, sourceIndex: 1 };
+  const draggedSubtree = subtreeIds(tree, "readme");
+  const base = { rows, getHeight, session, draggedSubtree };
+
+  it("top band inserts before the row", () => {
+    // button is flat row 2 → top band at y = 2H + 2
+    const hit = treeDropTargetForY({ ...base, localY: 2 * H + 2 })!;
+    expect(hit.target).toEqual({ parentId: "components", index: 0 });
+    expect(hit.indicator).toEqual({ kind: "line", flatIndex: 2, depth: 2 });
+  });
+
+  it("bottom band inserts after the row", () => {
+    // button bottom band: y = 2H + 0.9H
+    const hit = treeDropTargetForY({ ...base, localY: 2.9 * H })!;
+    expect(hit.target).toEqual({ parentId: "components", index: 1 });
+    expect(hit.indicator).toEqual({ kind: "line", flatIndex: 3, depth: 2 });
+  });
+
+  it("bottom band on an expanded branch targets its first-child slot", () => {
+    // components is flat row 1 (expanded) → bottom band
+    const hit = treeDropTargetForY({ ...base, localY: 1.9 * H })!;
+    expect(hit.target).toEqual({ parentId: "components", index: 0 });
+    expect(hit.indicator).toEqual({ kind: "line", flatIndex: 2, depth: 2 });
+  });
+
+  it("middle band nests into the row (parent highlight)", () => {
+    // hooks is flat row 4 → middle band
+    const hit = treeDropTargetForY({ ...base, localY: 4.5 * H })!;
+    expect(hit.target).toEqual({ parentId: "hooks", index: 1 });
+    expect(hit.indicator).toEqual({ kind: "into", parentId: "hooks" });
+  });
+
+  it("middle band over a leaf nests into it at index 0", () => {
+    // index is flat row 6
+    const hit = treeDropTargetForY({ ...base, localY: 6.5 * H })!;
+    expect(hit.target).toEqual({ parentId: "index", index: 0 });
+    expect(hit.indicator).toEqual({ kind: "into", parentId: "index" });
+  });
+
+  it("beyond the last row appends at the top level", () => {
+    const hit = treeDropTargetForY({ ...base, localY: 99 * H })!;
+    expect(hit.target).toEqual({ parentId: null, index: 1 }); // readme dragged → wd root count 1
+    expect(hit.indicator).toEqual({ kind: "line", flatIndex: rows.length, depth: 0 });
+  });
+
+  it("returns null over the dragged subtree", () => {
+    const srcSession = { nodeId: "src", sourceParentId: null, sourceIndex: 0 };
+    const hit = treeDropTargetForY({
+      ...base,
+      session: srcSession,
+      draggedSubtree: subtreeIds(tree, "src"),
+      localY: 2.5 * H, // over button, inside the dragged subtree
+    });
+    expect(hit).toBeNull();
+  });
+
+  it("wd-adjusts sibling indexes in the source parent", () => {
+    // Drag button (child 0 of components); before-input line must be wd index 0.
+    const s = { nodeId: "button", sourceParentId: "components", sourceIndex: 0 };
+    const hit = treeDropTargetForY({
+      ...base,
+      session: s,
+      draggedSubtree: subtreeIds(tree, "button"),
+      localY: 3 * H + 2, // top band of input (flat row 3)
+    })!;
+    expect(hit.target).toEqual({ parentId: "components", index: 0 });
+  });
+});
+
+describe("indicatorForTarget (keyboard indicator)", () => {
+  const rows = flattenDndRows(tree, allExpanded);
+
+  it("points at the sibling row the target displaces", () => {
+    const session = treeKeyboardLift(tree, "input")!;
+    const moved = treeKeyboardMove(session, tree, "up");
+    // target components[0] → line above button (flat row 2)
+    expect(indicatorForTarget(rows, moved, moved.target)).toEqual({
+      kind: "line",
+      flatIndex: 2,
+      depth: 2,
+    });
+  });
+
+  it("append positions land after the last visible sibling's subtree", () => {
+    const session = treeKeyboardLift(tree, "readme")!;
+    // target = top level index 1 (after src's whole subtree)
+    expect(indicatorForTarget(rows, session, { parentId: null, index: 1 })).toEqual({
+      kind: "line",
+      flatIndex: 7, // after src + its 6 visible descendants
+      depth: 0,
+    });
+  });
+
+  it("falls back to the parent highlight when no children are visible", () => {
+    const collapsedRows = flattenDndRows(tree, new Set(["src"]));
+    const session = treeKeyboardLift(tree, "index")!;
+    const nested = treeKeyboardMove(session, tree, "right"); // into hooks (collapsed)
+    expect(indicatorForTarget(collapsedRows, nested, nested.target)).toEqual({
+      kind: "into",
+      parentId: "hooks",
+    });
+  });
+});
+
+describe("applyTreeMove", () => {
+  it("reorders within a parent using wd coordinates", () => {
+    const next = applyTreeMove(tree, "input", { parentId: "components", index: 0 });
+    expect(childrenOf(next, "components").map((n) => n.id)).toEqual(["button", "input"].reverse());
+  });
+
+  it("moves a node (with its subtree) to another parent", () => {
+    const next = applyTreeMove(tree, "components", { parentId: "hooks", index: 1 });
+    expect(childrenOf(next, "src").map((n) => n.id)).toEqual(["hooks", "index"]);
+    expect(childrenOf(next, "hooks").map((n) => n.id)).toEqual(["use-form", "components"]);
+    expect(childrenOf(next, "components").map((n) => n.id)).toEqual(["button", "input"]);
+  });
+
+  it("moves to the top level", () => {
+    const next = applyTreeMove(tree, "input", { parentId: null, index: 2 });
+    expect(next.map((n) => n.id)).toEqual(["src", "readme", "input"]);
+  });
+
+  it("nests into a leaf, creating its children array", () => {
+    const next = applyTreeMove(tree, "readme", { parentId: "index", index: 0 });
+    expect(childrenOf(next, "index").map((n) => n.id)).toEqual(["readme"]);
+  });
+
+  it("refuses to move a node into its own subtree", () => {
+    const next = applyTreeMove(tree, "src", { parentId: "components", index: 0 });
+    expect(next.map((n) => n.id)).toEqual(["src", "readme"]);
+    expect(childrenOf(next, "components").map((n) => n.id)).toEqual(["button", "input"]);
+  });
+
+  it("refuses unknown nodes and unknown targets", () => {
+    expect(applyTreeMove(tree, "missing", { parentId: null, index: 0 }).map((n) => n.id)).toEqual([
+      "src",
+      "readme",
+    ]);
+    expect(
+      applyTreeMove(tree, "readme", { parentId: "missing", index: 0 }).map((n) => n.id),
+    ).toEqual(["src", "readme"]);
+  });
+
+  it("does not mutate the input tree", () => {
+    const snapshot = JSON.stringify(tree);
+    applyTreeMove(tree, "input", { parentId: null, index: 0 });
+    expect(JSON.stringify(tree)).toBe(snapshot);
+  });
+});
+
+describe("announcements", () => {
+  it("announces lift, move, drop with 1-based positions and parent labels", () => {
+    let session = treeKeyboardLift(tree, "input")!;
+    expect(describeTreeDragState("lift", session, tree, "Input.tsx")).toEqual({
+      type: "lift",
+      node: "Input.tsx",
+      parent: "components",
+      position: 2,
+      count: 2,
+    });
+    session = treeKeyboardMove(session, tree, "left");
+    expect(describeTreeDragState("move", session, tree, "Input.tsx")).toEqual({
+      type: "move",
+      node: "Input.tsx",
+      parent: "src",
+      position: 2,
+      count: 4,
+    });
+    expect(describeTreeDragState("drop", session, tree, "Input.tsx")).toMatchObject({
+      type: "drop",
+      parent: "src",
+      position: 2,
+    });
+  });
+
+  it("announces top-level targets with a null parent", () => {
+    const session = treeKeyboardLift(tree, "readme")!;
+    expect(describeTreeDragState("lift", session, tree, "README.md")).toMatchObject({
+      parent: null,
+      position: 2,
+      count: 2,
+    });
+    expect(describeTreeCancel(session, tree, "README.md")).toEqual({
+      type: "cancel",
+      node: "README.md",
+      parent: null,
+    });
+  });
+});