@charcuterie/ui 1.0.1 → 1.1.0

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/icons.storyHelpers.tsx

@@ -104,6 +104,28 @@ export const ImageOffIcon = (): ReactNode => (
   </svg>
 )
 
+export const SunIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <circle cx="12" cy="12" r="4" />
+
+    <path d="M12 2v2M12 20v2M4 12H2M22 12h-2M5.6 5.6 4.2 4.2M19.8 19.8l-1.4-1.4M18.4 5.6l1.4-1.4M4.2 19.8l1.4-1.4" />
+  </svg>
+)
+
+export const MoonIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M20 14.5A8 8 0 1 1 9.5 4a6.2 6.2 0 0 0 10.5 10.5z" />
+  </svg>
+)
+
+export const MonitorIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <rect height="12" rx="2" width="18" x="3" y="4.5" />
+
+    <path d="M8 20.5h8M12 16.5v4" />
+  </svg>
+)
+
 export const DotIcon = (): ReactNode => (
   <svg
     {...iconProps}

package/src/index.ts

@@ -52,6 +52,13 @@ export type {
   CardSurface,
 } from "./Card/Card.tsx"
 export { Card } from "./Card/Card.tsx"
+export type { ColorSchemeSwitcherProps } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
+export { ColorSchemeSwitcher } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
+export type {
+  ColorSchemeIcons,
+  ColorSchemeToggleProps,
+} from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
+export { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
 export type { BadgeSize } from "./controlStyles.ts"
 export {
   BADGE_SIZE_CLASS,
@@ -83,6 +90,8 @@ export {
   INTENT_HOVER_CLASS,
   INTENT_SOLID_FILL_CLASS,
 } from "./intentStyles.ts"
+export type { LightboxProps } from "./Lightbox/Lightbox.tsx"
+export { Lightbox } from "./Lightbox/Lightbox.tsx"
 export type {
   LiveStatusIndicatorProps,
   LiveStatusIndicatorSize,

package/src/sourceRules.test.ts

@@ -290,7 +290,12 @@ test("the barrel is the only place components are re-exported", async () => {
   // directory because a region with no toasts in it is not a thing
   // anybody renders. It is therefore outside this count by the same
   // rule, and the barrel assertion below does not reach it.
-  expect(componentNames.length).toBe(25)
+  //
+  // 2026-08-03 adds the two colour-scheme controls — `ColorSchemeToggle`
+  // (Layer 2, presentational) and `ColorSchemeSwitcher` (Layer 3,
+  // connected) — plus `Lightbox` (landed the same day on its own
+  // branch), taking the count to 28.
+  expect(componentNames.length).toBe(28)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)
@@ -364,6 +369,13 @@ const ENTRY_POINT_RUNTIMES: Record<
 > = {
   logic: {
     ".": ["react"],
+    // The DOM defaults for `useColorScheme`. It reaches no bare
+    // specifier at all: `matchMedia`/`localStorage`/`document` are
+    // globals, not imports, and its only imports are type-only ones
+    // into `core` — which is why `ColorSchemeApplier` lives in the
+    // core rather than beside the hook, so this entry never pulls
+    // `react`.
+    "./browser": [],
     "./core": [],
     "./jotai": ["jotai"],
     "./preact": ["preact", "preact/hooks"],
@@ -376,6 +388,10 @@ const ENTRY_POINT_RUNTIMES: Record<
   ui: {
     ".": [
       "@charcuterie/logic",
+      // `ColorSchemeSwitcher` is the one component that reaches the
+      // browser, and it does so through this subpath so the coupling
+      // is named rather than smuggled in through the main entry.
+      "@charcuterie/logic/browser",
       "@charcuterie/tokens",
       "@floating-ui/react",
       "react",