@charcuterie/ui 4.20.1 → 4.22.0

package/src/ComparisonChart/ComparisonChart.tsx

@@ -0,0 +1,161 @@
+import { ComparisonPlot } from "@charcuterie/logic/charts/react"
+import type { ChartSeries } from "@charcuterie/logic/core"
+import { getReadableTextColour } from "@charcuterie/tokens"
+import {
+  type CSSProperties,
+  useEffect,
+  useRef,
+  useState,
+} from "react"
+import { DataTable } from "../DataTable/DataTable.tsx"
+
+export type ComparisonChartProps = {
+  title: string
+  labels: readonly string[]
+  series: readonly ChartSeries[]
+  layout?: "nested" | "grouped"
+  formatValue?: (value: number) => string
+  isTableVisible?: boolean
+}
+
+/** Horizontal comparisons with one legend, a common scale, and original-value labels. */
+export const ComparisonChart = ({
+  title,
+  labels,
+  series,
+  layout = "nested",
+  formatValue = String,
+  isTableVisible = false,
+}: ComparisonChartProps) => {
+  const container = useRef<HTMLDivElement>(null)
+  const [width, setWidth] = useState(640)
+  useEffect(() => {
+    if (!container.current) return
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry.contentRect.width > 0)
+        setWidth(entry.contentRect.width)
+    })
+    observer.observe(container.current)
+    return () => observer.disconnect()
+  }, [])
+  const maximum = Math.max(
+    1,
+    ...series.flatMap((entry) =>
+      entry.values.filter(
+        (value): value is number =>
+          value !== null && Number.isFinite(value),
+      ),
+    ),
+  )
+  const minimum = Math.min(
+    0,
+    ...series.flatMap((entry) =>
+      entry.values.filter(
+        (value): value is number =>
+          value !== null && Number.isFinite(value),
+      ),
+    ),
+  )
+  return (
+    <figure
+      className="min-w-0 text-content-primary"
+      style={
+        {
+          "--ts-chart-tooltip-background":
+            "var(--color-surface-raised)",
+          "--ts-chart-tooltip-color":
+            "var(--color-content-primary)",
+        } as CSSProperties
+      }
+    >
+      <figcaption className="sr-only">{title}</figcaption>
+      <ul
+        aria-label={`${title} legend`}
+        className="mb-3 flex flex-wrap gap-3 text-xs"
+      >
+        {series.map((entry) => (
+          <li
+            key={entry.id}
+            className="min-w-0 wrap-anywhere"
+          >
+            <span
+              aria-hidden="true"
+              className="me-1 inline-block size-2 rounded-full"
+              style={{ backgroundColor: entry.color }}
+            />
+            {entry.label}
+          </li>
+        ))}
+      </ul>
+      <div ref={container} className="space-y-3">
+        {labels.map((label, index) => {
+          const values = series.map((entry) => ({
+            id: entry.id,
+            label: entry.label,
+            value: entry.values[index] ?? null,
+            colour: entry.color ?? "currentColor",
+            textColour:
+              entry.color &&
+              /^#[0-9a-f]{6}$/i.test(entry.color)
+                ? getReadableTextColour(entry.color)
+                : "var(--color-surface-base)",
+          }))
+          const shown = values.filter(
+            (entry) => entry.value !== null,
+          )
+          return (
+            <div
+              key={JSON.stringify([
+                label,
+                values
+                  .filter((entry) => entry.value !== null)
+                  .map((entry) => entry.id),
+              ])}
+            >
+              <p className="text-sm wrap-anywhere">
+                {label}
+              </p>
+              <ComparisonPlot
+                title={`${title}: ${label}`}
+                values={values}
+                maximum={maximum}
+                minimum={minimum}
+                layout={layout}
+                formatValue={formatValue}
+                width={width}
+                height={shown.length > 1 ? 60 : 34}
+              />
+            </div>
+          )
+        })}
+      </div>
+      {isTableVisible && (
+        <DataTable
+          label={`${title} values`}
+          rows={labels.map((label, index) => ({
+            label,
+            index,
+          }))}
+          getRowKey={(row) => String(row.index)}
+          columns={[
+            {
+              key: "label",
+              header: "Card",
+              renderCell: (row) => row.label,
+            },
+            ...series.map((entry) => ({
+              key: entry.id,
+              header: entry.label,
+              renderCell: (row: { index: number }) => {
+                const value = entry.values[row.index]
+                return value == null
+                  ? "-"
+                  : formatValue(value)
+              },
+            })),
+          ]}
+        />
+      )}
+    </figure>
+  )
+}

package/src/CopyButton/CopyButton.test.tsx

@@ -46,8 +46,12 @@ test("copies the value and confirms in place", async () => {
   await expect(copy).toHaveBeenCalledWith("335590")
   // The press and its proof are the same object — no toast, no
   // second place to look.
+  //
+  // `findBy`: `copy` is async, so the label changes a render after
+  // the click resolves. A synchronous read lost that race in CI's
+  // ultrawide window (master run 37298376242).
   await expect(
-    canvas.getByRole("button", { name: "Copied" }),
+    await canvas.findByRole("button", { name: "Copied" }),
   ).toBeVisible()
 })
 
@@ -73,7 +77,9 @@ test("says so when the clipboard refuses", async () => {
   )
 
   await expect(
-    canvas.getByRole("button", { name: "Copy failed" }),
+    await canvas.findByRole("button", {
+      name: "Copy failed",
+    }),
   ).toBeVisible()
   await expect(onCopy).toHaveBeenCalledWith(false, "335590")
 })
@@ -103,26 +109,30 @@ test("tells the caller what happened, both ways", async () => {
 test("announces the outcome in a status region", async () => {
   const { canvas } = await mountStory(Confirmed)
 
-  await expect(
-    canvas.getByRole("status"),
-  ).toHaveTextContent("Copied to the clipboard.")
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("status"),
+    ).toHaveTextContent("Copied to the clipboard.")
+  })
 })
 
 test("the failure says what to do instead", async () => {
   const { canvas } = await mountStory(Refused)
 
-  await expect(
-    canvas.getByRole("status"),
-  ).toHaveTextContent(
-    "The clipboard refused. Select the value and press Control C.",
-  )
+  await waitFor(async () => {
+    await expect(
+      canvas.getByRole("status"),
+    ).toHaveTextContent(
+      "The clipboard refused. Select the value and press Control C.",
+    )
+  })
 })
 
 /** The confirmation goes back on its own. */
 test("returns to the resting label", async () => {
   const { canvas } = await mountStory(
     composeStory(
-      { args: { confirmDuration: 20, copy: () => true } },
+      { args: { confirmDuration: 500, copy: () => true } },
       meta,
     ),
   )
@@ -130,8 +140,11 @@ test("returns to the resting label", async () => {
   await userEvent.click(
     canvas.getByRole("button", { name: "Copy" }),
   )
+  // 500ms, not 20: on a loaded runner a 20ms confirmation can come
+  // and go before the test looks, which fails the read below for the
+  // opposite reason to the race above.
   await expect(
-    canvas.getByRole("button", { name: "Copied" }),
+    await canvas.findByRole("button", { name: "Copied" }),
   ).toBeVisible()
 
   await waitFor(async () => {

package/src/Dialog/Dialog.test.tsx

@@ -1,6 +1,6 @@
 import { composeStories } from "@storybook/react"
 import { expect, userEvent, waitFor } from "storybook/test"
-import { test } from "vitest"
+import { inject, test } from "vitest"
 
 import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
 import { mountStory } from "../mountStory.testHelpers.ts"
@@ -69,7 +69,9 @@ test("the dialog is reachable from a body-scoped query", async () => {
   await expectNoAxeViolations(dialog)
 })
 
-test("size is a real width, not a class that happens to be there", async () => {
+const isNarrow = inject("viewport") === "narrow"
+
+const openLargeDialog = async () => {
   const { body, canvas } = await mountStory(AllVariants)
 
   await userEvent.click(
@@ -79,15 +81,43 @@ test("size is a real width, not a class that happens to be there", async () => {
     }),
   )
 
-  const dialog = expectAgentDrivable(body, {
+  return expectAgentDrivable(body, {
     name: "Read error — lg",
     role: "dialog",
   })
-
-  await expect(
-    dialog.getBoundingClientRect().width,
-  ).toBeGreaterThan(400)
-})
+}
+
+test.skipIf(isNarrow)(
+  "size is a real width, not a class that happens to be there",
+  async () => {
+    const dialog = await openLargeDialog()
+
+    await expect(
+      dialog.getBoundingClientRect().width,
+    ).toBeGreaterThan(400)
+  },
+)
+
+/*
+ * On the phone every size is `w-full` against a 384px window, so `lg`
+ * is no wider than `sm` and the test above has nothing to measure.
+ * What the Narrow View owes instead is that the largest dialog still
+ * fits: a dialog wider than the window is one whose close button is
+ * off the screen.
+ */
+test.runIf(isNarrow)(
+  "a large dialog still fits inside a phone's window",
+  async () => {
+    const { left, right } = (
+      await openLargeDialog()
+    ).getBoundingClientRect()
+
+    await expect(left).toBeGreaterThanOrEqual(0)
+    await expect(right).toBeLessThanOrEqual(
+      window.innerWidth,
+    )
+  },
+)
 
 test("a non-dismissable dialog ignores Escape rather than closing", async () => {
   const { body, canvas } = await mountStory(AllStates)

package/src/LaneTimeline/LaneTimelineBar.tsx

@@ -166,9 +166,9 @@ export const LaneTimelineBar = ({
        *
        * ⚠️ It does NOT reach a CAPITALIZED word. Chromium and
        * Firefox both skip a word whose first letter is upper case,
-       * as a proper-noun heuristic, and a 60px probe box confirmed
-       * it in both: `taekwondo` broke as `tae-` / `kwondo` and
-       * `Taekwondo` as `Taekwond` / `o`. Most calendar titles start
+       * as a proper-noun heuristic. A 60px probe box confirmed
+       * that the lower-case variant used dictionary hyphenation,
+       * while the capitalized variant broke at the edge. Titles start
        * with a capital, so this helps the second word of a title
        * more than the first. A capitalized word needs a soft
        * hyphen (U+00AD) placed in the DATA by the app; `auto`

package/src/Lightbox/Lightbox.mdx

@@ -61,3 +61,12 @@ that the contract `Dialog` guarantees is not quietly dropped by the wrapper —
 `onClose`, and focus back to the thumbnail.
 
 <Canvas of={LightboxStories.Interactive} />
+
+## An ordered gallery
+
+Pass `images` and `initialIndex` to open a collection at the selected thumbnail.
+Previous/Next controls and Left/Right arrow keys wrap through the collection. Escape
+closes it and restores focus to the trigger. `heading` stays stable while the image,
+caption, and announced position change. Omit `images` for the existing single-image view.
+
+<Canvas of={LightboxStories.Gallery} />

package/src/Lightbox/Lightbox.stories.tsx

@@ -133,3 +133,29 @@ export const Interactive: Story = {
     thumbnail: <PosterThumb />,
   },
 }
+
+/** Any thumbnail can start the same ordered gallery at its own image. */
+export const Gallery: Story = {
+  args: {
+    heading: "Poster gallery",
+    initialIndex: 1,
+    images: [
+      {
+        alt: "First poster",
+        src: toPosterSrc("FIRST"),
+        caption: "First view",
+      },
+      {
+        alt: "Second poster",
+        src: toPosterSrc("SECOND"),
+        caption: "Second view",
+      },
+      {
+        alt: "Third poster",
+        src: toPosterSrc("THIRD"),
+        caption: "Third view",
+      },
+    ],
+    thumbnail: <PosterThumb />,
+  },
+}

package/src/Lightbox/Lightbox.test.tsx

@@ -122,3 +122,56 @@ test("a controlled lightbox opens from an outside button", async () => {
 
   await expect(dialog).not.toBeInTheDocument()
 })
+
+test("a gallery opens at its thumbnail and navigates with controls and arrow keys", async () => {
+  const { Gallery } = composeStories(stories)
+  const { body, canvas } = await mountStory(Gallery)
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Enlarge Poster gallery",
+    role: "button",
+  })
+  await userEvent.click(trigger)
+  const dialog = expectAgentDrivable(body, {
+    name: "Poster gallery",
+    role: "dialog",
+  })
+  expectAgentDrivable(body, {
+    name: "Second poster",
+    role: "img",
+  })
+  await userEvent.keyboard("{ArrowRight}")
+  expectAgentDrivable(body, {
+    name: "Third poster",
+    role: "img",
+  })
+  await userEvent.click(
+    body.getByRole("button", { name: "Next image" }),
+  )
+  expectAgentDrivable(body, {
+    name: "First poster",
+    role: "img",
+  })
+  await userEvent.keyboard("{ArrowLeft}")
+  expectAgentDrivable(body, {
+    name: "Third poster",
+    role: "img",
+  })
+  await userEvent.click(
+    body.getByRole("button", { name: "Previous image" }),
+  )
+  expectAgentDrivable(body, {
+    name: "Second poster",
+    role: "img",
+  })
+  await expectNoAxeViolations(dialog)
+  await userEvent.keyboard("{Escape}")
+  await waitFor(() =>
+    expect(body.queryByRole("dialog")).toBeNull(),
+  )
+  await expect(document.activeElement).toBe(trigger)
+  await userEvent.click(trigger)
+  expectAgentDrivable(body, {
+    name: "Second poster",
+    role: "img",
+  })
+})

package/src/Lightbox/Lightbox.tsx

@@ -1,10 +1,20 @@
 import { useVisibility } from "@charcuterie/logic"
-import type { ReactNode } from "react"
+import { type ReactNode, useEffect, useState } from "react"
 
+import { Button } from "../Button/Button.tsx"
 import { Dialog } from "../Dialog/Dialog.tsx"
 import { toClassName } from "../toClassName.ts"
 
+export type LightboxImage = {
+  readonly alt: string
+  readonly src: string
+  readonly caption?: ReactNode
+}
+
 export type LightboxProps = {
+  /** Optional ordered gallery. The trigger opens at initialIndex. */
+  images?: readonly LightboxImage[]
+  initialIndex?: number
   /**
    * Required, and the whole reason this is not a bare `<img>` in a
    * dialog. It names both the enlarged image and — via `heading`'s
@@ -64,6 +74,8 @@ export const Lightbox = ({
   caption,
   className,
   heading,
+  images,
+  initialIndex = 0,
   isOpen,
   onOpenChange,
   src,
@@ -72,10 +84,66 @@ export const Lightbox = ({
   const isControlled = isOpen !== undefined
 
   const { hide, isVisible, show } = useVisibility()
+  const [index, setIndex] = useState(initialIndex)
 
   const isShown = isControlled ? isOpen : isVisible
+  const gallery = images?.length
+    ? images
+    : [{ alt, caption, src }]
+  const activeIndex = Math.max(
+    0,
+    Math.min(index, gallery.length - 1),
+  )
+  const active = gallery[activeIndex] ?? {
+    alt,
+    caption,
+    src,
+  }
+  const hasMultiple = gallery.length > 1
+
+  useEffect(() => {
+    if (!isShown || !hasMultiple) return
+    const navigate = (event: KeyboardEvent) => {
+      if (
+        event.altKey ||
+        event.ctrlKey ||
+        event.metaKey ||
+        event.shiftKey
+      )
+        return
+      if (
+        event.target instanceof HTMLElement &&
+        event.target.closest(
+          "input, textarea, [contenteditable=true]",
+        )
+      )
+        return
+      const delta =
+        event.key === "ArrowLeft"
+          ? -1
+          : event.key === "ArrowRight"
+            ? 1
+            : 0
+      if (delta === 0) return
+      event.preventDefault()
+      setIndex(
+        (current) =>
+          (Math.max(
+            0,
+            Math.min(current, gallery.length - 1),
+          ) +
+            delta +
+            gallery.length) %
+          gallery.length,
+      )
+    }
+    document.addEventListener("keydown", navigate)
+    return () =>
+      document.removeEventListener("keydown", navigate)
+  }, [isShown, hasMultiple, gallery.length])
 
   const requestOpen = () => {
+    setIndex(initialIndex)
     if (!isControlled) {
       show()
     }
@@ -120,20 +188,56 @@ export const Lightbox = ({
         isVisible={isShown}
         onClose={requestClose}
         size="xl"
+        footer={
+          hasMultiple ? (
+            <div className="flex w-full items-center justify-between gap-3">
+              <Button
+                appearance="ghost"
+                size="sm"
+                onClick={() =>
+                  setIndex(
+                    (activeIndex + gallery.length - 1) %
+                      gallery.length,
+                  )
+                }
+              >
+                Previous image
+              </Button>
+              <span
+                className="text-content-secondary text-sm"
+                role="status"
+                aria-live="polite"
+              >
+                {activeIndex + 1} of {gallery.length}
+              </span>
+              <Button
+                appearance="ghost"
+                size="sm"
+                onClick={() =>
+                  setIndex(
+                    (activeIndex + 1) % gallery.length,
+                  )
+                }
+              >
+                Next image
+              </Button>
+            </div>
+          ) : undefined
+        }
       >
         <figure className="flex flex-col items-center gap-3">
           <img
-            alt={alt}
+            alt={active.alt}
             // `object-contain`, not `cover`: the enlarged view must
             // show the whole image, and the clamp is `dvh` for the
             // same address-bar reason `Modal`'s is.
             className="max-h-[75dvh] w-auto max-w-full rounded-md object-contain"
-            src={src}
+            src={active.src}
           />
 
-          {caption ? (
+          {active.caption ? (
             <figcaption className="text-center text-content-muted text-sm">
-              {caption}
+              {active.caption}
             </figcaption>
           ) : null}
         </figure>

package/src/PortraitTiles/PortraitTiles.test.tsx

@@ -104,17 +104,23 @@ test("a picture that fails to load falls back to the initials", async () => {
     role: "group",
   })
 
-  await waitFor(async () => {
-    const broken = Array.from(
-      group.querySelectorAll<HTMLImageElement>("img"),
-    ).find((one) =>
-      one.src.includes("charcuterie-missing-portrait"),
-    )
-
-    // Gone from the DOM entirely, replaced by the letter — not left
-    // in place with a broken-image glyph in it.
-    await expect(broken).toBeUndefined()
-  })
+  // A real 404 over the network, not a mocked error event, so it gets
+  // longer than `waitFor`'s 1 s default: with four browser windows
+  // sharing a CI runner the failure arrived after it.
+  await waitFor(
+    async () => {
+      const broken = Array.from(
+        group.querySelectorAll<HTMLImageElement>("img"),
+      ).find((one) =>
+        one.src.includes("charcuterie-missing-portrait"),
+      )
+
+      // Gone from the DOM entirely, replaced by the letter — not left
+      // in place with a broken-image glyph in it.
+      await expect(broken).toBeUndefined()
+    },
+    { timeout: 5000 },
+  )
 
   const bailey = expectAgentDrivable(canvas, {
     name: "Bailey 860 points",

package/src/TableColumns/TableColumns.mdx

@@ -0,0 +1,14 @@
+import { Canvas, Meta } from "@storybook/addon-docs/blocks"
+import * as stories from "./TableColumns.stories.tsx"
+
+<Meta of={stories} />
+
+# TableColumns
+
+A reusable column visibility and ordering popover. The app supplies the ordered column choices and persists them if needed. Required columns cannot be hidden. Earlier and Later buttons make ordering keyboard accessible.
+
+<Canvas of={stories.Playground} />
+<Canvas of={stories.AllVariants} />
+<Canvas of={stories.AllStates} />
+<Canvas of={stories.Responsive} />
+<Canvas of={stories.Interactive} />