@charcuterie/ui 4.22.1 → 4.23.0

package/src/GroupedList/GroupedList.test.tsx

@@ -0,0 +1,271 @@
+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,
+} = 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)
+})

package/src/GroupedList/GroupedList.tsx

@@ -0,0 +1,200 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { GroupedListRow } from "./GroupedListRow.tsx"
+
+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` (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.
+ *
+ * ### 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,
+  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="flex flex-col gap-2"
+                key={group.key}
+              >
+                <div className="flex flex-wrap items-baseline gap-x-3 gap-y-0.5">
+                  <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>
+  )
+}

package/src/GroupedList/GroupedListRow.tsx

@@ -0,0 +1,117 @@
+import type { ReactNode } from "react"
+
+import { useIsTextClipped } from "../Badge/useIsTextClipped.ts"
+import { toClassName } from "../toClassName.ts"
+import type {
+  GroupedListItem,
+  GroupedListSize,
+} from "./GroupedList.tsx"
+
+export type GroupedListRowProps = {
+  isTextTruncated: boolean
+  item: GroupedListItem
+  size: GroupedListSize
+}
+
+const ROW_SIZE_CLASS: Record<GroupedListSize, string> = {
+  md: "px-4 py-3",
+  sm: "px-3 py-2",
+}
+
+/**
+ * Its own file because each row measures its own text, and a hook
+ * cannot run in a loop.
+ *
+ * ### The tooltip appears only while the text is clipped
+ *
+ * `useIsTextClipped` is `Badge`'s: an ellipsis leaves no trace in the
+ * DOM, so the only way to know a label is cut off is to measure it.
+ * A `title` on every row would put a tooltip on forty short names to
+ * help the one long one.
+ *
+ * ### The actions wrap; they never squeeze the text
+ *
+ * The row is a wrapping flex line. The text column asks for 12rem
+ * and grows into the rest, so in a wide list the actions sit at the
+ * inline end of the same line, and in a list narrower than the text
+ * plus the actions they drop under the text instead of crushing the
+ * label to an ellipsis and nothing. No container query: the wrap is
+ * decided by the content itself.
+ */
+export const GroupedListRow = ({
+  isTextTruncated,
+  item,
+  size,
+}: GroupedListRowProps): ReactNode => {
+  const [labelRef, clippedLabel] = useIsTextClipped()
+
+  const [descriptionRef, clippedDescription] =
+    useIsTextClipped()
+
+  const overflowClass = isTextTruncated
+    ? "truncate"
+    : "wrap-anywhere"
+
+  return (
+    <li
+      className={toClassName(
+        "flex flex-wrap items-center gap-x-3 gap-y-2",
+        ROW_SIZE_CLASS[size],
+      )}
+    >
+      <div className="flex min-w-0 flex-[1_1_12rem] flex-col gap-0.5">
+        <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+          <span
+            className={toClassName(
+              "min-w-0 max-w-full font-medium text-content-primary",
+              size === "sm" ? "text-sm" : "text-md",
+              overflowClass,
+            )}
+            ref={labelRef}
+            title={
+              isTextTruncated ? clippedLabel : undefined
+            }
+          >
+            {item.label}
+          </span>
+
+          {item.badges ? (
+            <span className="flex min-w-0 flex-wrap items-center gap-1">
+              {item.badges}
+            </span>
+          ) : null}
+        </div>
+
+        {item.description ? (
+          <span
+            className={toClassName(
+              "block min-w-0 text-content-secondary",
+              size === "sm" ? "text-xs" : "text-sm",
+              overflowClass,
+            )}
+            ref={descriptionRef}
+            title={
+              isTextTruncated
+                ? clippedDescription
+                : undefined
+            }
+          >
+            {item.description}
+          </span>
+        ) : null}
+
+        {item.content ? (
+          <div className="mt-1 min-w-0 wrap-anywhere text-content-secondary text-sm">
+            {item.content}
+          </div>
+        ) : null}
+      </div>
+
+      {item.actions ? (
+        <div className="flex shrink-0 items-center gap-2">
+          {item.actions}
+        </div>
+      ) : null}
+    </li>
+  )
+}

package/src/index.ts

@@ -235,6 +235,14 @@ export type { FieldGroupProps } from "./Field/FieldGroup.tsx"
 export { FieldGroup } from "./Field/FieldGroup.tsx"
 export type { FileDropZoneProps } from "./FileDropZone/FileDropZone.tsx"
 export { FileDropZone } from "./FileDropZone/FileDropZone.tsx"
+export type {
+  GroupedListGroup,
+  GroupedListHeadingLevel,
+  GroupedListItem,
+  GroupedListProps,
+  GroupedListSize,
+} from "./GroupedList/GroupedList.tsx"
+export { GroupedList } from "./GroupedList/GroupedList.tsx"
 export type { HeaderProps } from "./Header/Header.tsx"
 export { Header } from "./Header/Header.tsx"
 export type { IconButtonProps } from "./IconButton/IconButton.tsx"

package/src/sourceRules.test.ts

@@ -623,7 +623,10 @@ test("the barrel is the only place components are re-exported", async () => {
   // TableViewport owns readable comparisons and full-window expansion.
   // MetricCard shares prominent values and category-coloured icons through Card.
   // ComparisonChart and TableColumns share compact comparisons and column controls.
-  expect(componentNames.length).toBe(77)
+  // GroupedList owns rows under group headings; castkit, tally-marks
+  // and whereabouts each drew it by hand. `GroupedListRow.tsx` is its
+  // member and stays out of this count by the `<Name>/<Name>.tsx` rule.
+  expect(componentNames.length).toBe(78)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)