@charcuterie/ui 1.0.1 → 2.0.0

package/src/Dialog/Dialog.tsx

@@ -0,0 +1,127 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Modal } from "../Modal/Modal.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type DialogSize = "full" | "lg" | "md" | "sm" | "xl"
+
+export type DialogProps = {
+  children: ReactNode
+  className?: string
+  /** The footer row. Buttons, usually. */
+  footer?: ReactNode
+  heading: string
+  headingLevel?: 2 | 3 | 4
+  /**
+   * Escape and a backdrop press both close. Off for the one honest
+   * case — a destructive confirm the user has to answer.
+   */
+  isDismissable?: boolean
+  isVisible: boolean
+  /**
+   * Every route out lands here: the close button, Escape, a backdrop
+   * press. Wire it to a `useVisibility()`'s `hide`.
+   */
+  onClose: () => void
+  size?: DialogSize
+}
+
+/**
+ * `85dvh` rather than `85vh` — on a phone the two differ by the
+ * address bar, and a dialog whose footer is under it is a dialog
+ * with no buttons.
+ */
+const SIZE_CLASS: Record<DialogSize, string> = {
+  sm: "max-h-[85dvh] w-full max-w-sm",
+  md: "max-h-[85dvh] w-full max-w-md",
+  lg: "max-h-[85dvh] w-full max-w-2xl",
+  // M5 added this, because the scale jumped from 42rem straight to
+  // the whole viewport and rip-deck's capture tail lands in the
+  // gap: a MakeMKV robot log is fixed-width `MSG:5072,0,1,"…"`
+  // lines that wrap badly at 42rem, and a full-screen dialog over a
+  // nine-bay dashboard hides the thing being diagnosed. 56rem is
+  // what that app's hand-rolled `<dialog>` used before the swap.
+  xl: "max-h-[85dvh] w-full max-w-4xl",
+  full: "h-[100dvh] max-h-[100dvh] w-full max-w-full rounded-none",
+}
+
+/**
+ * `Modal` plus the chrome — heading, a Close button, a scrolling body,
+ * an optional footer, and five sizes. This is what `Modal` *was*
+ * before the M8 rebuild renamed it: a dialog is one kind of modal, so
+ * it takes the specific name and hands the generic one back to the
+ * base layer.
+ *
+ * Everything modal — the portal, the scrim, Escape and outside-press
+ * dismiss, the focus trap, the scroll lock, the stacking — is `Modal`'s
+ * (via `OverlayPanel`), so this component is just the box's contents
+ * and the size class it wants that box to be. `SIZE_CLASS` is composed
+ * over `Modal`'s default surface, which is why `full` carries
+ * `rounded-none` to square off the base's `rounded-lg` at the viewport
+ * edge.
+ *
+ * ### The accessible name
+ *
+ * `heading` is required and is a string, not a `ReactNode`. It names
+ * both the visible header and — through `aria-labelledby` on the
+ * modal — the dialog itself. A dialog with no name is announced as
+ * "dialog" and nothing else, which is what every hand-rolled modal in
+ * the inventory does.
+ */
+export const Dialog = ({
+  children,
+  className,
+  footer,
+  heading,
+  headingLevel = 2,
+  isDismissable = true,
+  isVisible,
+  onClose,
+  size = "md",
+}: DialogProps): ReactNode => {
+  const headingId = useUniqueId()
+
+  const Heading = `h${headingLevel}` as const
+
+  return (
+    <Modal
+      aria-labelledby={headingId}
+      className={toClassName(SIZE_CLASS[size], className)}
+      isDismissable={isDismissable}
+      isVisible={isVisible}
+      onClose={onClose}
+    >
+      <header className="flex shrink-0 items-start justify-between gap-3 border-b border-border-subtle p-4">
+        <Heading
+          className="font-semibold text-lg leading-tight"
+          id={headingId}
+        >
+          {heading}
+        </Heading>
+
+        {isDismissable ? (
+          <Button
+            appearance="ghost"
+            intent="neutral"
+            onClick={onClose}
+            size="sm"
+          >
+            Close
+          </Button>
+        ) : null}
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-auto p-4">
+        {children}
+      </div>
+
+      {footer ? (
+        <footer className="flex shrink-0 flex-wrap justify-end gap-2 border-t border-border-subtle p-4">
+          {footer}
+        </footer>
+      ) : null}
+    </Modal>
+  )
+}

package/src/Field/Field.test.tsx

@@ -180,7 +180,7 @@ test("a slot forwards what an outer slot gave it", async () => {
  * ref and the attribute to have all three arrived.
  */
 test("a slot forwards what an outer slot gave it, in the other order", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Archive path",
@@ -192,8 +192,10 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
   // only have been wired to the `<input>`.
   control.focus()
 
+  // The tip portals to the body now; the `aria-describedby` link still
+  // resolves across the boundary, asserted below.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "Where finished rips are moved.",
     )
   })
@@ -224,7 +226,7 @@ test("a slot forwards what an outer slot gave it, in the other order", async ()
  * tip.
  */
 test("a tip is described alongside the field's own text, not instead of it", async () => {
-  const { canvas } = await mountStory(Nested)
+  const { body, canvas } = await mountStory(Nested)
 
   const control = expectAgentDrivable(canvas, {
     name: "Rename pattern",
@@ -237,7 +239,7 @@ test("a tip is described alongside the field's own text, not instead of it", asy
   // tip is missing, and the reason this is testable without a
   // pointer at all.
   await waitFor(() => {
-    expect(canvas.getByRole("tooltip")).toHaveTextContent(
+    expect(body.getByRole("tooltip")).toHaveTextContent(
       "A JavaScript regular expression.",
     )
   })

package/src/Lightbox/Lightbox.mdx

@@ -0,0 +1,63 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as LightboxStories from "./Lightbox.stories";
+
+<Meta of={LightboxStories} />
+
+# Lightbox
+
+A thumbnail that opens its own full-size view. Three apps hand-roll this — a poster,
+a still, a scan the operator wants to read — and none get the focus trap or the scroll
+lock right, because the interesting part is not the overlay, it is the dialog underneath.
+
+So a `Lightbox` is a **skin over `Dialog`**, not a second dialog. `Dialog` (through
+`Modal`/`OverlayPanel`) owns the portal, the scrim, Escape, the focus trap and
+`lockScrollBehind`; this adds the image-specific part — a `cursor-zoom-in` trigger and an
+`object-contain` image clamped to the viewport, so a 2:3 poster and a 16:9 still both land
+whole.
+
+<Canvas of={LightboxStories.Default} />
+
+## Props
+
+<Controls />
+
+## The thumbnail is the trigger, and it carries the name
+
+Pass the small image as `thumbnail` and the `Lightbox` wraps it in the button that opens
+the overlay. That button carries the accessible name — `Enlarge {alt}` — so the
+`thumbnail` inside it goes `alt=""`, exactly as `MediaTile` names its link and silences
+the image within it. A button around an empty-alt image is otherwise `button-name` with
+nothing to announce.
+
+```tsx
+<Lightbox
+  alt="THE OUTFIT poster"
+  src={fullSizePoster}
+  thumbnail={<img alt="" className="h-40 w-28 object-cover" src={thumbSrc} />}
+/>
+```
+
+`alt` also names the dialog, through `heading`'s default. Pass `heading` when the two
+should differ — a filename overlay whose thumbnail alt is already the title.
+
+<Canvas of={LightboxStories.WithCaption} />
+
+## Controlled, when something else opens it
+
+Omit `thumbnail` and pass `isOpen` / `onOpenChange`, and the `Lightbox` renders only the
+overlay — a button elsewhere on the page owns the open state through its own
+`useVisibility`. The internal store still runs (hooks cannot be conditional) but goes
+unread; the caller is the one truth.
+
+<Canvas of={LightboxStories.Controlled} />
+
+## What it inherits, and does not re-test
+
+Escape, the focus trap, focus restore to the trigger, the scrim and the scroll lock are
+all `Dialog`'s (via `Modal`), asserted in their own tests. The lightbox's tests assert only
+the skin: that the thumbnail opens the enlarged image, that the caption rides along, and
+that the contract `Dialog` guarantees is not quietly dropped by the wrapper — Escape →
+`onClose`, and focus back to the thumbnail.
+
+<Canvas of={LightboxStories.Interactive} />

package/src/Lightbox/Lightbox.stories.tsx

@@ -0,0 +1,133 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { StoryRow } from "../board.storyHelpers.tsx"
+import { Lightbox } from "./Lightbox.tsx"
+
+/**
+ * An inline SVG rather than a fixture file or a placeholder service:
+ * it decodes synchronously and needs no network, so the enlarged
+ * image is deterministic in CI — the same reason `MediaTile`'s
+ * stories draw their posters this way.
+ */
+const toPosterSrc = (label: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 300"><rect width="200" height="300" fill="#3E38C4"/><text x="100" y="150" fill="#FFFFFF" font-family="sans-serif" font-size="18" text-anchor="middle">${label}</text></svg>`,
+  )}`
+
+const POSTER = toPosterSrc("THE OUTFIT")
+
+/**
+ * A small poster thumbnail, exactly as a card would render it —
+ * `object-cover` at a fixed poster trim. It is the child the
+ * `Lightbox` trigger wraps.
+ */
+const PosterThumb = (): ReactNode => (
+  <img
+    alt=""
+    className="h-40 w-28 rounded-md object-cover ring-1 ring-border-subtle"
+    src={POSTER}
+  />
+)
+
+const meta = {
+  title: "Components/Lightbox",
+  component: Lightbox,
+  parameters: { layout: "padded" },
+  args: {
+    alt: "THE OUTFIT poster",
+    src: POSTER,
+  },
+} satisfies Meta<typeof Lightbox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The uncontrolled default: the thumbnail *is* the trigger, and the
+ * component owns its open state. This is what a rip card passes —
+ * one `Lightbox` with the poster as its `thumbnail`.
+ */
+export const Default: Story = {
+  args: {
+    thumbnail: <PosterThumb />,
+  },
+}
+
+export const WithCaption: Story = {
+  args: {
+    caption: "2022 · Blu-ray · 1080p",
+    thumbnail: <PosterThumb />,
+  },
+}
+
+/**
+ * Boards here are a trigger plus one open overlay, not a grid — a
+ * lightbox is a `Dialog` underneath, and a dialog covers the viewport,
+ * so two side by side is not the real arrangement.
+ */
+export const AllStates: Story = {
+  render: () => (
+    <StoryRow>
+      <Lightbox
+        alt="THE OUTFIT poster"
+        src={POSTER}
+        thumbnail={<PosterThumb />}
+      />
+
+      <Lightbox
+        alt="THE OUTFIT poster"
+        caption="2022 · Blu-ray · 1080p"
+        src={POSTER}
+        thumbnail={<PosterThumb />}
+      />
+    </StoryRow>
+  ),
+}
+
+/**
+ * The controlled case: some other control opens the lightbox, and
+ * this renders only the overlay. `isOpen` present makes the internal
+ * store go unread — the caller's `useVisibility` is the one truth.
+ */
+const ControlledDemo = (): ReactNode => {
+  const { hide, isVisible, show } = useVisibility()
+
+  return (
+    <>
+      <Button appearance="soft" onClick={show} size="sm">
+        View the poster
+      </Button>
+
+      <Lightbox
+        alt="THE OUTFIT poster"
+        caption="Opened from a button, not the image"
+        isOpen={isVisible}
+        onOpenChange={(isNextOpen) => {
+          if (!isNextOpen) {
+            hide()
+          }
+        }}
+        src={POSTER}
+      />
+    </>
+  )
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledDemo />,
+}
+
+/**
+ * The keyboard contract, inherited from `Dialog` and asserted here so
+ * the skin cannot quietly drop it: the trigger opens, Escape routes
+ * through `onClose`, and focus returns to the thumbnail button.
+ */
+export const Interactive: Story = {
+  args: {
+    thumbnail: <PosterThumb />,
+  },
+}

package/src/Lightbox/Lightbox.test.tsx

@@ -0,0 +1,124 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } 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 "./Lightbox.stories.tsx"
+
+const { Controlled, Default, Interactive, WithCaption } =
+  composeStories(stories)
+
+test("the thumbnail opens the enlarged image", async () => {
+  const { body, canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Enlarge THE OUTFIT poster",
+      role: "button",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(body, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  // The enlarged image carries the name — a bare `<img>` in a dialog
+  // otherwise announces as nothing.
+  expectAgentDrivable(body, {
+    name: "THE OUTFIT poster",
+    role: "img",
+  })
+
+  // The open dialog audits itself: the empty-alt thumbnail, the
+  // named trigger and the named enlarged image are the arrangement
+  // most likely to trip `button-name` or a duplicate name.
+  await expectNoAxeViolations(dialog)
+})
+
+test("the caption rides along with the enlarged image", async () => {
+  const { body, canvas } = await mountStory(WithCaption)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Enlarge THE OUTFIT poster",
+    }),
+  )
+
+  await expect(
+    body.getByText("2022 · Blu-ray · 1080p"),
+  ).toBeInTheDocument()
+})
+
+/**
+ * The keyboard contract, inherited from `Dialog` and asserted here so
+ * the skin cannot quietly drop it — Escape routes through `onClose`,
+ * and focus returns to the trigger `FloatingFocusManager` restored it
+ * to. Escape is a real `userEvent` keypress now, since the overlay is
+ * no longer a native `<dialog>`.
+ */
+test("closing restores focus to the thumbnail trigger", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Enlarge THE OUTFIT poster",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  const dialog = expectAgentDrivable(body, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  await waitFor(() => {
+    expect(dialog.contains(document.activeElement)).toBe(
+      true,
+    )
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+
+  await expect(document.activeElement).toBe(trigger)
+})
+
+/**
+ * Controlled: the caller's `useVisibility` is the one truth, and the
+ * `Lightbox` renders no trigger of its own — a button elsewhere
+ * opens it, and closing it flows back through `onOpenChange`.
+ */
+test("a controlled lightbox opens from an outside button", async () => {
+  const { body, canvas } = await mountStory(Controlled)
+
+  // No built-in trigger: the only "Enlarge …" button a `thumbnail`
+  // would have added is absent.
+  await expect(
+    canvas.queryByRole("button", {
+      name: /^Enlarge/,
+    }),
+  ).toBeNull()
+
+  await userEvent.click(
+    canvas.getByRole("button", { name: "View the poster" }),
+  )
+
+  const dialog = expectAgentDrivable(body, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("dialog")).toBeNull()
+  })
+
+  await expect(dialog).not.toBeInTheDocument()
+})

package/src/Lightbox/Lightbox.tsx

@@ -0,0 +1,143 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Dialog } from "../Dialog/Dialog.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type LightboxProps = {
+  /**
+   * Required, and the whole reason this is not a bare `<img>` in a
+   * dialog. It names both the enlarged image and — via `heading`'s
+   * default below — the dialog itself, and a poster grid of unnamed
+   * images is unnavigable rather than merely imperfect. Same rule
+   * `MediaTile` makes.
+   */
+  alt: string
+  /** Shown under the enlarged image. A year, a source, a filename. */
+  caption?: ReactNode
+  /** Applied to the built-in trigger button, not the dialog. */
+  className?: string
+  /**
+   * The dialog's accessible name and visible heading. Defaults to
+   * `alt`, which is right when the thumbnail's alt is already the
+   * title ("THE OUTFIT poster"); pass it when the two should differ.
+   */
+  heading?: string
+  /**
+   * **Controlled** open state. Omit for the uncontrolled default,
+   * where the trigger owns it through `useVisibility`. Present means
+   * the caller owns it and the built-in trigger becomes a plain
+   * button that only *reports* intent through `onOpenChange`.
+   */
+  isOpen?: boolean
+  onOpenChange?: (isOpen: boolean) => void
+  src: string
+  /**
+   * The clickable thumbnail — a smaller `<img>`, usually. Omitted in
+   * the controlled, trigger-elsewhere case, where something else in
+   * the page opens the lightbox and this renders only the overlay.
+   */
+  thumbnail?: ReactNode
+}
+
+/**
+ * A thumbnail that opens its own full-size view — the one image
+ * interaction three apps hand-roll and none get the focus trap or
+ * the scroll lock right. It is a **skin over `Dialog`**, not a second
+ * dialog: `Dialog` (through `Modal`/`OverlayPanel`) owns the portal,
+ * the scrim, Escape, the focus trap and `lockScrollBehind`, and
+ * everything that makes those correct in every browser the fleet
+ * runs. What this adds is the image-specific part — a `cursor-zoom-in`
+ * trigger and an `object-contain` image clamped to the viewport so a
+ * 2:3 poster and a 16:9 still both land whole.
+ *
+ * ### Controlled and not, one component
+ *
+ * `useVisibility` runs unconditionally — hooks cannot be conditional
+ * — but is *consulted* only when `isOpen` is absent. A caller that
+ * passes `isOpen` owns the truth; the internal store is then an
+ * unread two-field object, which is cheaper than splitting this into
+ * two components that share a Modal body.
+ */
+export const Lightbox = ({
+  alt,
+  caption,
+  className,
+  heading,
+  isOpen,
+  onOpenChange,
+  src,
+  thumbnail,
+}: LightboxProps): ReactNode => {
+  const isControlled = isOpen !== undefined
+
+  const { hide, isVisible, show } = useVisibility()
+
+  const isShown = isControlled ? isOpen : isVisible
+
+  const requestOpen = () => {
+    if (!isControlled) {
+      show()
+    }
+
+    onOpenChange?.(true)
+  }
+
+  const requestClose = () => {
+    if (!isControlled) {
+      hide()
+    }
+
+    onOpenChange?.(false)
+  }
+
+  return (
+    <>
+      {thumbnail === undefined ? null : (
+        <button
+          // The trigger carries the name; the `thumbnail` inside it
+          // goes `alt=""`, exactly as `MediaTile` names its link and
+          // silences the image within it. A button around an
+          // empty-alt image is otherwise `button-name` with nothing
+          // to announce.
+          aria-label={`Enlarge ${heading ?? alt}`}
+          className={toClassName(
+            // `cursor-zoom-in` is the affordance a bare `<img>`
+            // never had, and the focus ring is the fleet's standard
+            // — the same one `MediaTile`'s link wears.
+            "group block cursor-zoom-in rounded-md outline-offset-2 focus-visible:outline-solid focus-visible:outline-(length:--focus-ring-width) focus-visible:outline-focus-ring",
+            className,
+          )}
+          onClick={requestOpen}
+          type="button"
+        >
+          {thumbnail}
+        </button>
+      )}
+
+      <Dialog
+        heading={heading ?? alt}
+        isVisible={isShown}
+        onClose={requestClose}
+        size="xl"
+      >
+        <figure className="flex flex-col items-center gap-3">
+          <img
+            alt={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}
+          />
+
+          {caption ? (
+            <figcaption className="text-center text-content-muted text-sm">
+              {caption}
+            </figcaption>
+          ) : null}
+        </figure>
+      </Dialog>
+    </>
+  )
+}

package/src/Listbox/Listbox.mdx

@@ -0,0 +1,68 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ListboxStories from "./Listbox.stories";
+
+<Meta of={ListboxStories} />
+
+# Listbox
+
+The single-select **fancy** dropdown — the rich-option sibling of the native
+[`Select`](?path=/docs/components-select--docs), not a replacement for it. `Select` keeps
+type-ahead, Home/End, the mobile wheel picker, form submission, `:invalid` and autofill;
+`Listbox` is for the cases `<option>` cannot render — a leading icon, two lines, a trailing
+badge ([decision](../../../docs/decisions/2026-08-03-listbox-and-combobox-are-siblings-of-select.md)).
+
+<Canvas of={ListboxStories.Default} />
+
+## Props
+
+<Controls />
+
+## A listbox is not a menu
+
+An `option` **is** something you are choosing; a `menuitem` **does** something. So a
+`Listbox` carries `aria-selected`, it type-aheads (the APG requires it of a listbox and
+`Menu` deliberately omits it), and a screen reader announces "listbox, selected, 2 of 4".
+That is the distinction `Menu` documents from the other side.
+
+```tsx
+const { hide, isVisible, toggle } = useVisibility()
+const [value, setValue] = useState<string>()
+
+<Listbox
+  isVisible={isVisible}
+  onDismiss={hide}
+  onSelect={setValue}
+  options={LANGUAGES}
+  selectedValue={value}
+  trigger={<Button onClick={toggle}>{label}</Button>}
+/>
+```
+
+## Two kinds of state, composed
+
+`useRovingFocus` owns which option is tabbable — exactly one, so Tab enters and leaves the
+group once and the arrow keys move within it — and `useSinglePicker` owns which option is
+chosen. They are the same two kinds `Tabs` composes, and they never disturb each other:
+arrowing moves focus without selecting, Enter selects the focused option. A disabled option
+joins the choice but not the focus group, so the arrow keys and type-ahead skip it.
+
+<Canvas of={ListboxStories.AllStates} />
+
+## Rich options, and `textValue`
+
+The options take a `ReactNode` label — two lines, a flag, an intent-coloured confidence
+badge. When the label is rich, `textValue` is required: it is the type-ahead target and the
+name a screen reader reads, so a picture of a value is still a value you can find by typing.
+
+<Canvas of={ListboxStories.AllVariants} />
+
+## Portalled, and a plain button opens it
+
+The panel portals to `document.body`. The trigger stays a native **button** that gains
+`aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls` — the button-opens-listbox
+pattern, not a `combobox` (that is `Combobox`, where focus stays in a text input). So there
+is no `heading` prop; the button names the widget. The panel height is clamped to the
+viewport by floating-ui's `size` middleware and scrolls within it.
+
+<Canvas of={ListboxStories.Interactive} />