@charcuterie/ui 1.0.0 → 1.1.0

package/src/ColorSchemeToggle/ColorSchemeToggle.tsx

@@ -0,0 +1,107 @@
+import type { ColorSchemeMode } from "@charcuterie/logic"
+import {
+  DEFAULT_COLOR_SCHEME_ORDER,
+  nextColorSchemeMode,
+} from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { IconButton } from "../IconButton/IconButton.tsx"
+import type { IntentAppearance } from "../intentStyles.ts"
+
+/**
+ * One `ReactNode` per mode. The library ships **no icons** — lucide
+ * (ISC) is the fleet recommendation — so an app passes its own
+ * `Sun` / `Moon` / `Monitor`, exactly as `IconButton` takes its
+ * glyph as `children`
+ * ([decision](../../../../docs/decisions/2026-07-29-ship-no-icons-and-no-symbol-glyphs.md)).
+ */
+export type ColorSchemeIcons = Record<
+  ColorSchemeMode,
+  ReactNode
+>
+
+export type ColorSchemeToggleProps = {
+  appearance?: IntentAppearance
+  className?: string
+  icons: ColorSchemeIcons
+  isDisabled?: boolean
+  /**
+   * Builds the accessible name from the current and next mode.
+   * Default announces the current mode and where a press goes —
+   * "Colour scheme: dark. Activate to switch to system." — so the
+   * name updates as the control cycles and
+   * `getByRole("button", { name: /colour scheme/i })` resolves.
+   */
+  label?: (
+    mode: ColorSchemeMode,
+    nextMode: ColorSchemeMode,
+  ) => string
+  mode: ColorSchemeMode
+  /**
+   * Called with the next mode on activation. **Controlled**: this
+   * component stores nothing — it renders `mode` and reports intent,
+   * which is what keeps it free of `matchMedia`/`document` and
+   * usable in any runtime. `<ColorSchemeSwitcher>` wires this to the
+   * `useColorScheme` hook; a plain consumer wires it to its own
+   * state.
+   */
+  onCycle: (nextMode: ColorSchemeMode) => void
+  order?: readonly ColorSchemeMode[]
+  size?: ControlSize
+}
+
+const MODE_LABEL: Record<ColorSchemeMode, string> = {
+  dark: "Dark",
+  light: "Light",
+  system: "System",
+}
+
+const defaultLabel = (
+  mode: ColorSchemeMode,
+  nextMode: ColorSchemeMode,
+) =>
+  `Colour scheme: ${MODE_LABEL[mode]}. Activate to switch to ${MODE_LABEL[nextMode]}.`
+
+/**
+ * The cycling colour-scheme button — light → dark → system → light.
+ *
+ * Layer 2 of the three: presentational and controlled, with no
+ * browser coupling. It is an `IconButton`, so it inherits the one
+ * rule that makes the fleet agent-drivable — a glyph is not a name,
+ * and this control's name states the current mode rather than
+ * leaving a screen reader to read a sun path as nothing.
+ *
+ * A *segmented* all-three-visible form was considered and deferred
+ * (owner chose cycling-only, 2026-08-03); `icons` and `order` are
+ * shaped so a `ColorSchemePicker` could join later without changing
+ * this API.
+ */
+export const ColorSchemeToggle = ({
+  appearance = "ghost",
+  className,
+  icons,
+  isDisabled = false,
+  label = defaultLabel,
+  mode,
+  onCycle,
+  order = DEFAULT_COLOR_SCHEME_ORDER,
+  size = "md",
+}: ColorSchemeToggleProps): ReactNode => {
+  const nextMode = nextColorSchemeMode(mode, order)
+
+  return (
+    <IconButton
+      appearance={appearance}
+      className={className}
+      isDisabled={isDisabled}
+      label={label(mode, nextMode)}
+      onClick={() => {
+        onCycle(nextMode)
+      }}
+      size={size}
+    >
+      {icons[mode]}
+    </IconButton>
+  )
+}

package/src/Lightbox/Lightbox.mdx

@@ -0,0 +1,62 @@
+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 `Modal`**, not a second dialog. `Modal` owns
+`showModal()`, the top layer, Escape, the `::backdrop` scrim 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 `Modal`'s, asserted in `Modal`'s 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 `Modal` 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 `Modal` underneath, and two dialogs in the top layer
+ * side by side is not a thing the platform can do.
+ */
+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={(isOpen) => {
+          if (!isOpen) {
+            hide()
+          }
+        }}
+        src={POSTER}
+      />
+    </>
+  )
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledDemo />,
+}
+
+/**
+ * The keyboard contract, inherited from `Modal` 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,135 @@
+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)
+
+/**
+ * The close request, dispatched where the browser would raise it.
+ * `userEvent`'s Escape is untrusted and a native `<dialog>` runs no
+ * default action for it, so — exactly as `Modal`'s tests do — the
+ * `cancel` event is dispatched directly, and only the half
+ * downstream of it (this component's `onClose`, the effect, the
+ * focus restore) is ours to assert.
+ */
+const requestClose = (dialog: HTMLElement) => {
+  dialog.dispatchEvent(
+    new Event("cancel", { cancelable: true }),
+  )
+}
+
+test("the thumbnail opens the enlarged image", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Enlarge THE OUTFIT poster",
+      role: "button",
+    }),
+  )
+
+  const dialog = expectAgentDrivable(canvas, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  await expect(dialog).toHaveAttribute("open")
+
+  // The enlarged image carries the name — a bare `<img>` in a dialog
+  // otherwise announces as nothing.
+  expectAgentDrivable(canvas, {
+    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(canvasElement)
+})
+
+test("the caption rides along with the enlarged image", async () => {
+  const { canvas } = await mountStory(WithCaption)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Enlarge THE OUTFIT poster",
+    }),
+  )
+
+  await expect(
+    canvas.getByText("2022 · Blu-ray · 1080p"),
+  ).toBeInTheDocument()
+})
+
+/**
+ * The keyboard contract, inherited from `Modal` and asserted here so
+ * the skin cannot quietly drop it — Escape routes through `onClose`,
+ * and focus returns to the trigger the platform restored it to.
+ */
+test("closing restores focus to the thumbnail trigger", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Enlarge THE OUTFIT poster",
+    role: "button",
+  })
+
+  await userEvent.click(trigger)
+
+  const dialog = expectAgentDrivable(canvas, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  await expect(dialog).toContainElement(
+    document.activeElement as HTMLElement,
+  )
+
+  requestClose(dialog)
+
+  await waitFor(() => {
+    expect(canvas.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 { 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(canvas, {
+    name: "THE OUTFIT poster",
+    role: "dialog",
+  })
+
+  requestClose(dialog)
+
+  await waitFor(() => {
+    expect(canvas.queryByRole("dialog")).toBeNull()
+  })
+})

package/src/Lightbox/Lightbox.tsx

@@ -0,0 +1,143 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Modal } from "../Modal/Modal.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 `Modal`**, not a second
+ * dialog: `Modal` owns `showModal()`, the top layer, Escape, the
+ * `::backdrop` scrim 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>
+      )}
+
+      <Modal
+        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>
+      </Modal>
+    </>
+  )
+}

package/src/Menu/Menu.mdx

@@ -101,3 +101,26 @@ a keystroke buffer and a timer in a component that has neither, for a menu you c
 three arrow presses.
 
 <Canvas of={MenuStories.Interactive} />
+
+## One trigger, two slots
+
+A `Menu` and a `Tooltip` on the same button — the obvious thing to write, and until 1.0.1
+it did not work.
+
+Both components clone onto the trigger and both hand it a floating-ui
+`refs.setReference` — the element each of them positions its panel against. Every merge in
+the library was last-write-wins, so the inner `Tooltip` wrote its ref and the `Menu`'s was
+gone. A menu with no reference element is not an error: floating-ui simply leaves the panel
+at `left: 0; top: 0`, in the corner of the viewport, which reads as a CSS bug.
+
+A `ref` is a subscription and an `on*` is a listener, and neither survives being replaced.
+So both are **merged** now — between two slots by `mergeSlotWiring`, and between a slot and
+the element you wrote by `useClonedChild`, which is what makes
+`<Menu trigger={<Button ref={buttonRef} onClick={toggle} />} />` keep your ref *and* your
+handler.
+
+`SharedTrigger` is padded so the trigger sits away from the viewport origin: at the corner,
+an anchored panel and an unanchored one land in the same place, and the test asserts that
+padding is still there before it asserts anything else.
+
+<Canvas of={MenuStories.SharedTrigger} />

package/src/Menu/Menu.stories.tsx

@@ -13,6 +13,7 @@ import {
   SettingsIcon,
   UndoIcon,
 } from "../icons.storyHelpers.tsx"
+import { Tooltip } from "../Tooltip/Tooltip.tsx"
 import type { MenuItem } from "./Menu.tsx"
 import { Menu } from "./Menu.tsx"
 
@@ -72,6 +73,40 @@ const MenuHarness = ({
   )
 }
 
+/**
+ * The same harness, with a `Tooltip` between the `Menu` and the
+ * button — two components cloning onto **one** trigger, which is what
+ * image-viewer wanted and could not have.
+ */
+const TooltipTriggerHarness = ({
+  isInitiallyVisible = false,
+  tip,
+  triggerLabel,
+}: {
+  isInitiallyVisible?: boolean
+  tip: string
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isInitiallyVisible,
+  })
+
+  return (
+    <Menu
+      isVisible={isVisible}
+      items={BAY_ACTIONS}
+      onDismiss={hide}
+      trigger={
+        <Tooltip label={tip}>
+          <Button appearance="outline" onClick={toggle}>
+            {triggerLabel}
+          </Button>
+        </Tooltip>
+      }
+    />
+  )
+}
+
 const meta = {
   title: "Components/Menu",
   component: Menu,
@@ -143,6 +178,38 @@ export const AllStates: Story = {
   ),
 }
 
+/**
+ * **One trigger, two slots.** `Menu` and `Tooltip` both clone onto
+ * the button and both hand it a `ref` — floating-ui's
+ * `refs.setReference`, which is the anchor each of them positions
+ * against. Until 1.0.1 the second clone's ref simply replaced the
+ * first's, so the panel it belonged to had no anchor and rendered in
+ * the top-left corner of the viewport.
+ *
+ * Hover the button and open the menu: the tip and the panel are both
+ * attached to it.
+ */
+export const SharedTrigger: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: noop,
+    trigger: <Button appearance="outline">Actions</Button>,
+  },
+  render: () => (
+    // Padded, and the padding is load-bearing rather than pretty: an
+    // anchor that has been dropped leaves floating-ui at
+    // `left: 0; top: 0`, so a trigger sitting in the corner of the
+    // viewport is a trigger where "anchored" and "not anchored" look
+    // identical. `Menu.test.tsx` asserts the padding is still here.
+    <div className="p-16">
+      <TooltipTriggerHarness
+        tip="Everything that can be done to this bay."
+        triggerLabel="Bay 5"
+      />
+    </div>
+  ),
+}
+
 /**
  * Open it and arrow down. Focus lands on the first item **on
  * opening** — a menu that leaves the caret on the trigger is one a