@charcuterie/ui 1.0.0 → 1.1.0

package/src/Menu/Menu.test.tsx

@@ -7,8 +7,12 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Menu.stories.tsx"
 
-const { AllStates, AllVariants, Interactive } =
-  composeStories(stories)
+const {
+  AllStates,
+  AllVariants,
+  Interactive,
+  SharedTrigger,
+} = composeStories(stories)
 
 test("the menu is named, and its items are menuitems", async () => {
   const { canvas, canvasElement } =
@@ -200,3 +204,110 @@ test("the menu is not portalled out of its canvas", async () => {
 
   await expectNoAxeViolations(canvasElement)
 })
+
+/**
+ * **One trigger, two slots** — the defect image-viewer reported, and
+ * the one shape `mergeSlotProps` did not cover when it shipped in
+ * 1.0.0.
+ *
+ * `Menu` and `Tooltip` both clone onto the button and both hand it a
+ * floating-ui `refs.setReference`. That is not an attribute, so
+ * last-write-wins destroyed one of them: the inner `Tooltip` wrote
+ * its own and the `Menu` was left with **no reference element at
+ * all**. Nothing threw, nothing was unnamed, axe was clean, and the
+ * panel rendered at `left: 0; top: 0` — a positioning bug that reads
+ * as CSS.
+ *
+ * So the assertion is geometric, and it is the only kind that can
+ * see this: the panel is where the trigger is. Nothing in `Menu`
+ * writes that number — floating-ui computes it from the reference
+ * element, and a dropped ref means no reference element.
+ */
+const expectAnchoredTrigger = (trigger: HTMLElement) => {
+  const triggerRect = trigger.getBoundingClientRect()
+
+  // The precondition, stated rather than assumed. An unanchored
+  // panel lands at the viewport origin, so a trigger that also sits
+  // at the origin makes every assertion below pass for the wrong
+  // reason. The story's padding is what keeps them apart, and this
+  // is where its removal fails.
+  expect(triggerRect.left).toBeGreaterThan(32)
+
+  expect(triggerRect.top).toBeGreaterThan(32)
+
+  return triggerRect
+}
+
+test("a menu sharing its trigger with a tooltip is still anchored to it", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(SharedTrigger)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Bay 5",
+    role: "button",
+  })
+
+  const triggerRect = expectAnchoredTrigger(trigger)
+
+  await userEvent.click(trigger)
+
+  const menu = await waitFor(() =>
+    expectAgentDrivable(canvas, { role: "menu" }),
+  )
+
+  // `bottom-start` with `offset(4)`: flush with the trigger's
+  // inline start, four pixels below it. Before the fix this read
+  // `left 0, top 0` — and it read that *forever*, so waiting for it
+  // costs a timeout rather than hiding a failure. The wait is for
+  // floating-ui's first position, which lands a frame after the
+  // panel does.
+  await waitFor(() => {
+    const menuRect = menu.getBoundingClientRect()
+
+    expect(Math.round(menuRect.left)).toBe(
+      Math.round(triggerRect.left),
+    )
+
+    expect(Math.round(menuRect.top)).toBe(
+      Math.round(triggerRect.bottom) + 4,
+    )
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The other ref, in the same composition — because a fix that
+ * reversed the priority instead of merging would leave *this* one
+ * pointing at nothing and the test above would still pass.
+ */
+test("the tooltip sharing that trigger is anchored to it too", async () => {
+  const { canvas } = await mountStory(SharedTrigger)
+
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Bay 5",
+    role: "button",
+  })
+
+  const triggerRect = expectAnchoredTrigger(trigger)
+
+  trigger.focus()
+
+  const tip = await waitFor(() =>
+    expectAgentDrivable(canvas, { role: "tooltip" }),
+  )
+
+  // The **main axis** only: `top` with `offset(6)`. The cross axis
+  // is not asserted because `shift({ padding: 8 })` legitimately
+  // moves it — a 229px tip over a 71px button cannot be centred
+  // this close to the edge — and an assertion that has to allow for
+  // that is one an unanchored tip at the viewport origin would also
+  // satisfy. This one it cannot: unanchored reads `bottom 24`.
+  await waitFor(() => {
+    const tipRect = tip.getBoundingClientRect()
+
+    expect(Math.round(tipRect.bottom)).toBe(
+      Math.round(triggerRect.top) - 6,
+    )
+  })
+})

package/src/Popover/Popover.mdx

@@ -85,6 +85,11 @@ announces nothing.
 have. An extra `<div>` around it is how a toolbar's layout quietly changes, and it is why
 this is the pattern v1 chose and M2 ported.
 
+It **composes** rather than overwrites: your button's own `ref` and its own `onClick` are
+still called, with the popover's added. Until 1.0.1 they were replaced — silently, because a
+ref that is never called and a handler that never runs both look exactly like nothing
+happening.
+
 ## Escape *is* pressable here
 
 Unlike `Modal`'s. `useDismiss` listens for a keydown rather than relying on a UA default

package/src/Select/Select.stories.tsx

@@ -9,11 +9,19 @@ import { Field } from "../Field/Field.tsx"
 import type { SelectItem } from "./Select.tsx"
 import { Select } from "./Select.tsx"
 
-const PROFILES: SelectItem[] = [
+/**
+ * `as const satisfies`, which is a **typecheck** of the `readonly`
+ * widening as much as it is a story: a consumer's options table is
+ * usually a constant, and until 1.0.1 handing one to `options`
+ * failed with `TS4104` — image-viewer copied the array at every call
+ * site to get past it. If that widening is ever reverted, this line
+ * is where `yarn typecheck` says so.
+ */
+const PROFILES = [
   { label: "Lossless remux", value: "lossless" },
   { label: "Compressed 1080p", value: "compressed" },
   { isDisabled: true, label: "Dolby Vision", value: "dv" },
-]
+] as const satisfies readonly SelectItem[]
 
 const GROUPED: SelectItem[] = [
   {

package/src/Select/Select.tsx

@@ -23,7 +23,7 @@ export type SelectOption = {
 
 export type SelectOptionGroup = {
   label: string
-  options: SelectOption[]
+  options: readonly SelectOption[]
 }
 
 export type SelectItem = SelectOption | SelectOptionGroup
@@ -56,7 +56,15 @@ export type SelectProps = Omit<
    */
   label?: string
   onChange?: (value: string) => void
-  options: SelectItem[]
+  /**
+   * `readonly`, because a caller's list is usually a constant and
+   * TypeScript will not hand a `readonly` array to a mutable
+   * parameter — image-viewer hit `TS4104` on an `as const` options
+   * table and had to spread a copy at every call. This component
+   * only ever `.map`s over it, so demanding a mutable array was
+   * asking for a permission it never uses.
+   */
+  options: readonly SelectItem[]
   /**
    * A disabled first entry, not a real option. Reads as a prompt to
    * a sighted user and cannot be submitted, which is what a

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/slotProps.ts

@@ -1,5 +1,7 @@
 import type { InputHTMLAttributes } from "react"
 
+import { mergeSlotWiring } from "./slotWiring.ts"
+
 /**
  * The props a **cloning ancestor** injects into the control below it.
  *
@@ -114,6 +116,17 @@ export type SlotProps = Pick<
  * `isRequired || undefined`, so a plain spread would let an inner
  * `Field` with no error erase an outer one's `aria-invalid` — the
  * same silent drop, one level down.
+ *
+ * ### The wiring is not a value, and does not last-write-win
+ *
+ * `ref` and the `on*` handlers are merged rather than replaced, by
+ * `mergeSlotWiring`. This was the 1.0.0 hole: `mergeSlotProps`
+ * settled the five *attributes* and left the two props that are not
+ * attributes on last-write-wins, so a `Menu` and a `Tooltip` on one
+ * trigger each handed it a floating-ui `refs.setReference` and the
+ * inner one won. The outer panel had no anchor and rendered in the
+ * corner of the viewport — no error, no failing test, and it looks
+ * like a CSS bug.
  */
 export const mergeSlotProps = <
   OwnProps extends Record<string, unknown>,
@@ -139,5 +152,12 @@ export const mergeSlotProps = <
     ...definedOwnProps,
     "aria-describedby":
       describedBy === "" ? undefined : describedBy,
+    // Last, because it is the only merge that has to beat
+    // `definedOwnProps` — it is composing what that spread would
+    // otherwise have thrown away.
+    ...mergeSlotWiring(
+      receivedProps as Record<string, unknown>,
+      definedOwnProps,
+    ),
   }
 }

package/src/slotWiring.ts

@@ -0,0 +1,173 @@
+/**
+ * The two props a slot may not overwrite, and how it merges them.
+ *
+ * `mergeSlotProps` next door settles the five *attributes* two
+ * nested slots both write, and last-write-wins is right for four of
+ * them. It is not right for the wiring, because neither of these is
+ * a value:
+ *
+ *  - **`ref`** is a subscription. `Menu` and `Tooltip` on one trigger
+ *    both hand it a floating-ui `refs.setReference` — the anchor each
+ *    of them positions its panel against — and the inner one used to
+ *    replace the outer one's. Nothing threw. The outer panel simply
+ *    had no reference element, so floating-ui left it at
+ *    `left: 0; top: 0` in the corner of the viewport, which reads as
+ *    a CSS bug and is not one.
+ *  - **`on*`** is a listener, and listeners are plural.
+ *
+ * ### Why this is not imported from `@charcuterie/logic`
+ *
+ * `useClonedChild`'s `mergeClonedProps` applies the same rule one
+ * level down — between a slot and the element a caller wrote — and
+ * the two are near-identical. Sharing them means a new public export
+ * on `@charcuterie/logic`, which is a `minor`; this is a patch, and
+ * the duplication is thirty lines against a wrong version number.
+ * Queued in `docs/2026-08-02-reported-by-consumers-queued-for-1-1.md`.
+ */
+
+const isEventHandlerName = (name: string) =>
+  /^on[A-Z]/.test(name)
+
+type MergeableRef =
+  | ((node: unknown) => unknown)
+  | { current: unknown }
+
+const isMergeableRef = (
+  value: unknown,
+): value is MergeableRef =>
+  typeof value === "function" ||
+  (typeof value === "object" &&
+    value !== null &&
+    "current" in value)
+
+const setRef = (ref: MergeableRef, node: unknown) => {
+  if (typeof ref === "function") {
+    return ref(node)
+  }
+
+  ref.current = node
+
+  return undefined
+}
+
+/**
+ * Every pair of refs ever merged, so the same two always come back
+ * as the **same function** — which is load-bearing rather than
+ * frugal.
+ *
+ * React re-runs a callback ref whenever its identity changes between
+ * renders, detaching with the old one and attaching with the new.
+ * Both refs here are floating-ui `setReference`s, and calling one
+ * sets state; a merged ref rebuilt every render would call both
+ * twice per render, each call scheduling the render that rebuilds
+ * it. `mergeSlotProps` is a plain function called during render, so
+ * it cannot reach for `useMemo` — the memo has to be in the identity
+ * of the inputs, which is what a `WeakMap` of `WeakMap`s is.
+ */
+const mergedRefs = new WeakMap<
+  MergeableRef,
+  WeakMap<MergeableRef, (node: unknown) => () => void>
+>()
+
+const mergeRefs = (
+  first: MergeableRef,
+  second: MergeableRef,
+) => {
+  const bySecond =
+    mergedRefs.get(first) ??
+    new WeakMap<
+      MergeableRef,
+      (node: unknown) => () => void
+    >()
+
+  mergedRefs.set(first, bySecond)
+
+  const cached = bySecond.get(second)
+
+  if (cached) {
+    return cached
+  }
+
+  const merged = (node: unknown) => {
+    const cleanups = [
+      setRef(first, node),
+      setRef(second, node),
+    ]
+
+    // Per ref: one that returned a cleanup has opted out of being
+    // called with `null`, and one that did not still expects it.
+    return () => {
+      for (const [index, cleanup] of cleanups.entries()) {
+        if (typeof cleanup === "function") {
+          cleanup()
+        } else {
+          setRef(index === 0 ? first : second, null)
+        }
+      }
+    }
+  }
+
+  bySecond.set(second, merged)
+
+  return merged
+}
+
+const chainHandlers =
+  (
+    first: (...args: unknown[]) => unknown,
+    second: (...args: unknown[]) => unknown,
+  ) =>
+  (...args: unknown[]) => {
+    // Outer first, the same order `aria-describedby` is joined in:
+    // the merge order is structural — whoever wrapped whom — and the
+    // author of the nesting is the one who chose it.
+    first(...args)
+
+    second(...args)
+  }
+
+/**
+ * The keys of `ownProps` that must not simply replace the ones
+ * `receivedProps` arrived with. Spread **last**, over both.
+ */
+export const mergeSlotWiring = (
+  receivedProps: Record<string, unknown>,
+  ownProps: Record<string, unknown>,
+): Record<string, unknown> =>
+  Object.fromEntries(
+    Object.entries(ownProps).flatMap(
+      ([name, ownValue]): [string, unknown][] => {
+        const receivedValue = receivedProps[name]
+
+        if (
+          name === "ref" &&
+          isMergeableRef(receivedValue) &&
+          isMergeableRef(ownValue)
+        ) {
+          return [
+            [name, mergeRefs(receivedValue, ownValue)],
+          ]
+        }
+
+        if (
+          isEventHandlerName(name) &&
+          typeof receivedValue === "function" &&
+          typeof ownValue === "function"
+        ) {
+          return [
+            [
+              name,
+              chainHandlers(
+                receivedValue as (
+                  ...args: unknown[]
+                ) => unknown,
+                ownValue as (...args: unknown[]) => unknown,
+              ),
+            ],
+          ]
+        }
+
+        return []
+      },
+    ),
+  )

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",