@charcuterie/ui 4.18.2 → 4.19.0

package/src/DataTable/DataTable.test.tsx

@@ -11,8 +11,15 @@ import {
 } from "../viewport.testHelpers.ts"
 import * as stories from "./DataTable.stories.tsx"
 
-const { AllVariants, Playground, Interactive, Responsive } =
-  composeStories(stories)
+const {
+  AllVariants,
+  Playground,
+  Interactive,
+  Responsive,
+  LongColumnLabels,
+  DenseComparison,
+  StackedList,
+} = composeStories(stories)
 
 /**
  * The `<caption>` is the table's accessible name. Without one a
@@ -384,3 +391,119 @@ test("an empty table keeps its headers", async () => {
       ?.querySelectorAll("thead th"),
   ).toHaveLength(5)
 })
+
+test("stacked cells show complete long column names within a narrow container", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    LongColumnLabels,
+  )
+  expectAgentDrivable(canvas, {
+    role: "table",
+    name: "Tasks with complete column labels",
+  })
+  const labels = Array.from(
+    canvasElement.querySelectorAll<HTMLElement>(
+      'tbody td > span[aria-hidden="true"]',
+    ),
+  )
+  await expect(labels).toHaveLength(6)
+  for (const label of labels) {
+    await expect(label).toBeVisible()
+    await expect(label.scrollWidth).toBeLessThanOrEqual(
+      label.clientWidth + 1,
+    )
+    await expect(label.scrollHeight).toBeLessThanOrEqual(
+      label.clientHeight + 1,
+    )
+    await expect(
+      getComputedStyle(label).textOverflow,
+    ).not.toBe("ellipsis")
+  }
+  await expect(
+    labels[0].getBoundingClientRect().height,
+  ).toBeGreaterThan(
+    Number.parseFloat(
+      getComputedStyle(labels[0]).lineHeight,
+    ),
+  )
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("dense comparisons reflow by container width while retaining every column", async () => {
+  await setViewport(DESKTOP)
+  const { canvas, canvasElement } =
+    await mountStory(DenseComparison)
+  const narrow = expectAgentDrivable(canvas, {
+    role: "table",
+    name: "Dense comparison at 60rem",
+  })
+  const wide = expectAgentDrivable(canvas, {
+    role: "table",
+    name: "Dense comparison at 75rem",
+  })
+  await expect(
+    getComputedStyle(
+      narrow.querySelector("tbody td") as HTMLElement,
+    ).display,
+  ).toBe("flex")
+  await expect(
+    getComputedStyle(
+      wide.querySelector("tbody td") as HTMLElement,
+    ).display,
+  ).toBe("table-cell")
+  for (const header of wide.querySelectorAll<HTMLElement>(
+    "thead th button",
+  )) {
+    await expect(
+      getComputedStyle(header).overflowWrap,
+    ).toBe("normal")
+  }
+  for (const cell of narrow.querySelectorAll<HTMLElement>(
+    "tbody td",
+  )) {
+    await expect(
+      cell.getBoundingClientRect().width,
+    ).toBeGreaterThan(800)
+  }
+  const priority = narrow.querySelector(
+    "tbody tr td:nth-child(3) > span:last-child",
+  ) as HTMLElement
+  await expect(
+    priority.getBoundingClientRect().height,
+  ).toBeLessThan(
+    Number.parseFloat(
+      getComputedStyle(priority).lineHeight,
+    ) * 1.1,
+  )
+  for (const table of [narrow, wide]) {
+    await expect(
+      table.querySelectorAll("tbody tr:first-child td"),
+    ).toHaveLength(8)
+    await expect(table.scrollWidth).toBeLessThanOrEqual(
+      (table.parentElement as HTMLElement).clientWidth + 1,
+    )
+  }
+  await expectNoAxeViolations(canvasElement)
+})
+test("the explicit list layout stays stacked in a wide container", async () => {
+  await setViewport(DESKTOP)
+  const { canvas } = await mountStory(StackedList)
+  const table = expectAgentDrivable(canvas, {
+    role: "table",
+    name: "Tasks as a list",
+  })
+  await expect(
+    getComputedStyle(
+      table.querySelector("tbody td") as HTMLElement,
+    ).display,
+  ).toBe("flex")
+  await expect(
+    table.querySelector("tbody td > span[aria-hidden]"),
+  ).toBeVisible()
+  for (const cell of table.querySelectorAll<HTMLElement>(
+    "tbody td",
+  )) {
+    await expect(
+      cell.getBoundingClientRect().width,
+    ).toBeGreaterThan(900)
+  }
+})

package/src/DataTable/DataTable.tsx

@@ -58,7 +58,13 @@ export type DataTableSelection<Row> = {
   selectedRowKeys: readonly string[]
 }
 
+export type DataTableReflowAt = "md" | "lg" | "xl"
+
 export type DataTableProps<Row> = {
+  /** Auto uses the container width; stacked keeps the labelled list at every width. */
+  layout?: "auto" | "stacked"
+  /** Dense tables can reflow earlier: md=32rem, lg=48rem, xl=64rem. */
+  reflowAt?: DataTableReflowAt
   className?: string
   columns: readonly DataTableColumn<Row>[]
   /**
@@ -100,6 +106,99 @@ export type DataTableProps<Row> = {
  * empty-state cell.
  */
 const CELL_PADDING_CLASS = "px-3 py-2"
+/** Complete literals keep Tailwind generation and consumer builds identical. */
+const WIDE_LAYOUT_CLASS = {
+  "cq-md:align-middle": {
+    md: "cq-md:align-middle",
+    lg: "cq-lg:align-middle",
+    xl: "cq-xl:align-middle",
+  },
+  "cq-md:bg-transparent": {
+    md: "cq-md:bg-transparent",
+    lg: "cq-lg:bg-transparent",
+    xl: "cq-xl:bg-transparent",
+  },
+  "cq-md:border-0": {
+    md: "cq-md:border-0",
+    lg: "cq-lg:border-0",
+    xl: "cq-xl:border-0",
+  },
+  "cq-md:border-b": {
+    md: "cq-md:border-b",
+    lg: "cq-lg:border-b",
+    xl: "cq-xl:border-b",
+  },
+  "cq-md:border-b-0": {
+    md: "cq-md:border-b-0",
+    lg: "cq-lg:border-b-0",
+    xl: "cq-xl:border-b-0",
+  },
+  "cq-md:border-border-subtle": {
+    md: "cq-md:border-border-subtle",
+    lg: "cq-lg:border-border-subtle",
+    xl: "cq-xl:border-border-subtle",
+  },
+  "cq-md:gap-0": {
+    md: "cq-md:gap-0",
+    lg: "cq-lg:gap-0",
+    xl: "cq-xl:gap-0",
+  },
+  "cq-md:hidden": {
+    md: "cq-md:hidden",
+    lg: "cq-lg:hidden",
+    xl: "cq-xl:hidden",
+  },
+  "cq-md:p-0": {
+    md: "cq-md:p-0",
+    lg: "cq-lg:p-0",
+    xl: "cq-xl:p-0",
+  },
+  "cq-md:pt-0": {
+    md: "cq-md:pt-0",
+    lg: "cq-lg:pt-0",
+    xl: "cq-xl:pt-0",
+  },
+  "cq-md:py-2": {
+    md: "cq-md:py-2",
+    lg: "cq-lg:py-2",
+    xl: "cq-xl:py-2",
+  },
+  "cq-md:rounded-none": {
+    md: "cq-md:rounded-none",
+    lg: "cq-lg:rounded-none",
+    xl: "cq-xl:rounded-none",
+  },
+  "cq-md:table": {
+    md: "cq-md:table",
+    lg: "cq-lg:table",
+    xl: "cq-xl:table",
+  },
+  "cq-md:table-cell": {
+    md: "cq-md:table-cell",
+    lg: "cq-lg:table-cell",
+    xl: "cq-xl:table-cell",
+  },
+  "cq-md:table-header-group": {
+    md: "cq-md:table-header-group",
+    lg: "cq-lg:table-header-group",
+    xl: "cq-xl:table-header-group",
+  },
+  "cq-md:table-row": {
+    md: "cq-md:table-row",
+    lg: "cq-lg:table-row",
+    xl: "cq-xl:table-row",
+  },
+  "cq-md:table-row-group": {
+    md: "cq-md:table-row-group",
+    lg: "cq-lg:table-row-group",
+    xl: "cq-xl:table-row-group",
+  },
+  "cq-md:wrap-normal": {
+    md: "cq-md:wrap-normal",
+    lg: "cq-lg:wrap-normal",
+    xl: "cq-xl:wrap-normal",
+  },
+} as const
 
 /**
  * `role` on every part, and it is not belt-and-braces.
@@ -206,11 +305,19 @@ export const DataTable = <Row,>({
   getRowKey,
   isLabelVisible = false,
   label,
+  layout = "auto",
+  reflowAt = "md",
   onSortChange,
   rows,
   selection,
   sort,
 }: DataTableProps<Row>): ReactNode => {
+  const wideClass = (
+    key: keyof typeof WIDE_LAYOUT_CLASS,
+  ) =>
+    layout === "stacked"
+      ? undefined
+      : WIDE_LAYOUT_CLASS[key][reflowAt]
   const tableRef = useRef<HTMLTableElement>(null)
 
   const selectedRowKeys = selection?.selectedRowKeys
@@ -278,9 +385,19 @@ export const DataTable = <Row,>({
     // below it. `className` stays on this element — the outermost
     // box the component renders — which is what lets a caller give
     // the table a width, a margin, or a grid placement.
-    <div className={toClassName("@container", className)}>
+    <div
+      className={toClassName(
+        "@container charcuterie-data-table",
+        className,
+      )}
+      data-layout={layout}
+      data-reflow-at={reflowAt}
+    >
       <table
-        className="block w-full border-collapse text-start text-content-primary text-md cq-md:table"
+        className={toClassName(
+          "block w-full border-collapse text-start text-content-primary text-md",
+          wideClass("cq-md:table"),
+        )}
         ref={tableRef}
         role="table"
       >
@@ -296,20 +413,31 @@ export const DataTable = <Row,>({
         </caption>
 
         <thead
-          className="block cq-md:table-header-group"
+          className={toClassName(
+            "block",
+            wideClass("cq-md:table-header-group"),
+          )}
           role={ROW_GROUP_ROLE}
         >
           {/* Narrow: a wrapping strip of sort controls, so sorting
               survives the layout that has no header row. Wide: the
               header row. */}
           <tr
-            className="flex flex-wrap items-center gap-x-1 border-border-subtle border-b cq-md:table-row cq-md:border-b-0"
+            className={toClassName(
+              "flex flex-wrap items-center gap-x-1 border-border-subtle border-b",
+              wideClass("cq-md:table-row"),
+              wideClass("cq-md:border-b-0"),
+            )}
             role="row"
           >
             {selection ? (
               <th
                 className={toClassName(
-                  "border-border-subtle p-2 text-start cq-md:table-cell cq-md:border-b",
+                  toClassName(
+                    "border-border-subtle p-2 text-start",
+                    wideClass("cq-md:table-cell"),
+                    wideClass("cq-md:border-b"),
+                  ),
                 )}
                 role="columnheader"
                 scope="col"
@@ -338,7 +466,10 @@ export const DataTable = <Row,>({
                   // one underline per chip reads as five separate
                   // rules rather than one header edge.
                   className={toClassName(
-                    "border-b-0 cq-md:border-b",
+                    toClassName(
+                      "border-b-0",
+                      wideClass("cq-md:border-b"),
+                    ),
                     column.className,
                   )}
                   direction={
@@ -359,7 +490,11 @@ export const DataTable = <Row,>({
               ) : (
                 <th
                   className={toClassName(
-                    "border-border-subtle text-start font-medium text-content-secondary text-sm uppercase tracking-wide cq-md:table-cell cq-md:border-b",
+                    toClassName(
+                      "border-border-subtle text-start wrap-normal font-medium text-content-secondary text-sm uppercase tracking-wide",
+                      wideClass("cq-md:table-cell"),
+                      wideClass("cq-md:border-b"),
+                    ),
                     CELL_PADDING_CLASS,
                     column.className,
                   )}
@@ -375,16 +510,27 @@ export const DataTable = <Row,>({
         </thead>
 
         <tbody
-          className="flex flex-col gap-2 pt-2 cq-md:table-row-group cq-md:gap-0 cq-md:pt-0"
+          className={toClassName(
+            "flex flex-col gap-2 pt-2",
+            wideClass("cq-md:table-row-group"),
+            wideClass("cq-md:gap-0"),
+            wideClass("cq-md:pt-0"),
+          )}
           role={ROW_GROUP_ROLE}
         >
           {rows.length === 0 ? (
             <tr
-              className="block cq-md:table-row"
+              className={toClassName(
+                "block",
+                wideClass("cq-md:table-row"),
+              )}
               role="row"
             >
               <td
-                className="block p-0 cq-md:table-cell"
+                className={toClassName(
+                  "block p-0",
+                  wideClass("cq-md:table-cell"),
+                )}
                 colSpan={columnCount}
                 role="cell"
               >
@@ -405,10 +551,23 @@ export const DataTable = <Row,>({
                     // than in a stylesheet so a reader can see the
                     // whole of a row's shape in one place.
                     "flex flex-col gap-1 rounded-lg border border-border-subtle p-3 transition-colors duration-(--duration-fast) ease-standard",
-                    "cq-md:table-row cq-md:gap-0 cq-md:rounded-none cq-md:border-0 cq-md:border-border-subtle cq-md:border-b cq-md:p-0",
+                    toClassName(
+                      wideClass("cq-md:table-row"),
+                      wideClass("cq-md:gap-0"),
+                      wideClass("cq-md:rounded-none"),
+                      wideClass("cq-md:border-0"),
+                      wideClass(
+                        "cq-md:border-border-subtle",
+                      ),
+                      wideClass("cq-md:border-b"),
+                      wideClass("cq-md:p-0"),
+                    ),
                     isSelected
                       ? "bg-intent-accent-surface"
-                      : "bg-surface-raised hover:bg-intent-neutral-surface cq-md:bg-transparent",
+                      : toClassName(
+                          "bg-surface-raised hover:bg-intent-neutral-surface",
+                          wideClass("cq-md:bg-transparent"),
+                        ),
                   )}
                   // Not `aria-selected`: that property belongs to
                   // `grid`/`treegrid` rows, and this is a `table`.
@@ -421,7 +580,11 @@ export const DataTable = <Row,>({
                 >
                   {selection ? (
                     <td
-                      className="block p-2 cq-md:table-cell cq-md:align-middle"
+                      className={toClassName(
+                        "block p-2",
+                        wideClass("cq-md:table-cell"),
+                        wideClass("cq-md:align-middle"),
+                      )}
                       role="cell"
                     >
                       <Checkbox
@@ -451,9 +614,15 @@ export const DataTable = <Row,>({
                   {columns.map((column) => (
                     <td
                       className={toClassName(
-                        "flex items-baseline gap-3 py-0.5 cq-md:table-cell cq-md:align-middle",
+                        toClassName(
+                          "flex items-baseline gap-3 py-0.5",
+                          wideClass("cq-md:table-cell"),
+                          wideClass("cq-md:align-middle"),
+                        ),
                         CELL_PADDING_CLASS,
-                        "cq-md:py-2",
+                        toClassName(
+                          wideClass("cq-md:py-2"),
+                        ),
                         column.className,
                       )}
                       key={column.key}
@@ -467,7 +636,10 @@ export const DataTable = <Row,>({
                           out twice per cell. */}
                       <span
                         aria-hidden="true"
-                        className="w-20 shrink-0 truncate text-content-secondary text-xs uppercase tracking-wide cq-sm:w-24 cq-md:hidden"
+                        className={toClassName(
+                          "w-20 shrink-0 wrap-anywhere cq-xs:w-28 text-content-secondary text-xs uppercase tracking-wide",
+                          wideClass("cq-md:hidden"),
+                        )}
                       >
                         {column.header}
                       </span>
@@ -481,7 +653,12 @@ export const DataTable = <Row,>({
                           break-anywhere text asks for almost nothing
                           and gets it — a title column one word wide
                           with "extract or fan filter" underneath. */}
-                      <span className="min-w-0 flex-1 wrap-anywhere cq-md:wrap-normal">
+                      <span
+                        className={toClassName(
+                          "min-w-0 flex-1 wrap-anywhere",
+                          wideClass("cq-md:wrap-normal"),
+                        )}
+                      >
                         {column.renderCell(row)}
                       </span>
                     </td>

package/src/MetricCard/MetricCard.mdx

@@ -0,0 +1,26 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+import * as MetricCardStories from "./MetricCard.stories";
+
+<Meta of={MetricCardStories} />
+
+# MetricCard
+
+A prominent measure with a stable category colour on its optional app-supplied icon and leading edge. The heading remains text, so colour is additional information. Apps format the value and supply supporting content. A zero and an unavailable reading remain different values.
+
+<Canvas of={MetricCardStories.Playground} />
+
+## Props
+
+<Controls />
+
+## Categories and available space
+
+<Canvas of={MetricCardStories.AllVariants} />
+<Canvas of={MetricCardStories.AllStates} />
+<Canvas of={MetricCardStories.Responsive} />
+
+## Actions
+
+Place actions in the inherited Card footer. Decorative icons are hidden from assistive technology; use the visible heading to identify the metric.
+
+<Canvas of={MetricCardStories.Interactive} />

package/src/MetricCard/MetricCard.stories.tsx

@@ -0,0 +1,104 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import { CATEGORICAL_INDEXES } from "@charcuterie/tokens"
+import type { Meta, StoryObj } from "@storybook/react"
+import { categoricalArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { SettingsIcon } from "../icons.storyHelpers.tsx"
+import { MetricCard } from "./MetricCard.tsx"
+
+const meta = {
+  title: "Components/Data/MetricCard",
+  component: MetricCard,
+  parameters: { layout: "padded" },
+  argTypes: { categorical: categoricalArgType },
+  args: {
+    heading: "Energy",
+    value: "0.35 kWh",
+    categorical: 3,
+    icon: <SettingsIcon />,
+    children: <p>Measured during the selected period</p>,
+  },
+} satisfies Meta<typeof MetricCard>
+export default meta
+type Story = StoryObj<typeof meta>
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
+export const AllVariants: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      {CATEGORICAL_INDEXES.map((categorical) => (
+        <StoryCell
+          align="stretch"
+          label={`Category ${categorical}`}
+          key={categorical}
+        >
+          <MetricCard
+            heading={`Category ${categorical}`}
+            value="123.45"
+            categorical={categorical}
+            icon={<SettingsIcon />}
+          />
+        </StoryCell>
+      ))}
+    </StoryGrid>
+  ),
+}
+export const AllStates: Story = {
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="Zero is a value">
+        <MetricCard
+          heading="Recorded total"
+          value="0"
+          categorical={6}
+        />
+      </StoryCell>
+      <StoryCell
+        align="stretch"
+        label="Unavailable is app-owned"
+      >
+        <MetricCard
+          heading="Energy"
+          value="Unavailable"
+          categorical={10}
+        >
+          <p>No meter is connected.</p>
+        </MetricCard>
+      </StoryCell>
+      <StoryCell align="stretch" label="Neutral, no icon">
+        <MetricCard heading="Print time" value="14.5 h" />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+export const Responsive: Story = {
+  render: () => (
+    <ContainerBoard>
+      {(width) => (
+        <MetricCard
+          heading={`Recorded cost at ${width}`}
+          value="$1,234.56"
+          categorical={9}
+          icon={<SettingsIcon />}
+        >
+          <p>
+            Includes the recorded filament and energy costs.
+          </p>
+        </MetricCard>
+      )}
+    </ContainerBoard>
+  ),
+}
+export const Interactive: Story = {
+  args: {
+    footer: (
+      <Button appearance="outline">Inspect records</Button>
+    ),
+  },
+}

package/src/MetricCard/MetricCard.test.tsx

@@ -0,0 +1,64 @@
+import { composeStories } from "@storybook/react"
+import { expect } 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 * as stories from "./MetricCard.stories.tsx"
+
+const { Playground, AllStates, Responsive, Interactive } =
+  composeStories(stories)
+
+test("a metric is named by its visible heading and decorates its icon with its category colour", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Playground)
+  const region = expectAgentDrivable(canvas, {
+    role: "region",
+    name: "Energy",
+  })
+  await expect(region).toHaveTextContent("0.35 kWh")
+  const icon = region.querySelector(
+    'span[aria-hidden="true"]',
+  ) as HTMLElement
+  await expect(icon).toBeVisible()
+  await expect(getComputedStyle(icon).color).not.toBe(
+    getComputedStyle(region).color,
+  )
+  await expect(
+    getComputedStyle(region, "::before").boxShadow,
+  ).not.toBe("none")
+  await expectNoAxeViolations(canvasElement)
+})
+test("zero and unavailable readings remain distinct", async () => {
+  const { canvas } = await mountStory(AllStates)
+  await expect(
+    expectAgentDrivable(canvas, {
+      role: "region",
+      name: "Recorded total",
+    }),
+  ).toHaveTextContent("0")
+  await expect(
+    expectAgentDrivable(canvas, {
+      role: "region",
+      name: "Energy",
+    }),
+  ).toHaveTextContent("Unavailable")
+})
+test("metric values and supporting text fit every container", async () => {
+  const { canvasElement } = await mountStory(Responsive)
+  for (const card of canvasElement.querySelectorAll<HTMLElement>(
+    "section",
+  )) {
+    await expect(card.scrollWidth).toBeLessThanOrEqual(
+      card.clientWidth + 1,
+    )
+  }
+  await expectNoAxeViolations(canvasElement)
+})
+test("a footer action is reachable by its accessible name", async () => {
+  const { canvas } = await mountStory(Interactive)
+  expectAgentDrivable(canvas, {
+    role: "button",
+    name: "Inspect records",
+  })
+})