@charcuterie/ui 3.20.0 → 3.22.0

package/src/Board/Board.stories.tsx

@@ -188,6 +188,45 @@ const ADA: [string, string] = ["AD", "Ada"]
 
 const WREN: [string, string] = ["WR", "Wren"]
 
+/**
+ * A categorical index per project, and the same four projects the
+ * rest of this file uses. The index is what a consumer's user
+ * PICKED — it is not derived here, and it is never a hex.
+ */
+const PROJECT_EDGE_ITEMS: BoardItem[] = (
+  [
+    [
+      PROJECTS.signal,
+      2,
+      "Retire the second scheduler and fold its jobs into the broker",
+    ],
+    [
+      PROJECTS.loom,
+      5,
+      "One composed Storybook for every app in the fleet",
+    ],
+    [
+      PROJECTS.atlas,
+      8,
+      "Fingerprint duplicate uploads before they reach the queue",
+    ],
+    [
+      PROJECTS.ferry,
+      10,
+      "Rewrite the ingest runbook against the new broker",
+    ],
+  ] as const
+).map(([project, categorical, title]) => ({
+  accentEdge: { categorical },
+  // The words the bar cannot say. A colour alone is a WCAG
+  // 1.4.1 failure and is silent to a screen reader.
+  accentLabel: project,
+  href: `#/task/${encodeURIComponent(title)}`,
+  key: title,
+  meta: <ProjectChip name={project} />,
+  title,
+}))
+
 const TODO_ITEMS: BoardItem[] = [
   toItem({
     assignee: WREN,
@@ -565,6 +604,67 @@ export const Responsive: Story = {
   ),
 }
 
+/**
+ * **The project on the leading edge**, in both of the shapes a card
+ * takes — and the reason `accentEdge` exists beside `accentIntent`.
+ *
+ * The pill arm is a `w-1` span INSIDE the card, so it is a straight
+ * rectangle next to a rounded box. The edge arm is `Card`'s own
+ * treatment: a pseudo-element taking `border-radius: inherit`, so it
+ * paints a straight stripe down a row that has no corner and wraps
+ * the corner once the lane passes `cq-lg` and the row becomes a
+ * card. One prop, correct in both shapes, and never a notch.
+ *
+ * The colours are CATEGORICAL — an identity, not a state. A project,
+ * a repo, a source. Priority stays on the pill arm, where an intent
+ * belongs.
+ */
+export const AccentEdge: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="font-mono text-content-muted text-xs">
+          a narrow lane — rows, so the edge is a straight
+          stripe
+        </span>
+
+        <Frame inlineSize="22rem">
+          <Board
+            label="Today, by project"
+            lanes={[
+              {
+                items: PROJECT_EDGE_ITEMS,
+                key: "todo",
+                label: "Todo",
+              },
+            ]}
+          />
+        </Frame>
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <span className="font-mono text-content-muted text-xs">
+          the same lane past --cq-lg (48rem) — cards, so the
+          edge wraps the corner
+        </span>
+
+        <Frame inlineSize="56rem">
+          <Board
+            label="Today, by project, wide"
+            lanes={[
+              {
+                items: PROJECT_EDGE_ITEMS,
+                key: "todo",
+                label: "Todo",
+              },
+            ]}
+          />
+        </Frame>
+      </div>
+    </div>
+  ),
+}
+
 /**
  * The complete keyboard path, and it is the **primary** way to move
  * a card rather than an accessible alternative to the real one.

package/src/Board/Board.test.tsx

@@ -13,6 +13,7 @@ import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Board.stories.tsx"
 
 const {
+  AccentEdge,
   AllStates,
   Default,
   InBoardScreen,
@@ -405,3 +406,64 @@ test("the board adds no link of its own around a rich title", async () => {
     null,
   )
 })
+
+/**
+ * The edge is drawn on the card's OWN box, which is the whole
+ * difference between it and the `accentIntent` pill.
+ *
+ * A pill is a `w-1` span inside the card: a straight rectangle
+ * beside a rounded box, which is the notch three apps grew
+ * independently before `Card` took the shape over. The edge is a
+ * pseudo-element taking `border-radius: inherit`, so it is correct
+ * in both of a board card's shapes without being told which one it
+ * is in — a straight stripe down a row that has no corner, and a
+ * wrapped bar once the lane passes `cq-lg`.
+ *
+ * The class is what is asserted rather than a painted pixel: the
+ * bar is a `box-shadow` on a `::before`, and the radius it inherits
+ * comes from a container query the runner's own width does not
+ * decide. `cardAccentEdge.test.ts` owns what the class contains.
+ */
+test("draws a project's colour on the card's own edge", async () => {
+  const { canvas } = await mountStory(AccentEdge)
+
+  const cards = canvas
+    .getAllByRole("listitem")
+    .filter(
+      (item: HTMLElement) => item.dataset.boardCard != null,
+    )
+
+  expect(cards.length).toBeGreaterThan(0)
+
+  for (const card of cards) {
+    // The overlay, and the radius it takes from the card.
+    expect(card.className).toContain("before:absolute")
+    expect(card.className).toContain(
+      "before:rounded-[inherit]",
+    )
+
+    // A categorical colour, never an intent — an edge is an
+    // identity and an intent is a claim about what happens.
+    expect(card.className).toMatch(
+      /before:shadow-\[inset_3px_0_0_var\(--color-categorical-\d+-solid\)\]/,
+    )
+
+    // And it never eats a press on the card it covers.
+    expect(card.className).toContain(
+      "before:pointer-events-none",
+    )
+  }
+
+  // The colour reaches a screen reader as words. Each card names
+  // its project through `accentLabel`, so the bar is not the only
+  // channel carrying the fact.
+  expect(
+    canvas.getAllByText("Ferry Docs").length,
+  ).toBeGreaterThan(1)
+
+  await expectNoAxeViolations(
+    canvas.getByRole("region", {
+      name: "Today, by project",
+    }),
+  )
+})

package/src/Board/BoardCard.tsx

@@ -3,6 +3,11 @@ import type { ReactNode } from "react"
 import { useState } from "react"
 
 import { Button } from "../Button/Button.tsx"
+import type { CardAccentEdge } from "../Card/cardAccentEdge.ts"
+import {
+  getAccentEdgeClassName,
+  getAccentEdgeStyle,
+} from "../Card/cardAccentEdge.ts"
 import {
   FOCUS_RING_CLASS,
   INTENT_SOLID_FILL_CLASS,
@@ -13,23 +18,7 @@ import { toClassName } from "../toClassName.ts"
 import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
 
 type BoardItemFields = {
-  /**
-   * 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". */
+  /** What the bar means, in words. "Priority 0", "Movies and Shows". */
   accentLabel?: string
   /**
    * Under the title and metadata, spanning the card: a live run
@@ -68,6 +57,42 @@ type BoardItemFields = {
   trailing?: ReactNode
 }
 
+/**
+ * The leading colour bar, in one of two shapes — and the second one
+ * exists because the first cannot follow a corner.
+ *
+ * `accentIntent` is an inset pill: a `w-1` span inside the card,
+ * beside the content. It was built for priority — *"Priority is
+ * styled as a leading colour bar, and **never** a coloured word
+ * before the title."* An intent is a claim the design system makes
+ * (`danger` says what happens if you press the thing), so this arm
+ * is for a bar that means a STATE.
+ *
+ * `accentEdge` is the card's own edge — `Card`'s treatment, the same
+ * pseudo-element, so it takes `border-radius: inherit` and wraps the
+ * corner at `cq-lg` where this card grows one. It carries a
+ * CATEGORICAL colour or a computed one, which is what an identity
+ * needs: a project, a repo, a source. The owner asked for exactly
+ * this on Docket's board — *"The Board has no colors. That could
+ * use project colors on the sides at least."* — after reporting the
+ * same treatment missing from the task rows.
+ *
+ * The two are mutually exclusive by type, not by convention. Both
+ * paint a leading bar in the same place, and a card wearing two of
+ * them is a card whose leading edge means two things.
+ *
+ * ⚠️ Either arm pairs 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 its bars `--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.
+ */
+type BoardItemAccent =
+  | { accentEdge?: never; accentIntent?: IntentName }
+  | { accentEdge: CardAccentEdge; accentIntent?: never }
+
 /**
  * Who owns the card title's link — the board, or the caller.
  *
@@ -114,7 +139,9 @@ type BoardItemTitleLink =
       titleContent: ReactNode
     }
 
-export type BoardItem = BoardItemFields & BoardItemTitleLink
+export type BoardItem = BoardItemAccent &
+  BoardItemFields &
+  BoardItemTitleLink
 
 export type BoardCardProps = {
   item: BoardItem
@@ -210,10 +237,36 @@ export const BoardCard = ({
         // 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",
+        // The edge is drawn on THIS box, which is why it needs no
+        // shape of its own: the box is a row below `cq-lg` and a
+        // rounded card above it, and `border-radius: inherit` gives
+        // the right answer at both — a straight stripe down a row
+        // that has no corner, and a bar that wraps the card's
+        // corner once it grows one.
+        //
+        // `ps-2` is what keeps the content off it. The bar is 3px
+        // and overlays rather than displaces, so without this the
+        // first mark sits on top of it; at `cq-lg` the card's own
+        // `p-3` is already wider than the bar.
+        item.accentEdge != null &&
+          toClassName(
+            "ps-2",
+            getAccentEdgeClassName(item.accentEdge),
+          ),
         item.isDimmed && "opacity-60",
       )}
       data-board-card={item.key}
+      {...(item.accentEdge == null
+        ? {}
+        : { style: getAccentEdgeStyle(item.accentEdge) })}
     >
+      {/* The label the bar cannot say. An edge has no content of
+          its own — it is a pseudo-element — so unlike the pill
+          arm below there is nowhere inside it to put the words. */}
+      {item.accentEdge != null && item.accentLabel ? (
+        <VisuallyHidden>{item.accentLabel}</VisuallyHidden>
+      ) : null}
+
       {item.accentIntent ? (
         <span
           className={toClassName(

package/src/DropRail/DropRail.mdx

@@ -0,0 +1,90 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as DropRailStories from "./DropRail.stories";
+
+<Meta of={DropRailStories} />
+
+# DropRail
+
+Every destination at once, brought to the pointer instead of the pointer being carried to
+it.
+
+<Canvas of={DropRailStories.Default} />
+
+## Props
+
+<Controls />
+
+## The measurement this exists for
+
+`Board` moves a card with a `Menu` on the card, and for a board that is the right control:
+three or four lanes, all of them on screen, and the menu opens where your hand already is.
+
+It stops being the right control at the size the fleet's real lists reach. Docket's Backlog
+draws **34 project groups down one page**, of which about four fit on a display. Dragging a
+card from the first group to the thirty-fourth means holding a pointer down while the page
+scrolls under it, and a menu of 34 items is a scrolling list inside a popup — which is the
+same problem in a smaller box.
+
+A rail answers both halves. It pins to the top for the length of the move, so no destination
+is ever off screen, and there is no travel: every destination is the same short distance
+away.
+
+<Canvas of={DropRailStories.ManyTargets} />
+
+## One control, three drivers
+
+WCAG 2.5.7 (AA since 2.2) requires a single-pointer alternative to any dragging movement,
+and `FileDropZone` says the same thing about its own gesture: build the accessible path
+first and let the drag be the enhancement.
+
+So this is **not** a drag affordance with a fallback bolted on. It is a listbox that three
+things drive, all committing through one `onPick`:
+
+| Driver | Active chip | Commits on |
+| --- | --- | --- |
+| Pointer | the chip under the pointer, while a button is held | release over a chip |
+| Tap | the chip you touch | the tap |
+| Keyboard | walked with the arrow keys | <kbd>Enter</kbd> |
+
+The rail does not know which of the three opened it, and the host does not have to say. It
+reads `event.buttons` on the first pointer event it sees — a button already down means a
+drag is in flight.
+
+<Canvas of={DropRailStories.InAList} />
+
+## It takes no drag-and-drop dependency
+
+The [board's decision](https://github.com/Sawtaytoes/charcuterie) priced four drag-and-drop
+libraries and took none of them, because a published library's dependency list is inherited
+by every consumer — including one with 60 KB gzipped to spend in total. Nothing here changes
+that arithmetic, and this component needs far less than `Board` does: a chip is a box under
+the pointer, so `elementFromPoint` answers the only geometric question there is. No
+snapshot, no collision strategy, no sortable transform.
+
+## It is not `Rail`
+
+`Rail` is the app shell's side rail — a landmark, an `<aside>` or a `<nav>`, permanent
+furniture down one edge of a page. `DropRail` is a horizontal strip of drop targets that
+exists only for the length of a move, and it is a `listbox`. They share four letters and
+nothing else; `FileDropZone` is the precedent for the prefix carrying the distinction.
+
+## The three chip states
+
+<Canvas of={DropRailStories.AllStates} />
+
+The destination the item is **already in** stays visible and unofferable rather than being
+filtered out. A rail whose contents change depending on what you grabbed is a rail whose
+chips move under the pointer between one move and the next, and muscle memory is the only
+reason this control is faster than a menu.
+
+Neither that state nor the disabled one is marked by colour alone. The current chip carries
+visually hidden text — *"— where it is now"* — and both carry `aria-disabled`, because the
+one chip a person must not aim for is exactly the one that must not rely on being dimmer
+(WCAG 1.4.1).
+
+## What it deliberately does not do
+
+It does not render the thing being dragged, own the handle, or know what a move means. The
+host keeps all three, which is what lets the same rail sit above a board, a card grid, or a
+list of accordions without any of them being modelled here.