@charcuterie/ui 4.23.0 → 4.25.0

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,9 @@ const {
   NarrowView,
   Playground,
   Responsive,
+  RowStates,
+  SelectableRows,
+  StickyHeadings,
 } = composeStories(stories)
 
 test("a group's heading names its list", async () => {
@@ -269,3 +273,509 @@ test("both schemes pass axe, contrast included", async () => {
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * The element `isHeadingSticky` pins: the heading's row, which also
+ * holds the summary.
+ */
+const headingRowOf = (heading: HTMLElement) =>
+  heading.parentElement as HTMLElement
+
+test("a heading scrolls with its rows unless isHeadingSticky is set", async () => {
+  const { canvas } = await mountStory(Playground)
+
+  const heading = expectAgentDrivable(canvas, {
+    name: "Screens",
+    role: "heading",
+  })
+
+  await expect(
+    getComputedStyle(headingRowOf(heading)).position,
+  ).toBe("static")
+})
+
+test("a sticky heading stays at the top of its pane while its rows scroll under it", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(StickyHeadings)
+
+  const pane = expectAgentDrivable(canvas, {
+    name: "Pages on a raised surface",
+    role: "region",
+  })
+
+  const paneCanvas = within(pane)
+
+  const heading = paneCanvas.getByRole("heading", {
+    name: "On the Lobby screen",
+  })
+
+  const list = paneCanvas.getByRole("list", {
+    name: "On the Lobby screen",
+  })
+
+  // The space under a stuck heading is its own padding, not a
+  // transparent gap the rows would show through.
+  await expect(
+    headingRowOf(heading).getBoundingClientRect().bottom,
+  ).toBeCloseTo(list.getBoundingClientRect().top, 0)
+
+  pane.scrollTop = 96
+
+  await waitFor(() => {
+    expect(pane.scrollTop).toBe(96)
+  })
+
+  const paneTop =
+    pane.getBoundingClientRect().top + pane.clientTop
+
+  await expect(
+    headingRowOf(heading).getBoundingClientRect().top,
+  ).toBeCloseTo(paneTop, 0)
+
+  // The first row has scrolled up past the heading, under it.
+  const firstRow = within(list).getAllByRole(
+    "listitem",
+  )[0] as HTMLElement
+
+  await expect(
+    firstRow.getBoundingClientRect().top,
+  ).toBeLessThan(paneTop)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a stuck heading's background is the surface its host names, and surface-base by default", async () => {
+  const { canvas } = await mountStory(StickyHeadings)
+
+  for (const name of [
+    "Pages on a base surface",
+    "Pages on a raised surface",
+  ]) {
+    const pane = expectAgentDrivable(canvas, {
+      name,
+      role: "region",
+    })
+
+    const heading = within(pane).getByRole("heading", {
+      name: "On the Break Room screen",
+    })
+
+    const headingBackground = getComputedStyle(
+      headingRowOf(heading),
+    ).backgroundColor
+
+    await expect(headingBackground).toBe(
+      getComputedStyle(pane).backgroundColor,
+    )
+
+    await expect(headingBackground).not.toBe(
+      "rgba(0, 0, 0, 0)",
+    )
+  }
+
+  // And the two surfaces are different, or the assertion above
+  // could pass with the property ignored.
+  await expect(
+    getComputedStyle(
+      expectAgentDrivable(canvas, {
+        name: "Pages on a base surface",
+        role: "region",
+      }),
+    ).backgroundColor,
+  ).not.toBe(
+    getComputedStyle(
+      expectAgentDrivable(canvas, {
+        name: "Pages on a raised surface",
+        role: "region",
+      }),
+    ).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)
+  }
+})

package/src/GroupedList/GroupedList.tsx

@@ -1,8 +1,10 @@
 import { useUniqueId } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
 import type { ReactNode } from "react"
 
 import { toClassName } from "../toClassName.ts"
 import { GroupedListRow } from "./GroupedListRow.tsx"
+import { STICKY_HEADING_CLASS } from "./groupedListStickyHeading.ts"
 
 export type GroupedListHeadingLevel = 2 | 3 | 4 | 5 | 6
 
@@ -17,24 +19,86 @@ export type GroupedListItem = {
    * **Name a repeated action after its row.** Ten rows of "Open" are
    * ten buttons an agent cannot tell apart; `aria-label="Open Lobby"`
    * on each is one `getByRole` away.
+   *
+   * In a row with `onSelect` these stay their own targets: they sit
+   * above the whole-row button, so pressing one never selects the
+   * row.
    */
   actions?: ReactNode
+  /**
+   * A figure that belongs beside the text rather than under it — a
+   * payout, a total, a schedule. It sits between the text and the
+   * actions in a wide list and drops under the text in a narrow one,
+   * the same content-decided wrap the actions use: it asks for at
+   * least 11rem beside the text column's 12rem. Never interactive:
+   * in a row with `onSelect` the whole-row button sits over it.
+   */
+  aside?: ReactNode
   /** `Badge`s, drawn after the label and wrapping onto their own line when they run out of room. */
   badges?: ReactNode
   /**
    * Anything richer than one line of help — a payout, a rule list.
    * Drawn under the description, inside the text column, and never
-   * truncated.
+   * truncated. Never interactive in a row with `onSelect`; a control
+   * belongs in `actions`.
    */
   content?: ReactNode
   /** One muted line under the label: a path, a key, a count. Truncated like the label. */
   description?: string
+  /**
+   * The intent `isHighlighted` rings the row in. `accent` by default;
+   * an app whose highlight means "this just paid out" passes
+   * `success`.
+   */
+  highlightIntent?: IntentName
+  /**
+   * `true` rings the row and pulses the ring twice — "this one just
+   * changed", for a row a scan, a save or an arrival has touched.
+   * The ring stays while the flag does, so the app decides how long
+   * it lasts, usually by clearing it on a timer.
+   *
+   * **To pulse a row that is already highlighted again, change its
+   * `key`.** A new key is a new row, and a new row starts the pulse
+   * from the beginning; `` `${id}-${sequence}` `` is the usual shape.
+   *
+   * Under `prefers-reduced-motion` and on ePaper the ring does not
+   * pulse; it is simply there.
+   */
+  isHighlighted?: boolean
+  /**
+   * `true` draws the row receded — a sunken surface and a quieter
+   * label — for an entry that exists but is switched off. It stays
+   * fully operable and every colour on it still clears AA, which is
+   * why it is a surface and a text role rather than an opacity: a
+   * faded row is not a disabled one, and only a disabled control may
+   * drop below the contrast floor. Say WHY in a badge too ("off").
+   */
+  isMuted?: boolean
   key: string
   /**
    * Plain text, because it is what the row is called — the thing a
    * search matched and the text a clipped row's tooltip repeats.
    */
   label: string
+  /**
+   * Makes the whole row one native `<button>` — "open this one" for a
+   * row whose primary action is the row itself. Hover tints the row
+   * and rings its edge, a press sinks it (with motion only when the
+   * user has not asked for less), and keyboard focus draws the focus
+   * ring inside the row's edge. `actions` stay separate targets
+   * above it.
+   *
+   * The button is drawn UNDER the row's text and the text lets the
+   * pointer through, so nothing interactive is ever nested inside a
+   * button: keep `badges`, `content` and `aside` free of controls.
+   */
+  onSelect?: () => void
+  /**
+   * The whole-row button's accessible name. Defaults to `label`.
+   * Name the verb when there is one — `"Edit Water the ferns"` —
+   * the same rule as a repeated action.
+   */
+  selectLabel?: string
 }
 
 export type GroupedListGroup = {
@@ -65,6 +129,24 @@ export type GroupedListProps = {
    * a document-outline break no gate here can see.
    */
   headingLevel?: GroupedListHeadingLevel
+  /**
+   * `true` pins each group's heading to the top of the nearest
+   * scrolling ancestor while that group's rows scroll under it, and
+   * the next group's heading pushes it away. For a list inside a
+   * scrolling pane, where the heading is the only thing that says
+   * which screen or team a row belongs to once it scrolls out of
+   * sight. `false` (the default) scrolls the heading with its rows.
+   *
+   * A stuck heading needs an opaque background or the rows show
+   * through it, and no one surface fits every host — a page is
+   * `surface-base`, a settings pane is `surface-raised`. So the
+   * background is read from `--charcuterie-grouped-list-heading-surface`,
+   * which falls back to `--color-surface-base`. Set it on any
+   * ancestor to match the surface the list sits on. Under a sticky
+   * page `Header`, set `--charcuterie-grouped-list-heading-offset`
+   * to the header's height so the headings stop below it.
+   */
+  isHeadingSticky?: boolean
   /**
    * `true` (the default) clips a long label or description to one
    * line, with the full text as a tooltip while it is clipped.
@@ -122,6 +204,27 @@ const HEADING_TAG: Record<
  * component does it, and when every group is empty it draws
  * `emptyState` instead.
  *
+ * ### A sticky heading is opt-in
+ *
+ * castkit's copy pinned its headings, and a pinned heading needs a
+ * background that matches whatever it sits on. The component cannot
+ * know that surface, so `isHeadingSticky` reads it from a custom
+ * property the host can set, falling back to `surface-base`.
+ *
+ * ### A row can be the target
+ *
+ * tally-marks' card list opens a card's editor from anywhere on the
+ * card, and the owner asked for that to feel like an app: hover,
+ * press, focus, touch. `onSelect` is that, as one real `<button>`
+ * stretched under the row's text — not a click handler on an
+ * `<li>`, which no keyboard reaches and no screen reader announces.
+ * The text lets the pointer through to it; the actions sit above it
+ * and keep their own targets, so "Delete" never opens the editor.
+ *
+ * A row can also be muted (switched off but still there) and
+ * highlighted (just touched by a scan or a save) — the two other
+ * per-row states the same list drew by hand.
+ *
  * ### Not collapsible
  *
  * A group you can close is `Accordion`. This is for a list that is
@@ -132,6 +235,7 @@ export const GroupedList = ({
   emptyState,
   groups,
   headingLevel = 3,
+  isHeadingSticky = false,
   isTextTruncated = true,
   size = "md",
 }: GroupedListProps): ReactNode => {
@@ -158,10 +262,18 @@ export const GroupedList = ({
 
             return (
               <div
-                className="flex flex-col gap-2"
+                className={toClassName(
+                  "flex flex-col",
+                  isHeadingSticky ? "gap-0" : "gap-2",
+                )}
                 key={group.key}
               >
-                <div className="flex flex-wrap items-baseline gap-x-3 gap-y-0.5">
+                <div
+                  className={toClassName(
+                    "flex flex-wrap items-baseline gap-x-3 gap-y-0.5",
+                    isHeadingSticky && STICKY_HEADING_CLASS,
+                  )}
+                >
                   <Heading
                     className={toClassName(
                       "m-0 min-w-0 wrap-anywhere font-semibold text-content-primary",