@charcuterie/ui 4.20.1 → 4.21.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/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} />

package/src/TableColumns/TableColumns.stories.tsx

@@ -0,0 +1,81 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { ContainerBoard } from "../board.storyHelpers.tsx"
+import { TableColumns } from "./TableColumns.tsx"
+
+const meta = {
+  title: "Components/Data/TableColumns",
+  component: TableColumns,
+  args: {
+    columns: [
+      {
+        key: "name",
+        label: "Name",
+        isVisible: true,
+        isRequired: true,
+      },
+      {
+        key: "duration",
+        label: "Duration",
+        isVisible: true,
+      },
+      { key: "median", label: "Median", isVisible: false },
+    ],
+    onChange: () => {},
+  },
+} satisfies Meta<typeof TableColumns>
+export default meta
+type Story = StoryObj<typeof meta>
+const Controlled = (
+  props: React.ComponentProps<typeof TableColumns>,
+) => {
+  const [columns, setColumns] = useState([...props.columns])
+  return (
+    <>
+      <TableColumns
+        {...props}
+        columns={columns}
+        onChange={setColumns}
+      />
+      <p>
+        {columns
+          .filter((column) => column.isVisible)
+          .map((column) => column.label)
+          .join(", ")}
+      </p>
+    </>
+  )
+}
+export const Playground: Story = {
+  parameters: playgroundParameters,
+  render: (props) => <Controlled {...props} />,
+}
+export const AllVariants: Story = {
+  render: (props) => (
+    <Controlled {...props} label="Choose columns" />
+  ),
+}
+export const AllStates: Story = {
+  args: {
+    columns: [
+      {
+        key: "name",
+        label: "Name",
+        isVisible: true,
+        isRequired: true,
+      },
+    ],
+  },
+  render: (props) => <Controlled {...props} />,
+}
+export const Responsive: Story = {
+  render: (props) => (
+    <ContainerBoard>
+      {() => <Controlled {...props} />}
+    </ContainerBoard>
+  ),
+}
+export const Interactive: Story = {
+  render: (props) => <Controlled {...props} />,
+}

package/src/TableColumns/TableColumns.test.tsx

@@ -0,0 +1,35 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { test } from "vitest"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./TableColumns.stories.tsx"
+
+const { Interactive } = composeStories(stories)
+test("column visibility and order can be changed with named controls", async () => {
+  const { canvas, body } = await mountStory(Interactive)
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      role: "button",
+      name: "Columns",
+    }),
+  )
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      role: "checkbox",
+      name: "Median",
+    }),
+  )
+  await expect(
+    canvas.getByText("Name, Duration, Median"),
+  ).toBeVisible()
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      role: "button",
+      name: "Move Median earlier",
+    }),
+  )
+  await expect(
+    canvas.getByText("Name, Median, Duration"),
+  ).toBeVisible()
+})