@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/src/components/toggle-button/toggle-button.context.tsx

@@ -0,0 +1,130 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { ButtonSize } from "../button/button.variants";
+import type { HapticFeedback } from "../pressable";
+import type {
+	ToggleButtonGroupLayout,
+	ToggleButtonGroupOrientation,
+	ToggleButtonSelectionMode,
+	ToggleButtonVariant,
+} from "./toggle-button.variants";
+
+export type ToggleButtonContextValue = {
+	/** Whether the toggle is pressed in right now. */
+	isSelected: boolean;
+	/** Whether the toggle is disabled, once its group has had its say. */
+	isDisabled: boolean;
+	/** The toggle's own variant, not the button variant it resolves to. */
+	variant: ToggleButtonVariant;
+	/** The size the toggle asked for, or `undefined` to take the button's default. */
+	size: ButtonSize | undefined;
+};
+
+const ToggleButtonContext = createContext<ToggleButtonContextValue | null>(null);
+
+/**
+ * Supplies the enclosing toggle's state to its subtree.
+ *
+ * In a leaf of its own, importing nothing but types, so a part can read it
+ * without importing `./toggle-button` and closing a cycle (package AGENTS.md
+ * rule 3).
+ */
+export function ToggleButtonProvider({
+	value,
+	children,
+}: {
+	value: ToggleButtonContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ToggleButtonContext value={value}>{children}</ToggleButtonContext>;
+}
+ToggleButtonProvider.displayName = "DelacourUI.ToggleButton.Provider";
+
+/** The enclosing toggle's state, or null outside a `<ToggleButton>`. */
+export function useToggleButtonContext(): ToggleButtonContextValue | null {
+	return use(ToggleButtonContext);
+}
+
+/**
+ * Reads the enclosing toggle's state.
+ *
+ * For a custom child that changes with the toggle — a glyph that fills when
+ * selected. Throws outside a `<ToggleButton>` — use
+ * {@link useToggleButtonContext} where the toggle is optional.
+ */
+export function useToggleButton(): ToggleButtonContextValue {
+	const context = useToggleButtonContext();
+	if (!context) {
+		throw new Error("useToggleButton must be called inside a <ToggleButton>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing toggle's state, for a compound part that cannot work without it.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useToggleButtonPart(component: string): ToggleButtonContextValue {
+	const context = useToggleButtonContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <ToggleButton>.`);
+	}
+	return context;
+}
+
+export type ToggleButtonGroupContextValue = {
+	/** The `value` of every selected member. */
+	selected: readonly string[];
+	/** Presses the member called `value`, as the selection mode decides. */
+	toggle: (value: string) => void;
+	selectionMode: ToggleButtonSelectionMode;
+	layout: ToggleButtonGroupLayout;
+	orientation: ToggleButtonGroupOrientation;
+	/** A default a member may override. */
+	variant?: ToggleButtonVariant;
+	/** A default a member may override. An attached group owns the step outright. */
+	size?: ButtonSize;
+	/** A default a member may override, so one option can disable itself. */
+	isDisabled?: boolean;
+	/** A default a member may override. */
+	haptic?: false | HapticFeedback;
+};
+
+const ToggleButtonGroupContext = createContext<ToggleButtonGroupContextValue | null>(null);
+
+/**
+ * Supplies a group's selection and shared axes to its members.
+ *
+ * The optional axes are published raw, so `undefined` means "the group said
+ * nothing" and a member's `??` ladder can see past it.
+ */
+export function ToggleButtonGroupProvider({
+	value,
+	children,
+}: {
+	value: ToggleButtonGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ToggleButtonGroupContext value={value}>{children}</ToggleButtonGroupContext>;
+}
+ToggleButtonGroupProvider.displayName = "DelacourUI.ToggleButton.Group.Provider";
+
+/** The enclosing group, or null for a toggle standing on its own. */
+export function useToggleButtonGroupContext(): ToggleButtonGroupContextValue | null {
+	return use(ToggleButtonGroupContext);
+}
+
+/**
+ * Reads the enclosing group's selection and axes.
+ *
+ * Throws outside a `<ToggleButton.Group>` — use
+ * {@link useToggleButtonGroupContext} where the group is optional, as a
+ * `ToggleButton` itself does.
+ */
+export function useToggleButtonGroup(): ToggleButtonGroupContextValue {
+	const context = useToggleButtonGroupContext();
+	if (!context) {
+		throw new Error("useToggleButtonGroup must be called inside a <ToggleButton.Group>.");
+	}
+	return context;
+}

package/src/components/toggle-button/toggle-button.tsx

@@ -0,0 +1,172 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { Button, type ButtonProps } from "../button";
+import {
+	type ToggleButtonContextValue,
+	ToggleButtonProvider,
+	useToggleButtonGroupContext,
+} from "./toggle-button.context";
+import {
+	resolveToggleButtonAccessibility,
+	resolveToggleButtonVariant,
+	type ToggleButtonVariant,
+} from "./toggle-button.variants";
+import { ToggleButtonGroup } from "./toggle-button-group";
+import { ToggleButtonLabel } from "./toggle-button-label";
+
+/** What a render-function child is handed. */
+export type ToggleButtonRenderState = {
+	isSelected: boolean;
+	isDisabled: boolean;
+};
+
+export type ToggleButtonProps = Omit<
+	ButtonProps,
+	"accessibilityRole" | "accessibilityState" | "children" | "variant"
+> & {
+	/** Identifies the toggle inside a `ToggleButton.Group`. Required there. */
+	value?: string;
+	/** How the toggle paints itself, off and on. Inherited from a group when not given. */
+	variant?: ToggleButtonVariant;
+	/** Controlled selection. Ignored inside a group, which owns the state. */
+	isSelected?: boolean;
+	/** Starting state while uncontrolled and outside a group. */
+	defaultSelected?: boolean;
+	/** Called with the new state on every press. Not called inside a group — the group's `onSelected` is. */
+	onSelected?: (isSelected: boolean) => void;
+	/** Content, or a function of the toggle's state for content that changes with it. */
+	children?: ReactNode | ((state: ToggleButtonRenderState) => ReactNode);
+};
+
+function ToggleButtonRoot({
+	value,
+	variant,
+	size,
+	isSelected,
+	defaultSelected = false,
+	onSelected,
+	isDisabled,
+	haptic,
+	onPress,
+	children,
+	...props
+}: ToggleButtonProps): ReactElement {
+	const group = useToggleButtonGroupContext();
+
+	// Called unconditionally, grouped or not: a hook may not sit behind a branch.
+	// Inside a group its state is simply never read.
+	const [ownSelected, setOwnSelected] = useControllableState<boolean>({
+		defaultValue: defaultSelected,
+		onChange: onSelected,
+		value: isSelected,
+	});
+
+	if (process.env.NODE_ENV !== "production" && group && value === undefined) {
+		console.warn(
+			"ToggleButton: a <ToggleButton> inside a <ToggleButton.Group> needs a `value`, or it can never be selected."
+		);
+	}
+
+	const resolvedIsSelected = group ? value !== undefined && group.selected.includes(value) : ownSelected;
+	const resolvedVariant = variant ?? group?.variant ?? "default";
+	const resolvedSize = size ?? group?.size;
+	const resolvedIsDisabled = isDisabled ?? group?.isDisabled ?? false;
+
+	// The caller's `onPress` runs first, then the state moves — so a handler
+	// reading the state it closed over sees what the toggle was when pressed.
+	const handlePress = useCallback(() => {
+		onPress?.();
+		if (group) {
+			if (value !== undefined) group.toggle(value);
+			return;
+		}
+		setOwnSelected(!ownSelected);
+	}, [group, onPress, ownSelected, setOwnSelected, value]);
+
+	const context = useMemo<ToggleButtonContextValue>(
+		() => ({
+			isDisabled: resolvedIsDisabled,
+			isSelected: resolvedIsSelected,
+			size: resolvedSize,
+			variant: resolvedVariant,
+		}),
+		[resolvedIsDisabled, resolvedIsSelected, resolvedSize, resolvedVariant]
+	);
+
+	const accessibility = resolveToggleButtonAccessibility(group?.selectionMode ?? null, resolvedIsSelected);
+
+	const content =
+		typeof children === "function"
+			? children({ isDisabled: resolvedIsDisabled, isSelected: resolvedIsSelected })
+			: children;
+
+	// The role, state and press handler are set after the caller's props on
+	// purpose: they are what keeps the announced state and the drawn state one
+	// and the same, so nothing passed in may pull them apart.
+	return (
+		<ToggleButtonProvider value={context}>
+			<Button
+				{...props}
+				accessibilityRole={accessibility.accessibilityRole}
+				accessibilityState={accessibility.accessibilityState}
+				haptic={haptic ?? group?.haptic}
+				isDisabled={resolvedIsDisabled}
+				onPress={handlePress}
+				size={resolvedSize}
+				variant={resolveToggleButtonVariant(resolvedVariant, resolvedIsSelected)}
+			>
+				{content}
+			</Button>
+		</ToggleButtonProvider>
+	);
+}
+
+/**
+ * A button that stays pressed — on its own, or as one of a group.
+ *
+ * It is a `Button`, and draws itself with one: each state names a button
+ * variant (`TOGGLE_BUTTON_APPEARANCE`), so the fill, the label colour and the
+ * colour a composed `Icon` inherits all come off the button's own tables. Sizes
+ * are the button's, square `icon-*` steps included, and so are `haptic`,
+ * `feedback`, `isLoading` and the rest.
+ *
+ * On its own it is controlled with `isSelected` and `onSelected`, or
+ * uncontrolled from `defaultSelected`. Inside a `ToggleButton.Group` its `value`
+ * identifies it and the group owns the state.
+ *
+ * The state is announced, not only drawn: a toggle is a `togglebutton` that is
+ * checked or not, and a member of a `single` group is a `radio` that is selected
+ * or not. A square toggle holds no text, so give it an `accessibilityLabel`.
+ *
+ * Children may be a function of the state, for content that changes with it.
+ *
+ * @example
+ * <ToggleButton defaultSelected>Follow</ToggleButton>
+ *
+ * @example
+ * <ToggleButton isSelected={saved} onSelected={setSaved} variant="outline">
+ *   {({ isSelected }) => (
+ *     <>
+ *       <Icon icon={isSelected ? IconBookmarkCheck : IconBookmark} />
+ *       <ToggleButton.Label>{isSelected ? "Saved" : "Save"}</ToggleButton.Label>
+ *     </>
+ *   )}
+ * </ToggleButton>
+ *
+ * @example
+ * <ToggleButton.Group selectionMode="single" defaultSelected={["left"]} isSelectionRequired>
+ *   <ToggleButton accessibilityLabel="Align left" size="icon-md" value="left">
+ *     <Icon icon={IconAlignmentLeft} />
+ *   </ToggleButton>
+ *   <ToggleButton accessibilityLabel="Align centre" size="icon-md" value="center">
+ *     <Icon icon={IconAlignmentCenter} />
+ *   </ToggleButton>
+ * </ToggleButton.Group>
+ */
+export const ToggleButton = Object.assign(ToggleButtonRoot, {
+	/** The toggle's text. Picks its colour from the state the toggle is in. */
+	Label: ToggleButtonLabel,
+	/** Toggles sharing one selection, joined into a run or spaced apart. */
+	Group: ToggleButtonGroup,
+	displayName: "DelacourUI.ToggleButton",
+});

package/src/components/toggle-button/toggle-button.variants.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { BUTTON_VARIANTS } from "../button/button.variants";
+import {
+	resolveToggleButtonAccessibility,
+	resolveToggleButtonVariant,
+	resolveToggleSelection,
+	TOGGLE_BUTTON_APPEARANCE,
+	TOGGLE_BUTTON_GROUP_LAYOUTS,
+	TOGGLE_BUTTON_SELECTION_MODES,
+	TOGGLE_BUTTON_VARIANTS,
+	toggleButtonVariants,
+} from "./toggle-button.variants";
+
+describe("TOGGLE_BUTTON_APPEARANCE", () => {
+	test("covers every variant, in both states", () => {
+		expect(Object.keys(TOGGLE_BUTTON_APPEARANCE).sort()).toEqual([...TOGGLE_BUTTON_VARIANTS].sort());
+	});
+
+	test("names only button variants, so the button's own paint and foreground apply", () => {
+		for (const variant of TOGGLE_BUTTON_VARIANTS) {
+			expect(BUTTON_VARIANTS).toContain(TOGGLE_BUTTON_APPEARANCE[variant].off);
+			expect(BUTTON_VARIANTS).toContain(TOGGLE_BUTTON_APPEARANCE[variant].on);
+		}
+	});
+
+	test("a selected button never looks like an unselected one", () => {
+		for (const variant of TOGGLE_BUTTON_VARIANTS) {
+			expect(TOGGLE_BUTTON_APPEARANCE[variant].on).not.toBe(TOGGLE_BUTTON_APPEARANCE[variant].off);
+		}
+	});
+
+	test("never paints a toggle destructive", () => {
+		for (const variant of TOGGLE_BUTTON_VARIANTS) {
+			for (const state of ["on", "off"] as const) {
+				expect(TOGGLE_BUTTON_APPEARANCE[variant][state].startsWith("destructive")).toBe(false);
+			}
+		}
+	});
+});
+
+describe("resolveToggleButtonVariant", () => {
+	test("reads the appearance table", () => {
+		expect(resolveToggleButtonVariant("default", false)).toBe("secondary");
+		expect(resolveToggleButtonVariant("default", true)).toBe("primary");
+		expect(resolveToggleButtonVariant("outline", false)).toBe("outline");
+		expect(resolveToggleButtonVariant("outline", true)).toBe("primary");
+		expect(resolveToggleButtonVariant("ghost", false)).toBe("ghost");
+		expect(resolveToggleButtonVariant("ghost", true)).toBe("secondary");
+	});
+});
+
+describe("resolveToggleSelection — multiple", () => {
+	const mode = "multiple" as const;
+
+	test("adds a value that was not selected, keeping press order", () => {
+		expect(resolveToggleSelection({ current: ["bold"], selectionMode: mode, value: "italic" })).toEqual([
+			"bold",
+			"italic",
+		]);
+	});
+
+	test("removes a value that was selected", () => {
+		expect(resolveToggleSelection({ current: ["bold", "italic"], selectionMode: mode, value: "bold" })).toEqual([
+			"italic",
+		]);
+	});
+
+	test("clears the last value when a selection is not required", () => {
+		expect(resolveToggleSelection({ current: ["bold"], selectionMode: mode, value: "bold" })).toEqual([]);
+	});
+
+	test("refuses to clear the last value when a selection is required", () => {
+		expect(
+			resolveToggleSelection({ current: ["bold"], isSelectionRequired: true, selectionMode: mode, value: "bold" })
+		).toBeNull();
+	});
+
+	test("still removes one of several when a selection is required", () => {
+		expect(
+			resolveToggleSelection({
+				current: ["bold", "italic"],
+				isSelectionRequired: true,
+				selectionMode: mode,
+				value: "bold",
+			})
+		).toEqual(["italic"]);
+	});
+
+	test("does not mutate the list it was given", () => {
+		const current = ["bold"];
+		resolveToggleSelection({ current, selectionMode: mode, value: "italic" });
+		resolveToggleSelection({ current, selectionMode: mode, value: "bold" });
+		expect(current).toEqual(["bold"]);
+	});
+});
+
+describe("resolveToggleSelection — single", () => {
+	const mode = "single" as const;
+
+	test("replaces the selection with the pressed value", () => {
+		expect(resolveToggleSelection({ current: ["left"], selectionMode: mode, value: "center" })).toEqual(["center"]);
+	});
+
+	test("selects from nothing", () => {
+		expect(resolveToggleSelection({ current: [], selectionMode: mode, value: "center" })).toEqual(["center"]);
+	});
+
+	test("a re-press clears the selection when one is not required", () => {
+		expect(resolveToggleSelection({ current: ["left"], selectionMode: mode, value: "left" })).toEqual([]);
+	});
+
+	test("a re-press is no change when a selection is required", () => {
+		expect(
+			resolveToggleSelection({ current: ["left"], isSelectionRequired: true, selectionMode: mode, value: "left" })
+		).toBeNull();
+	});
+
+	test("collapses a controlled list that arrived with several values", () => {
+		expect(resolveToggleSelection({ current: ["left", "right"], selectionMode: mode, value: "center" })).toEqual([
+			"center",
+		]);
+	});
+});
+
+describe("resolveToggleButtonAccessibility", () => {
+	test("a standalone button is a toggle button that is checked or not", () => {
+		expect(resolveToggleButtonAccessibility(null, true)).toEqual({
+			accessibilityRole: "togglebutton",
+			accessibilityState: { checked: true },
+		});
+		expect(resolveToggleButtonAccessibility(null, false)).toEqual({
+			accessibilityRole: "togglebutton",
+			accessibilityState: { checked: false },
+		});
+	});
+
+	test("a member of a multiple-selection group is still a toggle button", () => {
+		expect(resolveToggleButtonAccessibility("multiple", true)).toEqual({
+			accessibilityRole: "togglebutton",
+			accessibilityState: { checked: true },
+		});
+	});
+
+	test("a member of a single-selection group is a radio, selected or not", () => {
+		expect(resolveToggleButtonAccessibility("single", true)).toEqual({
+			accessibilityRole: "radio",
+			accessibilityState: { selected: true },
+		});
+		expect(resolveToggleButtonAccessibility("single", false)).toEqual({
+			accessibilityRole: "radio",
+			accessibilityState: { selected: false },
+		});
+	});
+});
+
+describe("toggleButtonVariants", () => {
+	test("exposes both selection modes and both layouts", () => {
+		expect([...TOGGLE_BUTTON_SELECTION_MODES]).toEqual(["single", "multiple"]);
+		expect([...TOGGLE_BUTTON_GROUP_LAYOUTS]).toEqual(["attached", "detached"]);
+	});
+
+	test("an attached group adds nothing — Button.Group draws the run", () => {
+		// `tv` returns undefined rather than "" for a slot with no classes.
+		expect(toggleButtonVariants({ layout: "attached", orientation: "horizontal" }).group() ?? "").toBe("");
+		expect(toggleButtonVariants({ layout: "attached", orientation: "vertical" }).group() ?? "").toBe("");
+	});
+
+	test("a detached horizontal group wraps with a gap", () => {
+		const group = toggleButtonVariants({ layout: "detached", orientation: "horizontal" }).group();
+		expect(group).toContain("flex-row");
+		expect(group).toContain("flex-wrap");
+		expect(group).toContain("gap-2");
+	});
+
+	test("a detached vertical group stacks with a gap", () => {
+		const group = toggleButtonVariants({ layout: "detached", orientation: "vertical" }).group();
+		expect(group).toContain("flex-col");
+		expect(group).toContain("gap-2");
+		expect(group).not.toContain("flex-row");
+	});
+
+	test("a caller's className merges over the group's own", () => {
+		const group = toggleButtonVariants({ layout: "detached", orientation: "horizontal" }).group({
+			className: "gap-4",
+		});
+		expect(group).toContain("gap-4");
+		expect(group).not.toContain("gap-2");
+	});
+});

package/src/components/toggle-button/toggle-button.variants.ts

@@ -0,0 +1,160 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { ButtonVariant } from "../button/button.variants";
+
+/**
+ * How a toggle paints itself, off and on.
+ *
+ * `default` is a quiet fill that turns into the action colour; `outline` is a
+ * bordered button that fills; `ghost` is bare until pressed and then takes the
+ * quiet fill, which is what a toolbar of formatting marks wants.
+ */
+export const TOGGLE_BUTTON_VARIANTS = ["default", "outline", "ghost"] as const;
+
+/**
+ * `multiple` is a set of independent marks — bold *and* italic. `single` is an
+ * either-or choice, where picking one clears the last.
+ */
+export const TOGGLE_BUTTON_SELECTION_MODES = ["single", "multiple"] as const;
+
+/**
+ * `attached` joins the members into one run through `Button.Group`, sharing a
+ * corner and a seam. `detached` spaces them apart and wraps — a row of filters.
+ */
+export const TOGGLE_BUTTON_GROUP_LAYOUTS = ["attached", "detached"] as const;
+
+export const TOGGLE_BUTTON_GROUP_ORIENTATIONS = ["horizontal", "vertical"] as const;
+
+export type ToggleButtonVariant = (typeof TOGGLE_BUTTON_VARIANTS)[number];
+export type ToggleButtonSelectionMode = (typeof TOGGLE_BUTTON_SELECTION_MODES)[number];
+export type ToggleButtonGroupLayout = (typeof TOGGLE_BUTTON_GROUP_LAYOUTS)[number];
+export type ToggleButtonGroupOrientation = (typeof TOGGLE_BUTTON_GROUP_ORIENTATIONS)[number];
+
+/**
+ * The `Button` variant each toggle variant draws with, off and on.
+ *
+ * A toggle owns no paint of its own. Every state is a button variant, so the
+ * fill, the border, the label colour and the colour a composed `Icon` inherits
+ * all come off `buttonVariants` and `BUTTON_FOREGROUND_TOKEN` — there is no
+ * second table of colours here to drift from the button's. Every variant the
+ * button already has draws with the same `border` box, so switching state never
+ * resizes the toggle.
+ *
+ * No state is ever destructive: a pressed toggle is a choice, not a warning.
+ */
+export const TOGGLE_BUTTON_APPEARANCE: Record<ToggleButtonVariant, { off: ButtonVariant; on: ButtonVariant }> = {
+	default: { off: "secondary", on: "primary" },
+	outline: { off: "outline", on: "primary" },
+	ghost: { off: "ghost", on: "secondary" },
+};
+
+/**
+ * Styling for the group's box. The toggle itself is a `Button` and carries none.
+ *
+ * An `attached` group adds nothing: it renders a `Button.Group`, which already
+ * owns the run's direction, its corners and its seams. A `detached` group is a
+ * plain wrapping row, or a column, spaced by a gap — the one thing an attached
+ * run must never have.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const toggleButtonVariants = tv({
+	slots: {
+		group: "",
+	},
+	variants: {
+		layout: { attached: {}, detached: {} },
+		orientation: { horizontal: {}, vertical: {} },
+	},
+	compoundVariants: [
+		{ layout: "detached", orientation: "horizontal", class: { group: "flex-row flex-wrap gap-2" } },
+		{ layout: "detached", orientation: "vertical", class: { group: "flex-col gap-2" } },
+	],
+	defaultVariants: {
+		layout: "attached",
+		orientation: "horizontal",
+	},
+});
+
+/**
+ * The `Button` variant a toggle draws with right now.
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveToggleButtonVariant(variant: ToggleButtonVariant, isSelected: boolean): ButtonVariant {
+	return TOGGLE_BUTTON_APPEARANCE[variant][isSelected ? "on" : "off"];
+}
+
+/**
+ * The group's next selection after `value` is pressed, or `null` for no change.
+ *
+ * `null` rather than the same list back, so the group never re-notifies a caller
+ * with a value it already holds — the same rule `Radio.Group` keeps for a
+ * re-press of the current option.
+ *
+ * - `multiple` adds or removes `value`, keeping the order things were pressed in.
+ * - `single` replaces the selection with `value`. A re-press of the selected one
+ *   clears it, unless `isSelectionRequired`, when it is no change at all — a
+ *   segmented choice like text alignment always has an answer.
+ * - `isSelectionRequired` also refuses to empty a `multiple` group, so the last
+ *   mark cannot be taken off.
+ *
+ * A controlled `single` group handed several values collapses to the one pressed
+ * rather than carrying the others along.
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveToggleSelection({
+	current,
+	value,
+	selectionMode,
+	isSelectionRequired = false,
+}: {
+	current: readonly string[];
+	value: string;
+	selectionMode: ToggleButtonSelectionMode;
+	isSelectionRequired?: boolean;
+}): string[] | null {
+	const isSelected = current.includes(value);
+
+	if (selectionMode === "single") {
+		if (!isSelected) return [value];
+		if (isSelectionRequired) return null;
+		return [];
+	}
+
+	if (!isSelected) return [...current, value];
+	const next = current.filter((entry) => entry !== value);
+	if (isSelectionRequired && next.length === 0) return null;
+	return next;
+}
+
+/** A toggle's announced role — see {@link resolveToggleButtonAccessibility}. */
+export type ToggleButtonAccessibility =
+	| { accessibilityRole: "togglebutton"; accessibilityState: { checked: boolean } }
+	| { accessibilityRole: "radio"; accessibilityState: { selected: boolean } };
+
+/**
+ * What a screen reader is told a toggle is.
+ *
+ * A toggle standing alone, or one of a set of independent marks, is a
+ * `togglebutton` that is checked or not — read out as on or off. A member of a
+ * `single` group is a choice among options, which is a radio: announcing it as a
+ * toggle would promise that pressing it again turns it off, and in a group that
+ * requires a selection it does not.
+ *
+ * `null` is "not in a group".
+ *
+ * Pure, so the whole matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveToggleButtonAccessibility(
+	selectionMode: ToggleButtonSelectionMode | null,
+	isSelected: boolean
+): ToggleButtonAccessibility {
+	if (selectionMode === "single") {
+		return { accessibilityRole: "radio", accessibilityState: { selected: isSelected } };
+	}
+	return { accessibilityRole: "togglebutton", accessibilityState: { checked: isSelected } };
+}
+
+export type ToggleButtonVariantProps = VariantProps<typeof toggleButtonVariants>;