@lovett/ui 0.0.11 → 0.2.0

package/src/board.tsx

@@ -0,0 +1,658 @@
+/**
+ * Board + BoardColumn — the shared kanban primitive.
+ *
+ * ADR-146 D2: **one board primitive, two consumers.** The Tasks lens and the
+ * Community roadmap render the same columns, the same drag behaviour and the
+ * same chrome; they differ only in what goes INSIDE a card. So this primitive
+ * is generic over its card BODY (`renderCard`), never over its data — a
+ * Community card carries votes and a reporter where a Tasks card carries a
+ * ledger and dates, and pretending those are one shape is what produced the
+ * workspace's second kanban in the first place.
+ *
+ * Design: `tasks-board-design-language.md` §4, as corrected by
+ * `tasks-board-interface-standards.md` §1–§6.
+ *
+ * ## The column container
+ *
+ * PlanIQ nests cards inside a large rounded column rather than floating them.
+ * Adopted, because it reads as a real container and gives drag a visible drop
+ * target: `--surface-frame`, 1px `--border`, `--radius-2xl`, `--space-2` pad —
+ * which is exactly what makes the card's `--radius-lg` concentric.
+ *
+ * ## The drag-over state
+ *
+ * The column's BORDER steps to `--border-strong` and its shell to
+ * `--surface-hover`. Deliberately **no accent tint**: the accent marks the one
+ * most important thing in a view, and "a card is hovering here" is not it.
+ *
+ * The signal comes from `MultiSortableList`'s RESOLVED container, never from
+ * `useDroppable().isOver`. Under `closestCorners`, `over` resolves to a
+ * sortable ITEM whenever the column holds one, so the column droppable never
+ * wins and its `isOver` is `false` for the very column the card is over — the
+ * whole treatment was dead code until this was derived instead of read.
+ *
+ * ## Keyboard
+ *
+ * Cross-column movement runs through dnd-kit's `KeyboardSensor` (wired in
+ * `MultiSortableList`), and every icon-only control in the header carries an
+ * `aria-label`. Accessibility is a floor here, not polish.
+ */
+
+import {
+  Fragment,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+  type ComponentPropsWithoutRef,
+} from 'react'
+import { ChevronDown, ChevronRight, Plus, X } from 'lucide-react'
+import { cn } from './lib/utils'
+import { Button } from './button'
+import { hueClass, type BoardHueKey } from './hue'
+import { StatusGlyph, StatusRing, type BoardStatusKey } from './status'
+import type { LedgerProgress } from './progress-ledger'
+import {
+  MultiSortableList,
+  SortableDropZone,
+  SortableItem,
+  type MultiSortableMove,
+  type SortableContainers,
+} from './sortable'
+import type { TaskCardDragProps } from './task-card'
+
+
+/**
+ * Heading level as a prop, not a hardcoded tag.
+ *
+ * A board sits under whatever heading its host page already renders, so the
+ * primitive cannot know whether its columns are h2 or h3. Hardcoding h3 gave
+ * the Tasks lens an h1 -> h3 skip the moment it grew a page heading. Levels are
+ * an accessibility contract, not styling: the visual weight comes from the
+ * class, and the tag only says where this sits in the document outline.
+ */
+type HeadingLevel = 2 | 3 | 4 | 5
+
+function ColumnHeading({
+  level,
+  ...rest
+}: { level: HeadingLevel } & ComponentPropsWithoutRef<'h3'>) {
+  const Tag = `h${level}` as const
+  return <Tag {...rest} />
+}
+
+export interface BoardColumnSpec {
+  id: string
+  /** Operator language, sentence case. Wraps rather than clips. */
+  label: string
+  hue: BoardHueKey
+  /** Overflow menu trigger for column actions. Supply its own `aria-label`. */
+  menu?: ReactNode
+  /** Omit to hide the `+` affordance on this column. */
+  onAdd?: () => void
+  /** Accessible name for `+`. Defaults to `Add to <label>`. */
+  addLabel?: string
+  /** Shown when the column holds nothing. An invitation, not a mood. */
+  emptyMessage?: string
+  /**
+   * The lane's completion — the SAME numbers its cards' ledgers print, from
+   * `ledgerProgress()`. Renders a `<StatusRing>` in place of the hue dot, in
+   * the header and in the hidden-columns rail.
+   *
+   * It is a property of the LANE, not of the current filter: typing in a
+   * search box does not change how far along the work in a column is. The
+   * count beside it is what moves, and it says `visible / total` when a filter
+   * is on so the two figures cannot be read as measuring the same set.
+   */
+  progress?: LedgerProgress
+  /**
+   * The lane's discrete state, for when there is nothing to measure — an empty
+   * lane, or one whose items carry no checklist. `progress` wins when both are
+   * supplied: a real number always beats a category.
+   */
+  status?: BoardStatusKey
+}
+
+export interface BoardCardContext {
+  itemId: string
+  columnId: string
+  /** True while rendering inside the DragOverlay — no hover lift there. */
+  isOverlay: boolean
+  /** Undefined on the overlay and on a non-draggable board. */
+  drag?: TaskCardDragProps
+}
+
+export interface BoardItemLeadContext {
+  itemId: string
+  columnId: string
+  /** Position within the lane, in the live arrangement. */
+  index: number
+  /** The lane's item ids, in the live arrangement. */
+  items: readonly string[]
+}
+
+export interface BoardProps {
+  /**
+   * Document-outline level for the column heading. Default 3.
+   * Set it to match the host page: a lens with its own `<h1>` passes 2 so the
+   * outline reads h1 -> h2 -> h3 without a skip. Visual weight is unaffected.
+   */
+  headingLevel?: HeadingLevel
+  columns: readonly BoardColumnSpec[]
+  /** columnId -> item ids, in order. FILTERED — what the board renders. */
+  items: SortableContainers
+  /**
+   * The same map, UNFILTERED and over the same scope.
+   *
+   * This is the architectural key to the hidden-columns rail
+   * (`tasks-board-header-primitives.md` §3): without both maps there is
+   * nothing to subtract, and the per-lane `0 / n` — the count of what the
+   * filter is hiding IN THAT LANE — cannot be computed at all.
+   *
+   * Omit it on a board with no filtering. Then `totalItems === items` by
+   * definition, nothing is hidden, and neither the rail nor the footer can
+   * appear.
+   */
+  totalItems?: SortableContainers
+  renderCard: (context: BoardCardContext) => ReactNode
+  /**
+   * Rendered BEFORE the card at `index` in a lane, outside the sortable
+   * wrapper — a sub-group heading, a "today" marker, a run divider.
+   *
+   * Outside the wrapper on purpose: inside it the heading would be picked up
+   * and dragged along with the card it happens to precede. Return `null` for
+   * the positions that need nothing, which is most of them.
+   *
+   * The `items` it is indexed against is the LIVE arrangement, so a heading
+   * recomputes while a card is being dragged between lanes rather than
+   * lagging one commit behind.
+   */
+  renderItemLead?: (context: BoardItemLeadContext) => ReactNode
+  /**
+   * Commit a move. Omit (or pass `draggable={false}`) for a read-only board —
+   * Community's roadmap is fixture-backed until AP-11 lands a write path.
+   */
+  onMove?: (move: MultiSortableMove, next: SortableContainers) => void
+  draggable?: boolean
+  /** Human name for an item id — used in the drag announcements. */
+  labelForItem?: (itemId: string) => string
+  collapsedColumnIds?: readonly string[]
+  onToggleCollapsed?: (columnId: string) => void
+  /**
+   * Whether a lane holding nothing — and hiding nothing — keeps its place in
+   * the strip. Default `false`: the plain omit behaviour.
+   *
+   * A DRAGGABLE board almost always wants `true`, because an omitted lane is
+   * also a missing drop target. This is unrelated to the rail: a lane that is
+   * empty BECAUSE OF A FILTER leaves the strip either way, and says so.
+   */
+  /**
+   * Render a lane that has no items when NO filter is active. Default `true`.
+   *
+   * An empty lane is part of the board's shape and is a drop target, so
+   * omitting it silently is the surprising behaviour — a consumer that never
+   * passes this should not lose a lane the moment it empties. Hiding is the
+   * FILTERED case, and that is the hidden-columns rail's job, not this flag's.
+   */
+  showEmptyColumns?: boolean
+  /**
+   * Clears the host's filters. Renders the "Clear filters" button in the
+   * hidden-by-filters footer; without it the footer still states the count,
+   * because a dead button is worse than an absent one.
+   */
+  onClearFilters?: () => void
+  /** The board's own word for a card, for the footer copy. Sentence case. */
+  itemNoun?: { one: string; many: string }
+  /** Trailing element after the last column — typically an "Add column" button. */
+  columnsEnd?: ReactNode
+  className?: string
+}
+
+export function Board({
+  headingLevel = 3,
+  columns,
+  items,
+  totalItems,
+  renderCard,
+  renderItemLead,
+  onMove,
+  draggable = true,
+  labelForItem,
+  collapsedColumnIds,
+  onToggleCollapsed,
+  showEmptyColumns = true,
+  onClearFilters,
+  itemNoun = { one: 'item', many: 'items' },
+  columnsEnd,
+  className,
+}: BoardProps) {
+  const collapsed = new Set(collapsedColumnIds ?? [])
+
+  // ---- The filtered / unfiltered partition -------------------------------
+  //
+  // Derived from the two maps rather than taken as a `filtersActive` flag:
+  // a lane is hidden BY A FILTER exactly when it holds nothing and its
+  // unfiltered self holds something, and that is knowable here. A flag would
+  // be a third source of truth for a fact the data already states.
+  //
+  // Partitioned on `items` (the committed prop), never on the live drag
+  // arrangement — otherwise dragging the last card out of a filtered lane
+  // would send that lane to the rail mid-drag, under the pointer.
+  const visibleIn = (columnId: string) => (items[columnId] ?? []).length
+  const totalIn = (columnId: string) =>
+    totalItems ? (totalItems[columnId] ?? []).length : visibleIn(columnId)
+  const hiddenIn = (columnId: string) => Math.max(0, totalIn(columnId) - visibleIn(columnId))
+
+  const railColumns = columns.filter(
+    (column) => visibleIn(column.id) === 0 && hiddenIn(column.id) > 0,
+  )
+  const railIds = new Set(railColumns.map((column) => column.id))
+  const stripColumns = columns.filter(
+    (column) =>
+      !railIds.has(column.id) && (showEmptyColumns || visibleIn(column.id) > 0),
+  )
+  const hiddenCount = columns.reduce((sum, column) => sum + hiddenIn(column.id), 0)
+  const labelForContainer = (columnId: string) =>
+    columns.find((column) => column.id === columnId)?.label ?? columnId
+
+  const columnFor = (itemId: string) =>
+    columns.find((column) => (items[column.id] ?? []).includes(itemId))?.id ?? ''
+
+  /* ---- clearing the filters must not drop focus -----------------------
+   *
+   * The "Clear filters" button lives in the footer that EXISTS because
+   * something is hidden. Pressing it takes the hidden count to zero, which
+   * unmounts the footer, which unmounts the button under the operator's
+   * finger — focus falls to `<body>` and a keyboard user restarts the
+   * document. The board strip is the nearest thing the button was about, so
+   * focus moves there.
+   *
+   * Moved BEFORE the callback rather than after: React batches the state
+   * update the consumer makes inside `onClearFilters`, so the commit that
+   * removes the button happens after this handler returns — by which time
+   * focus is already on the strip. Doing it in the other order would depend
+   * on the consumer not calling `flushSync`.
+   */
+  const scrollerRef = useRef<HTMLDivElement | null>(null)
+  const handleClearFilters = onClearFilters
+    ? () => {
+        scrollerRef.current?.focus()
+        onClearFilters()
+      }
+    : undefined
+
+  const scroller = (
+    arrangement: SortableContainers,
+    interactive: boolean,
+    overColumnId: string | null,
+  ) => (
+    // `tabIndex={-1}` makes the strip a focus TARGET without putting it in the
+    // tab ring: "Clear filters" unmounts itself, and this is where focus goes
+    // instead of `<body>` (see `handleClearFilters`). The baseline focus rule
+    // in styles.css deliberately excludes negative tabindex, so parking focus
+    // here paints no ring on a control that is not one.
+    <div ref={scrollerRef} tabIndex={-1} className={cn('ds-board-scroller', className)}>
+      {stripColumns.map((column) => {
+        const columnItems = arrangement[column.id] ?? []
+        const isCollapsed = collapsed.has(column.id)
+        const body = (
+          dropProps: { setNodeRef?: (node: HTMLElement | null) => void },
+        ) => (
+          <BoardColumn
+              headingLevel={headingLevel}
+            spec={column}
+            count={columnItems.length}
+            total={totalIn(column.id)}
+            collapsed={isCollapsed}
+            onToggleCollapsed={
+              onToggleCollapsed ? () => onToggleCollapsed(column.id) : undefined
+            }
+            setNodeRef={dropProps.setNodeRef}
+            isOver={overColumnId === column.id}
+          >
+            {columnItems.map((itemId, index) => (
+              <Fragment key={itemId}>
+                {renderItemLead
+                  ? renderItemLead({
+                      itemId,
+                      columnId: column.id,
+                      index,
+                      items: columnItems,
+                    })
+                  : null}
+                {interactive ? (
+                <SortableItem id={itemId}>
+                  {({
+                    dragListeners,
+                    dragAttributes,
+                    setNodeRef,
+                    setActivatorNodeRef,
+                    style,
+                    isDragging,
+                  }) =>
+                    renderCard({
+                      itemId,
+                      columnId: column.id,
+                      isOverlay: false,
+                      drag: {
+                        // The card is the MEASURED node and nothing else. Both
+                        // activators — pointer and keyboard — plus dnd-kit's
+                        // aria wiring ride the grip, so a pointer-down on the
+                        // card body is a click on the card, not a drag, and the
+                        // card never becomes a role="button" holding its own
+                        // buttons.
+                        activatorProps: { ...dragAttributes, ...dragListeners },
+                        activatorRef: setActivatorNodeRef,
+                        setNodeRef,
+                        style,
+                        isDragging,
+                      },
+                    })
+                  }
+                </SortableItem>
+                ) : (
+                  <div>
+                    {renderCard({ itemId, columnId: column.id, isOverlay: false })}
+                  </div>
+                )}
+              </Fragment>
+            ))}
+          </BoardColumn>
+        )
+
+        return interactive ? (
+          <SortableDropZone key={column.id} id={column.id} items={columnItems}>
+            {/* `isOver` from the droppable is deliberately ignored — see the
+                file header. The drop target is the RESOLVED container. */}
+            {({ setNodeRef }) => body({ setNodeRef })}
+          </SortableDropZone>
+        ) : (
+          <div key={column.id} className="contents">
+            {body({})}
+          </div>
+        )
+      })}
+      {railColumns.length > 0 ? (
+        <BoardHiddenColumns columns={railColumns} totalIn={totalIn} />
+      ) : null}
+      {columnsEnd ? <div className="ds-board-columns-end">{columnsEnd}</div> : null}
+    </div>
+  )
+
+  /**
+   * The shell exists only to hang the footer under the scroller, so it is
+   * `display: contents` until there IS a footer — a board with no filtering
+   * keeps exactly the box tree it had before this prop existed.
+   */
+  const shell = (content: ReactNode) => (
+    <div className="ds-board-shell" data-footer={hiddenCount > 0 ? 'true' : undefined}>
+      {content}
+      {hiddenCount > 0 ? (
+        <BoardHiddenSummary
+          count={hiddenCount}
+          noun={itemNoun}
+          {...(handleClearFilters ? { onClearFilters: handleClearFilters } : {})}
+        />
+      ) : null}
+    </div>
+  )
+
+  if (!draggable || !onMove) {
+    return shell(scroller(items, false, null))
+  }
+
+  return shell(
+    <MultiSortableList
+      containers={items}
+      containerOrder={columns.map((column) => column.id)}
+      onMove={onMove}
+      labelForItem={labelForItem}
+      labelForContainer={labelForContainer}
+      // The DESTINATION column, not the origin: mid-drag the live arrangement
+      // has already moved the item, and the overlay must match the placeholder
+      // sitting under it rather than showing the same card in two hues.
+      renderOverlay={(itemId, containerId) =>
+        renderCard({
+          itemId,
+          columnId: containerId ?? columnFor(itemId),
+          isOverlay: true,
+        })
+      }
+    >
+      {(arrangement, overColumnId) => scroller(arrangement, true, overColumnId)}
+    </MultiSortableList>,
+  )
+}
+
+/**
+ * The lane's marker — a ring when there is a real number, a glyph when the
+ * state is discrete, the plain hue dot when the caller says neither.
+ *
+ * One component so the header and the rail row cannot drift apart, which is
+ * how the source ended up with four different answers to "this bucket is
+ * empty" in one app.
+ */
+function LaneMarker({ spec }: { spec: BoardColumnSpec }) {
+  if (spec.progress && spec.progress.total > 0) {
+    return (
+      <StatusRing
+        percent={spec.progress.percent}
+        label={`${spec.label} is ${spec.progress.percent}% complete`}
+      />
+    )
+  }
+  if (spec.status) {
+    return <StatusGlyph status={spec.status} />
+  }
+  // A hue dot, so a column is identifiable without reading its label — and
+  // squared off, because it is a marker, not a status light.
+  return <span className="ds-board-column-dot" aria-hidden="true" />
+}
+
+/**
+ * The hidden-columns rail — the best idea in the source repo
+ * (`grouped-issues-view.tsx:80-113`), and the one that answers "how does the
+ * board show that a lane is hidden".
+ *
+ * Two things it deliberately is NOT:
+ *
+ *   - **It is not a rotated column.** Nothing here uses `writing-mode` or a
+ *     90° transform. A row stays readable and, more to the point, it has
+ *     somewhere to put the count — which a vertical strip does not.
+ *   - **It is not the manual collapse.** A collapsed lane keeps its place in
+ *     the strip, its caret and its own header; a filter-hidden lane leaves the
+ *     strip entirely and reads as `0 / n`. Two different states, two different
+ *     shapes, so neither can be mistaken for the other.
+ */
+function BoardHiddenColumns({
+  columns,
+  totalIn,
+}: {
+  columns: readonly BoardColumnSpec[]
+  totalIn: (columnId: string) => number
+}) {
+  // Open by default: the whole point is that the hiding is visible.
+  const [open, setOpen] = useState(true)
+  const listId = useId()
+  const Caret = open ? ChevronDown : ChevronRight
+
+  return (
+    <aside className="ds-board-hidden-rail" aria-label="Hidden columns">
+      <button
+        type="button"
+        className="ds-board-hidden-rail-head"
+        aria-expanded={open}
+        aria-controls={listId}
+        onClick={() => setOpen((current) => !current)}
+      >
+        <Caret size={15} strokeWidth={2} aria-hidden="true" />
+        <span className="ds-board-hidden-rail-title">Hidden columns</span>
+        <span className="ds-board-hidden-rail-count tabular-nums">{columns.length}</span>
+      </button>
+      <ul id={listId} className="ds-board-hidden-rail-list" hidden={!open}>
+        {columns.map((column) => {
+          const total = totalIn(column.id)
+          return (
+            <li key={column.id} className={cn('ds-board-hidden-row', hueClass(column.hue))}>
+              <LaneMarker spec={column} />
+              <span className="ds-board-hidden-row-label">{column.label}</span>
+              {/* The figure a filtered board cannot compute without both maps:
+                  what this lane is hiding. Read out in words rather than as
+                  "zero slash five". */}
+              <span className="ds-board-hidden-row-count tabular-nums" aria-hidden="true">
+                0 / {total}
+              </span>
+              <span className="sr-only">{`0 of ${total} shown`}</span>
+            </li>
+          )
+        })}
+      </ul>
+    </aside>
+  )
+}
+
+/** "{n} items hidden by filters", with the way out beside it. */
+function BoardHiddenSummary({
+  count,
+  noun,
+  onClearFilters,
+}: {
+  count: number
+  noun: { one: string; many: string }
+  onClearFilters?: () => void
+}) {
+  return (
+    <div className="ds-board-hidden-summary">
+      {/* Announced on change: the count moves as the operator types, and the
+          number of things they can no longer see is worth hearing. */}
+      <span role="status" className="ds-board-hidden-summary-text tabular-nums">
+        {count} {count === 1 ? noun.one : noun.many} hidden by filters
+      </span>
+      {onClearFilters ? (
+        // Secondary, never ghost: a button reads as a button (CLAUDE.md §2).
+        // The trailing glyph is the reference's `Clear filters ✕` — decoration
+        // on a labelled button, so it is aria-hidden and carries no name of its
+        // own.
+        <Button
+          variant="secondary"
+          size="sm"
+          onClick={onClearFilters}
+          trailingIcon={<X size={13} strokeWidth={2} aria-hidden="true" />}
+        >
+          Clear filters
+        </Button>
+      ) : null}
+    </div>
+  )
+}
+
+export interface BoardColumnProps {
+  /**
+   * Document-outline level for the column heading. Default 3.
+   * Set it to match the host page: a lens with its own `<h1>` passes 2 so the
+   * outline reads h1 -> h2 -> h3 without a skip. Visual weight is unaffected.
+   */
+  headingLevel?: HeadingLevel
+  spec: BoardColumnSpec
+  /** Cards currently rendered in this lane. */
+  count: number
+  /**
+   * Cards in this lane before filtering. When it exceeds `count` the header
+   * reads `visible / total`, so the number beside the ring is never mistaken
+   * for the whole lane.
+   */
+  total?: number
+  collapsed?: boolean
+  onToggleCollapsed?: (() => void) | undefined
+  isOver?: boolean | undefined
+  setNodeRef?: ((node: HTMLElement | null) => void) | undefined
+  children?: ReactNode
+  className?: string | undefined
+}
+
+export function BoardColumn({
+  headingLevel = 3,
+  spec,
+  count,
+  total,
+  collapsed = false,
+  onToggleCollapsed,
+  isOver = false,
+  setNodeRef,
+  children,
+  className,
+}: BoardColumnProps) {
+  const headingId = useId()
+  const Caret = collapsed ? ChevronRight : ChevronDown
+
+  return (
+    <section
+      ref={setNodeRef}
+      aria-labelledby={headingId}
+      className={cn('ds-board-column', hueClass(spec.hue), className)}
+      data-over={isOver ? 'true' : undefined}
+      // The hook the CSS needs to let ONE lane shrink. The scroller stretches
+      // its items so an expanded lane reaches the bottom of the page; without
+      // a per-item override a collapsed lane keeps the height of the tallest
+      // expanded one, and only the all-collapsed case appears to work.
+      data-collapsed={collapsed ? 'true' : undefined}
+    >
+      <header className="ds-board-column-head">
+        {onToggleCollapsed ? (
+          <Button
+            variant="icon"
+            size="sm"
+            aria-label={collapsed ? `Expand ${spec.label}` : `Collapse ${spec.label}`}
+            aria-expanded={!collapsed}
+            onClick={onToggleCollapsed}
+          >
+            <Caret size={15} strokeWidth={2} aria-hidden="true" />
+          </Button>
+        ) : null}
+        <LaneMarker spec={spec} />
+        <ColumnHeading id={headingId} className="ds-board-column-label" level={headingLevel}>
+          {spec.label}
+        </ColumnHeading>
+        {/* `2 / 9` under a filter, plain `9` otherwise — so the count and the
+            ring never look like two measurements of the same set. */}
+        {typeof total === 'number' && total > count ? (
+          <span className="ds-board-column-count tabular-nums">
+            <span aria-hidden="true">
+              {count} / {total}
+            </span>
+            <span className="sr-only">{`${count} of ${total} shown`}</span>
+          </span>
+        ) : (
+          <span className="ds-board-column-count tabular-nums">{count}</span>
+        )}
+        {/* Adjacent bordered controls sit 12px apart (interface-standards §3). */}
+        {spec.onAdd || spec.menu ? (
+          <span className="ds-board-column-actions">
+            {spec.onAdd ? (
+              <Button
+                variant="icon"
+                size="sm"
+                aria-label={spec.addLabel ?? `Add to ${spec.label}`}
+                onClick={spec.onAdd}
+              >
+                <Plus size={15} strokeWidth={2} aria-hidden="true" />
+              </Button>
+            ) : null}
+            {spec.menu}
+          </span>
+        ) : null}
+      </header>
+
+      {collapsed ? null : (
+        <div className="ds-board-column-body">
+          {count === 0 ? (
+            <p className="ds-board-column-empty">
+              {spec.emptyMessage ?? `Nothing in ${spec.label} yet. Drag one here, or add one.`}
+            </p>
+          ) : null}
+          {children}
+        </div>
+      )}
+    </section>
+  )
+}