@charcuterie/ui 3.25.0 → 3.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.25.0",
+  "version": "3.27.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/Board/Board.mdx

@@ -11,6 +11,8 @@ Lanes of cards, sized by their **container**, moved by keyboard or by pointer
 
 <Canvas of={BoardStories.Default} />
 
+<Canvas of={BoardStories.CardMenuItems} />
+
 ## Props
 
 <Controls />
@@ -43,6 +45,18 @@ The narrow panel there is **not a phone**. It is the same board in a sidebar, in
 window, or on a display somebody has zoomed to 175% — and a media query cannot tell any of
 those apart from a maximised 4K window.
 
+## Workflow columns and project-pool rows
+
+The default `laneLayout="columns"` is for workflow stages. At `cq-lg` the lanes sit side by
+side; below it, one selected lane stays on screen and a segmented control names the others.
+
+`laneLayout="rows"` is for parallel project pools. Every lane becomes one horizontal band,
+every lane stays visible, and the cards form a responsive grid inside their band. A consumer
+can pass a short `items` array with the true `itemCount`; the remaining count stays explicit
+instead of making one large pool determine the page height. Neither layout scrolls sideways.
+
+<Canvas of={BoardStories.RowLayout} />
+
 ### The three card shapes
 
 Straight from the consumer requirement, which is specific because the owner answered *"which
@@ -84,6 +98,9 @@ The move is one control with two drivers, and they commit through the same `onMo
    code path, with `setPointerCapture` so the drag survives the pointer leaving the card.
    Escape abandons it.
 
+An item can append actions to that existing menu with `menuItems`. The Board inserts a
+separator after the lane destinations, so a card action does not need a second trigger.
+
 <Canvas of={BoardStories.Interactive} />
 
 Every move is announced in a `role="status"` region that names the **destination and the

package/src/Board/Board.stories.tsx

@@ -404,6 +404,35 @@ const LANES: BoardLane[] = [
   },
 ]
 
+/**
+ * Eight parallel project pools, not workflow steps. The repeated
+ * source items are cloned with lane-qualified keys so the story can
+ * put realistic card density in every row without claiming that one
+ * card belongs to eight pools.
+ */
+const POOL_LANES: BoardLane[] = [
+  ["repair", "Repair source", 83],
+  ["add", "Add media", 78],
+  ["replace", "Replace copy", 66],
+  ["review", "Review retention", 38],
+  ["find", "Find source", 31],
+  ["extras", "Specials and films", 18],
+  ["difficult", "Difficult repair", 14],
+  ["unfiled", "Not in a lane", 1],
+].map(([key, label, itemCount]) => ({
+  itemCount: Number(itemCount),
+  items: TODO_ITEMS.slice(
+    0,
+    Math.min(3, Number(itemCount)),
+  ).map((item) => ({
+    ...item,
+    key: `${String(key)}-${item.key}`,
+  })),
+  key: String(key),
+  label: String(label),
+  onShowMore: () => undefined,
+}))
+
 /**
  * A **fixed** inline size, because the three-up layout is a
  * measurement of the board's own box. A story that inherited the
@@ -446,6 +475,25 @@ type Story = StoryObj<typeof meta>
  */
 export const Default: Story = {}
 
+/**
+ * Parallel project pools as horizontal bands. Every lane stays on
+ * screen; the cards form a responsive grid inside their own lane,
+ * and the honest overflow keeps a large pool from making the page
+ * endless.
+ */
+export const RowLayout: Story = {
+  render: (boardProps) => (
+    <Frame inlineSize="72rem">
+      <Board
+        {...boardProps}
+        label="Project pools"
+        laneLayout="rows"
+        lanes={POOL_LANES}
+      />
+    </Frame>
+  ),
+}
+
 /**
  * Read-only against movable, side by side.
  *
@@ -750,6 +798,46 @@ export const Interactive: Story = {
   render: () => <MovableBoard />,
 }
 
+/**
+ * A consumer can add a card action to the same menu as the lane
+ * moves. The separator is supplied by `BoardCard`, so the action
+ * does not need a second trigger beside the existing one.
+ */
+export const CardMenuItems: Story = {
+  render: () => (
+    <Frame inlineSize="72rem">
+      <Board
+        label="Today, with card actions"
+        lanes={[
+          {
+            items: [
+              {
+                ...TODO_ITEMS[0],
+                menuItems: [
+                  {
+                    key: "send-to-backlog",
+                    label: "Send to Backlog",
+                    onSelect: () => undefined,
+                  },
+                ],
+              },
+            ],
+            key: "todo",
+            label: "Todo",
+          },
+          {
+            items: IN_PROGRESS_ITEMS.slice(0, 1),
+            key: "in-progress",
+            label: "In Progress",
+          },
+        ]}
+        moveIcon={<MoreIcon />}
+        onMove={() => undefined}
+      />
+    </Frame>
+  ),
+}
+
 /**
  * Where it actually goes, and what the consumer still owns.
  *

package/src/Board/Board.test.tsx

@@ -15,6 +15,7 @@ import * as stories from "./Board.stories.tsx"
 const {
   AccentEdge,
   AllStates,
+  CardMenuItems,
   Default,
   InBoardScreen,
   Interactive,
@@ -22,6 +23,7 @@ const {
   LinkedLaneHeadings,
   MoveHandleByWidth,
   Responsive,
+  RowLayout,
 } = composeStories(stories)
 
 /**
@@ -74,6 +76,30 @@ test("a board wider than cq-lg shows every lane at once", async () => {
   ).toHaveLength(0)
 })
 
+test("the row layout keeps every lane visible and grids the cards inside it", async () => {
+  const { canvas } = await mountStory(RowLayout)
+
+  await expect(canvas.getAllByRole("group")).toHaveLength(8)
+  await expect(
+    canvas.queryAllByRole("radiogroup"),
+  ).toHaveLength(0)
+
+  const repair = expectAgentDrivable(canvas, {
+    name: "Repair source",
+    role: "group",
+  })
+  const list = within(repair).getByRole("list")
+  const columns = getComputedStyle(list)
+    .gridTemplateColumns.split(" ")
+    .filter(Boolean)
+
+  await expect(getComputedStyle(list).display).toBe("grid")
+  await expect(columns.length).toBeGreaterThan(1)
+  await expect(
+    within(repair).getByText("+ 80 more in Repair source"),
+  ).toBeInTheDocument()
+})
+
 /**
  * The count is the lane's **real** size, not the number of rows
  * painted. A board that truncates and then reports the truncated
@@ -408,6 +434,46 @@ test("the board adds no link of its own around a rich title", async () => {
   )
 })
 
+/**
+ * Extra card actions share the existing move menu. A second
+ * trigger would make the card look busy and would split related
+ * actions across two controls, so the component owns the separator
+ * between the lane destinations and the consumer's items.
+ */
+test("a card can append an action to its existing menu", async () => {
+  const { body, canvas } = await mountStory(CardMenuItems)
+
+  const todo = expectAgentDrivable(canvas, {
+    name: "Todo",
+    role: "group",
+  })
+
+  await userEvent.click(
+    within(todo).getByRole("button", {
+      name: /^Move Retire the second scheduler/,
+    }),
+  )
+
+  const menu = await waitFor(() =>
+    expectAgentDrivable(body, {
+      name: /Move Retire the second scheduler/,
+      role: "menu",
+    }),
+  )
+
+  expect(
+    within(menu).getByRole("menuitem", {
+      name: "In Progress",
+    }),
+  ).toBeInTheDocument()
+  expect(
+    within(menu).getByRole("menuitem", {
+      name: "Send to Backlog",
+    }),
+  ).toBeInTheDocument()
+  expect(menu.querySelector("hr")).not.toBeNull()
+})
+
 /**
  * The edge is drawn on the card's OWN box, which is the whole
  * difference between it and the `accentIntent` pill.

package/src/Board/Board.tsx

@@ -42,6 +42,16 @@ export type BoardProps = {
   headingLevel?: 2 | 3 | 4 | 5
   /** The board's accessible name. Required — it is a landmark. */
   label: string
+  /**
+   * How the lanes themselves are arranged.
+   *
+   * `columns` is the workflow shape: lanes sit side by side above
+   * `cq-lg`, and the Narrow View selects one lane. `rows` is the
+   * project-pool shape: every lane is one horizontal band, its cards
+   * form a responsive grid inside that band, and every lane stays on
+   * screen at every width.
+   */
+  laneLayout?: "columns" | "rows"
   lanes: readonly BoardLane[]
   /**
    * What the move handle shows **while the lanes are side by side**.
@@ -91,9 +101,11 @@ export type BoardProps = {
  * So there are **two nested containers**, and they answer two
  * different questions:
  *
- *  - The board's own box decides *how many lanes are on screen* —
- *    three-up at `cq-lg` and wider, one lane plus a segmented
- *    control below it.
+ *  - The board's own box decides *how workflow lanes are shown* —
+ *    side by side at `cq-lg` and wider, one lane plus a segmented
+ *    control below it. A project-pool board with
+ *    `laneLayout="rows"` keeps every lane on screen and grids the
+ *    cards inside each horizontal band instead.
  *  - Each lane's list decides *what shape a card is* — two lines,
  *    one line, or its own card. See `BoardCard`.
  *
@@ -105,9 +117,10 @@ export type BoardProps = {
  * *"No horizontal scroll, ever. The board becomes a segmented
  * control, never a pan surface."* A board that pans sideways hides
  * lanes behind a gesture with no affordance, and on a trackpad it
- * fights the browser's own back-navigation. So the narrow layout
- * shows one lane at a time and names the others in a `radiogroup`
- * that says how many cards each holds.
+ * fights the browser's own back-navigation. So the narrow workflow
+ * layout shows one lane at a time and names the others in a
+ * `radiogroup` that says how many cards each holds. A row layout
+ * wraps its cards inside each lane and also never pans.
  *
  * ### Moving a card is a first-class operation, and it is not a drag
  *
@@ -137,6 +150,7 @@ export const Board = ({
   className,
   headingLevel = 3,
   label,
+  laneLayout = "columns",
   lanes,
   moveIcon,
   narrowLaneKey,
@@ -249,7 +263,12 @@ export const Board = ({
          * board has no stray radiogroup in it.
          */}
         <SegmentedControl
-          className="max-w-full flex-wrap cq-lg:hidden"
+          className={toClassName(
+            "max-w-full flex-wrap",
+            laneLayout === "rows"
+              ? "hidden"
+              : "cq-lg:hidden",
+          )}
           items={lanes.map((lane) => ({
             // Stacked rather than `Todo (6)`, because the count is
             // the reason to look: a lane picker that reads
@@ -276,7 +295,13 @@ export const Board = ({
           selectedValue={visibleLaneKey}
         />
 
-        <div className="flex flex-col gap-4 cq-lg:flex-row cq-lg:items-start">
+        <div
+          className={toClassName(
+            "flex flex-col gap-4",
+            laneLayout === "columns" &&
+              "cq-lg:flex-row cq-lg:items-start",
+          )}
+        >
           {lanes.map((lane) => (
             <BoardLaneList
               headingLevel={headingLevel}
@@ -290,6 +315,7 @@ export const Board = ({
               }
               key={lane.key}
               lane={lane}
+              laneLayout={laneLayout}
               moveIcon={moveIcon}
               moveTargets={lanes
                 .filter((one) => one.key !== lane.key)

package/src/Board/BoardCard.tsx

@@ -12,6 +12,7 @@ import {
   FOCUS_RING_CLASS,
   INTENT_SOLID_FILL_CLASS,
 } from "../intentStyles.ts"
+import type { MenuProps } from "../Menu/Menu.tsx"
 import { Menu } from "../Menu/Menu.tsx"
 import { TextLink } from "../TextLink/TextLink.tsx"
 import { toClassName } from "../toClassName.ts"
@@ -55,6 +56,12 @@ type BoardItemFields = {
   title: string
   /** The trailing cluster: an assignee avatar, an elapsed-time chip. */
   trailing?: ReactNode
+  /**
+   * Extra actions in the card's existing menu, after the lane moves.
+   * A separator is added when both sets have entries, so a consumer
+   * can add a card action without creating a second trigger.
+   */
+  menuItems?: MenuProps["items"]
 }
 
 /**
@@ -144,6 +151,12 @@ export type BoardItem = BoardItemAccent &
   BoardItemTitleLink
 
 export type BoardCardProps = {
+  /**
+   * A grid card measures its own inline size for its inner layout.
+   * A list card inherits the lane's measurement, which is almost
+   * the same width and avoids an unnecessary nested container.
+   */
+  isInGrid: boolean
   item: BoardItem
   laneLabel: string
   /**
@@ -175,25 +188,25 @@ export type BoardCardProps = {
  * 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 three shapes are one component, chosen by available space
  *
  * 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 |
+ * | The card's available width 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.
+ * Every one of those is a **container** query, never a media query.
+ * A list card reads the lane because it fills that lane. A grid card
+ * is its own container because several cards share a wide row. A
+ * lane in a three-up board is narrow on a 4K display, and a zoomed
+ * browser can report far fewer effective CSS pixels than its window
+ * has. 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
@@ -242,6 +255,7 @@ export type BoardCardProps = {
  * answers this question exactly backwards.
  */
 export const BoardCard = ({
+  isInGrid,
   item,
   laneLabel,
   moveIcon,
@@ -251,6 +265,34 @@ export const BoardCard = ({
 }: BoardCardProps): ReactNode => {
   const [isMenuVisible, setIsMenuVisible] = useState(false)
 
+  const isMovable =
+    onMoveToLane != null && moveTargets.length > 0
+  const hasMenuItems = (item.menuItems?.length ?? 0) > 0
+  const hasMenu =
+    onMoveToLane != null && (isMovable || hasMenuItems)
+  const menuItems: MenuProps["items"] = [
+    ...(isMovable
+      ? moveTargets.map((target) => ({
+          key: target.key,
+          label: target.label,
+          onSelect: () => {
+            onMoveToLane?.(target.key)
+          },
+        }))
+      : []),
+    ...(hasMenuItems && isMovable
+      ? [
+          {
+            key: "board-extra-actions",
+            type: "separator" as const,
+          },
+        ]
+      : []),
+    ...(item.menuItems ?? []),
+  ]
+
+  const menuLabel = isMovable ? "Move" : "More"
+
   const titleBlock = (
     // `line-clamp-none` before `truncate`, because `line-clamp-2`
     // sets `display: -webkit-box` and `text-overflow` has nothing to
@@ -267,6 +309,7 @@ export const BoardCard = ({
     <li
       className={toClassName(
         "group relative flex gap-2 border-border-subtle border-b py-2 pe-1 last:border-b-0",
+        isInGrid && "@container",
         // 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
@@ -359,20 +402,14 @@ export const BoardCard = ({
             ) : null}
           </div>
 
-          {item.trailing || onMoveToLane ? (
+          {item.trailing || hasMenu ? (
             <div className="flex shrink-0 items-center gap-1">
               {item.trailing}
 
-              {onMoveToLane && moveTargets.length > 0 ? (
+              {hasMenu ? (
                 <Menu
                   isVisible={isMenuVisible}
-                  items={moveTargets.map((target) => ({
-                    key: target.key,
-                    label: target.label,
-                    onSelect: () => {
-                      onMoveToLane(target.key)
-                    },
-                  }))}
+                  items={menuItems}
                   onDismiss={() => {
                     setIsMenuVisible(false)
                   }}
@@ -409,9 +446,13 @@ export const BoardCard = ({
                           (isVisible) => !isVisible,
                         )
                       }}
-                      onPointerDown={(pointerEvent) => {
-                        onStartDrag?.(pointerEvent)
-                      }}
+                      onPointerDown={
+                        isMovable
+                          ? (pointerEvent) => {
+                              onStartDrag?.(pointerEvent)
+                            }
+                          : undefined
+                      }
                       size="sm"
                       sizing="control"
                     >
@@ -441,7 +482,7 @@ export const BoardCard = ({
                             "@min-[48rem]/board:hidden",
                         )}
                       >
-                        Move
+                        {menuLabel}
                       </span>
 
                       {/*
@@ -459,7 +500,9 @@ export const BoardCard = ({
                        * X" narrow is one control with two names.
                        */}
                       <VisuallyHidden>
-                        {`Move ${item.title}, currently in ${laneLabel}`}
+                        {isMovable
+                          ? `Move ${item.title}, currently in ${laneLabel}`
+                          : `More actions for ${item.title}, currently in ${laneLabel}`}
                       </VisuallyHidden>
                     </Button>
                   }

package/src/Board/BoardLaneList.tsx

@@ -89,6 +89,7 @@ export type BoardLaneListProps = {
   headingLevel: 2 | 3 | 4 | 5
   isVisibleWhenNarrow: boolean
   lane: BoardLane
+  laneLayout: "columns" | "rows"
   moveIcon?: ReactNode
   moveTargets: readonly { key: string; label: string }[]
   onMoveToLane?: (
@@ -144,6 +145,7 @@ export const BoardLaneList = ({
   headingLevel,
   isVisibleWhenNarrow,
   lane,
+  laneLayout,
   moveIcon,
   moveTargets,
   onMoveToLane,
@@ -189,7 +191,11 @@ export const BoardLaneList = ({
         // 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",
+        laneLayout === "rows"
+          ? "flex"
+          : isVisibleWhenNarrow
+            ? "flex"
+            : "hidden cq-lg:flex",
       )}
     >
       {/*
@@ -201,8 +207,20 @@ export const BoardLaneList = ({
        * 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">
+        <div
+          className={toClassName(
+            "gap-2 rounded-lg border border-border-subtle px-3 py-2",
+            laneLayout === "rows"
+              ? "grid bg-surface-raised cq-lg:grid-cols-[12rem_minmax(0,1fr)] cq-lg:items-start cq-lg:gap-x-3"
+              : "flex flex-col bg-surface-raised cq-lg:border-0 cq-lg:bg-transparent cq-lg:p-0",
+          )}
+        >
+          <header
+            className={toClassName(
+              "flex items-center gap-2",
+              laneLayout === "rows" && "flex-wrap",
+            )}
+          >
             <Heading
               className="font-semibold text-content-primary text-sm"
               id={headingId}
@@ -245,7 +263,12 @@ export const BoardLaneList = ({
           </header>
 
           <ul
-            className="relative flex flex-col"
+            className={toClassName(
+              "relative",
+              laneLayout === "rows"
+                ? "grid grid-cols-[repeat(auto-fit,minmax(min(100%,14rem),1fr))] gap-2"
+                : "flex flex-col",
+            )}
             ref={registerListElement}
           >
             {lane.items.length === 0 ? (
@@ -266,6 +289,7 @@ export const BoardLaneList = ({
             ) : (
               lane.items.map((item, index) => (
                 <BoardCard
+                  isInGrid={laneLayout === "rows"}
                   item={item}
                   key={item.key}
                   laneLabel={lane.label}
@@ -304,7 +328,13 @@ export const BoardLaneList = ({
           </ul>
 
           {hiddenCount > 0 ? (
-            <p className="text-content-muted text-xs">
+            <p
+              className={toClassName(
+                "text-content-muted text-xs",
+                laneLayout === "rows" &&
+                  "cq-lg:col-start-2",
+              )}
+            >
               {lane.onShowMore ? (
                 <Button
                   appearance="ghost"

package/src/MarkdownEditor/MarkdownEditor.mdx

@@ -114,7 +114,7 @@ A consumer that must swap the whole document — Docket opening a different task
 with a `key`. That is one line, and it is honest about the fact that the old undo history
 belonged to the old document.
 
-## Paste an image at the cursor
+## Put an image at the cursor — paste, drop, or press **Image**
 
 ```tsx
 <MarkdownEditor
@@ -137,8 +137,35 @@ during an upload and the insertion point has to move with what they type. It car
 counter so two files of the same name do not resolve into each other's slot, and a failed
 upload leaves a document the user can read and fix rather than a dangling widget.
 
-Omit `onUploadImage` and image paste is simply not offered. A `<textarea>` ignores a pasted
-image on its own, which is the correct fallback rather than a broken one.
+Omit `onUploadImage` and none of the three is offered — no toolbar button, and a paste left
+to the browser. A `<textarea>` ignores a pasted image on its own, which is the correct
+fallback rather than a broken one.
+
+### The **Image** button, and why it is in the toolbar
+
+Paste and drop are both mouse-and-keyboard gestures. On a tablet there is nothing to paste
+from and nothing to drag, so wiring `onUploadImage` also puts an **Image** action in the
+toolbar: it opens the platform file picker, which on a phone is where the camera is offered.
+
+It is a toolbar action rather than a `FileDropZone` under the box **because of the caret**.
+Pressing anything outside the editor moves focus out of it, so a control beside the editor
+can only append to the end of the document — and an image in prose belongs at the point it
+is explained, not stapled to the bottom. The `<textarea>` keeps its `selectionStart` while
+blurred, so the insertion lands where the user last was.
+
+**It is the fourth action, and the position is load-bearing.** `Toolbar` overflows from the
+**end** of the list, so the order in that list is the priority order. Placed last — beside
+Link, where it reads most naturally — Image was the first thing to collapse, hidden behind
+"More actions" at 900px. A control nobody can find does not fix "adding an image is buried";
+it moves the problem. Fourth is visible wherever four actions fit, and it reads as a group:
+emphasis, structure, insert.
+
+⚠️ **It still collapses on a genuinely narrow editor, and that is not a bug to route around.**
+Measured on the `Interactive` story: at 900px the bar carries eight actions and Image is one
+of them; at 460px it carries three, and everything after Heading is in the overflow. A
+comment box in a rail is that width. Keep a `FileDropZone` beside such an editor as well —
+appending to the end of the document is the right trade when the alternative is a control
+nobody can reach.
 
 ## Composition, and the one component that did not fit
 
@@ -152,7 +179,8 @@ component.
 `<label>` around a file input covering its whole area — correct for "drop a disc image here",
 and wrong for a text surface, where the drop has to land *at a character offset* and the area
 has to keep taking clicks as caret placement. So the editor handles its own drop, and
-`FileDropZone` stays the right answer for the attachment list beside it.
+`FileDropZone` stays the right answer for the attachment list beside it — and for a
+narrow editor whose toolbar has collapsed the Image action away.
 
 <Canvas of={MarkdownEditorStories.Responsive} />