@lovett/ui 0.0.11 → 0.2.0

package/src/detail/detail-surface.tsx

@@ -0,0 +1,1110 @@
+/**
+ * DetailSurface — one item, three modes, one DOM.
+ *
+ * `docs/design-briefs/tasks-item-detail-full.md` §1:
+ *
+ *   full   default; near-full-screen with a margin, so the board stays
+ *          faintly visible behind it. NOT a takeover.
+ *   modal  a smaller centred window.
+ *   panel  a right side panel.
+ *
+ * ## Why this is not `Modal` for two of them and `FloatingDrawer` for the third
+ *
+ * That was the first shape tried, and the brief kills it in one line:
+ * "Switching modes must not lose the open item, the active tab, scroll
+ * position, or an in-progress edit." Swapping which PRIMITIVE holds the
+ * content unmounts the content — React reconciles by position under a parent,
+ * and `<Modal>` and `<FloatingDrawer>` are different parents. Everything
+ * living below the swap dies with it: the active tab, both scrollers, and
+ * every half-typed field editor. The predecessor
+ * (`lenses/tasks/components/detail/item-detail-surface.tsx`) paid for this by
+ * hoisting the title and description drafts into the frame chooser and
+ * re-applying `scrollTop` in a layout effect after every reframe — and that
+ * still only covered the two edits it knew the names of. With five field
+ * editors, an activity tab and two scrollers, that approach does not scale;
+ * it just moves the loss somewhere less obvious.
+ *
+ * So the frame is ONE element tree in every mode, and the mode changes only
+ * positioning, size and flex direction. Nothing unmounts, so nothing is
+ * hoisted, so nothing is lost — the requirement is satisfied structurally
+ * rather than by a list of state to remember.
+ *
+ * That does mean this file owns dialog mechanics `Modal` already owns, so it
+ * borrows the same pieces rather than reimplementing them: `useLayer` for
+ * topmost-wins Escape, `tabbablesWithin` for the trap, `.ds-card-surface` for
+ * the chrome. What is genuinely new here is the framing, and the framing is
+ * the part neither primitive could express.
+ *
+ * ## Orientation follows the mode
+ *
+ * `detailPaneSide()` — activity at the inline end in `full` and `modal`, below
+ * in `panel`, with the divider turning with it. There is no second setting to
+ * disagree with the mode.
+ *
+ * ## Modality
+ *
+ * `full` and `modal` are modal: a backdrop, a focus trap. `panel` is not —
+ * the board stays legible and operable beside it, which is the whole point of
+ * the shape — so it has no backdrop and no trap, and answers Escape through
+ * the shared layer stack so a select opened inside it closes first.
+ *
+ * The dialog is ALWAYS MOUNTED and driven by `open` (§8). Closed it is
+ * `inert`, so an off-screen panel is neither a stray dialog in the
+ * accessibility tree nor a set of stray tab stops.
+ *
+ * ## The split's bounds are the CONTAINER's, not a constant
+ *
+ * The first version expressed the constraint on one pane only: the activity
+ * pane had a `min` and a `max` in absolute px, and the fields pane was
+ * `flex-1 min-w-0` — which is to say it had no minimum at all and would shrink
+ * to nothing. In `modal` mode (840px at most) an activity pane at its legal
+ * 720 left the fields ~116px, and the label column alone is 132px; the value
+ * column went negative and every value wrapped to about four characters
+ * ("Aug 22, 202", "Set star date"). An absolute maximum cannot know that.
+ *
+ * So the bounds are RECOMPUTED from the measured split — the aside may grow to
+ * `container − FIELDS_MIN − the divider`, and no further, in every mode and at
+ * every viewport. A `ResizeObserver` is what makes that hold: `full` / `modal`
+ * / `panel` and the viewport all change the container, and none of them is a
+ * React render this component can hook. The divider is handed the DERIVED
+ * bounds, so it cannot be dragged into a state the layout will not honour —
+ * the constraint is enforced where the gesture happens, not repaired after it.
+ *
+ * The fields pane still degrades below that floor rather than colliding: the
+ * field row stacks its label above its value under a container query, and
+ * every value truncates. See `field-row.tsx` and the `ds-field-list` block in
+ * styles.css.
+ *
+ * ## The PANEL has an outer edge, and it obeys the same rule
+ *
+ * `panel` mode's width was a hardcoded `max-inline-size: 560px`. That is fine
+ * at 1512 and wrong on a laptop — 560 of side panel plus a 308px rail leaves a
+ * 1024px screen 144px of board, which is half a lane. So the panel's leading
+ * edge is a `ResizableHandle` too, and its ceiling is derived the same way the
+ * split's is: MEASURED wrapper less a reserve the host declares, recomputed by
+ * a `ResizeObserver` on the wrapper, so the board keeps a whole lane beside it
+ * at every viewport. Its floor is the panel's own content minimum (`PANEL_MIN`
+ * — the header's non-shrinking cluster), never an arbitrary number.
+ *
+ * The two resizes are INDEPENDENT and both live: the outer one moves the
+ * panel's leading edge, the inner one moves the seam between the fields and
+ * the activity pane. Only `panel` mode draws the outer one — `full` and
+ * `modal` are centred overlays already sized against the viewport.
+ *
+ * Note which axis each governs, because it is the thing that looks like a bug
+ * and is not: in `panel` mode the split is a COLUMN, so the inner divider's
+ * bounds are derived from the container's HEIGHT and the outer drag does not
+ * move them. What the outer drag does move is the fields pane's INLINE size,
+ * and the collision that lives there — the value column falling under its
+ * 256px floor — is held off by `PANEL_MIN`, not by the split's clamp. The
+ * split's observer still watches the same box and re-derives from whatever it
+ * reports, so neither clamp is ever computed once and left stale.
+ *
+ * ## Collapsing a pane must not unmount it
+ *
+ * The whole reason this is one element tree is that state survives. A collapse
+ * that swapped a pane for `null` would throw away exactly what a mode switch
+ * is careful to keep — the scroll, the drafts, the active tab — so it is a
+ * SIZE change, not a conditional render.
+ *
+ * It is two boxes per pane, and that is load-bearing rather than decorative.
+ * The OUTER box is what collapses, to zero, with `overflow: hidden`. The INNER
+ * box keeps an explicit pixel size, so the collapsed pane's content is laid out
+ * at exactly the width it had a moment ago — which is what preserves
+ * `scrollTop`. Collapse the pane by shrinking the scroller itself and its
+ * content reflows to zero width, its `scrollHeight` collapses with it, and the
+ * browser clamps the scroll position to nothing; restoring then lands the
+ * operator at the top of a conversation they had scrolled halfway down.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from 'react'
+import { ChevronsDown, ChevronsLeft, ChevronsRight, ChevronsUp } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { tabbablesWithin } from '../lib/focus'
+import { useLayer } from '../lib/layer-stack'
+import { ResizableHandle } from '../resizable'
+import { DetailDivider } from './detail-divider'
+import {
+  DETAIL_PANEL_DEFAULT_SIZE,
+  detailPaneSide,
+  type DetailCollapse,
+  type DetailMode,
+  type DetailPaneSide,
+} from './types'
+
+/** Per-orientation defaults for the activity pane, in px. */
+const DEFAULT_ASIDE_SIZE: Readonly<Record<DetailPaneSide, number>> = {
+  side: 400,
+  bottom: 260,
+}
+
+const DEFAULT_ASIDE_MIN: Readonly<Record<DetailPaneSide, number>> = {
+  side: 280,
+  bottom: 160,
+}
+
+/**
+ * The ceiling the OPERATOR is offered, before the container has its say. The
+ * effective maximum is the smaller of this and what the fields pane can spare;
+ * see `boundsFor`.
+ */
+const DEFAULT_ASIDE_MAX: Readonly<Record<DetailPaneSide, number>> = {
+  side: 720,
+  bottom: 560,
+}
+
+/**
+ * What the FIELDS pane may never go below, per orientation. The number the
+ * whole clamp is built on, so it is derived from the row rather than picked:
+ *
+ *   side    288px. The field list pads `--space-4` each side (32), leaving
+ *           256px of content. Below 400px the row STACKS — label above value,
+ *           full width — so 256px is the value column outright, which is about
+ *           30 characters at the row's 13px. Side by side above 400px the same
+ *           256px is what is left after the tightened 104px label and the 8px
+ *           gap, so the value column lands on 256 from both directions and
+ *           never goes under it at any divider position. That is the fix: not
+ *           "a bit more room", a floor the value column cannot fall through.
+ *   bottom  200px. A height, and a different question: the list's toolbar is
+ *           ~48px, so this is the toolbar plus roughly four rows — enough for
+ *           the pane to read as a list rather than as a sliver.
+ */
+const FIELDS_MIN: Readonly<Record<DetailPaneSide, number>> = {
+  side: 288,
+  bottom: 200,
+}
+
+/**
+ * The divider strip, px — `w-1` / `h-1` in `detail-divider.tsx`. It sits
+ * BETWEEN the panes and therefore comes out of the container before either of
+ * them is measured.
+ */
+const DIVIDER_SIZE = 4
+
+/**
+ * The rail a collapsed pane leaves behind, px — `--space-6`, and the same 24
+ * the thread's collapse rail uses for the same reason: it is the interface
+ * standards' minimum target, and a rail thinner than that is a hairline
+ * pretending to be a control.
+ *
+ * It is IN FLOW rather than floating. The first pass pinned a round pill to
+ * the split's top corner and it landed on top of the field list's search and
+ * filter row — chrome overlapping chrome, which is the layout-stability rule
+ * from the other side: reserve the space, do not park something over content.
+ */
+const RESTORE_RAIL_SIZE = 24
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.max(low, Math.min(high, value))
+}
+
+/**
+ * The bounds the divider actually gets.
+ *
+ * `container` is null until the observer has measured — before first layout,
+ * and in any environment without a `ResizeObserver`. There the absolute bounds
+ * stand, which is the behaviour this component already had.
+ *
+ * The order matters when the container is too small to satisfy both panes: the
+ * FIELDS floor wins and the aside takes what is left, down to nothing, rather
+ * than the two of them overflowing a panel that clips. `min` is pulled down to
+ * `max` in that case, because a separator whose minimum exceeds its maximum
+ * describes a range that does not exist.
+ */
+function boundsFor(
+  container: number | null,
+  side: DetailPaneSide,
+  min: number,
+  max: number,
+): { readonly min: number; readonly max: number } {
+  if (container === null) return { min, max }
+  // Floored: `contentRect` is fractional on a scaled display, and a separator
+  // reporting `aria-valuemax="252.90625"` is both unreadable to a screen
+  // reader and a subpixel over the floor it is supposed to protect.
+  const room = Math.floor(container - FIELDS_MIN[side] - DIVIDER_SIZE)
+  const effectiveMax = Math.max(Math.min(max, room), 0)
+  return { min: Math.min(min, effectiveMax), max: effectiveMax }
+}
+
+/**
+ * What the PANEL may never be dragged below in `panel` mode, px — its own
+ * content minimum, derived from the widest thing it holds rather than picked.
+ *
+ * That thing is the HEADER, not the field list. Measured on the running lens,
+ * its non-shrinking cluster is 365px: mark-complete (110) + "Updated ‹when›"
+ * (75) + prev / next (68) + star, ellipsis and close (32 each), six
+ * `--space-2` gaps (48), and `--space-4` of inline padding either side (32).
+ * The title is the only flexible child, so under 365 the header stops fitting
+ * and the panel's `overflow: hidden` eats controls from the end — the close
+ * button first, which is a trap rather than a tight layout.
+ *
+ * 400 is that floor plus enough for the title to still read as a field, and it
+ * is also the width at which `FieldRow` stacks its label above its value: at
+ * and below it the value column is the full content width (~368px), well over
+ * the 256px floor `FIELDS_MIN` protects on the other axis. So neither
+ * collision is reachable by dragging the edge.
+ */
+const PANEL_MIN = 400
+
+/**
+ * How much inline space must stay clear beside the panel when the host does
+ * not say, px. One board lane at its floor (`grid-auto-columns: minmax(288px,
+ * 1fr)`) plus a `--space-4` gutter either side.
+ *
+ * It is a RESERVE rather than a constant maximum because 560px is fine at
+ * 1512 and wrong on a laptop: the ceiling has to be the viewport's answer, not
+ * a number. A host whose content sits behind a fixed rail passes its own
+ * `panelReserve` — this component measures the viewport, not what is under it,
+ * and 320px of viewport is not 320px of board when a 308px rail holds the left
+ * edge.
+ */
+const DEFAULT_PANEL_RESERVE = 320
+
+/**
+ * `ResizableHandle`'s own cross-axis hit padding, px — it widens the 4px line
+ * to an 8px target and pulls itself back by the same amount so the line stays
+ * centred on the edge it decorates.
+ *
+ * The panel's leading edge is the one place that pull-back would be thrown
+ * away: half the target would sit outside `overflow: hidden` and be clipped,
+ * leaving 6px to grab. So the strip is offset by it, and the whole 8px lands
+ * inside the panel. Mirrored rather than imported because it is the handle's
+ * internal geometry, not a shared measure.
+ */
+const HANDLE_HIT_PAD = 2
+
+/**
+ * The bounds the panel's leading edge actually gets.
+ *
+ * `available` is null until the wrapper has been measured — before first
+ * layout, and in any environment without a `ResizeObserver`. There the panel
+ * keeps the fixed geometry it has always had.
+ *
+ * The order matches `boundsFor`, and for the same reason: when the viewport
+ * cannot afford both the panel's floor and the reserve, the reserve wins and
+ * the minimum is pulled down to the maximum, because a separator whose minimum
+ * exceeds its maximum describes a range that does not exist.
+ */
+function panelBoundsFor(
+  available: number | null,
+  reserve: number,
+): { readonly min: number; readonly max: number } {
+  if (available === null) {
+    return { min: PANEL_MIN, max: Math.max(PANEL_MIN, DETAIL_PANEL_DEFAULT_SIZE) }
+  }
+  // Floored for the same reason `boundsFor` floors: `contentRect` is
+  // fractional on a scaled display, and `aria-valuemax="879.328125"` is
+  // unreadable to a screen reader.
+  const max = Math.max(Math.floor(available - reserve), 0)
+  return { min: Math.min(PANEL_MIN, max), max }
+}
+
+/**
+ * The margin that keeps `full` from being a takeover, and the geometry of the
+ * other two. Sizes are `min()`-clamped against the viewport so the panel can
+ * never exceed the space its margin leaves.
+ */
+const PANEL_GEOMETRY: Readonly<Record<DetailMode, CSSProperties>> = {
+  full: {
+    inlineSize: '100%',
+    maxInlineSize: '1280px',
+    blockSize: '100%',
+  },
+  modal: {
+    inlineSize: '100%',
+    maxInlineSize: '840px',
+    blockSize: 'min(720px, 100%)',
+  },
+  // `inlineSize` is REPLACED by the measured width below; what is here is the
+  // pre-measurement fallback, and it is the size the mode had before its
+  // leading edge became draggable. `maxInlineSize` stays as the last-resort
+  // guard: a stored width from a wider monitor can never overflow the wrapper
+  // even for the frame before the observer reports.
+  panel: {
+    inlineSize: `${DETAIL_PANEL_DEFAULT_SIZE}px`,
+    maxInlineSize: '100%',
+    blockSize: '100%',
+  },
+}
+
+const WRAPPER_PADDING: Readonly<Record<DetailMode, string>> = {
+  full: 'var(--space-6)',
+  modal: 'var(--space-6)',
+  panel: 'var(--space-3)',
+}
+
+export interface DetailSurfaceProps {
+  /** Drive the dialog with this. NEVER conditionally render the surface (§8). */
+  open: boolean
+  mode: DetailMode
+  onClose: () => void
+  /** Names the dialog. There is no `<h2>` of our own to point at. */
+  ariaLabel: string
+  /** The header row — a `<DetailHeader>`. Spans the full width above the split. */
+  header?: ReactNode | undefined
+  /** The fields pane. */
+  children: ReactNode
+  /** The activity pane. Omitted, the surface renders no divider and no pane. */
+  aside?: ReactNode | undefined
+  /**
+   * Size of the activity pane along the split axis, px. Controlled when
+   * supplied — and it is per-ORIENTATION, which is why the change handler is
+   * told which side it is reporting: 400px of width is not 400px of height.
+   */
+  asideSize?: number | undefined
+  onAsideSizeChange?: ((next: number, side: DetailPaneSide) => void) | undefined
+  /** Fires once on release / keypress. Persist from here, not the change. */
+  onAsideSizeCommit?: ((next: number, side: DetailPaneSide) => void) | undefined
+  /**
+   * The bounds the operator is OFFERED. Both are narrowed further against the
+   * measured container so the fields pane keeps its floor — passing a large
+   * `asideMax` cannot squeeze the fields to nothing.
+   */
+  asideMin?: number | undefined
+  asideMax?: number | undefined
+  /**
+   * Which pane is collapsed. Controlled when supplied, and per-ORIENTATION for
+   * the same reason the size is — the handler is told which side it reports.
+   */
+  collapsed?: DetailCollapse | undefined
+  onCollapsedChange?: ((next: DetailCollapse, side: DetailPaneSide) => void) | undefined
+  /** Names what the divider resizes. Default "Resize the activity pane". */
+  dividerLabel?: string | undefined
+  /**
+   * `panel` MODE ONLY: the panel's own width along the inline axis, px.
+   * Controlled when supplied. `full` and `modal` ignore every `panel*` prop —
+   * they are centred overlays whose size is already viewport-relative, and
+   * they render no edge handle at all.
+   */
+  panelSize?: number | undefined
+  onPanelSizeChange?: ((next: number) => void) | undefined
+  /** Fires once on release / keypress. Persist from here, not the change. */
+  onPanelSizeCommit?: ((next: number) => void) | undefined
+  /**
+   * How much inline space must stay clear beside the panel, px — the panel's
+   * effective maximum is the measured wrapper less this. Default
+   * `DEFAULT_PANEL_RESERVE`; a host whose content sits behind a fixed rail
+   * should pass the rail's width plus whatever its own content needs.
+   *
+   * Measured INSIDE this component's padding box, so a reserve derived from a
+   * viewport-relative offset is conservative by one gutter — which errs toward
+   * leaving the host MORE room, never less.
+   */
+  panelReserve?: number | undefined
+  /** Names the panel's own edge handle. Default "Resize the panel". */
+  panelResizeLabel?: string | undefined
+  /** On the dialog panel. */
+  className?: string | undefined
+}
+
+export function DetailSurface({
+  open,
+  mode,
+  onClose,
+  ariaLabel,
+  header,
+  children,
+  aside,
+  asideSize,
+  onAsideSizeChange,
+  onAsideSizeCommit,
+  asideMin,
+  asideMax,
+  collapsed,
+  onCollapsedChange,
+  dividerLabel = 'Resize the activity pane',
+  panelSize,
+  onPanelSizeChange,
+  onPanelSizeCommit,
+  panelReserve,
+  panelResizeLabel = 'Resize the panel',
+  className,
+}: DetailSurfaceProps) {
+  const wrapperRef = useRef<HTMLDivElement | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const splitRef = useRef<HTMLDivElement | null>(null)
+  const side = detailPaneSide(mode)
+  const isModal = mode !== 'panel'
+  const isPanel = !isModal
+  const vertical = side === 'side'
+
+  /* ---- the activity pane's size, per orientation ------------------ */
+
+  // Uncontrolled state is a RECORD, not a number: the two orientations are
+  // different measurements and carrying one value across the switch would
+  // hand a 400px-wide pane's width to a pane that is now a height.
+  const [internalSize, setInternalSize] =
+    useState<Record<DetailPaneSide, number>>(DEFAULT_ASIDE_SIZE)
+  const controlled = asideSize !== undefined
+  const requested = controlled ? asideSize : internalSize[side]
+  const min = asideMin ?? DEFAULT_ASIDE_MIN[side]
+  const max = asideMax ?? DEFAULT_ASIDE_MAX[side]
+
+  /* ---- what the container will actually allow ---------------------- */
+
+  // Measured rather than derived: `full` / `modal` / `panel` and the viewport
+  // all change this box, and none of them is a render this component sees.
+  // A zero is ignored — that is a box with no layout yet, not a real
+  // measurement, and treating it as one would clamp the split to nothing on
+  // the frame before first paint.
+  const [containerSize, setContainerSize] = useState<number | null>(null)
+  useEffect(() => {
+    const node = splitRef.current
+    if (node === null) return
+    if (typeof ResizeObserver === 'undefined') return
+    // The reading in hand measured the OTHER axis if the orientation just
+    // changed. Dropped here rather than in an effect of its own, because two
+    // effects run in declaration order and the second would undo the first's
+    // fresh measurement on every re-run.
+    setContainerSize(null)
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (entry === undefined) return
+      const measured = vertical ? entry.contentRect.width : entry.contentRect.height
+      if (measured > 0) setContainerSize(measured)
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [vertical])
+
+  const bounds = useMemo(
+    () => boundsFor(containerSize, side, min, max),
+    [containerSize, side, min, max],
+  )
+  const size = clamp(requested, bounds.min, bounds.max)
+
+  const setSize = useCallback(
+    (next: number) => {
+      if (!controlled) setInternalSize((current) => ({ ...current, [side]: next }))
+      onAsideSizeChange?.(next, side)
+    },
+    [controlled, onAsideSizeChange, side],
+  )
+
+  const commitSize = useCallback(
+    (next: number) => {
+      onAsideSizeCommit?.(next, side)
+    },
+    [onAsideSizeCommit, side],
+  )
+
+  /* ---- the panel's own width, `panel` mode only -------------------- */
+
+  // Uncontrolled state is a single number rather than a record: unlike the
+  // split, there is only one panel geometry — `full` and `modal` are centred
+  // overlays and never read it.
+  const [internalPanelSize, setInternalPanelSize] = useState(DETAIL_PANEL_DEFAULT_SIZE)
+  const panelControlled = panelSize !== undefined
+  const requestedPanel = panelControlled ? panelSize : internalPanelSize
+
+  // The wrapper is `inset: 0`, so its content box IS the viewport less this
+  // mode's padding. MEASURED, not read off `window`: the same observer then
+  // answers a viewport resize, a mode change and a zoom step, and there is no
+  // second copy of "how wide is it" for the two to disagree about.
+  //
+  // Cleared when the mode leaves `panel` so the reading in hand can never be
+  // the wrong layout's — the same discipline the split's observer applies on
+  // an orientation change.
+  const [availableSize, setAvailableSize] = useState<number | null>(null)
+  useEffect(() => {
+    if (!isPanel) {
+      setAvailableSize(null)
+      return
+    }
+    const node = wrapperRef.current
+    if (node === null) return
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (entry === undefined) return
+      const measured = entry.contentRect.width
+      // A zero is a box with no layout yet, not a measurement.
+      if (measured > 0) setAvailableSize(measured)
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [isPanel])
+
+  const panelBounds = useMemo(
+    () => panelBoundsFor(availableSize, panelReserve ?? DEFAULT_PANEL_RESERVE),
+    [availableSize, panelReserve],
+  )
+  // CLAMPED at render rather than written back to the host. A bound that moves
+  // with the viewport is not a reason to throw away a stored preference: shrink
+  // the window and the panel comes down to the ceiling, widen it again and the
+  // operator's own width returns.
+  const panelWidth = clamp(requestedPanel, panelBounds.min, panelBounds.max)
+
+  const setPanelWidth = useCallback(
+    (next: number) => {
+      if (!panelControlled) setInternalPanelSize(next)
+      onPanelSizeChange?.(next)
+    },
+    [panelControlled, onPanelSizeChange],
+  )
+
+  const commitPanelWidth = useCallback(
+    (next: number) => {
+      onPanelSizeCommit?.(next)
+    },
+    [onPanelSizeCommit],
+  )
+
+  /* ---- which pane is collapsed, per orientation -------------------- */
+
+  const [internalCollapsed, setInternalCollapsed] = useState<
+    Record<DetailPaneSide, DetailCollapse>
+  >({ side: 'none', bottom: 'none' })
+  const collapseControlled = collapsed !== undefined
+  const collapse: DetailCollapse = collapseControlled ? collapsed : internalCollapsed[side]
+
+  const setCollapse = useCallback(
+    (next: DetailCollapse) => {
+      if (!collapseControlled) {
+        setInternalCollapsed((current) => ({ ...current, [side]: next }))
+      }
+      onCollapsedChange?.(next, side)
+    },
+    [collapseControlled, onCollapsedChange, side],
+  )
+
+  /* ---- collapsing moves focus to the rail it leaves behind ---------
+   *
+   * The collapse capsule lives INSIDE the divider, and the divider is
+   * `hidden` the moment a pane collapses — so the button the operator just
+   * pressed unmounts under their finger and focus falls to `<body>`. A
+   * keyboard user then has to Tab from the top of the document to get back
+   * to anything, and the thing they were doing (put a pane away, bring it
+   * back) is exactly the thing they can no longer reach.
+   *
+   * The `RestoreRail` mounts in the SAME commit the capsule unmounts, so the
+   * move cannot happen in the click handler — the rail's DOM node does not
+   * exist yet. It is a layout effect keyed on a bumped counter rather than on
+   * `collapse` itself, so a re-render for any other reason (a resize, a prop
+   * change) never steals focus, and collapsing twice to the same value still
+   * fires.
+   *
+   * `useLayoutEffect` and not `useEffect`: it runs before paint, so focus
+   * never visibly sits on `<body>` in between.
+   */
+  const restoreRailRef = useRef<HTMLButtonElement | null>(null)
+  const [restoreFocusTick, setRestoreFocusTick] = useState(0)
+  const restoreFocusPending = useRef<'rail' | 'fields-capsule' | 'aside-capsule' | null>(
+    null,
+  )
+
+  const collapseTo = useCallback(
+    (next: DetailCollapse) => {
+      // Both directions unmount the control that was pressed. Collapsing
+      // replaces the capsule with the rail; EXPANDING unmounts the rail and
+      // brings the capsules back — measured in the browser landing on
+      // <body>, exactly the same defect mirrored.
+      restoreFocusPending.current =
+        next !== 'none'
+          ? 'rail'
+          : collapse === 'aside'
+            ? 'aside-capsule'
+            : 'fields-capsule'
+      setCollapse(next)
+      setRestoreFocusTick((tick) => tick + 1)
+    },
+    [collapse, setCollapse],
+  )
+
+  useLayoutEffect(() => {
+    const target = restoreFocusPending.current
+    if (target === null) return
+    restoreFocusPending.current = null
+    if (target === 'rail') {
+      restoreRailRef.current?.focus()
+      return
+    }
+    // The capsules belong to `DetailDivider`, which mounts them in the same
+    // commit — scoped to THIS surface's split, in DOM order (fields, then
+    // activity), so a second detail surface on the page cannot be hit.
+    const capsules = splitRef.current?.querySelectorAll<HTMLButtonElement>(
+      '[data-slot="detail-collapse-button"]',
+    )
+    const capsule = capsules?.[target === 'aside-capsule' ? 1 : 0]
+    capsule?.focus()
+  }, [restoreFocusTick])
+
+  // A deliberate size gesture — drag, arrow, Home — is also a statement that
+  // the operator wants both panes. Matching `ResizableSplit`'s `setMode('split')`.
+  const resizeTo = useCallback(
+    (next: number) => {
+      if (collapse !== 'none') setCollapse('none')
+      setSize(next)
+    },
+    [collapse, setCollapse, setSize],
+  )
+
+  /* ---- focus: in on open, back to the opener on close ------------- */
+
+  useEffect(() => {
+    if (!open) return
+    const panel = panelRef.current
+    if (!panel) return
+    const active = document.activeElement
+    const previous =
+      active instanceof HTMLElement && active !== document.body ? active : null
+    const initial = panel.querySelector<HTMLElement>('[data-autofocus]')
+    ;(initial ?? panel).focus()
+    return () => {
+      // The half that gets forgotten. Without it, closing drops the caret to
+      // <body> and the next Tab restarts from the top of the page.
+      if (previous && previous.isConnected) previous.focus()
+    }
+  }, [open])
+
+  /* ---- Escape, through the shared stack --------------------------- */
+
+  // `modal` for the two centred modes so the Tab trap's topmost-MODAL guard
+  // can find it; `popover` for the side panel, which is non-modal and must
+  // let a select opened inside it answer Escape first.
+  const layer = useLayer({
+    enabled: open,
+    kind: isModal ? 'modal' : 'popover',
+    elementRef: panelRef,
+    onEscape: () => onClose(),
+  })
+
+  /* ---- Tab trap, modal modes only --------------------------------- */
+
+  useEffect(() => {
+    if (!open || !isModal) return
+    const panel = panelRef.current
+    if (!panel) return
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Tab') return
+      if (!layer.isTopOfKind()) return
+      const active = document.activeElement
+      // Focus outside the panel is almost always a body-level portal (a
+      // menu, a popover) opened FROM it. Wrapping that back in would break
+      // the portal's own keyboard handling.
+      if (!(active instanceof HTMLElement) || !panel.contains(active)) return
+
+      const tabbables = tabbablesWithin(panel)
+      const first = tabbables[0]
+      const last = tabbables[tabbables.length - 1]
+      if (!first || !last) {
+        event.preventDefault()
+        panel.focus()
+        return
+      }
+      if (active === panel) {
+        if (event.shiftKey) {
+          event.preventDefault()
+          last.focus()
+        }
+        return
+      }
+      if (event.shiftKey && active === first) {
+        event.preventDefault()
+        last.focus()
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [open, isModal, layer])
+
+  const backdropLit = open && isModal
+
+  /* ---- the split's geometry ---------------------------------------- */
+
+  const hasAside = aside !== undefined
+  const fieldsCollapsed = hasAside && collapse === 'fields'
+  const asideCollapsed = !hasAside || collapse === 'aside'
+  const floor = FIELDS_MIN[side]
+
+  // The size the fields pane is holding right now. When it collapses, its
+  // INNER box is pinned here so its content does not reflow to zero width and
+  // take the scroll position with it.
+  const railShowing = hasAside && collapse !== 'none'
+  const fieldsFrozen = Math.max(
+    floor,
+    containerSize === null
+      ? floor
+      : containerSize - DIVIDER_SIZE - size - (railShowing ? RESTORE_RAIL_SIZE : 0),
+  )
+
+  /** Along the split axis; the cross axis is always released to 0. */
+  const axis = (along: CSSProperties['inlineSize']): CSSProperties =>
+    vertical
+      ? { inlineSize: along, minInlineSize: along, minBlockSize: 0 }
+      : { blockSize: along, minBlockSize: along, minInlineSize: 0 }
+
+  const fieldsClipStyle: CSSProperties = fieldsCollapsed
+    ? { flex: '0 0 0px', ...axis(0), overflow: 'hidden' }
+    : {
+        flex: '1 1 0%',
+        ...(vertical
+          ? { minInlineSize: `${floor}px`, minBlockSize: 0 }
+          : { minBlockSize: `${floor}px`, minInlineSize: 0 }),
+        overflow: 'hidden',
+      }
+
+  const fieldsInnerStyle: CSSProperties | undefined = fieldsCollapsed
+    ? {
+        flex: '0 0 auto',
+        ...(vertical
+          ? { inlineSize: `${fieldsFrozen}px`, blockSize: '100%' }
+          : { blockSize: `${fieldsFrozen}px`, inlineSize: '100%' }),
+      }
+    : undefined
+
+  /** Fill what is left, along either axis. */
+  const fill: CSSProperties = {
+    flex: '1 1 0%',
+    minInlineSize: 0,
+    minBlockSize: 0,
+  }
+
+  const asideClipStyle: CSSProperties = asideCollapsed
+    ? { flex: '0 0 0px', ...axis(0), overflow: 'hidden' }
+    : fieldsCollapsed
+      ? // The other pane is away, so this one takes the room. Without this the
+        // aside sat at its stored 400px with the rest of the panel blank.
+        { ...fill, overflow: 'hidden' }
+      : { flex: '0 0 auto', ...axis(`${size}px`), overflow: 'hidden' }
+
+  // Explicit while the pane is the one that may be COLLAPSED — that is what
+  // keeps its content laid out at the width it had while its clip is at zero,
+  // and therefore what keeps its scroll position. When the OTHER pane is the
+  // collapsed one this pane is on screen and simply fills.
+  const asideInnerStyle: CSSProperties = fieldsCollapsed
+    ? fill
+    : {
+        flex: '0 0 auto',
+        ...(vertical
+          ? { inlineSize: `${size}px`, blockSize: '100%' }
+          : { blockSize: `${size}px`, inlineSize: '100%' }),
+      }
+
+  // `panel` is the only mode whose inline size is the operator's to set, so it
+  // is the only one whose geometry is not the table's verbatim.
+  const geometry: CSSProperties = isPanel
+    ? { ...PANEL_GEOMETRY.panel, inlineSize: `${panelWidth}px` }
+    : PANEL_GEOMETRY[mode]
+
+  // The chevron points the way the pane will come BACK — outward from the
+  // rail, which is the edge it went behind.
+  const RestoreFieldsIcon = vertical ? ChevronsRight : ChevronsDown
+  const RestoreAsideIcon = vertical ? ChevronsLeft : ChevronsUp
+
+  return (
+    <div
+      ref={wrapperRef}
+      data-slot="detail-surface"
+      data-mode={mode}
+      data-state={open ? 'open' : 'closed'}
+      className={cn(
+        'fixed inset-0 z-50 flex',
+        mode === 'panel' ? 'items-stretch justify-end' : 'items-center justify-center',
+      )}
+      // The wrapper covers the viewport in every mode so the panel can be
+      // positioned against it, but only the backdrop and the panel take
+      // pointer events — otherwise `panel` mode would swallow every click on
+      // the board it is meant to leave usable.
+      style={{ padding: WRAPPER_PADDING[mode], pointerEvents: 'none' }}
+    >
+      {/* Backdrop. Present in every mode and driven by opacity, so switching
+          from `panel` to `full` fades one in rather than popping it. It is
+          translucent by token (`--modal-overlay`), which is what leaves the
+          board faintly visible behind `full`. */}
+      <div
+        aria-hidden="true"
+        data-slot="detail-backdrop"
+        onClick={onClose}
+        className="absolute inset-0 transition-opacity duration-[var(--dur-base)] ease-[var(--ease-out)] motion-reduce:transition-none"
+        style={{
+          background: 'rgb(var(--modal-overlay))',
+          opacity: backdropLit ? 1 : 0,
+          pointerEvents: backdropLit ? 'auto' : 'none',
+        }}
+      />
+
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-label={ariaLabel}
+        {...(isModal ? { 'aria-modal': true } : {})}
+        tabIndex={-1}
+        inert={!open}
+        // `inert` already takes the closed panel out of the accessibility
+        // tree and the tab ring in a browser. `aria-hidden` says the same
+        // thing to everything that does NOT implement `inert` — older AT, and
+        // every testing-library query, which is not a footnote: an
+        // always-mounted dialog that stays visible to `getByRole('dialog')`
+        // makes the NEXT dialog on the page ambiguous, and the host's own
+        // tests start failing on a component they never touched. Safe
+        // together here because nothing inside can hold focus while closed:
+        // the same `open` that sets this drives the focus effect.
+        aria-hidden={open ? undefined : true}
+        data-slot="detail-panel"
+        data-mode={mode}
+        className={cn(
+          'ds-card-surface relative flex min-h-0 flex-col overflow-hidden',
+          'transition-[opacity,transform] duration-[var(--dur-base)] ease-[var(--ease-out)]',
+          'motion-reduce:transition-none',
+          // The panel takes focus on open (`tabIndex={-1}` + the focus
+          // effect below), so `focus:outline-none` with nothing in its
+          // place left the first keyboard landing spot in a dialog with no
+          // visible cue at all. Same treatment as every other control in
+          // the package: kill the UA outline on the `focus-visible` state
+          // only, and replace it with the ring. Forced-colors restores a
+          // real outline (styles.css).
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+          open ? 'opacity-100' : 'opacity-0',
+          !open && (mode === 'panel' ? 'translate-x-2' : 'translate-y-2'),
+          className,
+        )}
+        // `pointerEvents` is INLINE, not a utility class. The wrapper sets
+        // `none` so `panel` mode leaves the board clickable, and the panel has
+        // to opt back in — through the one channel that cannot be lost to a
+        // missing Tailwind `@source` (CLAUDE.md §2: build-clean but visually
+        // broken). Whether a dialog can be clicked is behaviour, not styling.
+        style={{
+          ...geometry,
+          borderRadius: 'var(--radius-xl)',
+          pointerEvents: open ? 'auto' : 'none',
+        }}
+      >
+        {/* The panel's OWN edge, and only in `panel` mode. `full` and `modal`
+            are centred overlays already sized against the viewport, so an edge
+            handle on them would be a control with nothing to say.
+
+            It is `ResizableHandle` itself, not a third implementation of a
+            drag: the WAI-ARIA splitter role, `aria-valuenow/min/max`, the
+            arrows, `Home` and the double-click reset all come from there, the
+            same as the inner divider's. What differs is that this one needs no
+            strip of its own — the panel's border already draws the seam — so
+            it is absolute on the leading edge, offset by `HANDLE_HIT_PAD` so
+            the whole 8px target lands inside the panel's `overflow: hidden`
+            rather than half outside it. */}
+        {isPanel ? (
+          <div
+            data-slot="detail-panel-resize"
+            className="absolute z-[2] w-1"
+            style={{ insetBlock: 0, insetInlineStart: `${HANDLE_HIT_PAD}px` }}
+          >
+            <ResizableHandle
+              side="left"
+              value={panelWidth}
+              onChange={setPanelWidth}
+              onCommit={commitPanelWidth}
+              min={panelBounds.min}
+              max={panelBounds.max}
+              defaultValue={clamp(
+                DETAIL_PANEL_DEFAULT_SIZE,
+                panelBounds.min,
+                panelBounds.max,
+              )}
+              aria-label={panelResizeLabel}
+              // A RING, not the handle's own fill: this edge sits over the
+              // panel's border rather than between two panes, and a 4px tint
+              // there is not a focus indicator anyone can find.
+              className="focus-visible:[box-shadow:var(--ring-focus)]"
+            />
+          </div>
+        ) : null}
+
+        {header === undefined ? null : header}
+
+        <div
+          ref={splitRef}
+          data-slot="detail-split"
+          data-orientation={vertical ? 'side' : 'bottom'}
+          data-collapsed={collapse}
+          className={cn(
+            'relative flex min-h-0 flex-1',
+            vertical ? 'flex-row' : 'flex-col',
+          )}
+        >
+          {/* The way back, and it is IN FLOW on the edge the pane went behind
+              — a pane the operator cannot restore is a trap, and a floating
+              pill over the field list's own toolbar is a different bug. */}
+          {fieldsCollapsed ? (
+            <RestoreRail
+              buttonRef={restoreRailRef}
+              vertical={vertical}
+              edge="start"
+              label="Show the fields pane"
+              onClick={() => collapseTo('none')}
+            >
+              <RestoreFieldsIcon size={14} strokeWidth={1.5} aria-hidden="true" />
+            </RestoreRail>
+          ) : null}
+
+          {/* Outer box collapses; inner box keeps its size. See the header. */}
+          <div
+            data-slot="detail-fields-clip"
+            data-detail-clip=""
+            className="flex"
+            style={fieldsClipStyle}
+            inert={fieldsCollapsed}
+            // Same policy as the closed dialog above, and for the same reason:
+            // `inert` is honoured by browsers, `aria-hidden` is what every
+            // non-`inert`-aware AT and every testing-library query reads. A
+            // collapsed pane is clipped to zero, so leaving it in the
+            // accessibility tree means a screen reader still walks fields the
+            // operator has put away. Safe together because nothing inside can
+            // hold focus while collapsed — collapsing moves focus to the
+            // restore rail (see `collapseTo`).
+            aria-hidden={fieldsCollapsed ? true : undefined}
+          >
+            <div
+              data-slot="detail-fields"
+              className="flex min-h-0 min-w-0 flex-1 flex-col"
+              {...(fieldsInnerStyle === undefined ? {} : { style: fieldsInnerStyle })}
+            >
+              {children}
+            </div>
+          </div>
+
+          {aside === undefined ? null : (
+            <>
+              <DetailDivider
+                orientation={side}
+                value={size}
+                onChange={resizeTo}
+                onCommit={commitSize}
+                min={bounds.min}
+                max={bounds.max}
+                defaultValue={DEFAULT_ASIDE_SIZE[side]}
+                aria-label={dividerLabel}
+                hidden={collapse !== 'none'}
+                onCollapseFields={() => collapseTo('fields')}
+                onCollapseAside={() => collapseTo('aside')}
+                onToggleCollapse={() =>
+                  collapseTo(collapse === 'none' ? 'aside' : 'none')
+                }
+              />
+              <div
+                data-slot="detail-activity-clip"
+                data-detail-clip=""
+                className="flex"
+                style={asideClipStyle}
+                inert={asideCollapsed}
+                // See the fields pane above — same policy, same reason.
+                aria-hidden={asideCollapsed ? true : undefined}
+              >
+                <div
+                  data-slot="detail-activity"
+                  className="flex min-h-0 min-w-0 flex-col"
+                  style={asideInnerStyle}
+                >
+                  {aside}
+                </div>
+              </div>
+
+              {collapse === 'aside' ? (
+                <RestoreRail
+                  buttonRef={restoreRailRef}
+                  vertical={vertical}
+                  edge="end"
+                  label="Show the activity pane"
+                  onClick={() => collapseTo('none')}
+                >
+                  <RestoreAsideIcon size={14} strokeWidth={1.5} aria-hidden="true" />
+                </RestoreRail>
+              ) : null}
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The rail a collapsed pane leaves behind.
+ *
+ * The whole rail IS the button — the same trick the thread's collapse rail
+ * uses: a 1px hairline is the right VISUAL weight for a seam and a hopeless
+ * target, so the target is 24px wide and the hairline is pinned inside it,
+ * leaving 23px of it transparent.
+ */
+function RestoreRail({
+  buttonRef,
+  vertical,
+  edge,
+  label,
+  onClick,
+  children,
+}: {
+  /** The surface parks focus here after a collapse — see `collapseTo`. Only
+   *  one rail is ever mounted (`collapse` is one of three exclusive values),
+   *  so both call sites can share a single ref. */
+  buttonRef?: RefObject<HTMLButtonElement | null> | undefined
+  vertical: boolean
+  edge: 'start' | 'end'
+  label: string
+  onClick: () => void
+  children: ReactNode
+}) {
+  return (
+    <button
+      type="button"
+      ref={buttonRef}
+      data-slot="detail-restore"
+      data-edge={edge}
+      onClick={onClick}
+      aria-label={label}
+      title={label}
+      className={cn(
+        'relative flex shrink-0 items-center justify-center',
+        'transition-colors duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+        'motion-reduce:transition-none',
+        'hover:bg-[rgb(var(--surface-hover))] hover:text-[rgb(var(--foreground))]',
+        'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+      )}
+      style={{
+        ...(vertical
+          ? { inlineSize: `${RESTORE_RAIL_SIZE}px`, alignSelf: 'stretch' }
+          : { blockSize: `${RESTORE_RAIL_SIZE}px`, inlineSize: '100%' }),
+        color: 'rgb(var(--text-tertiary))',
+      }}
+    >
+      {/* The seam keeps reading as a seam while the pane is away. */}
+      <span
+        aria-hidden="true"
+        className="pointer-events-none absolute"
+        style={{
+          background: 'rgb(var(--border))',
+          ...(vertical
+            ? {
+                insetBlock: 0,
+                inlineSize: '1px',
+                ...(edge === 'end'
+                  ? { insetInlineStart: 0 }
+                  : { insetInlineEnd: 0 }),
+              }
+            : {
+                insetInline: 0,
+                blockSize: '1px',
+                ...(edge === 'end'
+                  ? { insetBlockStart: 0 }
+                  : { insetBlockEnd: 0 }),
+              }),
+        }}
+      />
+      {children}
+    </button>
+  )
+}