@charcuterie/ui 2.4.0 → 2.5.0

package/src/Switch/Switch.test.tsx

@@ -0,0 +1,86 @@
+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 "./Switch.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("it is a switch a screen reader can name and read", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Automatic imports",
+    role: "switch",
+  })
+
+  // `aria-checked`, not `aria-pressed`: a switch announces "off",
+  // where a toggle button would announce "not pressed". The role is
+  // the whole reason to reach for this over a `Checkbox`.
+  await expect(control).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("Space flips it, and flips it back", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Automatic imports",
+    role: "switch",
+  })
+
+  control.focus()
+
+  await userEvent.keyboard(" ")
+
+  await waitFor(() => {
+    expect(control).toHaveAttribute("aria-checked", "true")
+  })
+
+  await userEvent.keyboard(" ")
+
+  await waitFor(() => {
+    expect(control).toHaveAttribute("aria-checked", "false")
+  })
+})
+
+test("a disabled switch cannot be flipped", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const control = expectAgentDrivable(canvas, {
+    name: "Disabled",
+    role: "switch",
+  })
+
+  await expect(control).toBeDisabled()
+
+  await userEvent.click(control)
+
+  await expect(control).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("isChecked decides the first render", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "On",
+      role: "switch",
+    }),
+  ).toHaveAttribute("aria-checked", "true")
+})

package/src/Switch/Switch.tsx

@@ -0,0 +1,162 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { ControlSize } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type SwitchProps = {
+  className?: string
+  /**
+   * **Initial** only. The `Switch` owns it from then on — the same
+   * uncontrolled contract as `Checkbox` and `SegmentedControl`, so
+   * `onChange` reports the new state and there is no controlled
+   * `checked` prop to keep in step.
+   */
+  isChecked?: boolean
+  isDisabled?: boolean
+  /** The visible text, and the switch's accessible name. */
+  label: ReactNode
+  onChange?: (isChecked: boolean) => void
+  size?: ControlSize
+}
+
+// Track and thumb are sized so `p-1` (4px) breathes evenly on every
+// side and the thumb is centred by arithmetic, not by eye: inner
+// height (track − 2·padding) equals the thumb, and the on-translate is
+// (track width − 2·padding − thumb). Break one of those and the thumb
+// clips an edge, which is what the first cut did.
+const TRACK_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "h-5 w-9",
+  md: "h-6 w-11",
+  lg: "h-7 w-14",
+}
+
+const THUMB_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "size-3",
+  md: "size-4",
+  lg: "size-5",
+}
+
+const THUMB_ON_TRANSLATE_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "translate-x-4",
+  md: "translate-x-5",
+  lg: "translate-x-7",
+}
+
+const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
+  sm: "text-sm",
+  md: "text-md",
+  lg: "text-lg",
+}
+
+/**
+ * A boolean that takes effect the moment it is flipped — a setting,
+ * not a form value.
+ *
+ * A `Checkbox` and a `Switch` are the same state kind and a
+ * different affordance, and the split is meaning rather than looks:
+ * a checkbox is a value you submit ("I agree"), a switch is a state
+ * you toggle and live with immediately ("dark mode on"). ARIA gives
+ * the second its own role, and a screen reader announces "on/off"
+ * for a `switch` where it announces "checked/unchecked" for a
+ * checkbox.
+ *
+ * ### A `button role="switch"`, not an `input`
+ *
+ * The sliding track and thumb are the whole point of the affordance,
+ * and a `<button>` styles them without fighting a native control's
+ * own rendering. It carries `aria-checked`, `aria-labelledby`, and
+ * nothing else the browser would try to own. The value lives in
+ * React state seeded once from `isChecked` — the switch is the
+ * store, the same as the DOM is for `Checkbox`.
+ *
+ * ### The thumb is one colour, the track carries the state
+ *
+ * `bg-surface-raised` in both positions — the knob is the same object
+ * sliding, not two differently-painted dots, which is what the first
+ * cut looked like when off was `content-secondary` and on was
+ * `on-solid`. A themed system has no single colour that is "light" in
+ * both schemes, so consistency lives *within* a scheme: `surface-raised`
+ * is a white knob in a light one and a raised charcoal knob in a dark
+ * one, off and on identical either way. The **track** shows the state —
+ * `bg-intent-accent-solid` on, `bg-surface-sunken` with a `ring-2`
+ * outline off — which is where a switch's state belongs, and the ring
+ * gives the off track the defined edge a bare well would miss on a pale
+ * theme.
+ */
+export const Switch = ({
+  className,
+  isChecked = false,
+  isDisabled = false,
+  label,
+  onChange,
+  size = "md",
+}: SwitchProps): ReactNode => {
+  const [isOn, setIsOn] = useState(isChecked)
+
+  const labelId = useUniqueId()
+
+  return (
+    <span
+      className={toClassName(
+        "inline-flex items-center gap-2 text-content-secondary select-none",
+        TEXT_SIZE_CLASS[size],
+        isDisabled && "text-content-disabled",
+        className,
+      )}
+    >
+      <button
+        aria-checked={isOn}
+        aria-labelledby={labelId}
+        className={toClassName(
+          // `p-1` is the breathing room; `ring-inset` draws the off
+          // outline without changing the box size, so the centring
+          // arithmetic above stays exact.
+          "inline-flex shrink-0 cursor-pointer items-center rounded-full p-1 transition-colors duration-(--duration-fast) ease-standard",
+          // One state class, chosen by ternary — two `bg-`/`ring-`
+          // utilities of the same specificity do not resolve by
+          // class-list order, so disabled has to win as the only one
+          // written.
+          isDisabled
+            ? "cursor-not-allowed bg-surface-sunken ring-2 ring-border-subtle ring-inset"
+            : isOn
+              ? "bg-intent-accent-solid"
+              : "bg-surface-sunken ring-2 ring-border-strong ring-inset",
+          TRACK_SIZE_CLASS[size],
+          FOCUS_RING_CLASS,
+        )}
+        disabled={isDisabled}
+        onClick={() => {
+          const isNextOn = !isOn
+
+          setIsOn(isNextOn)
+
+          onChange?.(isNextOn)
+        }}
+        role="switch"
+        type="button"
+      >
+        <span
+          className={toClassName(
+            "rounded-full transition-transform duration-(--duration-fast) ease-standard",
+            // One knob, same colour off and on; disabled mutes it.
+            isDisabled
+              ? "bg-content-disabled"
+              : "bg-surface-raised",
+            isOn
+              ? THUMB_ON_TRANSLATE_CLASS[size]
+              : "translate-x-0",
+            THUMB_SIZE_CLASS[size],
+          )}
+        />
+      </button>
+
+      <span id={labelId}>{label}</span>
+    </span>
+  )
+}

package/src/index.ts

@@ -52,6 +52,8 @@ export type {
   CardSurface,
 } from "./Card/Card.tsx"
 export { Card } from "./Card/Card.tsx"
+export type { CheckboxProps } from "./Checkbox/Checkbox.tsx"
+export { Checkbox } from "./Checkbox/Checkbox.tsx"
 export type { ColorSchemeSwitcherProps } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
 export { ColorSchemeSwitcher } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"
 export type {
@@ -141,6 +143,11 @@ export {
   toProgressPercent,
   toProgressValue,
 } from "./ProgressBar/progressValue.ts"
+export type {
+  RadioGroupProps,
+  RadioItem,
+} from "./RadioGroup/RadioGroup.tsx"
+export { RadioGroup } from "./RadioGroup/RadioGroup.tsx"
 export type {
   SegmentedControlProps,
   SegmentedItem,
@@ -171,6 +178,8 @@ export type {
   SwatchSize,
 } from "./Swatch/Swatch.tsx"
 export { Swatch } from "./Swatch/Swatch.tsx"
+export type { SwitchProps } from "./Switch/Switch.tsx"
+export { Switch } from "./Switch/Switch.tsx"
 export type { SlotProps } from "./slotProps.ts"
 export { mergeSlotProps } from "./slotProps.ts"
 export {

package/src/slotWiring.ts

@@ -15,116 +15,24 @@
  *    a CSS bug and is not one.
  *  - **`on*`** is a listener, and listeners are plural.
  *
- * ### Why this is not imported from `@charcuterie/logic`
+ * ### Shared with `@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`.
+ * `useClonedChild`'s `mergeClonedProps` applies the identical rule
+ * one level down — between a slot and the element a caller wrote —
+ * so the `ref`/`on*` primitives (`mergeRefs`, `chainHandlers`, and
+ * the two guards) are imported from `@charcuterie/logic` rather than
+ * copied here, where they used to be a byte-for-byte duplicate. Only
+ * `mergeSlotWiring` stays local: it merges the *other* direction
+ * (own over received) and returns just the wiring keys, which is a
+ * different function from `mergeClonedProps`.
  */
 
-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)
-  }
+import {
+  chainHandlers,
+  isEventHandlerName,
+  isMergeableRef,
+  mergeRefs,
+} from "@charcuterie/logic"
 
 /**
  * The keys of `ownProps` that must not simply replace the ones

package/src/sourceRules.test.ts

@@ -303,7 +303,17 @@ test("the barrel is the only place components are re-exported", async () => {
   // `Swatch` — a colour as content with a required name, the one
   // colour the system does not own — comes out of `portly-controllers`,
   // the fleet's newest consumer: +1 -> 32.
-  expect(componentNames.length).toBe(32)
+  //
+  // The boolean-input family fills the gap `mux-magic`'s `BooleanField`
+  // hand-rolled around: `Checkbox` and `Switch` (the same state kind,
+  // a submitted value versus a setting that takes effect on flip) and
+  // `RadioGroup` (the stacked sibling of `SegmentedControl`, same
+  // `SinglePicker` + `RovingFocus` composition): +3 -> 35.
+  // `RadioGroupOption` is `RadioGroup`'s member — its own file only
+  // because both registrations are effects — and stays out of this
+  // count and the barrel by the `<Name>/<Name>.tsx` rule, exactly as
+  // `SegmentedOption` does.
+  expect(componentNames.length).toBe(35)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/tailwindCandidates.test.ts

@@ -256,16 +256,18 @@ test("this package has class names to check at all", () => {
 })
 
 /**
- * The two class names in this package that are deliberately not
+ * The class names in this package that are deliberately not
  * utilities.
  *
- * `group` is Tailwind's own marker — it generates no CSS by design,
- * it is what `group-hover:` reads. The `charcuterie-*` four are the
- * looping affordances, which cannot be utilities because Tailwind's
- * own `animate-spin` hardcodes 1s past `prefers-reduced-motion`;
- * they live in `styles.css` and are checked against it below.
+ * `group` and `peer` are Tailwind's own markers — they generate no
+ * CSS by design, they are what `group-hover:` and `peer-checked:`
+ * read (`Checkbox` overlays its tick with `peer-checked:visible`).
+ * The `charcuterie-*` four are the looping affordances, which cannot
+ * be utilities because Tailwind's own `animate-spin` hardcodes 1s
+ * past `prefers-reduced-motion`; they live in `styles.css` and are
+ * checked against it below.
  */
-const TAILWIND_MARKER_CLASSES = ["group"]
+const TAILWIND_MARKER_CLASSES = ["group", "peer"]
 
 test("every `charcuterie-` class a component uses is defined in styles.css", async () => {
   // The other half of the "no silently-unstyled component" gate. A