@charcuterie/ui 3.0.0 → 3.2.0

package/src/Board/BoardCard.tsx

@@ -0,0 +1,290 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import {
+  FOCUS_RING_CLASS,
+  INTENT_SOLID_FILL_CLASS,
+} from "../intentStyles.ts"
+import { Menu } from "../Menu/Menu.tsx"
+import { TextLink } from "../TextLink/TextLink.tsx"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type BoardItem = {
+  /**
+   * The leading colour bar. Priority, in the consumer this was built
+   * for — *"Priority is styled as a leading colour bar, and **never**
+   * a coloured word before the title."*
+   *
+   * Pair it with `accentLabel`. A bar is colour and nothing else, so
+   * on its own it fails WCAG 1.4.1 outright and is invisible to
+   * every screen reader; the label rides along in a
+   * `VisuallyHidden` so the same fact reaches both channels. Docket's
+   * first board painted these `--color-danger-9` — a Radix-style
+   * scale this token set has never had — so every bar was
+   * transparent while every "is it rendered" assertion passed. The
+   * families here are `--color-intent-<intent>-<role>`; there is no
+   * numeric scale to reach for.
+   */
+  accentIntent?: IntentName
+  /** What the bar means, in words. "Priority 0". */
+  accentLabel?: string
+  /**
+   * Under the title and metadata, spanning the card: a live run
+   * line, a gate explanation, a due date. A `ProgressBar` goes here.
+   */
+  footer?: ReactNode
+  /** Where the title navigates. Routed through `RouterLinkProvider`. */
+  href?: string
+  /**
+   * Visibly present but not actionable — Docket's *gated*: a task
+   * whose phase has not opened yet. Paint only; it does not disable
+   * the title, because being able to read a thing you cannot start
+   * yet is the entire point of showing it.
+   */
+  isDimmed?: boolean
+  key: string
+  /**
+   * Small status marks rendered immediately before the title —
+   * running, blocked, stale. Each one needs its own accessible name;
+   * a bare coloured dot is the same WCAG 1.4.1 failure as the bar.
+   */
+  marks?: ReactNode
+  /**
+   * Chips. Under the title when the lane is narrow, right-aligned
+   * beside it when there is room. `Badge` is what goes here.
+   */
+  meta?: ReactNode
+  /** Fires when there is no `href` — for a board that opens a modal. */
+  onSelect?: () => void
+  title: string
+  /** The trailing cluster: an assignee avatar, an elapsed-time chip. */
+  trailing?: ReactNode
+}
+
+export type BoardCardProps = {
+  item: BoardItem
+  laneLabel: string
+  /**
+   * Shown on the move handle instead of the word "Move". The
+   * library ships no icons, so the default is words — a `⋮` renders
+   * as nothing where the font lacks it, which includes the kiosk
+   * image and the ePaper build. An app that already owns a glyph
+   * set passes one and buys back the ~55px per row that a word
+   * costs, which in a 500px lane is the difference between twenty
+   * characters of title and thirty.
+   */
+  moveIcon?: ReactNode
+  /** The lanes this card can be sent to — never its own. */
+  moveTargets: readonly { key: string; label: string }[]
+  /** Absent on a read-only board, and then so is the handle. */
+  onMoveToLane?: (toLaneKey: string) => void
+  onStartDrag?: (pointerEvent: {
+    clientX: number
+    clientY: number
+    currentTarget: EventTarget & Element
+    pointerId: number
+  }) => void
+}
+
+/**
+ * One row on the board — and *row* is only what it is at some
+ * widths.
+ *
+ * ### The three shapes are one component, chosen by the lane
+ *
+ * The requirement this was built against is unusually specific, and
+ * it is specific because the owner answered "which row style?" with
+ * *"all three, depending"*:
+ *
+ * | The lane is | The card is |
+ * | --- | --- |
+ * | narrower than `cq-sm` (24rem) | **two lines** — title clamped to two, metadata underneath, only the trailing slot beside it |
+ * | `cq-sm` to `cq-lg` | **one line** — title ellipsised, metadata right-aligned |
+ * | `cq-lg` (48rem) and wider | **a card** — its own border, surface and elevation, instead of a divider in a list |
+ *
+ * Every one of those is a **container** query against the lane's
+ * list, never a media query, and the difference is not pedantry: a
+ * lane in a three-up board is narrow on a 4K display, and the owner
+ * browses zoomed in, so a 1500px window at 175% zoom is ~860
+ * effective CSS pixels. Window width is not a proxy for the space
+ * this card has. A `@media (max-width: …)` anywhere in this file
+ * would be a defect.
+ *
+ * It also dissolved a bug rather than only satisfying a preference:
+ * a *fixed* two-line row collapsed its title to `a…` inside a narrow
+ * lane, because the metadata beside it could not shrink. A card
+ * sized by its container has no such state to be in.
+ *
+ * ### The move handle is a button first and a drag handle second
+ *
+ * One control, two drivers. Pressing it opens a `Menu` of the other
+ * lanes — the keyboard and screen-reader path, which also works on
+ * touch, and works in the Narrow View where the other lanes are not
+ * on screen at all. Dragging from it moves the card directly. Both
+ * commit through the same callback, so there is no second code path
+ * to keep honest and neither is a fallback for the other.
+ */
+export const BoardCard = ({
+  item,
+  laneLabel,
+  moveIcon,
+  moveTargets,
+  onMoveToLane,
+  onStartDrag,
+}: BoardCardProps): ReactNode => {
+  const [isMenuVisible, setIsMenuVisible] = useState(false)
+
+  const titleContent = (
+    // `line-clamp-none` before `truncate`, because `line-clamp-2`
+    // sets `display: -webkit-box` and `text-overflow` has nothing to
+    // ellipsise inside one.
+    <span className="line-clamp-2 cq-sm:line-clamp-none cq-sm:block cq-sm:truncate">
+      {item.title}
+    </span>
+  )
+
+  return (
+    <li
+      className={toClassName(
+        "group relative flex gap-2 border-border-subtle border-b py-2 pe-1 last:border-b-0",
+        // At `cq-lg` the list stops being a list of rows: the
+        // divider goes and each card grows its own box. The *list*
+        // cannot do this to itself — it is the container, and a
+        // container query never matches its own container.
+        "cq-lg:mb-2 cq-lg:rounded-lg cq-lg:border cq-lg:bg-surface-raised cq-lg:p-3 cq-lg:shadow-low",
+        item.isDimmed && "opacity-60",
+      )}
+      data-board-card={item.key}
+    >
+      {item.accentIntent ? (
+        <span
+          className={toClassName(
+            "w-1 shrink-0 self-stretch rounded-full",
+            INTENT_SOLID_FILL_CLASS[item.accentIntent],
+          )}
+        >
+          {item.accentLabel ? (
+            <VisuallyHidden>
+              {item.accentLabel}
+            </VisuallyHidden>
+          ) : null}
+        </span>
+      ) : null}
+
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <div className="flex min-w-0 items-start gap-2">
+          <div className="flex min-w-0 flex-1 flex-col gap-1 cq-sm:flex-row cq-sm:items-center cq-sm:gap-2">
+            <div className="flex min-w-0 flex-1 items-start gap-1.5 text-sm leading-snug">
+              {item.marks ? (
+                <span className="flex shrink-0 items-center gap-1 pt-1">
+                  {item.marks}
+                </span>
+              ) : null}
+
+              {item.href ? (
+                <TextLink
+                  appearance="standalone"
+                  className="min-w-0 max-w-full font-normal"
+                  href={item.href}
+                  intent="neutral"
+                >
+                  {titleContent}
+                </TextLink>
+              ) : item.onSelect ? (
+                <button
+                  className={toClassName(
+                    "min-w-0 max-w-full cursor-pointer rounded-xs text-start text-intent-neutral-content hover:underline",
+                    FOCUS_RING_CLASS,
+                  )}
+                  onClick={item.onSelect}
+                  type="button"
+                >
+                  {titleContent}
+                </button>
+              ) : (
+                titleContent
+              )}
+            </div>
+
+            {item.meta ? (
+              <div className="flex min-w-0 flex-wrap items-center gap-1 cq-sm:shrink-0 cq-sm:flex-nowrap cq-sm:justify-end">
+                {item.meta}
+              </div>
+            ) : null}
+          </div>
+
+          {item.trailing || onMoveToLane ? (
+            <div className="flex shrink-0 items-center gap-1">
+              {item.trailing}
+
+              {onMoveToLane && moveTargets.length > 0 ? (
+                <Menu
+                  isVisible={isMenuVisible}
+                  items={moveTargets.map((target) => ({
+                    key: target.key,
+                    label: target.label,
+                    onSelect: () => {
+                      onMoveToLane(target.key)
+                    },
+                  }))}
+                  onDismiss={() => {
+                    setIsMenuVisible(false)
+                  }}
+                  placement="bottom-end"
+                  trigger={
+                    <Button
+                      appearance="ghost"
+                      intent="neutral"
+                      // `touch-none` so a touch drag is a drag
+                      // rather than a page scroll. Only the handle
+                      // needs it; the rest of the gesture is covered
+                      // by `preventDefault` on the captured
+                      // `pointermove`.
+                      className="touch-none opacity-70 group-hover:opacity-100"
+                      onClick={() => {
+                        setIsMenuVisible(
+                          (isVisible) => !isVisible,
+                        )
+                      }}
+                      onPointerDown={(pointerEvent) => {
+                        onStartDrag?.(pointerEvent)
+                      }}
+                      size="sm"
+                      sizing={moveIcon ? "icon" : "control"}
+                    >
+                      {moveIcon ?? "Move"}
+
+                      {/*
+                       * Thirty controls all named "Move" is thirty
+                       * indistinguishable buttons to a screen reader
+                       * and to `getByRole("button", { name })`, so
+                       * the accessible name says *which* card and
+                       * where it currently is. With an icon this is
+                       * the whole name; with the word it qualifies
+                       * it.
+                       */}
+                      <VisuallyHidden>
+                        {moveIcon
+                          ? `Move ${item.title}, currently in ${laneLabel}`
+                          : ` ${item.title}, currently in ${laneLabel}`}
+                      </VisuallyHidden>
+                    </Button>
+                  }
+                />
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+
+        {item.footer ? (
+          <div className="min-w-0 text-content-secondary text-xs">
+            {item.footer}
+          </div>
+        ) : null}
+      </div>
+    </li>
+  )
+}

package/src/Board/BoardLaneList.tsx

@@ -0,0 +1,275 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import { EmptyState } from "../EmptyState/EmptyState.tsx"
+import { toClassName } from "../toClassName.ts"
+import type { BoardItem } from "./BoardCard.tsx"
+import { BoardCard } from "./BoardCard.tsx"
+
+export type BoardLane = {
+  /**
+   * Lane-level controls, beside the count — Docket's *"Accept all"*
+   * on the review lane. `Button`s, usually.
+   */
+  actions?: ReactNode
+  /**
+   * Shown instead of the rows when the lane is empty. Defaults to a
+   * real `EmptyState`, because *"Real empty states"* was a stated
+   * requirement and an empty lane is the one a person sees most.
+   */
+  emptyState?: ReactNode
+  /**
+   * The **true** size of the lane, when `items` is a truncated page
+   * of it. This is what the count badge shows, and the difference
+   * between it and `items.length` is what the "+ n more" line says.
+   *
+   * Defaults to `items.length`, so a consumer that does not truncate
+   * says nothing about truncation.
+   */
+  itemCount?: number
+  items: readonly BoardItem[]
+  key: string
+  label: string
+  /**
+   * What "+ n more in this lane" does. With no handler the line is
+   * still shown — the honest count matters more than the
+   * affordance — but it is text rather than a button.
+   */
+  onShowMore?: () => void
+}
+
+export type BoardLaneListProps = {
+  /**
+   * Pixels from the top of the list box, or `null` for no
+   * indicator. Absolute rather than a real element between two
+   * cards: an indicator that takes up space moves the cards it is
+   * measured against, and the resulting feedback loop is why so many
+   * hand-rolled boards flicker.
+   */
+  dropIndicatorOffset: number | null
+  /**
+   * The lane heading's level. The caller's, because only the caller
+   * knows what the board sits under — an `<h3>` directly below the
+   * page's `<h1>` is an axe `heading-order` failure, and a board is
+   * as likely to sit under a section heading as under the page
+   * title.
+   */
+  headingLevel: 2 | 3 | 4 | 5
+  isVisibleWhenNarrow: boolean
+  lane: BoardLane
+  moveIcon?: ReactNode
+  moveTargets: readonly { key: string; label: string }[]
+  onMoveToLane?: (
+    itemKey: string,
+    toLaneKey: string,
+  ) => void
+  onStartDrag?: (
+    pointerEvent: {
+      clientX: number
+      clientY: number
+      currentTarget: EventTarget & Element
+      pointerId: number
+    },
+    origin: { fromIndex: number; itemKey: string },
+  ) => void
+  registerListElement: (element: HTMLElement | null) => void
+}
+
+/**
+ * One lane: a named heading, an honest count, its rows, and what it
+ * says when there are none.
+ *
+ * ### The lane is the container, and that is the whole design
+ *
+ * `@container` sits on a wrapper inside this section, so everything
+ * below it — the panel, its rows — is sized by **the lane**. Three
+ * lanes in a 1600px window are ~500px each; one lane in the Narrow
+ * View is ~360px; the same lane in a docked sidebar is 280px. All
+ * three happen on the same monitor, and no media query can tell
+ * them apart.
+ *
+ * The wrapper is a wrapper because a container query matches
+ * **descendants only**. Declaring `@container` on the panel itself
+ * would compile, generate real CSS, and silently never fire — so
+ * the panel could never take its own frame off at `cq-lg`, which is
+ * the one thing the widest layout asks for.
+ *
+ * This `<section>` is outside all of that: it carries the
+ * hidden/shown classes, and those resolve against the **board's**
+ * container, one level up.
+ *
+ * ### Long lanes truncate; they do not scroll
+ *
+ * *"Long lanes truncate with an honest `+ n more` rather than
+ * scrolling forever."* So the lane never grows a scrollbar and never
+ * virtualises. `itemCount` is the real total and `items` is whatever
+ * the consumer chose to render — which keeps paging, sorting and any
+ * windowing on the side that owns the data, and keeps this component
+ * from pretending to know how many rows are worth painting.
+ */
+export const BoardLaneList = ({
+  dropIndicatorOffset,
+  headingLevel,
+  isVisibleWhenNarrow,
+  lane,
+  moveIcon,
+  moveTargets,
+  onMoveToLane,
+  onStartDrag,
+  registerListElement,
+}: BoardLaneListProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  const itemCount = lane.itemCount ?? lane.items.length
+
+  const hiddenCount = itemCount - lane.items.length
+
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    /**
+     * `role="group"`, **not** a landmark — the same call the
+     * accordion made, for the same reason
+     * ([decision](../../../docs/decisions/2026-07-31-an-accordion-panel-is-a-group-not-a-landmark.md)).
+     * A named `<section>` is a `region`, and a board would then put
+     * three or four landmarks on a page that has one job. Worse,
+     * two boards on one page — or three copies of one in a
+     * container-width story — put two landmarks called "Todo" in
+     * the document, which is axe's `landmark-unique` and a genuine
+     * navigation problem rather than a lint nit. The board itself
+     * stays a region; its lanes are groups inside it.
+     *
+     * A `<div>` rather than a `<section role="group">`, and the
+     * difference is not cosmetic: axe's `landmark-unique` matches
+     * `section[aria-labelledby]` on the **element**, so a named
+     * `<section>` is still audited as a landmark after its role has
+     * been overridden. It failed exactly that way here before this
+     * line changed.
+     */
+    // biome-ignore lint/a11y/useSemanticElements: the semantic element for `group` is `<fieldset>`, which is a form-control grouping — it drags `<legend>` semantics, a border and form-reset behaviour onto a lane that holds a list of cards. Same call `Menu`'s group and `AccordionSection` already made.
+    <div
+      aria-labelledby={headingId}
+      role="group"
+      className={toClassName(
+        "min-w-0 flex-1 flex-col gap-2",
+        // Below the board's own `cq-lg`, one lane is on screen and
+        // the rest are chosen with the segmented control above. This
+        // queries the **board**, not the list below — an element
+        // carrying `container-type` still resolves its own container
+        // queries against its nearest ancestor container.
+        isVisibleWhenNarrow ? "flex" : "hidden cq-lg:flex",
+      )}
+    >
+      {/*
+       * The container is this wrapper rather than the panel inside
+       * it, and that is what buys the `cq-lg` treatment: an element
+       * cannot query the container it declares, so a panel that
+       * declared its own container could never take its own frame
+       * off again. One `<div>` and the whole width-dependent
+       * treatment becomes expressible.
+       */}
+      <div className="@container">
+        <div className="flex flex-col gap-2 rounded-lg border border-border-subtle bg-surface-raised px-3 py-2 cq-lg:border-0 cq-lg:bg-transparent cq-lg:p-0">
+          <header className="flex items-center gap-2">
+            <Heading
+              className="font-semibold text-content-primary text-sm"
+              id={headingId}
+            >
+              {lane.label}
+            </Heading>
+
+            <Badge
+              appearance="soft"
+              intent="neutral"
+              size="sm"
+            >
+              {String(itemCount)}
+            </Badge>
+
+            <span className="flex-1" />
+
+            {lane.actions}
+          </header>
+
+          <ul
+            className="relative flex flex-col"
+            ref={registerListElement}
+          >
+            {lane.items.length === 0 ? (
+              <li>
+                {lane.emptyState ?? (
+                  <EmptyState
+                    description="Nothing is waiting here."
+                    heading="Nothing here"
+                    headingLevel={
+                      // One below the lane's own, so the outline
+                      // stays whole wherever the board is mounted.
+                      (headingLevel + 1) as 3 | 4 | 5 | 6
+                    }
+                    size="sm"
+                  />
+                )}
+              </li>
+            ) : (
+              lane.items.map((item, index) => (
+                <BoardCard
+                  item={item}
+                  key={item.key}
+                  laneLabel={lane.label}
+                  moveIcon={moveIcon}
+                  moveTargets={moveTargets}
+                  onMoveToLane={
+                    onMoveToLane
+                      ? (toLaneKey) => {
+                          onMoveToLane(item.key, toLaneKey)
+                        }
+                      : undefined
+                  }
+                  onStartDrag={
+                    onStartDrag
+                      ? (pointerEvent) => {
+                          onStartDrag(pointerEvent, {
+                            fromIndex: index,
+                            itemKey: item.key,
+                          })
+                        }
+                      : undefined
+                  }
+                />
+              ))
+            )}
+
+            {dropIndicatorOffset === null ? null : (
+              <li
+                aria-hidden="true"
+                className="pointer-events-none absolute end-0 start-0 h-0.5 rounded-full bg-intent-accent-solid"
+                style={{
+                  insetBlockStart: `${dropIndicatorOffset}px`,
+                }}
+              />
+            )}
+          </ul>
+
+          {hiddenCount > 0 ? (
+            <p className="text-content-muted text-xs">
+              {lane.onShowMore ? (
+                <Button
+                  appearance="ghost"
+                  intent="neutral"
+                  onClick={lane.onShowMore}
+                  size="sm"
+                >
+                  {`+ ${hiddenCount} more in ${lane.label}`}
+                </Button>
+              ) : (
+                `+ ${hiddenCount} more in ${lane.label}`
+              )}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  )
+}