@charcuterie/ui 4.22.1 → 4.24.0

package/src/GroupedList/GroupedList.test.tsx

@@ -0,0 +1,390 @@
+import {
+  composeStories,
+  composeStory,
+} from "@storybook/react"
+import {
+  expect,
+  userEvent,
+  waitFor,
+  within,
+} from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import meta, * as stories from "./GroupedList.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  ColorSchemes,
+  Empty,
+  Interactive,
+  LongText,
+  NarrowView,
+  Playground,
+  Responsive,
+  StickyHeadings,
+} = composeStories(stories)
+
+test("a group's heading names its list", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+
+  // The heading labels the `<ul>` rather than a `<section>`: a named
+  // section is a landmark, and one per group is the landmark
+  // proliferation the APG warns about.
+  const screens = expectAgentDrivable(canvas, {
+    name: "Screens",
+    role: "list",
+  })
+
+  await expect(
+    within(screens).getAllByRole("listitem"),
+  ).toHaveLength(2)
+
+  await expect(
+    canvasElement.querySelector("section"),
+  ).toBeNull()
+
+  await expect(
+    canvas.getByRole("heading", {
+      level: 3,
+      name: "Screens",
+    }),
+  ).toBeVisible()
+
+  expectAgentDrivable(canvas, {
+    name: "Open Lobby",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the heading level is the caller's", async () => {
+  const { canvas } = await mountStory(
+    composeStory({ args: { headingLevel: 2 } }, meta),
+  )
+
+  const heading = expectAgentDrivable(canvas, {
+    name: "Not on a screen",
+    role: "heading",
+  })
+
+  await expect(heading.tagName).toBe("H2")
+})
+
+test("an empty group is not drawn", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  await expect(
+    canvas.queryByRole("heading", { name: "Never drawn" }),
+  ).toBeNull()
+
+  expectAgentDrivable(canvas, {
+    name: "Drawn",
+    role: "list",
+  })
+
+  // The last cell has no group with an item, so it draws its
+  // `emptyState` and no list at all.
+  expectAgentDrivable(canvas, {
+    name: "No page matches",
+    role: "heading",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a list with nothing in it draws the caller's empty state", async () => {
+  const { canvas, canvasElement } = await mountStory(Empty)
+
+  expectAgentDrivable(canvas, {
+    name: "This server has no pages",
+    role: "heading",
+  })
+
+  await expect(canvas.queryByRole("list")).toBeNull()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a clipped label carries its full text as a tooltip, and a short one has none", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(LongText)
+
+  const label = canvas.getByText(
+    "Quarterly All-Hands Countdown and Seating Chart",
+  )
+
+  await waitFor(() => {
+    expect(label).toHaveAttribute(
+      "title",
+      "Quarterly All-Hands Countdown and Seating Chart",
+    )
+  })
+
+  await expect(label.scrollWidth).toBeGreaterThan(
+    label.clientWidth,
+  )
+
+  const path = canvas.getByText(
+    "/views/quarterly-all-hands-countdown-and-seating-chart-for-the-north-atrium",
+  )
+
+  await waitFor(() => {
+    expect(path).toHaveAttribute("title")
+  })
+
+  await expect(canvas.getByText("Map")).not.toHaveAttribute(
+    "title",
+  )
+
+  expectAgentDrivable(canvas, {
+    name: "Open Map",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("isTextTruncated={false} wraps the whole label instead", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  // The third cell truncates, the fourth wraps; same fixture.
+  const [truncated, wrapped] = canvas.getAllByText(
+    "Quarterly All-Hands Countdown and Seating Chart",
+  ) as [HTMLElement, HTMLElement]
+
+  await waitFor(() => {
+    expect(truncated).toHaveAttribute("title")
+  })
+
+  await expect(wrapped.scrollWidth).toBeLessThanOrEqual(
+    wrapped.clientWidth,
+  )
+
+  await expect(wrapped).not.toHaveAttribute("title")
+
+  await expect(
+    canvas.getAllByRole("list", {
+      name: "On the Conference Center North Atrium Wayfinding screen",
+    }),
+  ).toHaveLength(2)
+})
+
+test("Tab walks the actions in reading order", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const order = [
+    "Open Lobby",
+    "Open Break Room",
+    "Open Welcome",
+    "Open Weather",
+    "Open Schedule",
+    "Open Test Pattern",
+  ]
+
+  for (const name of order) {
+    await userEvent.tab()
+
+    await expect(
+      expectAgentDrivable(canvas, { name, role: "button" }),
+    ).toHaveFocus()
+  }
+})
+
+/**
+ * The text column asks for 12rem and grows. In the 15rem panel the
+ * actions cannot fit beside it, so they drop under the text; in the
+ * 34rem panel they sit on the same line.
+ */
+test("the actions wrap under the text when the list is narrow", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const labels = canvas.getAllByText("Water the ferns")
+
+  const buttons = canvas.getAllByRole("button", {
+    name: "Edit Water the ferns",
+  })
+
+  const [narrowLabel, , wideLabel] = labels as [
+    HTMLElement,
+    HTMLElement,
+    HTMLElement,
+  ]
+
+  const [narrowButton, , wideButton] = buttons as [
+    HTMLElement,
+    HTMLElement,
+    HTMLElement,
+  ]
+
+  await expect(
+    narrowButton.getBoundingClientRect().top,
+  ).toBeGreaterThanOrEqual(
+    narrowLabel.getBoundingClientRect().bottom,
+  )
+
+  await expect(
+    wideButton.getBoundingClientRect().top,
+  ).toBeLessThan(wideLabel.getBoundingClientRect().bottom)
+
+  // Nothing pushes past its panel: no row is wider than its list.
+  for (const list of canvas.getAllByRole("list", {
+    name: "Team Orion",
+  })) {
+    await expect(list.scrollWidth).toBeLessThanOrEqual(
+      list.clientWidth,
+    )
+  }
+})
+
+test("the Narrow View keeps every row inside the window", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(NarrowView)
+
+  const list = expectAgentDrivable(canvas, {
+    name: "Team Orion",
+    role: "list",
+  })
+
+  await expect(list.scrollWidth).toBeLessThanOrEqual(
+    list.clientWidth,
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("both schemes pass axe, contrast included", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(ColorSchemes)
+
+  expectAgentDrivable(canvas, {
+    name: "Open dark Lobby",
+    role: "button",
+  })
+
+  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,
+  )
+})

package/src/GroupedList/GroupedList.tsx

@@ -0,0 +1,235 @@
+import { useUniqueId } from "@charcuterie/logic"
+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
+
+export type GroupedListSize = "md" | "sm"
+
+export type GroupedListItem = {
+  /**
+   * Trailing controls — usually one `Button size="sm"`. They sit at
+   * the row's inline end and wrap under the text when the list is
+   * too narrow to hold both.
+   *
+   * **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.
+   */
+  actions?: 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.
+   */
+  content?: ReactNode
+  /** One muted line under the label: a path, a key, a count. Truncated like the label. */
+  description?: string
+  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
+}
+
+export type GroupedListGroup = {
+  /** Plain text. It is the accessible name of the group's list, so `getByRole("list", { name })` finds it. */
+  heading: string
+  items: readonly GroupedListItem[]
+  key: string
+  /**
+   * A muted note beside the heading — a count, a total. Kept out of
+   * the heading element so the list's name stays "Screens" rather
+   * than "Screens 3 pages".
+   */
+  summary?: ReactNode
+}
+
+export type GroupedListProps = {
+  className?: string
+  /**
+   * Rendered in place of the groups when **no group has an item** —
+   * usually an `EmptyState` whose wording says why (nothing yet, or
+   * nothing matches the search). Nothing renders without one.
+   */
+  emptyState?: ReactNode
+  groups: readonly GroupedListGroup[]
+  /**
+   * The level every group heading sits at. A list under a page's
+   * `<h2>` needs `3`, which is the default, and getting it wrong is
+   * 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.
+   * `false` wraps it anywhere instead — for a list whose rows are
+   * read rather than scanned.
+   */
+  isTextTruncated?: boolean
+  /** `sm` for a settings pane or a sidebar; `md` for a page. */
+  size?: GroupedListSize
+}
+
+/**
+ * Written out rather than interpolated into a tag name, matching
+ * `Accordion`: "which heading levels does this component emit"
+ * should be answerable by looking.
+ */
+const HEADING_TAG: Record<
+  GroupedListHeadingLevel,
+  "h2" | "h3" | "h4" | "h5" | "h6"
+> = {
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+}
+
+/**
+ * An always-open list whose rows sit under group headings.
+ *
+ * Three apps had built this by hand — castkit's page picker (pages
+ * under the screen that shows them), tally-marks' cards (cards under
+ * the child who earns them) and whereabouts' nested holdings (things
+ * under the place that holds them). Same shape each time: a heading,
+ * then rows of a name, a muted line, some badges and a button. The
+ * library owns that shape; the app still owns the grouping, the
+ * search and the filters, because those are questions about its
+ * data.
+ *
+ * ### A group is a named list, not a landmark
+ *
+ * castkit's copy wrapped each group in `<section aria-labelledby>`,
+ * and a named `<section>` is a `region` landmark. One screen of
+ * pages is a dozen groups, so that is a dozen landmarks — the
+ * "landmark region proliferation" the APG warns about, which is why
+ * `Accordion`'s panels are a `group` too. Here the heading labels
+ * the `<ul>` itself: a screen reader announces "Screens, list, 3
+ * items", which is the same fact, and the landmark list keeps
+ * meaning "the parts of the page".
+ *
+ * ### An empty group is not drawn
+ *
+ * Every copy filtered them out before rendering, because a heading
+ * over nothing reads as a bug once a search narrows the list. So the
+ * 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`.
+ *
+ * ### Not collapsible
+ *
+ * A group you can close is `Accordion`. This is for a list that is
+ * short enough to read whole and long enough to want headings.
+ */
+export const GroupedList = ({
+  className,
+  emptyState,
+  groups,
+  headingLevel = 3,
+  isHeadingSticky = false,
+  isTextTruncated = true,
+  size = "md",
+}: GroupedListProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const shownGroups = groups.filter(
+    (group) => group.items.length > 0,
+  )
+
+  const Heading = HEADING_TAG[headingLevel]
+
+  return (
+    <div
+      className={toClassName(
+        "flex flex-col",
+        size === "sm" ? "gap-4" : "gap-6",
+        className,
+      )}
+    >
+      {shownGroups.length === 0
+        ? (emptyState ?? null)
+        : shownGroups.map((group, index) => {
+            const headingId = `${baseId}-heading-${index}`
+
+            return (
+              <div
+                className={toClassName(
+                  "flex flex-col",
+                  isHeadingSticky ? "gap-0" : "gap-2",
+                )}
+                key={group.key}
+              >
+                <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",
+                      size === "sm" ? "text-sm" : "text-md",
+                    )}
+                    id={headingId}
+                  >
+                    {group.heading}
+                  </Heading>
+
+                  {group.summary ? (
+                    <span className="min-w-0 wrap-anywhere text-content-secondary text-sm">
+                      {group.summary}
+                    </span>
+                  ) : null}
+                </div>
+
+                <ul
+                  aria-labelledby={headingId}
+                  className="m-0 flex list-none flex-col divide-y divide-border-subtle overflow-hidden rounded-md border border-border-subtle bg-surface-raised p-0"
+                >
+                  {group.items.map((item) => (
+                    <GroupedListRow
+                      isTextTruncated={isTextTruncated}
+                      item={item}
+                      key={item.key}
+                      size={size}
+                    />
+                  ))}
+                </ul>
+              </div>
+            )
+          })}
+    </div>
+  )
+}