@charcuterie/ui 1.0.1 → 2.0.0

package/src/Tooltip/Tooltip.mdx

@@ -45,15 +45,18 @@ instead of falling out of it.** Here `useRole` writes `aria-describedby` on the
 An `IconButton` under a tooltip still carries its own `aria-label`. `AllVariants` proves the
 button stays findable by the same query whether or not the tip is open.
 
-## No `popover` and no focus manager
-
-Unlike `Popover`, which is in the top layer and traps nothing. Focus never enters a tooltip
-— moving it there is what makes one inescapable — so there is no `FloatingFocusManager` and
-no `popover="manual"`.
-
-The trade is real and worth stating: a tooltip is therefore **not** in the top layer and can
-be clipped by an `overflow: hidden` ancestor. `strategy: "fixed"` keeps that to ancestors
-which actually clip fixed descendants.
+## Portalled, and no focus manager
+
+The tip renders in a `FloatingPortal` at `document.body` — the same reversal as the other
+overlays
+([decision](../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md)):
+`strategy: "fixed"` alone still let an `overflow: hidden` ancestor clip it, and a portal
+does not. `--layer-tooltip` keeps it above a modal.
+
+There is no `FloatingFocusManager`, unlike `Popover`. Focus never enters a tooltip — moving
+it there is what would make one inescapable — so the tip stays out of the focus manager and
+the overlay stack. A scoped query for the tip now reaches for `body`; `useRole` writes
+`aria-describedby` on the trigger, so the link survives the boundary.
 
 <Canvas of={TooltipStories.AllStates} />
 

package/src/Tooltip/Tooltip.test.tsx

@@ -11,7 +11,7 @@ const { AllVariants, Default, Interactive } =
   composeStories(stories)
 
 test("nothing is shown until something asks", async () => {
-  const { canvas, canvasElement } =
+  const { body, canvas, canvasElement } =
     await mountStory(Default)
 
   expectAgentDrivable(canvas, {
@@ -19,9 +19,9 @@ test("nothing is shown until something asks", async () => {
     role: "button",
   })
 
-  await expect(
-    canvas.queryAllByRole("tooltip"),
-  ).toHaveLength(0)
+  await expect(body.queryAllByRole("tooltip")).toHaveLength(
+    0,
+  )
 
   await expectNoAxeViolations(canvasElement)
 })
@@ -34,8 +34,7 @@ test("nothing is shown until something asks", async () => {
  * floating node nobody is pointed at.
  */
 test("the trigger is described by the tip that opened", async () => {
-  const { canvas, canvasElement } =
-    await mountStory(Interactive)
+  const { body, canvas } = await mountStory(Interactive)
 
   const trigger = expectAgentDrivable(canvas, {
     name: "Keyboard tip",
@@ -52,8 +51,10 @@ test("the trigger is described by the tip that opened", async () => {
     expect(trigger).toHaveFocus()
   })
 
+  // Portalled now, so found through `body`; the `aria-describedby`
+  // link survives the boundary.
   const tip = await waitFor(() =>
-    expectAgentDrivable(canvas, { role: "tooltip" }),
+    expectAgentDrivable(body, { role: "tooltip" }),
   )
 
   await expect(trigger).toHaveAttribute(
@@ -65,10 +66,7 @@ test("the trigger is described by the tip that opened", async () => {
     "Opened by focus, closed by Escape.",
   )
 
-  // Audited in the *driven* state, not at mount. The a11y addon
-  // runs axe once, when `run()` resolves — before anything has been
-  // focused — so an open tip would never be seen by it.
-  await expectNoAxeViolations(canvasElement)
+  await expectNoAxeViolations(tip)
 })
 
 /**
@@ -77,28 +75,28 @@ test("the trigger is described by the tip that opened", async () => {
  * failure on the one control whose explanation lives there.
  */
 test("focus opens it and blur closes it", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body } = await mountStory(Interactive)
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+    expect(body.queryAllByRole("tooltip")).toHaveLength(0)
   })
 })
 
 test("Escape dismisses it", async () => {
-  const { canvas } = await mountStory(Interactive)
+  const { body } = await mountStory(Interactive)
 
   await userEvent.tab()
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   // WCAG 1.4.13 requires content shown on hover or focus to be
@@ -106,7 +104,7 @@ test("Escape dismisses it", async () => {
   await userEvent.keyboard("{Escape}")
 
   await waitFor(() => {
-    expect(canvas.queryAllByRole("tooltip")).toHaveLength(0)
+    expect(body.queryAllByRole("tooltip")).toHaveLength(0)
   })
 })
 
@@ -117,7 +115,7 @@ test("Escape dismisses it", async () => {
  * whether or not the tip is open.
  */
 test("the tip does not become the control's name", async () => {
-  const { canvas } = await mountStory(AllVariants)
+  const { body, canvas } = await mountStory(AllVariants)
 
   const iconButton = expectAgentDrivable(canvas, {
     name: "Bay settings",
@@ -127,7 +125,7 @@ test("the tip does not become the control's name", async () => {
   await userEvent.hover(iconButton)
 
   await waitFor(() => {
-    expectAgentDrivable(canvas, { role: "tooltip" })
+    expectAgentDrivable(body, { role: "tooltip" })
   })
 
   // Still "Bay settings", not "Opens the bay's rip settings."

package/src/Tooltip/Tooltip.tsx

@@ -5,6 +5,7 @@ import {
 import type { Placement } from "@floating-ui/react"
 import {
   autoUpdate,
+  FloatingPortal,
   flip,
   offset,
   shift,
@@ -155,38 +156,40 @@ export const Tooltip = ({
       {clonedTrigger}
 
       {isVisible ? (
-        <div
-          {...getFloatingProps()}
-          className={toClassName(
-            // `intent-neutral-solid` + its own `on-solid`, rather
-            // than `surface-inverse` + `content-on-accent`. The
-            // second pair looks like the obvious one and is not a
-            // *pair* at all — nothing in the token set promises those
-            // two contrast, and in `daylight` dark they land at
-            // 2.9:1. The `solid`/`on-solid` roles exist precisely to
-            // be a guaranteed couple, and the contrast gate checks
-            // them as one.
-            "inset-auto m-0 max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
-            className,
-          )}
-          // No `popover="manual"` and no `FloatingFocusManager`,
-          // unlike `Popover`. Both exist to manage focus, and focus
-          // never enters a tooltip — moving it here is what makes
-          // one unescapable. The trade is that a tooltip is not in
-          // the top layer, so it can be clipped by an
-          // `overflow: hidden` ancestor; `strategy: "fixed"` keeps
-          // that to ancestors that actually clip fixed descendants.
-          ref={refs.setFloating}
-          // Duplicated from `getFloatingProps()` deliberately, and
-          // the two cannot differ — `useRole(context, { role:
-          // "tooltip" })` above is where it comes from. Stated here
-          // because a linter cannot see a role through a spread, and
-          // neither can the next reader.
-          role="tooltip"
-          style={floatingStyles}
-        >
-          {label}
-        </div>
+        <FloatingPortal>
+          <div
+            {...getFloatingProps()}
+            className={toClassName(
+              // `intent-neutral-solid` + its own `on-solid`, rather
+              // than `surface-inverse` + `content-on-accent`. The
+              // second pair looks like the obvious one and is not a
+              // *pair* at all — nothing in the token set promises those
+              // two contrast, and in `daylight` dark they land at
+              // 2.9:1. The `solid`/`on-solid` roles exist precisely to
+              // be a guaranteed couple, and the contrast gate checks
+              // them as one.
+              "z-[var(--layer-tooltip)] max-w-xs rounded-md bg-intent-neutral-solid px-2 py-1 text-intent-neutral-on-solid text-xs shadow-medium",
+              className,
+            )}
+            // Portalled to `document.body`, the same reversal as the
+            // other overlays: `strategy: "fixed"` alone still let an
+            // `overflow: hidden` ancestor clip the tip, and a portal
+            // does not. No `FloatingFocusManager`, unlike `Popover` —
+            // focus never enters a tooltip, and moving it here is what
+            // would make one unescapable. `--layer-tooltip` keeps it
+            // above a modal.
+            ref={refs.setFloating}
+            // Duplicated from `getFloatingProps()` deliberately, and
+            // the two cannot differ — `useRole(context, { role:
+            // "tooltip" })` above is where it comes from. Stated here
+            // because a linter cannot see a role through a spread, and
+            // neither can the next reader.
+            role="tooltip"
+            style={floatingStyles}
+          >
+            {label}
+          </div>
+        </FloatingPortal>
       ) : null}
     </>
   )

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,15 @@ 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 { ComboboxProps } from "./Combobox/Combobox.tsx"
+export { Combobox } from "./Combobox/Combobox.tsx"
 export type { BadgeSize } from "./controlStyles.ts"
 export {
   BADGE_SIZE_CLASS,
@@ -61,6 +70,11 @@ export {
   MIN_TOUCH_TARGET_CLASS,
   SPINNER_SIZE_CLASS,
 } from "./controlStyles.ts"
+export type {
+  DialogProps,
+  DialogSize,
+} from "./Dialog/Dialog.tsx"
+export { Dialog } from "./Dialog/Dialog.tsx"
 export type {
   EmptyStateProps,
   EmptyStateSize,
@@ -83,6 +97,13 @@ 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 {
+  ListboxItem,
+  ListboxProps,
+} from "./Listbox/Listbox.tsx"
+export { Listbox } from "./Listbox/Listbox.tsx"
 export type {
   LiveStatusIndicatorProps,
   LiveStatusIndicatorSize,
@@ -105,10 +126,7 @@ export type {
   MenuProps,
 } from "./Menu/Menu.tsx"
 export { Menu } from "./Menu/Menu.tsx"
-export type {
-  ModalProps,
-  ModalSize,
-} from "./Modal/Modal.tsx"
+export type { ModalProps } from "./Modal/Modal.tsx"
 export { Modal } from "./Modal/Modal.tsx"
 export type { PopoverProps } from "./Popover/Popover.tsx"
 export { Popover } from "./Popover/Popover.tsx"

package/src/mountStory.testHelpers.ts

@@ -46,12 +46,26 @@ type MountableStory = {
  * The stale tree is removed rather than unmounted because portable
  * stories expose no unmount. Detaching is enough: it takes the node
  * out of the layout, which is the entire problem.
+ *
+ * ### Portalled panels leave the canvas
+ *
+ * Once the overlays portal to `document.body`, their panels are no
+ * longer inside `canvasElement`, and floating-ui's portal roots
+ * (`[data-floating-ui-portal]`) are body children a portable story
+ * never unmounts. A previous test's panel therefore lingers next to
+ * the live one, and `expectAgentDrivable(body, …)` fails with "2
+ * elements match" — the portal analogue of the fixed-position
+ * `ToastRegion` bug above. So the same cleanup that detaches stale
+ * canvases also removes stale portal roots, and `mountStory` now hands
+ * back `body` (scoped to `document.body`) for querying the panels the
+ * triggers still open from inside `canvas`.
  */
 const mountedCanvases: HTMLElement[] = []
 
 export const mountStory = async (
   story: MountableStory,
 ): Promise<{
+  body: Canvas
   canvas: Canvas
   canvasElement: HTMLElement
 }> => {
@@ -59,6 +73,12 @@ export const mountStory = async (
     previous.remove()
   }
 
+  for (const portalRoot of document.querySelectorAll(
+    "[data-floating-ui-portal]",
+  )) {
+    portalRoot.remove()
+  }
+
   const canvasElement = document.createElement("div")
 
   document.body.append(canvasElement)
@@ -67,5 +87,9 @@ export const mountStory = async (
 
   await story.run({ canvasElement })
 
-  return { canvas: within(canvasElement), canvasElement }
+  return {
+    body: within(document.body),
+    canvas: within(canvasElement),
+    canvasElement,
+  }
 }

package/src/sourceRules.test.ts

@@ -290,7 +290,17 @@ 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) — and `Lightbox`, the thumbnail-over-`Dialog` viewer —
+  // taking the count to 28.
+  //
+  // The M8 overlay rebuild renames the old chrome-bearing `Modal` to
+  // `Dialog` and reintroduces `Modal` as the base layer, so both are
+  // components: +1 → 29. The picker family adds `Listbox` (single-select)
+  // and `Combobox` (searchable/virtualized): +2 → 31.
+  expect(componentNames.length).toBe(31)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)
@@ -364,6 +374,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,8 +393,16 @@ 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",
+      // `Combobox`'s virtualization — the second runtime dependency
+      // this package has ever taken. MIT, US-origin (Tanner Linsley),
+      // tree-shakeable, ~4 KB gz.
+      "@tanstack/react-virtual",
       "react",
     ],
     "./testing": [],

package/src/storyControls.test.ts

@@ -24,21 +24,32 @@ import { expect, test } from "vitest"
 const sourceDirectory = resolve(import.meta.dirname)
 
 const readComponent = async (name: string) => {
-  const [component, story] = await Promise.all([
-    readFile(
+  // A `<Name>/<Name>.tsx` is the component-folder signal. An
+  // uppercase folder without one — `Overlay/`, which holds the shared
+  // portal/backdrop/anchoring infrastructure and no storied component
+  // — is not a component and is skipped, so this rule stays about the
+  // things that have a Controls panel to get wrong. A real component
+  // missing only its *story* still throws below, which is the guard.
+  let component: string
+
+  try {
+    component = await readFile(
       join(sourceDirectory, name, `${name}.tsx`),
       "utf8",
-    ),
-    readFile(
-      join(sourceDirectory, name, `${name}.stories.tsx`),
-      "utf8",
-    ),
-  ])
+    )
+  } catch {
+    return null
+  }
+
+  const story = await readFile(
+    join(sourceDirectory, name, `${name}.stories.tsx`),
+    "utf8",
+  )
 
   return { component, name, story }
 }
 
-const componentNames = (
+const componentDirectories = (
   await readdir(sourceDirectory, { withFileTypes: true })
 )
   .filter(
@@ -48,9 +59,11 @@ const componentNames = (
   .map((entry) => entry.name)
   .sort()
 
-const components = await Promise.all(
-  componentNames.map(readComponent),
-)
+const components = (
+  await Promise.all(componentDirectories.map(readComponent))
+).filter((one) => one !== null)
+
+const componentNames = components.map((one) => one.name)
 
 /**
  * `import type { A, B } from "@scope/pkg"` — bare specifiers only.

package/dist/Modal/lockScrollBehind.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"lockScrollBehind.d.ts","sourceRoot":"","sources":["../../src/Modal/lockScrollBehind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,eAAO,MAAM,gBAAgB,QAAO,CAAC,MAAM,IAAI,CAiC9C,CAAA"}

package/dist/Modal/lockScrollBehind.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"lockScrollBehind.js","sourceRoot":"","sources":["../../src/Modal/lockScrollBehind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,IAAI,SAAS,GAAG,CAAC,CAAA;AAEjB,IAAI,gBAAgB,GAAG,EAAE,CAAA;AAEzB,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAiB,EAAE;IACjD,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAAA;IAEpC,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,gBAAgB,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAA;QAEjD,eAAe,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC3C,CAAC;IAED,SAAS,IAAI,CAAC,CAAA;IAEd,IAAI,UAAU,GAAG,KAAK,CAAA;IAEtB,OAAO,GAAG,EAAE;QACV,6DAA6D;QAC7D,6DAA6D;QAC7D,qCAAqC;QACrC,IAAI,UAAU,EAAE,CAAC;YACf,OAAM;QACR,CAAC;QAED,UAAU,GAAG,IAAI,CAAA;QAEjB,SAAS,IAAI,CAAC,CAAA;QAEd,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;YACpB,eAAe,CAAC,KAAK,CAAC,QAAQ,GAAG,gBAAgB,CAAA;QACnD,CAAC;IACH,CAAC,CAAA;AACH,CAAC,CAAA"}