@charcuterie/ui 2.4.1 → 2.6.0

package/src/Switch/Switch.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { controlSizeArgType } from "../argTypes.storyHelpers.ts"
+import {
+  StoryCell,
+  StoryGrid,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Switch } from "./Switch.tsx"
+
+const meta = {
+  title: "Components/Switch",
+  component: Switch,
+  parameters: { layout: "padded" },
+  argTypes: { size: controlSizeArgType },
+  // The component's own defaults, restated — Storybook does not seed
+  // `args` from docgen, so an unstated default shows in the props
+  // table with nothing selected in its control.
+  args: {
+    isChecked: false,
+    isDisabled: false,
+    isReadOnly: false,
+    size: "md",
+  },
+} satisfies Meta<typeof Switch>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Automatic imports" },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Automatic imports" },
+  render: (controlProps) => (
+    <StorySection title="Three control heights, all reading the density axis rather than hardcoding a length.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell key={size} label={size}>
+            <Switch
+              {...controlProps}
+              isChecked
+              label={`On at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * The thumb changes colour as well as position, so the state reads at
+ * a glance in `daylight` sunlight — a thumb that only moved would not.
+ */
+export const AllStates: Story = {
+  args: { label: "Automatic imports" },
+  render: (controlProps) => (
+    <StorySection title="What varies is whether the switch is on and whether it can be changed.">
+      <StoryGrid columns={2}>
+        <StoryCell label="off">
+          <Switch {...controlProps} label="Off" />
+        </StoryCell>
+
+        <StoryCell label="on">
+          <Switch {...controlProps} isChecked label="On" />
+        </StoryCell>
+
+        <StoryCell label="disabled, off">
+          <Switch
+            {...controlProps}
+            isDisabled
+            label="Disabled"
+          />
+        </StoryCell>
+
+        <StoryCell label="disabled, on">
+          <Switch
+            {...controlProps}
+            isChecked
+            isDisabled
+            label="Disabled and on"
+          />
+        </StoryCell>
+
+        <StoryCell label="read-only, off">
+          <Switch
+            {...controlProps}
+            isReadOnly
+            label="Read-only"
+          />
+        </StoryCell>
+
+        <StoryCell label="read-only, on">
+          <Switch
+            {...controlProps}
+            isChecked
+            isReadOnly
+            label="Read-only and on"
+          />
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
+/**
+ * A `button role="switch"`, so its keyboard path is the button's:
+ * Tab reaches it, Space and Enter flip it.
+ */
+export const Interactive: Story = {
+  args: { label: "Automatic imports" },
+}

package/src/Switch/Switch.test.tsx

@@ -0,0 +1,115 @@
+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")
+})
+
+test("a read-only switch is announced and cannot be flipped", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  const readOnly = expectAgentDrivable(canvas, {
+    name: "Read-only",
+    role: "switch",
+  })
+
+  await expect(readOnly).toHaveAttribute(
+    "aria-readonly",
+    "true",
+  )
+
+  await expect(readOnly).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  await userEvent.click(readOnly)
+
+  await expect(readOnly).toHaveAttribute(
+    "aria-checked",
+    "false",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Switch/Switch.tsx

@@ -0,0 +1,183 @@
+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
+  /**
+   * Shows the state at full contrast but refuses to flip it — a
+   * setting you may read here and change elsewhere. Unlike
+   * `isDisabled` it does not dim, and it announces `aria-readonly`.
+   */
+  isReadOnly?: 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,
+  isReadOnly = 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],
+        // Disabled turns the whole control down with `opacity-60`, the
+        // same family treatment as `Checkbox` and `RadioGroup` — the
+        // track keeps its full-contrast state colour underneath.
+        isDisabled && "opacity-60",
+        className,
+      )}
+    >
+      <button
+        aria-checked={isOn}
+        aria-labelledby={labelId}
+        aria-readonly={isReadOnly || undefined}
+        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 items-center rounded-full p-1 transition-colors duration-(--duration-fast) ease-standard",
+          // The track carries the state at full contrast whether or not
+          // it is disabled; `opacity-60` on the wrapper does the dimming.
+          // Read-only swaps the accent for the neutral intent and softens
+          // the off outline — readable, plainly not an actionable accent,
+          // the same language as `Checkbox` and `RadioGroup`.
+          isReadOnly
+            ? isOn
+              ? "bg-intent-neutral-solid"
+              : "bg-surface-sunken ring-2 ring-border-default ring-inset"
+            : isOn
+              ? "bg-intent-accent-solid"
+              : "bg-surface-sunken ring-2 ring-border-strong ring-inset",
+          isDisabled
+            ? "cursor-not-allowed"
+            : isReadOnly
+              ? "cursor-default"
+              : "cursor-pointer",
+          TRACK_SIZE_CLASS[size],
+          FOCUS_RING_CLASS,
+        )}
+        disabled={isDisabled}
+        onClick={() => {
+          // Read-only shows the state but will not flip it — the switch
+          // owns its value, so the guard is just an early return.
+          if (isReadOnly) {
+            return
+          }
+
+          const isNextOn = !isOn
+
+          setIsOn(isNextOn)
+
+          onChange?.(isNextOn)
+        }}
+        role="switch"
+        type="button"
+      >
+        <span
+          className={toClassName(
+            "rounded-full bg-surface-raised transition-transform duration-(--duration-fast) ease-standard",
+            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