@charcuterie/ui 4.24.0 → 4.25.0

package/src/GroupedList/GroupedList.stories.tsx

@@ -1,6 +1,6 @@
 import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
 import type { Meta, StoryObj } from "@storybook/react"
-import type { CSSProperties } from "react"
+import { type CSSProperties, useState } from "react"
 
 import { Badge } from "../Badge/Badge.tsx"
 import { Button } from "../Button/Button.tsx"
@@ -10,7 +10,11 @@ import {
   StoryGrid,
 } from "../board.storyHelpers.tsx"
 import { EmptyState } from "../EmptyState/EmptyState.tsx"
-import type { GroupedListGroup } from "./GroupedList.tsx"
+import { ValuePairs } from "../ValuePairs/ValuePairs.tsx"
+import type {
+  GroupedListGroup,
+  GroupedListItem,
+} from "./GroupedList.tsx"
 import { GroupedList } from "./GroupedList.tsx"
 import { GROUPED_LIST_HEADING_SURFACE_PROPERTY } from "./groupedListStickyHeading.ts"
 
@@ -183,6 +187,142 @@ const CHORE_GROUPS: GroupedListGroup[] = [
   },
 ]
 
+/**
+ * Fixture data only. A chore card whose whole row opens its editor:
+ * the shape tally-marks' Rows view draws, with the payout beside the
+ * text and the daily cap under it.
+ */
+type ChoreCard = {
+  isActive: boolean
+  isHighlighted?: boolean
+  key: string
+  label: string
+  maxPerDay: number
+  points: number
+}
+
+const CHORE_CARDS: ChoreCard[] = [
+  {
+    isActive: true,
+    key: "water-ferns",
+    label: "Water the ferns",
+    maxPerDay: 5,
+    points: 5,
+  },
+  {
+    isActive: true,
+    isHighlighted: true,
+    key: "sort-recycling",
+    label: "Sort the recycling",
+    maxPerDay: 6,
+    points: 2,
+  },
+  {
+    isActive: false,
+    key: "feed-goldfish",
+    label: "Feed the goldfish",
+    maxPerDay: 2,
+    points: 2,
+  },
+]
+
+/**
+ * One chore card as a row. `onSelect` opens it; the action beside it
+ * is a separate target. A switched-off card is muted and says so in
+ * a badge.
+ */
+const toChoreRow = (
+  card: ChoreCard,
+  {
+    onDelete,
+    onSelect,
+  }: {
+    onDelete?: (label: string) => void
+    onSelect?: (label: string) => void
+  } = {},
+): GroupedListItem => ({
+  actions: (
+    <Button
+      appearance="ghost"
+      aria-label={`Delete ${card.label}`}
+      intent="danger"
+      onClick={() => {
+        onDelete?.(card.label)
+      }}
+      size="sm"
+    >
+      Delete
+    </Button>
+  ),
+  aside: (
+    <ValuePairs
+      items={[
+        {
+          id: "scan",
+          label: "Per scan",
+          value: `${card.points} pts`,
+        },
+      ]}
+      label="Payout"
+    />
+  ),
+  badges: card.isActive ? undefined : (
+    <Badge appearance="soft" size="sm">
+      off
+    </Badge>
+  ),
+  content: `Up to ${card.maxPerDay} pts a day`,
+  description: card.key,
+  highlightIntent: "success",
+  isHighlighted: card.isHighlighted,
+  isMuted: !card.isActive,
+  key: card.key,
+  label: card.label,
+  onSelect: () => {
+    onSelect?.(card.label)
+  },
+  selectLabel: `Edit ${card.label}`,
+})
+
+const toChoreGroups = (
+  handlers?: Parameters<typeof toChoreRow>[1],
+): GroupedListGroup[] => [
+  {
+    heading: "Team Orion",
+    items: CHORE_CARDS.map((card) =>
+      toChoreRow(card, handlers),
+    ),
+    key: "orion",
+    summary: "3 cards · up to 11 pts a day",
+  },
+]
+
+/**
+ * Fixture data only. The same plain row in each highlight intent.
+ */
+const HIGHLIGHT_INTENT_GROUPS: GroupedListGroup[] = [
+  {
+    heading: "Highlight intents",
+    items: (
+      [
+        "accent",
+        "success",
+        "info",
+        "warning",
+        "danger",
+        "neutral",
+      ] as const
+    ).map((intent) => ({
+      description: `highlightIntent="${intent}"`,
+      highlightIntent: intent,
+      isHighlighted: true,
+      key: intent,
+      label: `Highlighted ${intent}`,
+    })),
+    key: "intents",
+  },
+]
+
 const LONG_GROUPS: GroupedListGroup[] = [
   {
     heading:
@@ -524,6 +664,116 @@ export const StickyHeadings: Story = {
   ),
 }
 
+/**
+ * A row whose whole surface is its primary action. `onSelect` draws
+ * one native button under the row's text, named by `selectLabel`;
+ * the Delete action sits above it as its own target. The status
+ * line under the list says which one a click reached.
+ *
+ * The second card is highlighted (a scan just paid it), and the
+ * third is switched off, so it is muted.
+ */
+export const SelectableRows: Story = {
+  render: function SelectableRowsStory() {
+    const [lastEvent, setLastEvent] = useState(
+      "Nothing chosen yet",
+    )
+
+    return (
+      <div className="flex flex-col gap-3">
+        <GroupedList
+          groups={toChoreGroups({
+            onDelete: (label) => {
+              setLastEvent(`Deleted ${label}`)
+            },
+            onSelect: (label) => {
+              setLastEvent(`Opened ${label}`)
+            },
+          })}
+        />
+
+        <p
+          className="m-0 text-content-secondary text-sm"
+          role="status"
+        >
+          {lastEvent}
+        </p>
+      </div>
+    )
+  },
+}
+
+/**
+ * Every per-row state at once: hover, press and keyboard focus on
+ * the whole-row button (forced by the pseudo-states addon, the only
+ * way to review them in a static board), a muted row, and a
+ * highlight in each intent. The highlight's pulse is frozen here, so
+ * this is also its static, reduced-motion look.
+ */
+export const RowStates: Story = {
+  parameters: {
+    pseudo: {
+      active: ["#active-row li:first-child > button"],
+      focusVisible: ["#focus-row li:first-child > button"],
+      hover: ["#hover-row li:first-child > button"],
+    },
+  },
+  render: () => (
+    <StoryGrid columns={2}>
+      {(
+        [
+          ["resting", "resting-row"],
+          ["hover (forced)", "hover-row"],
+          ["active (forced)", "active-row"],
+          ["focus-visible (forced)", "focus-row"],
+        ] as const
+      ).map(([label, id]) => (
+        <StoryCell align="stretch" key={id} label={label}>
+          <div id={id}>
+            <GroupedList
+              groups={[
+                {
+                  heading: `Team Orion, ${label}`,
+                  items: CHORE_CARDS.slice(0, 1).map(
+                    (card) => toChoreRow(card),
+                  ),
+                  key: id,
+                },
+              ]}
+              size="sm"
+            />
+          </div>
+        </StoryCell>
+      ))}
+
+      <StoryCell align="stretch" label="isMuted">
+        <GroupedList
+          groups={[
+            {
+              heading: "Switched off",
+              items: [
+                toChoreRow(CHORE_CARDS[2] as ChoreCard),
+              ],
+              key: "muted",
+            },
+          ]}
+          size="sm"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="isHighlighted, each highlightIntent"
+      >
+        <GroupedList
+          groups={HIGHLIGHT_INTENT_GROUPS}
+          size="sm"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
 /**
  * Light and dark side by side, each panel scoped with its own
  * `data-scheme`, so both read at once whatever the toolbar says.

package/src/GroupedList/GroupedList.test.tsx

@@ -9,6 +9,7 @@ import {
   within,
 } from "storybook/test"
 import { test } from "vitest"
+import { userEvent as browserUserEvent } from "vitest/browser"
 
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
@@ -25,6 +26,8 @@ const {
   NarrowView,
   Playground,
   Responsive,
+  RowStates,
+  SelectableRows,
   StickyHeadings,
 } = composeStories(stories)
 
@@ -388,3 +391,391 @@ test("a stuck heading's background is the surface its host names, and surface-ba
     ).backgroundColor,
   )
 })
+
+/** The `<li>` a whole-row button stretches over. */
+const rowOf = (button: HTMLElement) =>
+  button.closest("li") as HTMLElement
+
+/** What the pointer would hit at the middle of an element's box. */
+const elementAtCentreOf = (element: HTMLElement) => {
+  const box = element.getBoundingClientRect()
+
+  return document.elementFromPoint(
+    box.left + box.width / 2,
+    box.top + box.height / 2,
+  )
+}
+
+test("a row without onSelect draws no row button", async () => {
+  const { canvas } = await mountStory(Playground)
+
+  await expect(
+    canvas.queryByRole("button", { name: "Lobby" }),
+  ).toBeNull()
+
+  await expect(
+    canvas
+      .getAllByRole("button")
+      .map((button: HTMLElement) =>
+        button.getAttribute("aria-label"),
+      ),
+  ).toEqual([
+    "Open Lobby",
+    "Open Break Room",
+    "Open Welcome",
+    "Open Weather",
+    "Open Schedule",
+    "Open Test Pattern",
+  ])
+})
+
+test("onSelect makes the whole row one native button, named by selectLabel", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(SelectableRows)
+
+  const rowButton = expectAgentDrivable(canvas, {
+    name: "Edit Water the ferns",
+    role: "button",
+  })
+
+  await expect(rowButton.tagName).toBe("BUTTON")
+
+  await expect(rowButton).toHaveAttribute("type", "button")
+
+  // Nothing is nested inside it: the row's text is a sibling drawn
+  // over it, so there is no interactive content inside a button.
+  await expect(rowButton.childElementCount).toBe(0)
+
+  const row = rowOf(rowButton)
+
+  const buttonBox = rowButton.getBoundingClientRect()
+
+  // Full-area: the button covers the row's whole padding box — all
+  // of it but the 1px divider between rows.
+  await expect(buttonBox.width).toBeCloseTo(
+    row.clientWidth,
+    0,
+  )
+
+  await expect(buttonBox.height).toBeCloseTo(
+    row.clientHeight,
+    0,
+  )
+
+  // A pointer on the label, the description, the cap line or the
+  // payout lands on the row's button.
+  for (const text of [
+    "Water the ferns",
+    "water-ferns",
+    "Up to 5 pts a day",
+    "5 pts",
+  ]) {
+    await expect(
+      elementAtCentreOf(within(row).getByText(text)),
+    ).toBe(rowButton)
+  }
+
+  await userEvent.click(rowButton)
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Opened Water the ferns")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a row's action stays its own target and never selects the row", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  const deleteButton = expectAgentDrivable(canvas, {
+    name: "Delete Water the ferns",
+    role: "button",
+  })
+
+  const hit = elementAtCentreOf(deleteButton)
+
+  await expect(
+    hit === deleteButton || deleteButton.contains(hit),
+  ).toBe(true)
+
+  // A real click at the action's centre, with real hit-testing.
+  await browserUserEvent.click(deleteButton)
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Deleted Water the ferns")
+})
+
+test("Tab reaches each row's button, then its action, in reading order, and Enter and Space open the row", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  const order = [
+    "Edit Water the ferns",
+    "Delete Water the ferns",
+    "Edit Sort the recycling",
+    "Delete Sort the recycling",
+    "Edit Feed the goldfish",
+    "Delete Feed the goldfish",
+  ]
+
+  for (const name of order) {
+    await userEvent.tab()
+
+    await expect(
+      expectAgentDrivable(canvas, { name, role: "button" }),
+    ).toHaveFocus()
+  }
+
+  const muted = canvas.getByRole("button", {
+    name: "Edit Feed the goldfish",
+  })
+
+  muted.focus()
+
+  await userEvent.keyboard("{Enter}")
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Opened Feed the goldfish")
+
+  canvas
+    .getByRole("button", {
+      name: "Edit Sort the recycling",
+    })
+    .focus()
+
+  await userEvent.keyboard(" ")
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Opened Sort the recycling")
+})
+
+test("keyboard focus draws the focus ring inside the row's edge", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  // A real Tab, because only a trusted key press makes the browser
+  // match `:focus-visible`.
+  await browserUserEvent.tab()
+
+  const rowButton = expectAgentDrivable(canvas, {
+    name: "Edit Water the ferns",
+    role: "button",
+  })
+
+  await expect(rowButton).toHaveFocus()
+
+  const style = getComputedStyle(rowButton)
+
+  await expect(style.outlineStyle).toBe("solid")
+
+  // Inside the edge: the group's list clips its corners, and an
+  // outside ring would be cut off on the first and last row. One
+  // ring-width further in again, so it never shares pixels with the
+  // highlight ring that hugs the edge.
+  const ringWidth = Number.parseFloat(style.outlineWidth)
+
+  await expect(ringWidth).toBeGreaterThan(0)
+
+  await expect(
+    Number.parseFloat(style.outlineOffset),
+  ).toBeCloseTo(-2 * ringWidth, 1)
+})
+
+test("hover tints the row and rings its edge; holding the row presses it", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  const rowButton = expectAgentDrivable(canvas, {
+    name: "Edit Water the ferns",
+    role: "button",
+  })
+
+  const resting = getComputedStyle(rowButton)
+
+  const restingBackground = resting.backgroundColor
+
+  const restingShadow = resting.boxShadow
+
+  await browserUserEvent.hover(rowButton)
+
+  await waitFor(() => {
+    expect(
+      getComputedStyle(rowButton).backgroundColor,
+    ).not.toBe(restingBackground)
+  })
+
+  await expect(
+    getComputedStyle(rowButton).boxShadow,
+  ).not.toBe(restingShadow)
+
+  await browserUserEvent.unhover(rowButton)
+
+  // Holding Space keeps a focused button `:active`, which is a press
+  // without a pointer — and it presses only the row whose button it
+  // is.
+  rowButton.focus()
+
+  await browserUserEvent.keyboard("{ >}")
+
+  const row = rowOf(rowButton)
+
+  // Tailwind's `scale-*` writes the individual `scale` property,
+  // not `transform`.
+  await waitFor(() => {
+    expect(getComputedStyle(row).scale).toBe("0.99")
+  })
+
+  await expect(
+    getComputedStyle(
+      rowOf(
+        canvas.getByRole("button", {
+          name: "Edit Sort the recycling",
+        }),
+      ),
+    ).scale,
+  ).toBe("none")
+
+  await browserUserEvent.keyboard("{/ }")
+
+  await expect(
+    canvas.getByRole("status"),
+  ).toHaveTextContent("Opened Water the ferns")
+})
+
+test("a muted row is a sunken surface with a quieter label, and still clears axe", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(SelectableRows)
+
+  const mutedRow = rowOf(
+    canvas.getByRole("button", {
+      name: "Edit Feed the goldfish",
+    }),
+  )
+
+  const activeRow = rowOf(
+    canvas.getByRole("button", {
+      name: "Edit Water the ferns",
+    }),
+  )
+
+  await expect(
+    getComputedStyle(mutedRow).backgroundColor,
+  ).not.toBe(getComputedStyle(activeRow).backgroundColor)
+
+  await expect(
+    getComputedStyle(
+      within(mutedRow).getByText("Feed the goldfish"),
+    ).color,
+  ).not.toBe(
+    getComputedStyle(
+      within(activeRow).getByText("Water the ferns"),
+    ).color,
+  )
+
+  // Muted is not disabled: the row still opens.
+  await expect(
+    canvas.getByRole("button", {
+      name: "Edit Feed the goldfish",
+    }),
+  ).toBeEnabled()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a highlighted row is ringed, and the ring lets the pointer through", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  const rowButton = canvas.getByRole("button", {
+    name: "Edit Sort the recycling",
+  })
+
+  const row = rowOf(rowButton)
+
+  const ring = row.querySelector(
+    ".charcuterie-highlight",
+  ) as HTMLElement
+
+  await expect(ring).not.toBeNull()
+
+  await expect(ring).toHaveAttribute("aria-hidden", "true")
+
+  await expect(getComputedStyle(ring).boxShadow).toContain(
+    "inset",
+  )
+
+  await expect(
+    elementAtCentreOf(within(row).getByText("2 pts")),
+  ).toBe(rowButton)
+
+  // Only the row that asked for it.
+  await expect(
+    rowOf(
+      canvas.getByRole("button", {
+        name: "Edit Water the ferns",
+      }),
+    ).querySelector(".charcuterie-highlight"),
+  ).toBeNull()
+})
+
+test("the aside sits beside the text in a wide list and never pushes the row past its list", async () => {
+  const { canvas } = await mountStory(SelectableRows)
+
+  const list = expectAgentDrivable(canvas, {
+    name: "Team Orion",
+    role: "list",
+  })
+
+  await expect(list.scrollWidth).toBeLessThanOrEqual(
+    list.clientWidth,
+  )
+
+  const row = rowOf(
+    canvas.getByRole("button", {
+      name: "Edit Water the ferns",
+    }),
+  )
+
+  const label = within(row).getByText("Water the ferns")
+
+  const capLine = within(row).getByText("Up to 5 pts a day")
+
+  const payout = within(row).getByText("Per scan")
+
+  // 12rem of text, the payout and the action fit on one line well
+  // inside 40rem; below that the content decides.
+  if (list.clientWidth >= 640) {
+    await expect(
+      payout.getBoundingClientRect().top,
+    ).toBeLessThan(capLine.getBoundingClientRect().bottom)
+
+    await expect(
+      payout.getBoundingClientRect().left,
+    ).toBeGreaterThan(label.getBoundingClientRect().right)
+  } else {
+    await expect(
+      payout.getBoundingClientRect().top,
+    ).toBeGreaterThanOrEqual(
+      capLine.getBoundingClientRect().bottom,
+    )
+  }
+})
+
+test("every row state passes axe in both schemes", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(RowStates)
+
+  expectAgentDrivable(canvas, {
+    name: "Highlight intents",
+    role: "list",
+  })
+
+  // The canvas paints the scheme's own page surface, so the headings
+  // are measured against the background they would really sit on.
+  canvasElement.classList.add("bg-surface-base")
+
+  for (const scheme of ["light", "dark"]) {
+    canvasElement.setAttribute("data-scheme", scheme)
+
+    await expectNoAxeViolations(canvasElement)
+  }
+})