@delacour/react-native-ui 0.1.0-alpha.20260925053522

package/src/components/chart/use-chart-palette.ts

@@ -0,0 +1,38 @@
+import { useMemo } from "react";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import type { ChartResolvedSeries } from "./chart.types";
+import { applyChartColors, CHART_MAX_TOKEN_SERIES, partitionChartColors } from "./chart.variants";
+
+/**
+ * Resolves a series list's theme tokens into colour strings.
+ *
+ * Every theme lookup happens here, above the canvas. Skia's renderer is a
+ * second React reconciler with no Uniwind provider in it, so a hook called
+ * inside would resolve nothing — the marks receive resolved strings instead.
+ * A hook rather than a helper in a root so `Chart` and `PieChart` share one
+ * palette and one cap.
+ *
+ * Eight calls, written out. `partitionChartColors` pads its token list to
+ * exactly this many so the hook count cannot vary between renders, and a loop
+ * over the series would break the rules of hooks the moment a series was
+ * added. The repetition is the mechanism, not an oversight. Tokens are
+ * deduped first, so the eight are eight *distinct* tokens — the five-token
+ * ramp costs five, however many series walk it.
+ */
+export function useChartPalette(declared: readonly ChartResolvedSeries[]): ChartResolvedSeries[] {
+	const partition = useMemo(() => partitionChartColors(declared, CHART_MAX_TOKEN_SERIES), [declared]);
+
+	const color0 = useThemeColor(partition.tokens[0] as string);
+	const color1 = useThemeColor(partition.tokens[1] as string);
+	const color2 = useThemeColor(partition.tokens[2] as string);
+	const color3 = useThemeColor(partition.tokens[3] as string);
+	const color4 = useThemeColor(partition.tokens[4] as string);
+	const color5 = useThemeColor(partition.tokens[5] as string);
+	const color6 = useThemeColor(partition.tokens[6] as string);
+	const color7 = useThemeColor(partition.tokens[7] as string);
+
+	return useMemo(
+		() => applyChartColors(declared, partition, [color0, color1, color2, color3, color4, color5, color6, color7]),
+		[declared, partition, color0, color1, color2, color3, color4, color5, color6, color7]
+	);
+}

package/src/components/checkbox/AGENTS.md

@@ -0,0 +1,185 @@
+# Checkbox
+
+A box that is ticked or not — alone, or as one of a group sharing a value list.
+Root plus `Checkbox.Label` and `Checkbox.Group`.
+
+`import { Checkbox } from "@delacour/react-native-ui/checkbox";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/checkbox` |
+| `checkbox.tsx` | Root + the `Object.assign` compound surface |
+| `checkbox-label.tsx` | `Checkbox.Label`, the `Text.Label` inside the tap target |
+| `checkbox-group.tsx` | `Checkbox.Group`, which owns the checked list |
+| `checkbox-box.tsx` | The square, its animated border, fill and tick — internal |
+| `checkbox.context.tsx` | `CheckboxContext` and `CheckboxGroupContext`, with their hooks |
+| `checkbox.types.ts` | Prop types shared by two or more parts |
+| `checkbox.variants.ts` | Pure `tv()` slots + six resolvers, no RN imports |
+| `checkbox.variants.test.ts` | |
+
+## Design
+
+- **Colours**: `default`, `primary`, `success`, `warning`, `destructive`, `info` —
+  [Badge](../badge/AGENTS.md)'s set, reusing tokens the theme already has. **Sizes**: `sm`, `md`, `lg`.
+  **Alignment**: `start`, `end`. There is no `variant` axis: a checkbox has one
+  shape, and a second way to paint it would be a second thing to keep in step
+  with the [radio](../radio/AGENTS.md) that will sit beside it.
+- **The root draws the box itself**, which is what makes `<Checkbox />` a
+  complete control with no children. Anything composed inside lands *beside* the
+  box and shares its tap target — which is the entire reason `Checkbox.Label`
+  exists next to [`Field.Label`](../field/AGENTS.md). `Field.Label` names a control from a row away;
+  this one is inside the pressable, so tapping the words toggles the box. Use the
+  field's in a horizontal `Field` and this one everywhere else.
+- **`Checkbox.Label` *is* [`Text.Label`](../text/AGENTS.md).** It renders the preset and passes a
+  step and a colour, never a class for either — `resolveCheckboxLabelSize` maps
+  the checkbox's own step names onto `TEXT_SIZES`', and
+  `resolveCheckboxLabelColor` returns `undefined` to mean "leave the preset's own
+  alone". The `label` slot carries layout and nothing else, and a test asserts it
+  holds no `text-*` or `font-*` at any size. Same rule as [`Field`](../field/AGENTS.md), same reason
+  [`Input`](../input/AGENTS.md) ships no label part at all.
+- **`color` paints the indicator, not the box.** The indicator is an
+  absolute-fill layer that is invisible until the box is ticked, so an unticked
+  box is `border-input bg-card` at every colour — the same chrome a field wears,
+  because it is the same kind of thing. Only the border has to know both states,
+  which is why the six `color × isFilled` cells are the whole of
+  `compoundVariants` instead of a thirty-six cell matrix. The border always
+  matches its own fill, and a test pins the pair rather than trusting two maps.
+- **`isFilled`, not `isChecked`, is the tv axis.** Checked and indeterminate both
+  paint the surface and only the glyph tells them apart, so the axis is named for
+  what it does and `resolveCheckboxFilled` is the translation. Indeterminate also
+  reports `checked="mixed"`, so a "select all" row says what it means rather than
+  claiming a half-truth.
+- **Invalid outranks the colour**, on the border and the fill, ticked or not.
+  A checkbox that stayed green while its value was rejected would drop the only
+  signal it has, exactly while the value is being corrected — the precedence
+  [`Input`](../input/AGENTS.md) sets between invalid and focus.
+- **The axis ladder is `own ?? group ?? field ?? default`, and it is deliberately
+  not [`Input`](../input/AGENTS.md)'s.** `Input.Group` puts itself *first* because it owns the one box
+  a grouped field renders into: two answers to one question is not a state worth
+  expressing. `Checkbox.Group` owns no box. It is a state controller that also
+  carries shared defaults, which makes it the same kind of thing as [`Field`](../field/AGENTS.md) — a
+  wrapper a control overrides — so "make the group `lg`" and "make this one
+  `destructive`" are different questions and both get an answer. `??` throughout and
+  never `||`, so `isDisabled={false}` opts a child out of a disabled group.
+- **`Checkbox.Group`'s state is one array of the children's `value`s.**
+  `toggleCheckedValue` is the whole transition and it is pure, so `bun test`
+  reaches it — including that it always returns a *new* array, since React bails
+  out of a re-render on an unchanged reference and a mutation would flip the
+  state while leaving the screen alone. A grouped checkbox with no `value`
+  throws by name: group membership is invisible in the child's props at compile
+  time, so it cannot be a type error.
+- **The group is a plain `View` with no role.** A group of checkboxes is a
+  container, and announcing it as a control would put an actionless element in
+  front of every child. Lay them out any other way with a `className` —
+  `flex-row flex-wrap` for a row.
+- **Inside a `Field` the box hands its toggle back up**, so the row is the
+  target and a form checkbox can be a bare `<Checkbox />` with the field naming
+  it, rather than a `Checkbox.Label` repeating the name. It registers a
+  ref-backed trampoline rather than the toggle itself: the toggle is a new
+  function whenever `checked` changes, and re-registering on every tick would
+  re-render the field for nothing. See [Field](../field/AGENTS.md).
+- **The whole [`Pressable`](../pressable/AGENTS.md) surface passes through**, because the root *is* one.
+  Two defaults differ from a bare `Pressable` and only two: `feedback="fade"`,
+  since a spring on a 20pt square reads as a jitter rather than a press, and
+  `haptic="selection"`, since a checkbox is a state toggle and the tick landing
+  is the confirmation — [`Button`](../button/AGENTS.md) and [`Badge`](../badge/AGENTS.md) leave it off because their press is
+  an action, not a state change. Both are ordinary props, so `haptic={false}`
+  silences it. `onPress` is the one prop `Omit`ed rather than forwarded: the
+  press *is* the toggle, and `onCheckedChange` is where a side effect goes.
+- **The fill, the tick and the border are three gestures off one shared value.**
+  The fill fades and scales **from the centre**: a box is filled, not slid into,
+  and there is no edge a checkbox is filled *from* — a `translateX` here reads as
+  a panel arriving rather than a surface appearing, so there is none. The tick is
+  not faded up with it; it sits behind a container whose width opens from the
+  box's left edge, so the stroke is drawn on when ticking and taken back when
+  unticking. `tickDelay` holds it until the surface it is drawn on is most of the
+  way there — starting both at once reads as one blurred event. The border comes
+  last, held by `borderDelay` until the surface is near the edge, so it reads as
+  the fill *arriving* at the border rather than as an outline changing on its
+  own. All three interpolate off a single `withTiming`, so they cannot drift, and
+  the values live in `CHECKBOX_INDICATOR_ANIMATION` where a test pins that every
+  track travels and that the filled end is a finished box rather than something
+  stopped mid-way.
+- **The fill overlaps the border rather than meeting it, and its corner is the
+  box's own.** `-inset-px` on the `indicator` slot puts it a point past the
+  padding box on every side, so it runs *under* the border ring instead of
+  stopping against it, and `resolveCheckboxFillRadius` gives it the same corner
+  the box wears. It does not animate: `scale` shrinks the rendered corner along
+  with the square, which is what keeps a half-grown fill looking like a smaller
+  version of the finished one, and animating the radius would only make it
+  correct at one end.
+
+  **The overlap is the whole point, and it replaced the opposite rule.** The fill
+  used to be `inset-0` with the box's radius *minus* its border width — the rule
+  for two rounded rectangles to sit concentric. Concentric is exactly what went
+  wrong: the fill's outer curve and the border's inner curve became the same
+  curve, rasterised twice on two layers and antialiased independently. At a
+  corner pixel where each gives coverage `a` the composite covers `2a - a²`, so
+  `(1 - a)²` of the box's own `bg-card` bleeds through — a dull arc at each of
+  the four corners, on iOS and Android alike. The straight edges are pixel
+  aligned and showed nothing, which is what made it read as a corner artifact
+  rather than as a sizing bug. Overlapping the two removes the shared edge
+  instead of concealing it, and holds whichever way a platform orders its paint:
+  iOS draws a `CALayer` border above its sublayers, Android draws it below.
+
+  It went unnoticed until the playground opened in the house preset, whose
+  `radius: "small"` is 7.2 against the library default's 10. The seam is a fixed
+  sub-pixel width, so shrinking an `md` box's corner from 4pt to 2.88pt made the
+  same defect a third louder. Do not "tidy" the inset back to `inset-0`, or
+  restore the subtraction; a test fails by name if either happens.
+- **It is computed from `--radius`, not written down.** Minting a token for it
+  would only give the box and the fill a second place to disagree. It cannot be
+  read back either: the corner scale is `@theme inline`, so Tailwind substitutes
+  each step into its utilities and no `--radius-xs` variable reaches the runtime
+  — though what it substitutes still carries a live `var(--radius)`, which is
+  what keeps a class-based `rounded-xs` and this function in step when a preset
+  retunes the base at runtime.
+  `resolveCheckboxFillRadius` takes the live `--radius` and applies
+  `CHECKBOX_RADIUS_MULTIPLIER`, which is why a consumer pasting a theme with a
+  different `--radius` moves the fill with the border instead of leaving it
+  behind. `checkbox.variants.test.ts` reads `tokens.css` and asserts the
+  multipliers match it, that the result *is* the box's own step at any
+  `--radius`, that `CHECKBOX_RADIUS_STEP` names the `rounded-*` the `box` slot
+  actually wears, and that the box's border really is the bare 1pt `border` the
+  `-inset-px` assumes. Retuning the scale, or reaching for `border-2`, fails the
+  build rather than quietly reopening the gap.
+- **The border is the one part of the box no `tv()` describes.** A colour that
+  fades cannot be a class, so it interpolates between two token *values* —
+  `resolveCheckboxBorderTokens` names them, and `CHECKBOX_SURFACE_TOKEN` is the
+  same colour the `indicator` slot paints as a `bg-*`, pinned against it by a
+  test. The base keeps `border-input` as the resting appearance the animated
+  style starts from, and nothing else in the slot set mentions a border colour;
+  two sources for one border is how a class and a style end up disagreeing for a
+  frame on every toggle. An **invalid** box returns `destructive` at *both* ends, so
+  there is nothing to fade — the border is the signal the value is wrong, and it
+  has to be there before the box is ticked as much as after.
+- **The clip is measured, not tabulated.** It needs the box's width in points and
+  `size-checkbox-md` cannot be read from JavaScript, so it comes from the fill
+  layer's own `onLayout` — that layer is already exactly the width the clip has
+  to span. A table of numbers here would be `tokens.css` restated in TypeScript,
+  which is the drift `tokens.test.ts` exists to catch everywhere else.
+- **Reduce-motion takes Reanimated's default `System` policy here**, unlike
+  [`Spinner`](../spinner/AGENTS.md). Under it `withTiming` completes instantly, which for a checkbox is
+  right: the state change is the point and the travel is decoration. A spinner
+  had to opt out because its animation *is* the status signal.
+- **`hitSlop` is new to this package, and only a bare box gets any.** A bare `md`
+  checkbox is a 20pt square against a 44pt minimum, with no padded capsule to
+  absorb the difference the way [`Badge.CloseButton`](../badge/AGENTS.md) has. Once there is a label
+  the row is the target and is already wide, so `resolveCheckboxHitSlop` returns
+  nothing — slop on top of that would overlap the row below and make a tap
+  between two checkboxes ambiguous, which is worse than a merely adequate target.
+- **There is no `Checkbox.Description` and no `Checkbox.Indicator`.**
+  `Field.Description` already is the first, and a label defined twice is a type
+  scale that can drift. The second has nothing to configure that
+  `isIndeterminate` does not already decide — the glyph swap is the only choice
+  it would offer.
+- **The box mints no scale of its own — it reads `--spacing-icon-*`, two steps
+  above its own glyph.** A checkbox *is* a glyph in a box, and both measurements
+  already sit on that scale: 18/14, 20/16, 24/18. A private
+  `--spacing-checkbox-*` would be three numbers that have to be retuned in step
+  with three others forever, and nothing would notice when they stopped
+  agreeing. The two-step offset is what leaves the tick breathing room, and a
+  test pins the *offset* rather than the points, so the icon scale can be
+  retuned without the test becoming a transcript of it.

package/src/components/checkbox/checkbox-box.tsx

@@ -0,0 +1,152 @@
+import { type ReactElement, useCallback, useEffect } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import Animated, {
+	cancelAnimation,
+	Extrapolation,
+	interpolate,
+	interpolateColor,
+	useAnimatedStyle,
+	useSharedValue,
+	withTiming,
+} from "react-native-reanimated";
+import { useCSSVariable } from "uniwind";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { IconCheckmark1Small, IconMinusSmall } from "../../icons/central";
+import { Icon } from "../icon";
+import { useCheckboxPart } from "./checkbox.context";
+import {
+	CHECKBOX_BORDER_WIDTH,
+	CHECKBOX_GLYPH_TOKEN,
+	CHECKBOX_INDICATOR_ANIMATION,
+	CHECKBOX_INVALID_GLYPH_TOKEN,
+	checkboxVariants,
+	resolveCheckboxBorderTokens,
+	resolveCheckboxFilled,
+	resolveCheckboxFillRadius,
+} from "./checkbox.variants";
+
+/**
+ * The square itself: its border, the fill behind it and the tick drawn on top.
+ *
+ * Internal — the checkbox renders one and there is nothing for a caller to
+ * compose here that `isIndeterminate` does not already decide. It takes a file
+ * of its own because it owns every animated value; keeping them in the root
+ * would make the root a component that changes for two unrelated reasons.
+ *
+ * Three things move, off one shared progress, so they cannot drift out of step:
+ *
+ * - the **fill** fades and scales from the centre. A box is filled, not slid
+ *   into, so it arrives from no edge. Its corner radius is fixed rather than
+ *   animated — {@link resolveCheckboxFillRadius} gives it the box's own corner at
+ *   every scale, and the transform shrinks the rendered one with it. It spans the
+ *   whole border box rather than the padding box, so it runs *under* the border
+ *   ring instead of stopping against it; two coincident antialiased curves leave
+ *   a seam at each corner, and there is no longer a shared edge to leave one.
+ * - the **tick** is clipped by a container whose width opens from the left, so
+ *   the stroke is drawn on when ticking and taken back when unticking rather
+ *   than faded up in place.
+ * - the **border** interpolates from the field chrome to the fill's own colour,
+ *   held back by `borderDelay` until the surface is near the edge — so it reads
+ *   as the fill arriving at the border rather than as an outline changing on its
+ *   own. A colour being interpolated cannot be a class, which is why this one is
+ *   the only part of the box a `tv()` does not describe.
+ *
+ * The clip needs the box's width in points, and a `size-checkbox-*` class cannot
+ * be read from JavaScript. It comes from the box's own `onLayout` rather than a
+ * table of numbers restating `tokens.css`, less its two borders — `onLayout`
+ * reports the border box, and the clip is positioned in the padding box inside
+ * it. The fill cannot be the thing measured: it deliberately overhangs.
+ *
+ * Reduce-motion takes Reanimated's default `System` policy here, deliberately
+ * unlike `Spinner`. Under it `withTiming` completes instantly, which for a
+ * checkbox is exactly right: the state change is the point and the travel is
+ * decoration. A spinner had to opt out because its animation *is* the signal.
+ */
+export function CheckboxBox(): ReactElement {
+	const { color, size, isChecked, isIndeterminate, isInvalid } = useCheckboxPart("Checkbox.Box");
+	const isFilled = resolveCheckboxFilled({ isChecked, isIndeterminate });
+
+	const progress = useSharedValue(isFilled ? 1 : 0);
+	const boxWidth = useSharedValue(0);
+
+	useEffect(() => {
+		progress.value = withTiming(isFilled ? 1 : 0, { duration: CHECKBOX_INDICATOR_ANIMATION.durationMs });
+
+		// Without this a box unmounted mid-toggle leaves its timing running.
+		return () => cancelAnimation(progress);
+	}, [isFilled, progress]);
+
+	// Subtracting the border twice is what keeps the glyph on the box's centre
+	// line. `tick` and `tickInner` are positioned in the padding box, so handing
+	// them the border-box width moves the centre they resolve against.
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			boxWidth.value = Math.max(0, event.nativeEvent.layout.width - 2 * CHECKBOX_BORDER_WIDTH);
+		},
+		[boxWidth]
+	);
+
+	// `--radius` is the only step of the corner scale that survives to runtime —
+	// the rest are `@theme inline` and get substituted into their utilities — so
+	// the fill's own corner is computed from the base rather than read back.
+	const radius = (useCSSVariable("--radius") as number | undefined) ?? 0;
+	const fillRadius = resolveCheckboxFillRadius(size, radius);
+
+	const border = resolveCheckboxBorderTokens({ color, isInvalid });
+	const restBorderColor = useThemeColor(border.rest) ?? "transparent";
+	const activeBorderColor = useThemeColor(border.active) ?? "transparent";
+
+	const boxStyle = useAnimatedStyle(() => ({
+		borderColor: interpolateColor(
+			interpolate(progress.value, [CHECKBOX_INDICATOR_ANIMATION.borderDelay, 1], [0, 1], Extrapolation.CLAMP),
+			[0, 1],
+			[restBorderColor, activeBorderColor]
+		),
+	}));
+
+	const fillStyle = useAnimatedStyle(() => ({
+		opacity: interpolate(progress.value, [0, 1], CHECKBOX_INDICATOR_ANIMATION.opacity),
+		transform: [{ scale: interpolate(progress.value, [0, 1], CHECKBOX_INDICATOR_ANIMATION.scale) }],
+	}));
+
+	// Clamped, so the tick sits at zero width through the delay rather than being
+	// extrapolated to a negative one.
+	const tickStyle = useAnimatedStyle(() => ({
+		width:
+			boxWidth.value *
+			interpolate(progress.value, [CHECKBOX_INDICATOR_ANIMATION.tickDelay, 1], [0, 1], Extrapolation.CLAMP),
+	}));
+
+	// Full width regardless of the clip in front of it, so the glyph stays on the
+	// box's centre line while the clip opens instead of sliding across with it.
+	const tickInnerStyle = useAnimatedStyle(() => ({ width: boxWidth.value }));
+
+	const slots = checkboxVariants({ color, isFilled, isInvalid, size });
+	// A colour that has to reach an SVG paint prop cannot be a class. See Theming.
+	const glyphColor = useThemeColor(isInvalid ? CHECKBOX_INVALID_GLYPH_TOKEN : CHECKBOX_GLYPH_TOKEN[color]);
+
+	return (
+		<Animated.View className={slots.box()} onLayout={handleLayout} style={boxStyle}>
+			<Animated.View
+				className={slots.indicator()}
+				// A fixed radius rather than an animated one: the fill wears the box's
+				// own corner, and that value does not change while the box is growing.
+				// `scale` shrinks the rendered corner along with the square, which is
+				// what keeps a half-grown fill looking like a smaller version of the
+				// finished one. It is read from `--radius` rather than written down
+				// because a consumer's theme is allowed to retune that.
+				style={[{ borderRadius: fillRadius }, fillStyle]}
+			/>
+			<Animated.View className={slots.tick()} style={tickStyle}>
+				<Animated.View className={slots.tickInner()} style={tickInnerStyle}>
+					<Icon
+						className={slots.glyph()}
+						color={glyphColor}
+						icon={isIndeterminate ? IconMinusSmall : IconCheckmark1Small}
+					/>
+				</Animated.View>
+			</Animated.View>
+		</Animated.View>
+	);
+}
+CheckboxBox.displayName = "DelacourUI.Checkbox.Box";

package/src/components/checkbox/checkbox-group.tsx

@@ -0,0 +1,107 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type CheckboxGroupContextValue, CheckboxGroupProvider } from "./checkbox.context";
+import {
+	type CheckboxAlignment,
+	type CheckboxColor,
+	type CheckboxSize,
+	checkboxVariants,
+	toggleCheckedValue,
+} from "./checkbox.variants";
+
+export type CheckboxGroupProps = Omit<ViewProps, "children"> & {
+	/** The `value` of every checked child. Controlled. */
+	checked?: string[];
+	/** The values checked to begin with, while uncontrolled. */
+	defaultChecked?: string[];
+	/** Fired with the whole list every time a child is toggled. */
+	onChecked?: (checked: string[]) => void;
+	/** Defaults every child takes unless it names its own. */
+	color?: CheckboxColor;
+	size?: CheckboxSize;
+	alignment?: CheckboxAlignment;
+	isInvalid?: boolean;
+	isDisabled?: boolean;
+	className?: string;
+	children?: ReactNode;
+};
+
+function CheckboxGroupRoot({
+	checked,
+	defaultChecked = EMPTY,
+	onChecked,
+	color,
+	size,
+	alignment,
+	isInvalid,
+	isDisabled,
+	className,
+	children,
+	...props
+}: CheckboxGroupProps): ReactElement {
+	const [values, setValues] = useControllableState<string[]>({
+		defaultValue: defaultChecked,
+		onChange: onChecked,
+		value: checked,
+	});
+
+	const toggle = useCallback((value: string) => setValues(toggleCheckedValue(values, value)), [setValues, values]);
+
+	const context = useMemo<CheckboxGroupContextValue>(
+		() => ({ alignment, checked: values, color, isDisabled, isInvalid, size, toggle }),
+		[alignment, color, isDisabled, isInvalid, size, toggle, values]
+	);
+
+	return (
+		<CheckboxGroupProvider value={context}>
+			<View className={checkboxVariants().group({ className })} {...props}>
+				{children}
+			</View>
+		</CheckboxGroupProvider>
+	);
+}
+
+/**
+ * A stable empty list, so an uncontrolled group does not seed its state from a
+ * fresh array on every render.
+ */
+const EMPTY: string[] = [];
+
+/**
+ * The checked list for the checkboxes inside it, and the axes they share.
+ *
+ * State is one array of the children's `value`s: `checked={["email"]}` ticks the
+ * box called `email`, and `onChecked` fires with the whole new list each time
+ * one is toggled. Controlled or uncontrolled from the same hook — pass `checked`
+ * to own it, or `defaultChecked` and let the group hold it.
+ *
+ * **The axes here are defaults, not overrides.** A child's own `color` or `size`
+ * wins, and so does an explicit `isDisabled={false}` under a disabled group.
+ * That is the opposite of `Input.Group`, and the difference is what each owns:
+ * `Input.Group` *is* the box its field renders into, so the axes that draw one
+ * can only have a single answer. A `Checkbox.Group` owns no box — it is a
+ * wrapper supplying context, the same kind of thing as `Field`, and a control
+ * overrides one of those.
+ *
+ * A plain `View`, with no role. A group of checkboxes is a container, and
+ * announcing it as a control would put an element with no action in front of
+ * every child. Lay them out any other way with a `className` —
+ * `flex-row flex-wrap` for a row.
+ *
+ * @example
+ * <Checkbox.Group checked={channels} onChecked={setChannels}>
+ *   <Checkbox value="email">Email</Checkbox>
+ *   <Checkbox value="sms">SMS</Checkbox>
+ *   <Checkbox value="push">Push</Checkbox>
+ * </Checkbox.Group>
+ *
+ * @example
+ * <Checkbox.Group color="success" defaultChecked={["daily"]} size="lg">
+ *   <Checkbox value="daily">Daily digest</Checkbox>
+ *   <Checkbox color="destructive" value="alerts">Incident alerts</Checkbox>
+ * </Checkbox.Group>
+ */
+export const CheckboxGroup = Object.assign(CheckboxGroupRoot, {
+	displayName: "DelacourUI.Checkbox.Group",
+});

package/src/components/checkbox/checkbox-label.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCheckboxPart } from "./checkbox.context";
+import type { CheckboxLabelProps } from "./checkbox.types";
+import { checkboxVariants, resolveCheckboxLabelColor, resolveCheckboxLabelSize } from "./checkbox.variants";
+
+/**
+ * The checkbox's text, inside the checkbox's own tap target.
+ *
+ * That is the whole reason this part exists next to `Field.Label`, which does
+ * the same job a row away: this one sits inside the pressable, so tapping the
+ * words toggles the box. Use `Field.Label` for a checkbox that sits beside its
+ * name in a horizontal `Field`, and this one for a checkbox that carries its
+ * own.
+ *
+ * Renders `Text.Label` and passes it a step and a colour, never a class for
+ * either — the type scale belongs to the preset, and restating it here would be
+ * a second definition of `Text.Label` that could drift from it. The `className`
+ * carries layout alone. It turns destructive with the box it names, so the pair reads
+ * as one state.
+ */
+export function CheckboxLabel({ className, color, size, ...props }: CheckboxLabelProps): ReactElement {
+	const { alignment, isInvalid, size: checkboxSize } = useCheckboxPart("Checkbox.Label");
+
+	return (
+		<Text.Label
+			className={checkboxVariants({ alignment }).label({ className })}
+			color={color ?? resolveCheckboxLabelColor(isInvalid)}
+			size={size ?? resolveCheckboxLabelSize(checkboxSize)}
+			{...props}
+		/>
+	);
+}
+CheckboxLabel.displayName = "DelacourUI.Checkbox.Label";

package/src/components/checkbox/checkbox.context.tsx

@@ -0,0 +1,136 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { CheckboxAlignment, CheckboxColor, CheckboxSize } from "./checkbox.variants";
+
+export type CheckboxContextValue = {
+	/** What a ticked box means. */
+	color: CheckboxColor;
+	/** Size of the box, its glyph and the label beside it. */
+	size: CheckboxSize;
+	/** Which side of the label the box sits on. */
+	alignment: CheckboxAlignment;
+	/** Whether the box is ticked. */
+	isChecked: boolean;
+	/** Whether the box reports a mixed state rather than a settled one. */
+	isIndeterminate: boolean;
+	/** Whether the box reports an invalid value. */
+	isInvalid: boolean;
+	/** Whether the box is unavailable. */
+	isDisabled: boolean;
+};
+
+export type CheckboxGroupContextValue = {
+	/** The `value` of every checked child. */
+	checked: readonly string[];
+	/** Flips one child's value in that list. */
+	toggle: (value: string) => void;
+	/** Defaults a child takes when it names none of its own. */
+	color?: CheckboxColor;
+	size?: CheckboxSize;
+	alignment?: CheckboxAlignment;
+	isInvalid?: boolean;
+	isDisabled?: boolean;
+};
+
+const CheckboxContext = createContext<CheckboxContextValue | null>(null);
+
+const CheckboxGroupContext = createContext<CheckboxGroupContextValue | null>(null);
+
+/**
+ * Supplies the enclosing checkbox's axes and state to its subtree.
+ *
+ * Lives in its own module, importing nothing but React and a type, so a part can
+ * read it without importing `./checkbox`. That import would close a cycle, and
+ * Metro serves a partially initialised module for a cycle — leaving the context
+ * `undefined` at import time and red-boxing the app on a cold start.
+ */
+export function CheckboxProvider({
+	value,
+	children,
+}: {
+	value: CheckboxContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <CheckboxContext value={value}>{children}</CheckboxContext>;
+}
+CheckboxProvider.displayName = "DelacourUI.Checkbox.Provider";
+
+/** The enclosing checkbox's context, or null outside a `<Checkbox>`. */
+export function useCheckboxContext(): CheckboxContextValue | null {
+	return use(CheckboxContext);
+}
+
+/**
+ * Reads the enclosing checkbox's axes and state.
+ *
+ * Lets a custom child style itself to match without the checkbox having to pass
+ * props down through every slot. Throws outside a `<Checkbox>` — use
+ * {@link useCheckboxContext} where the enclosing checkbox is optional.
+ */
+export function useCheckbox(): CheckboxContextValue {
+	const context = useCheckboxContext();
+	if (!context) {
+		throw new Error("useCheckbox must be called inside a <Checkbox>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing checkbox's context, for a compound part that cannot work without
+ * one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useCheckbox}, whose error message names the hook rather
+ * than a part.
+ */
+export function useCheckboxPart(component: string): CheckboxContextValue {
+	const context = useCheckboxContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Checkbox>.`);
+	}
+	return context;
+}
+
+/**
+ * Supplies the enclosing group's checked list and its shared defaults.
+ *
+ * A second context rather than a field on the first: a checkbox reads its group
+ * to work out what it *is*, and publishes its own context describing what it
+ * *became*. One value carrying both would have to exist before it could be
+ * computed.
+ */
+export function CheckboxGroupProvider({
+	value,
+	children,
+}: {
+	value: CheckboxGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <CheckboxGroupContext value={value}>{children}</CheckboxGroupContext>;
+}
+CheckboxGroupProvider.displayName = "DelacourUI.Checkbox.Group.Provider";
+
+/**
+ * The enclosing group's context, or null for a checkbox standing on its own.
+ *
+ * This is the export the root reads. It is nullable because a checkbox has to
+ * work perfectly well alone — a group is a layout and a state owner a caller
+ * opts into, not a wrapper anything requires.
+ */
+export function useCheckboxGroupContext(): CheckboxGroupContextValue | null {
+	return use(CheckboxGroupContext);
+}
+
+/**
+ * Reads the enclosing group's checked list and defaults.
+ *
+ * For a custom control that has to sit in a group the way a `Checkbox` does.
+ * Throws outside one — use {@link useCheckboxGroupContext} where the group is
+ * optional, as the checkbox itself does.
+ */
+export function useCheckboxGroup(): CheckboxGroupContextValue {
+	const context = useCheckboxGroupContext();
+	if (!context) {
+		throw new Error("useCheckboxGroup must be called inside a <Checkbox.Group>.");
+	}
+	return context;
+}