@lovett/ui 0.1.0 → 0.2.3

package/src/sortable.tsx

@@ -9,7 +9,7 @@
  * - <DragHandle> is a Lucide-grip handle pre-wired to the listeners
  */
 
-import { useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
 import {
   DndContext,
@@ -17,11 +17,13 @@ import {
   MeasuringStrategy,
   closestCenter,
   closestCorners,
+  pointerWithin,
   useDroppable,
   KeyboardSensor,
   PointerSensor,
   useSensor,
   useSensors,
+  type CollisionDetection,
   type DragEndEvent,
   type DragOverEvent,
   type DragStartEvent,
@@ -203,15 +205,63 @@ export function DragHandle({
  *     as a click and not a 1px drag
  *
  * Added:
- *   - `closestCorners` rather than `closestCenter`. Center-based collision
- *     mis-resolves when the dragged card is taller than the row it is over,
- *     which is the normal case on a board with variable-height cards.
+ *   - pointer-first collision (`pointerFirstCollision` below), which resolves
+ *     the drop target from the CURSOR and falls back to `closestCorners` when
+ *     there is no cursor. That fallback is not a nicety: it is the keyboard
+ *     drag's only path.
  *   - `MeasuringStrategy.Always`, because a container's height changes as
  *     cards enter and leave it and a cached rect drops the item in the wrong
  *     lane.
  *   - screen-reader announcements naming the destination container, not its id.
  * ========================================================================== */
 
+/**
+ * Pointer first, `closestCorners` second — dnd-kit's documented shape for a
+ * multi-container board (the pointer, then a rect-based fallback; which rect
+ * strategy is the choice made at the bottom of this note), and the answer to
+ * two defects rather than one.
+ *
+ * The history is a ladder, and each rung is still true:
+ *
+ *   `closestCenter` measured the dragged card's CENTRE against each droppable
+ *   and mis-resolved whenever the card was taller than the row it was over,
+ *   which is the normal case on a board with variable-height cards.
+ *
+ *   `closestCorners` measured the card's four CORNERS instead. Better, and
+ *   still wrong in the same family: it measures the CARD. A tall card's
+ *   corners stay nearer its source lane until most of its body has crossed the
+ *   boundary, so the user has to drag the whole card into the destination
+ *   rather than point at it. Reported as "I have to literally drag the full
+ *   entire card over the lane so it catches it".
+ *
+ *   `pointerWithin` measures the POINTER, so a card is caught by the lane the
+ *   cursor is over regardless of how tall the card is. Card height stops being
+ *   an input at all, which is why this does not reintroduce the defect
+ *   `closestCorners` was adopted to fix — it retires the whole measurement.
+ *
+ * `pointerWithin` returns EVERY droppable containing the pointer, ordered by
+ * the pointer's mean distance to that rect's four corners — so the tightest
+ * box around the cursor wins. A pointer inside a card yields [card, column]
+ * and `over` resolves to the card, which is what gives a cross-column drop its
+ * insertion INDEX. A pointer in the column's empty space below the last card
+ * yields just the column, and the item appends. Both are wanted.
+ *
+ * It returns nothing at all when `pointerCoordinates` is null, and dnd-kit
+ * derives those from the activator event's `clientX`/`clientY`. A KeyboardEvent
+ * has neither, so EVERY keyboard drag takes the fallback — a pointer-only
+ * strategy would leave `over` permanently null and break cross-column keyboard
+ * movement silently, gates all green. The fallback is therefore `closestCorners`
+ * and not `rectIntersection`: keyboard drags keep the exact resolution they
+ * have been tested against, and the pointer-outside-every-droppable case (the
+ * board's margins and gutters) keeps resolving to the nearest lane rather than
+ * to nothing. `rectIntersection` would answer that case by area of overlap —
+ * "most of the card", the defect above, back in the gutters.
+ */
+export const pointerFirstCollision: CollisionDetection = (args) => {
+  const byPointer = pointerWithin(args)
+  return byPointer.length > 0 ? byPointer : closestCorners(args)
+}
+
 /** containerId -> the ids it holds, in order. */
 export type SortableContainers = Readonly<Record<string, readonly string[]>>
 
@@ -228,11 +278,30 @@ export interface MultiSortableListProps {
   /** Container ids in board order. Also the set treated as drop targets. */
   containerOrder: readonly string[]
   /**
-   * Commit the move. Called synchronously from the drop handler, so a
-   * `setState` here batches with the primitive's own reset and the board does
-   * not flash the pre-drag arrangement for a frame.
+   * Commit the move. Called from the drop handler with the arrangement the
+   * board is already showing, so the consumer's job is to make `containers`
+   * agree — it is not being asked to produce a frame.
+   *
+   * It used to say "called synchronously ... so a `setState` here batches with
+   * the primitive's own reset". True, and it described the wrong consumer. A
+   * consumer that patches its cache synchronously never saw the ghost; one
+   * that patches from a mutation's `onMutate` — a microtask at best, an
+   * `await cancelQueries` at worst — is not in that batch, and got a frame of
+   * the pre-drag arrangement. See the preview note below for what replaced it.
    */
   onMove: (move: MultiSortableMove, next: SortableContainers) => void
+  /**
+   * Override the drop-target strategy. Defaults to `pointerFirstCollision`,
+   * whose reasoning is in its own docblock.
+   *
+   * A prop because this component has now changed collision strategy twice
+   * (`closestCenter` → `closestCorners` → pointer-first) and both times a
+   * consumer had to wait for a release of this package to get the fix. The
+   * escape hatch costs one optional prop; a third such wait costs a release.
+   * Overriding it is opting out of the reasoning above, including the keyboard
+   * fallback — a bare `pointerWithin` here disables keyboard dragging.
+   */
+  collisionDetection?: CollisionDetection | undefined
   /**
    * What follows the pointer. Without this the card appears to vanish.
    *
@@ -251,9 +320,11 @@ export interface MultiSortableListProps {
    * and the container the drag is currently resolved INTO.
    *
    * The second argument exists because `useDroppable().isOver` cannot answer
-   * it on a board: `closestCorners` resolves `over` to a sortable ITEM
-   * whenever a column holds one, so the column's own droppable never wins and
-   * its `isOver` measured `false` on every column during real pointer AND
+   * it on a board: every collision strategy here resolves `over` to a sortable
+   * ITEM whenever a column holds one — `closestCorners` by distance, and
+   * `pointerWithin` because a pointer inside a card is inside its column too
+   * and the card's centre is nearer — so the column's own droppable never wins
+   * and its `isOver` measured `false` on every column during real pointer AND
    * keyboard drags. The container has to be derived from the resolved `over`
    * id — the same `containerOf` the announcements already use.
    */
@@ -263,6 +334,66 @@ export interface MultiSortableListProps {
   ) => ReactNode
 }
 
+/**
+ * The arrangement the board renders INSTEAD of `containers`, and the thing
+ * `containers` has to catch up to.
+ *
+ * Defect: dropping a card in another lane showed it snap back to its origin
+ * and then forward again — "like an invisible or ghost presence". The old
+ * `handleDragEnd` cleared the preview and then called `onMove`. Clearing means
+ * rendering from `containers`, and `containers` is the consumer's cache, which
+ * at that instant still holds the PRE-DRAG arrangement. One frame in the old
+ * lane, then the consumer's patch lands and moves it again. That frame is the
+ * ghost.
+ *
+ * Reordering the two lines does not fix it. Both are in one discrete event
+ * handler, React flushes that as one batch, and an asynchronous consumer patch
+ * is not in the batch either way — the render it produces still has the
+ * preview cleared and `containers` stale. The fix is not to clear the preview
+ * at the drop at all: hold it, and let the next `containers` supersede it.
+ *
+ * So the preview is held against the exact `containers` value it was committed
+ * over. Any new one means the consumer has spoken — a patch, a rollback, a
+ * refetch, all of them authoritative — and the preview is dropped in the same
+ * render, not a frame later.
+ *
+ * WHEN THE CONSUMER NEVER PATCHES. A held preview is a claim that a move
+ * landed. A consumer that rejects the move, fails its write without rolling
+ * back, or simply ignores `onMove` never produces a new `containers`, and an
+ * unbounded hold would leave the board asserting a move that did not happen —
+ * silently, until something unrelated invalidated the query. So the hold is
+ * bounded: after `PREVIEW_SETTLE_MS` the preview expires and `containers`
+ * wins, which renders as the card returning to its lane. That is the correct
+ * picture of a rejected move, and the only picture available, because the
+ * primitive has no other way to be told.
+ *
+ * The cost is paid by a consumer that commits WITHOUT an optimistic patch and
+ * waits for a server round trip: past the deadline the card returns and then
+ * moves again when the response lands. That is the ghost, delayed — and it is
+ * honest, because a board that does not yet know the move landed should not be
+ * drawing it. The fix for that consumer is an optimistic patch, which is the
+ * pattern this component is shaped around.
+ */
+interface DragPreview {
+  arrangement: SortableContainers
+  /** The `containers` identity this was committed over. A new one supersedes. */
+  basis: SortableContainers
+  /** False while the drag is in flight — a live preview is never superseded. */
+  settled: boolean
+}
+
+/**
+ * How long a settled preview outlives the drop before `containers` wins.
+ *
+ * Floor: dnd-kit's drop animation is 250ms, and the preview has to still be
+ * under the overlay when it lands or the overlay animates onto an empty slot.
+ * Ceiling: a rejected move has to read as rejected rather than as accepted,
+ * and half a second is about where a snap-back stops looking like a response.
+ * The healthy path never reaches either — an optimistic patch supersedes this
+ * in a frame or two, and the timer is cleared.
+ */
+export const PREVIEW_SETTLE_MS = 500
+
 function moveBetween(
   arrangement: SortableContainers,
   itemId: string,
@@ -284,6 +415,7 @@ export function MultiSortableList({
   containers,
   containerOrder,
   onMove,
+  collisionDetection = pointerFirstCollision,
   renderOverlay,
   labelForItem,
   labelForContainer,
@@ -296,11 +428,59 @@ export function MultiSortableList({
 
   const [activeId, setActiveId] = useState<string | null>(null)
   const [overContainerId, setOverContainerId] = useState<string | null>(null)
-  const [preview, setPreview] = useState<SortableContainers | null>(null)
+  const [preview, setPreview] = useState<DragPreview | null>(null)
   // The arrangement the drag started from, so a cancel restores it exactly.
   const originRef = useRef<SortableContainers | null>(null)
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (settleTimer.current !== null) clearTimeout(settleTimer.current)
+    },
+    [],
+  )
+
+  const stopSettleTimer = () => {
+    if (settleTimer.current !== null) {
+      clearTimeout(settleTimer.current)
+      settleTimer.current = null
+    }
+  }
+
+  // Derived, not stored: on the render where `containers` finally carries the
+  // move, the board is already right — no second commit, no frame in between.
+  const superseded = preview !== null && preview.settled && preview.basis !== containers
+  const arrangement = preview !== null && !superseded ? preview.arrangement : containers
 
-  const arrangement = preview ?? containers
+  // And a supersede is FINAL. `containers` can return to the exact object the
+  // preview was held against — a rolled-back optimistic write restores the
+  // previous reference, not a copy of it — and a preview still sitting in state
+  // would then stop looking superseded and draw the move a second time, after
+  // the consumer had undone it. Dropping it here rather than in an effect keeps
+  // that to zero frames: React re-runs this render with the state already gone.
+  // The pending timer is left to fire into a null preview, where it is a no-op.
+  if (superseded) setPreview(null)
+
+  /**
+   * Show `next` until `containers` says otherwise. Called at every exit from a
+   * drag — committed, no-op, dropped outside, cancelled — so there is exactly
+   * one place where the board stops previewing.
+   *
+   * `next === containers` covers the ordinary cancel: the board is already
+   * rendering the truth, so there is nothing to hold and no timer to run.
+   */
+  const holdPreview = (next: SortableContainers) => {
+    stopSettleTimer()
+    if (next === containers) {
+      setPreview(null)
+      return
+    }
+    setPreview({ arrangement: next, basis: containers, settled: true })
+    settleTimer.current = setTimeout(() => {
+      settleTimer.current = null
+      setPreview(null)
+    }, PREVIEW_SETTLE_MS)
+  }
 
   const containerOf = (id: string): string | null => {
     if (containerOrder.includes(id)) return id
@@ -316,8 +496,14 @@ export function MultiSortableList({
   const handleDragStart = (event: DragStartEvent) => {
     const id = String(event.active.id)
     setActiveId(id)
-    originRef.current = containers
-    setPreview(containers)
+    stopSettleTimer()
+    // `arrangement`, not `containers`. A previous drop may still be held while
+    // its consumer patch is in flight, and rebasing on `containers` here would
+    // yank that card back to its old lane the moment the user picks up the
+    // next one — the ghost again, one drag later. The drag starts from what is
+    // on screen, which is also what the user is dragging.
+    originRef.current = arrangement
+    setPreview({ arrangement, basis: containers, settled: false })
     // The card starts over its own column, so the drop target is lit from the
     // first frame rather than only once the pointer crosses a boundary.
     setOverContainerId(containerOf(id))
@@ -341,7 +527,11 @@ export function MultiSortableList({
     const overItems = arrangement[to] ?? []
     const overIndex = overItems.indexOf(overId)
     const index = overIndex === -1 ? overItems.length : overIndex
-    setPreview(moveBetween(arrangement, itemId, from, to, index))
+    setPreview({
+      arrangement: moveBetween(arrangement, itemId, from, to, index),
+      basis: containers,
+      settled: false,
+    })
   }
 
   const handleDragEnd = (event: DragEndEvent) => {
@@ -355,8 +545,11 @@ export function MultiSortableList({
     setOverContainerId(null)
     originRef.current = null
 
+    // Dropped outside every column, or an id the origin does not hold. Nothing
+    // is committed, so nothing will patch: the board goes back to what it was
+    // showing when the drag began.
     if (!over || !from) {
-      setPreview(null)
+      holdPreview(origin)
       return
     }
 
@@ -367,22 +560,33 @@ export function MultiSortableList({
     const index = overIndex === -1 ? overItems.length : overIndex
     const next = moveBetween(origin, itemId, from, to, index)
 
-    setPreview(null)
-    if (from === to && (origin[from] ?? []).indexOf(itemId) === index) return
+    // Same lane, same slot. No `onMove`, therefore no patch to wait for.
+    if (from === to && (origin[from] ?? []).indexOf(itemId) === index) {
+      holdPreview(origin)
+      return
+    }
+
+    // Hold BEFORE handing over. The primitive's own state is then complete and
+    // consistent whatever `onMove` does, including throw.
+    holdPreview(next)
     onMove({ itemId, fromContainerId: from, toContainerId: to, toIndex: index }, next)
   }
 
   const handleDragCancel = () => {
     setActiveId(null)
     setOverContainerId(null)
+    const origin = originRef.current ?? containers
     originRef.current = null
-    setPreview(null)
+    // Not `setPreview(null)`: clearing renders `containers`, which is only the
+    // right answer when the drag started from it. If a previous drop is still
+    // held, cancelling this one must return to THAT, not undo both.
+    holdPreview(origin)
   }
 
   return (
     <DndContext
       sensors={sensors}
-      collisionDetection={closestCorners}
+      collisionDetection={collisionDetection}
       measuring={{ droppable: { strategy: MeasuringStrategy.Always } }}
       onDragStart={handleDragStart}
       onDragOver={handleDragOver}
@@ -424,11 +628,12 @@ export function MultiSortableList({
  * accent (design brief §4), and only the consumer knows what its border is.
  *
  * `isOver` here is `useDroppable`'s raw answer and is NOT the board's drag-over
- * signal: with `closestCorners`, `over` resolves to a sortable item whenever
- * the column holds one, so this reads `false` for the column the card is
- * actually over. It is kept because the droppable registration is what makes an
- * EMPTY column a drop target at all. The state a consumer should paint comes
- * from `MultiSortableList`'s `overContainerId`.
+ * signal: `over` resolves to a sortable item whenever the column holds one, so
+ * this reads `false` for the column the card is actually over. It is kept
+ * because the droppable registration is what makes an EMPTY column a drop
+ * target at all — and, under pointer-first collision, what makes the column's
+ * empty space below the last card a target for an append. The state a consumer
+ * should paint comes from `MultiSortableList`'s `overContainerId`.
  */
 export function SortableDropZone({
   id,

package/src/styles.css

@@ -956,7 +956,13 @@
   display: flex;
   flex-direction: column;
   gap: var(--space-2);
-  min-block-size: 96px;
+  /* 96px is the OUTER floor, and `min-block-size` is a border-box one — so it
+     carries the block-start compensation below, which lives outside the border
+     box. Without the `+ --space-1` an empty lane in a content-sized board
+     (the only layout where this floor binds at all; a stretched board takes
+     its height from the grid row) drew its frame 4px shorter than before.
+     Measured: column 154px -> 150px, with the empty message itself unmoved. */
+  min-block-size: calc(96px + var(--space-1));
   /* Overridable by the consuming surface. Capping it is what produces the
      next-card peek instead of an infinitely tall column. Declared here rather
      than spelled as a `var(--x, fallback)` so the token-shape guard can still
@@ -968,6 +974,52 @@
   max-block-size: var(--board-column-max-block-size);
   flex: 1 1 auto;
   overflow-y: auto;
+
+  /* THE LANE IS A CLIP, AND A CARD PAINTS OUTSIDE ITSELF.
+   *
+   * `overflow-y: auto` here does not clip one axis. A `visible` companion is
+   * coerced to `auto` — the same rule `.ds-board-scroller` above declares
+   * `overflow-y: hidden` to dodge — so this box clips INLINE as well. That is
+   * why the reserve below is four-sided and not a top inset: with zero padding
+   * the clip edge WAS the card's own border box, so every card lost shadow
+   * left and right, the top one lost its hover lift into the header gap, and
+   * the last one lost its shadow at the scroll end. Owner, in a browser, 2026-
+   * 09-09: the lift is sliced. Nothing typecheck, lint, build or the suite
+   * reads can see a sliced shadow, and jsdom has no layout to measure one.
+   *
+   * `scroll-padding-block-end` below is NOT this and never was. It positions
+   * where `scrollIntoView` lands. It reserves no paint room whatsoever.
+   *
+   * The reserve is READ OFF the shadow tokens, not guessed. A shadow paints
+   * `|offset| + spread + blur/2` past the border box, so the hover step
+   * --shadow-md reaches furthest in the theme where it is a plain
+   * `0 4px 12px`: 6px inline, 2px block-start, 10px block-end. The hover
+   * `translateY(-1px)` lifts all of that one pixel, taking block-start to 3.
+   * Rounded up onto the spacing scale: 8 / 4 / 12. A value off the scale would
+   * mean the scale is wrong; these are on it.
+   *
+   * Inline and block-start are pulled straight back by an equal NEGATIVE
+   * margin, so this box grows outward into the column's own --space-2 padding
+   * and not one card moves. That is the entire requirement — paint room
+   * without repositioning the lane's resting composition. The side effect is
+   * an improvement: an overlay vertical scrollbar now floats over the reserve
+   * instead of over the cards.
+   *
+   * Block-end takes no such margin, deliberately, and this is where the
+   * scroller's note at ~:839 is respected rather than overruled. 12px exceeds
+   * the column's 8px of bottom padding, so pulling back would drive this box
+   * through the column's border AND consume the 8px that note keeps clear for
+   * an overlay HORIZONTAL scrollbar to float over — the one thing it asks for.
+   * Uncompensated trailing padding on a scroll container costs nothing at
+   * rest, because `flex: 1 1 auto` already makes this box taller than its
+   * content; it surfaces only at the bottom of a scrolled lane, where it reads
+   * as the end of the list rather than as a gap. */
+  padding-inline: var(--space-2);
+  margin-inline: calc(var(--space-2) * -1);
+  padding-block-start: var(--space-1);
+  margin-block-start: calc(var(--space-1) * -1);
+  padding-block-end: var(--space-3);
+
   scroll-padding-block-end: var(--space-6);
 }
 

package/src/theme-v2.css

@@ -158,6 +158,19 @@
      against its surface, under the 3:1 WCAG 2.2 SC 2.4.11 asks of a focus
      indicator. See the note on --ring-focus in tokens.css. */
   --ring-focus: 0 0 0 2px rgb(var(--accent));
+  /* The SAME ring, painted inward. An outset box-shadow is clipped by ANY
+     ancestor with a non-visible overflow, and when that happens the focus
+     indicator does not degrade — it disappears, which is a WCAG 2.4.7 failure
+     rather than a cosmetic one.
+     Use this at a clipping boundary: inside a scroll container, inside the
+     `overflow-hidden` a grid-rows reveal needs, inside a Card that keeps its
+     default clip. It cannot be clipped by an ancestor because it paints inside
+     the element's own border box.
+     Found the long way on 2026-09-09: the reply composer, the reaction chips
+     and the GIF picker all lost their ring, and `thread.tsx` had already been
+     forced to override a Card's `overflow-hidden` to `overflow-visible` to keep
+     one. That override is the cost this token removes. */
+  --ring-focus-inset: inset 0 0 0 2px rgb(var(--accent));
   --ring-error: 0 0 0 2px rgb(var(--destructive));
 }
 
@@ -225,4 +238,17 @@
   --inset-highlight: 255 255 255 / 0.05;
   --modal-overlay: 0 0 0 / 0.7;
   --ring-focus: 0 0 0 2px rgb(var(--accent));
+  /* The SAME ring, painted inward. An outset box-shadow is clipped by ANY
+     ancestor with a non-visible overflow, and when that happens the focus
+     indicator does not degrade — it disappears, which is a WCAG 2.4.7 failure
+     rather than a cosmetic one.
+     Use this at a clipping boundary: inside a scroll container, inside the
+     `overflow-hidden` a grid-rows reveal needs, inside a Card that keeps its
+     default clip. It cannot be clipped by an ancestor because it paints inside
+     the element's own border box.
+     Found the long way on 2026-09-09: the reply composer, the reaction chips
+     and the GIF picker all lost their ring, and `thread.tsx` had already been
+     forced to override a Card's `overflow-hidden` to `overflow-visible` to keep
+     one. That override is the cost this token removes. */
+  --ring-focus-inset: inset 0 0 0 2px rgb(var(--accent));
 }

package/src/thread/__tests__/fixtures/thread-fixture.ts

@@ -11,6 +11,9 @@
  *   • 8 replies on one parent              — 3 visible, 5 hidden (D-port)
  *   • a DELETED parent with live children  — D4, the tombstone that keeps its
  *                                            subtree instead of orphaning it
+ *   • a MODERATED tombstone                — FU-0032, the second way a comment
+ *                                            becomes one; `moderated` is all
+ *                                            that separates it from the first
  *   • a reply whose parent is ABSENT       — D4's other half: "not fetched" is
  *                                            not "deleted", and must be labelled
  *   • a pending and a failed send          — D17
@@ -143,6 +146,20 @@ export const THREAD_FIXTURE: readonly ThreadComment[] = [
     createdAt: ago(4 * HOUR + 20 * MINUTE),
   },
 
+  // ── FU-0032: a tombstone somebody ELSE made. Structurally identical to
+  //    the one above — same blanked body, same `deletedAt` — and `moderated`
+  //    is the entire difference, which is the point: without it the two are
+  //    the same row and the reader is told the wrong thing about one of them.
+  //    The author is still withheld, and the wire never carries who removed it.
+  {
+    id: 'c-moderated',
+    author: { id: 'usr_kai', name: 'Kai Moreau' },
+    bodyMd: '',
+    createdAt: ago(5 * HOUR + 30 * MINUTE),
+    deletedAt: ago(3 * HOUR),
+    moderated: true,
+  },
+
   // ── D4's other half: the parent is ABSENT from this page, not deleted. ──
   {
     id: 'c-orphan',