@charcuterie/ui 1.0.1 → 1.1.0

package/src/ColorSchemeSwitcher/ColorSchemeSwitcher.tsx

@@ -0,0 +1,90 @@
+import type {
+  ColorSchemeApplier,
+  ColorSchemePersistence,
+  ColorSchemeResolver,
+} from "@charcuterie/logic"
+import { useColorScheme } from "@charcuterie/logic"
+import {
+  dataSchemeApplier,
+  localStoragePersistence,
+  matchMediaResolver,
+} from "@charcuterie/logic/browser"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import type {
+  ColorSchemeIcons,
+  ColorSchemeToggleProps,
+} from "../ColorSchemeToggle/ColorSchemeToggle.tsx"
+import { ColorSchemeToggle } from "../ColorSchemeToggle/ColorSchemeToggle.tsx"
+
+export type ColorSchemeSwitcherProps = Pick<
+  ColorSchemeToggleProps,
+  | "appearance"
+  | "className"
+  | "isDisabled"
+  | "label"
+  | "order"
+  | "size"
+> & {
+  /** Override where the resolved scheme is written. Default `<html>`. */
+  apply?: ColorSchemeApplier
+  icons: ColorSchemeIcons
+  /** Override persistence. Default `localStorage` under `storageKey`. */
+  persistence?: ColorSchemePersistence
+  /**
+   * Override the OS resolver. Default `matchMedia`. This is the seam
+   * the image-viewer passes Electron `nativeTheme` into, and a
+   * future React-Native app passes `Appearance` — the whole reason
+   * the browser dependency is isolated to this one layer.
+   */
+  resolver?: ColorSchemeResolver
+  storageKey?: string
+}
+
+/**
+ * The connected colour-scheme switcher — Layer 3, and the only
+ * layer that touches the browser.
+ *
+ * It is a thin wrapper: it wires `useColorScheme` to the three
+ * browser defaults from `@charcuterie/logic/browser`
+ * (`matchMedia` + `localStorage` + `data-scheme` on `<html>`), and
+ * renders the presentational `ColorSchemeToggle`. Every seam is
+ * overridable, so a non-browser host swaps `resolver`/`persistence`/
+ * `apply` and the same component drives Electron or React-Native.
+ *
+ * The seams are built once (lazy `useState`) so the `matchMedia`
+ * query and the core survive re-renders and StrictMode's double
+ * mount.
+ */
+export const ColorSchemeSwitcher = ({
+  apply,
+  icons,
+  order,
+  persistence,
+  resolver,
+  storageKey,
+  ...toggleProps
+}: ColorSchemeSwitcherProps): ReactNode => {
+  const [seams] = useState(() => ({
+    apply: apply ?? dataSchemeApplier(),
+    persistence:
+      persistence ?? localStoragePersistence(storageKey),
+    resolver: resolver ?? matchMediaResolver(),
+  }))
+
+  const { cycle, mode } = useColorScheme({
+    ...seams,
+    order,
+  })
+
+  return (
+    <ColorSchemeToggle
+      {...toggleProps}
+      icons={icons}
+      mode={mode}
+      onCycle={cycle}
+      order={order}
+    />
+  )
+}

package/src/ColorSchemeToggle/ColorSchemeToggle.mdx

@@ -0,0 +1,48 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ColorSchemeToggleStories from "./ColorSchemeToggle.stories";
+
+<Meta of={ColorSchemeToggleStories} />
+
+# ColorSchemeToggle
+
+The cycling colour-scheme button — **light → dark → system → light**. Layer 2 of three:
+presentational and **controlled**, with no `matchMedia`, `localStorage`, or `document` in
+sight. It renders the current `mode` and reports the next one through `onCycle`; it stores
+nothing.
+
+That split is deliberate. The browser dependency lives one layer up in
+[`ColorSchemeSwitcher`](?path=/docs/components-colorschemeswitcher--docs), so this component
+runs unchanged in any runtime — a plain React app wires `onCycle` to `useState`, an Electron
+or React-Native host wires it to `useColorScheme` with its own resolver.
+
+<Canvas of={ColorSchemeToggleStories.Default} />
+
+## Props
+
+<Controls />
+
+## `mode` vs scheme
+
+`mode` is the three-way user preference — `"light" | "dark" | "system"`. It is **not** a
+`data-scheme` value: `data-scheme` only ever holds `"light"` or `"dark"`. Resolving
+`system` to a concrete scheme is the connected layer's job, not this one's.
+
+## Icons are yours
+
+The library ships **no icons**
+([decision](?path=/docs/foundations-decisions--docs)) — `icons` is a `ReactNode` per mode,
+and an app passes lucide `Sun` / `Moon` / `Monitor` (the fleet recommendation). The glyph is
+`aria-hidden`; the button's name comes from `label`, which states the current mode so the
+control is agent-drivable and a screen reader that lands on it hears "Colour scheme: system"
+rather than a nameless button.
+
+<Canvas of={ColorSchemeToggleStories.AllModes} />
+
+## Cycling is the only form, for now
+
+A segmented, all-three-visible `ColorSchemePicker` was considered and deferred (owner chose
+cycling-only, 2026-08-03). `icons` and `order` are shaped so that form can be added later
+without changing this API.
+
+<Canvas of={ColorSchemeToggleStories.Sizes} />

package/src/ColorSchemeToggle/ColorSchemeToggle.stories.tsx

@@ -0,0 +1,161 @@
+import type { ColorSchemeMode } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import {
+  MonitorIcon,
+  MoonIcon,
+  SunIcon,
+} from "../icons.storyHelpers.tsx"
+import type { ColorSchemeIcons } from "./ColorSchemeToggle.tsx"
+import { ColorSchemeToggle } from "./ColorSchemeToggle.tsx"
+
+/**
+ * The library ships **no icons** — these are the story-only
+ * hand-drawn SVGs an app would replace with lucide `Sun` / `Moon` /
+ * `Monitor`.
+ */
+const ICONS: ColorSchemeIcons = {
+  dark: <MoonIcon />,
+  light: <SunIcon />,
+  system: <MonitorIcon />,
+}
+
+const meta = {
+  title: "Components/ColorSchemeToggle",
+  component: ColorSchemeToggle,
+  parameters: { layout: "padded" },
+  argTypes: {
+    // `mode` is `ColorSchemeMode` from @charcuterie/logic — a bare
+    // specifier docgen cannot enumerate, so it gets an explicit
+    // radio rather than falling through to the object control.
+    mode: {
+      control: "radio",
+      options: ["light", "dark", "system"],
+    },
+    size: controlSizeArgType,
+  },
+  args: {
+    appearance: "ghost",
+    icons: ICONS,
+    isDisabled: false,
+    mode: "system",
+    onCycle: () => {},
+    size: "md",
+  },
+} satisfies Meta<typeof ColorSchemeToggle>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * Controlled and self-contained: this story owns the mode in local
+ * state and advances it on each press, which is what a plain
+ * consumer wires up. `<ColorSchemeSwitcher>` wires the same
+ * `onCycle` to the `useColorScheme` hook instead.
+ *
+ * The accessible name states the current mode and the next one, so
+ * it changes as the button cycles — that is what the test asserts.
+ */
+export const Default: Story = {
+  render: (toggleProps) => {
+    const [mode, setMode] =
+      useState<ColorSchemeMode>("system")
+
+    return (
+      <ColorSchemeToggle
+        {...toggleProps}
+        mode={mode}
+        onCycle={setMode}
+      />
+    )
+  },
+}
+
+/**
+ * Each mode's icon, held fixed so the three glyphs are visible at
+ * once — light is the sun, dark the moon, system the monitor.
+ */
+export const AllModes: Story = {
+  render: (toggleProps) => (
+    <StorySection title="light → dark → system, the order a press cycles through.">
+      <StoryGrid columns={3}>
+        <StoryCell label="light">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="light"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+
+        <StoryCell label="dark">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="dark"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+
+        <StoryCell label="system">
+          <ColorSchemeToggle
+            {...toggleProps}
+            mode="system"
+            onCycle={() => {}}
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+export const Sizes: Story = {
+  render: (toggleProps) => (
+    <StorySection title="Square on the control height, so it lines up with the buttons beside it in a toolbar.">
+      <StoryRow>
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="light"
+          onCycle={() => {}}
+          size="sm"
+        />
+
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="dark"
+          onCycle={() => {}}
+          size="md"
+        />
+
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="system"
+          onCycle={() => {}}
+          size="lg"
+        />
+      </StoryRow>
+    </StorySection>
+  ),
+}
+
+export const Responsive: Story = {
+  render: (toggleProps) => (
+    <ContainerBoard>
+      <StoryRow>
+        <ColorSchemeToggle
+          {...toggleProps}
+          mode="system"
+          onCycle={() => {}}
+        />
+      </StoryRow>
+    </ContainerBoard>
+  ),
+}

package/src/ColorSchemeToggle/ColorSchemeToggle.test.tsx

@@ -0,0 +1,80 @@
+import { composeStories } from "@storybook/react"
+import { userEvent } 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 "./ColorSchemeToggle.stories.tsx"
+
+const { AllModes, Default } = composeStories(stories)
+
+/**
+ * The name states the current mode — a screen reader that lands on
+ * the control hears "Colour scheme: system", not a nameless button,
+ * and an agent can find it.
+ */
+test("the toggle is named for its current mode", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+})
+
+test("a press cycles the mode and updates the name", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const button = expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+
+  // system → light
+  await userEvent.click(button)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: light/i,
+    role: "button",
+  })
+
+  // light → dark
+  await userEvent.click(button)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: dark/i,
+    role: "button",
+  })
+})
+
+test("the icon is hidden from assistive tech; the name carries it", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme/i,
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("each mode renders its own control", async () => {
+  const { canvas } = await mountStory(AllModes)
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: light/i,
+    role: "button",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: dark/i,
+    role: "button",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: /colour scheme: system/i,
+    role: "button",
+  })
+})

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 />,
+  },
+}