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

package/src/components/bottom-sheet/use-bottom-sheet-input.ts

@@ -0,0 +1,125 @@
+import { useBottomSheetInternal } from "@gorhom/bottom-sheet";
+import { type RefCallback, useCallback, useRef } from "react";
+import { type BlurEvent, type FocusEvent, findNodeHandle, TextInput } from "react-native";
+
+/**
+ * `findNodeHandle` for a value React Native's own types do not admit.
+ *
+ * `TextInput.State.currentlyFocusedInput()` returns a Fabric host instance, and
+ * the shipped signature still describes the pre-Fabric parameter — the runtime
+ * accepts it, which is what gorhom's own `BottomSheetTextInput` relies on. One
+ * cast, in one place, rather than at each call.
+ */
+function nodeHandleOf(instance: unknown): number | null {
+	return findNodeHandle(instance as Parameters<typeof findNodeHandle>[0]);
+}
+
+export type BottomSheetInputHandlers = {
+	onFocus: (event: FocusEvent) => void;
+	onBlur: (event: BlurEvent) => void;
+	ref: RefCallback<TextInput | null>;
+};
+
+/**
+ * Makes this package's `Input` behave like a text field the sheet owns.
+ *
+ * Spread the result onto any `TextInput` inside a `BottomSheet`:
+ *
+ * ```tsx
+ * <Input {...useBottomSheetInput()} placeholder="Name" />
+ * ```
+ *
+ * A sheet only knows to grow for the keyboard when it knows the focused field is
+ * one of its own. gorhom ships `BottomSheetTextInput` to register that, but
+ * reaching for it here would mean this library's `Input` — its variants, its
+ * `Input.Group`, its invalid and disabled cascade — could not be used inside a
+ * sheet at all. So the registration is exposed as handlers instead, and `Input`
+ * keeps knowing nothing about `@gorhom/bottom-sheet`.
+ *
+ * Three props, and all three are load-bearing:
+ *
+ * - `ref` registers the field's native node with the sheet. Without it, moving
+ *   focus from one field in the sheet to the next reads as the keyboard closing
+ *   and reopening, and the sheet resizes twice on the way.
+ * - `onFocus` tells the sheet which field to keep clear of the keyboard.
+ * - `onBlur` gives that up again, unless focus went to another field in the same
+ *   sheet.
+ *
+ * Called outside a sheet it returns inert handlers rather than throwing, so a
+ * form component shared between a screen and a sheet needs no branch.
+ *
+ * It covers the keyboard half only. A *drag* across a field can still be claimed
+ * by the sheet's content pan, because gorhom's input is built on Gesture
+ * Handler's `TextInput` and this one is not; if that ever bites, the fix is
+ * `enableContentPanningGesture={false}` on the `BottomSheet.Container`. The
+ * *tap* half — a scrim that used to swallow the press meant for the field — is
+ * solved in `BottomSheet.Overlay`, not here.
+ *
+ * @example
+ * <Field>
+ *   <Field.Label>Name</Field.Label>
+ *   <Input {...useBottomSheetInput()} onChangeText={setName} value={name} />
+ * </Field>
+ */
+export function useBottomSheetInput(): BottomSheetInputHandlers {
+	const internal = useBottomSheetInternal(true);
+	// The node this field last registered, so the ref can withdraw exactly it.
+	// A JS ref rather than a shared value: nothing renders differently for it.
+	const registeredNodeRef = useRef<number | null>(null);
+
+	const ref = useCallback<RefCallback<TextInput | null>>(
+		(instance) => {
+			const nodes = internal?.textInputNodesRef.current;
+			const previous = registeredNodeRef.current;
+
+			if (previous !== null) {
+				nodes?.delete(previous);
+				registeredNodeRef.current = null;
+				if (internal !== null && internal.animatedKeyboardState.get().target === previous) {
+					internal.animatedKeyboardState.set((state) => ({ ...state, target: undefined }));
+				}
+			}
+
+			if (instance === null || nodes === undefined) return;
+
+			const node = nodeHandleOf(instance);
+			if (node === null) return;
+
+			nodes.add(node);
+			registeredNodeRef.current = node;
+		},
+		[internal]
+	);
+
+	const onFocus = useCallback(
+		(event: FocusEvent) => {
+			if (internal === null) return;
+			const target = event.nativeEvent.target;
+			internal.animatedKeyboardState.set((state) => ({ ...state, target }));
+		},
+		[internal]
+	);
+
+	const onBlur = useCallback(
+		(event: BlurEvent) => {
+			if (internal === null) return;
+
+			const target = event.nativeEvent.target;
+			const isThisFieldsTarget = internal.animatedKeyboardState.get().target === target;
+			if (!isThisFieldsTarget) return;
+
+			// React Native's own focus registry, not the sheet's: focus may already
+			// have moved to the next field in the same sheet, and giving the target
+			// up there would close and reopen the sheet's keyboard allowance between
+			// two taps that never dismissed the keyboard.
+			const focused = TextInput.State.currentlyFocusedInput();
+			const focusedNode = focused === null ? null : nodeHandleOf(focused);
+			if (focusedNode !== null && internal.textInputNodesRef.current.has(focusedNode)) return;
+
+			internal.animatedKeyboardState.set((state) => ({ ...state, target: undefined }));
+		},
+		[internal]
+	);
+
+	return { onBlur, onFocus, ref };
+}

package/src/components/button/AGENTS.md

@@ -0,0 +1,217 @@
+# Button
+
+A pressable action, composed from parts rather than configured by flags —
+compound root plus `Button.Label`, `Button.StartContent` and `Button.EndContent`,
+and `Button.Group` for joining several into one run.
+The reference implementation for the patterns in the package
+[AGENTS.md](../../../AGENTS.md).
+
+`import { Button } from "@delacour/react-native-ui/button";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/button` |
+| `button.tsx` | Root + the `Object.assign` compound surface |
+| `button-label.tsx` | `Button.Label` |
+| `button-start-content.tsx` | `Button.StartContent` |
+| `button-end-content.tsx` | `Button.EndContent` |
+| `button-group.tsx` | `Button.Group` + its `Object.assign` compound surface |
+| `button-group-separator.tsx` | `Button.Group.Separator` |
+| `button-group-text.tsx` | `Button.Group.Text` |
+| `button.context.tsx` | `ButtonContext` and the two group contexts, with their hooks |
+| `button.types.ts` | Prop types shared by two or more parts |
+| `button.variants.ts` | Pure `tv()` slots, no RN imports |
+| `button.variants.test.ts` | |
+
+## Design
+
+- **Variants**: `primary`, `secondary`, `tertiary`, `outline`, `ghost`,
+  `destructive`, `destructive-soft`. **Sizes**: `sm`, `md`, `lg`, and the square
+  `icon-sm`, `icon-md`, `icon-lg`.
+- **Icons are composed, never passed as props.** Put an `Icon` in the children,
+  before or after the label. The button wraps its subtree in an
+  `IconDefaultsProvider` carrying `buttonVariants({ size }).icon()` and
+  `BUTTON_FOREGROUND_TOKEN[variant]`, so a bare `<Icon icon={IconPlus} />`
+  comes out the right size and colour with nothing said at the call site. An
+  explicit `size` or `color` on the icon still wins. `Button.StartContent` /
+  `Button.EndContent` remain for wrapping non-icon content.
+- **The corner is a token on the size axis crossed with the group axis, and
+  nothing else sets one.** A button standing alone names
+  `rounded-button-{step}` — half its own height, so it is a capsule, and a
+  circle at a square size. Keeping it out of the base and off every variant
+  means exactly one corner *statement* reaches the root, so a caller's
+  `className="rounded-lg"` has a single thing to beat and tailwind-merge is
+  never picking between two. The shape is a default rather than a law: three
+  numbers in `tokens.css` square the whole kit off without touching a
+  component. Values above half the height are clamped by the renderer, which is
+  why `tokens.test.ts` holds them under it.
+- **A square footprint is a size, not a flag.** `icon-sm` / `icon-md` /
+  `icon-lg` are `sm` / `md` / `lg` with the horizontal padding traded for a width
+  off the same token. Padding and width are then mutually exclusive by
+  construction rather than by rule, which is what let an `isIconOnly` axis and
+  six compound variants reconciling it against `size` be deleted outright. It is
+  also shadcn's spelling (rule 11), so `size="icon-md"` pastes across. Always
+  pair one with an `accessibilityLabel`; there is no text for a screen reader to
+  fall back on.
+- **String children** are wrapped in a `Button.Label` automatically. React
+  Native crashes on bare text outside a `<Text>`, so never render a raw string
+  in a component that accepts free-form children without doing the same. Note
+  that *consecutive* strings collapse into one label — `Row {i}` is a single
+  piece of text, and wrapping each part separately would space them apart by
+  the button's own `gap`.
+- **A button is a [`Pressable`](../pressable/AGENTS.md).** `ButtonProps` extends
+  `PressableProps`, so `feedback`, `haptic` and the rest are inherited rather
+  than restated; only the default differs, `scale`. It carried a narrowed
+  `ButtonFeedback` union for a while — that is gone, because a second definition
+  of a prop the button does not change is a definition that can drift. **Do not
+  add ripple, ink, glow or highlight overlays** — no wash layers on pressables
+  in this library. That rule is about wash layers, not the opacity axis, which
+  `fade` and `scale-fade` are welcome to use.
+- **`isLoading` replaces the icon on its own side, it does not join it.** The
+  spinner takes the place of the composed `Icon` at the edge `spinnerPlacement`
+  names — the first child at `start`, the last at `end` — so the label does not
+  shift when work begins and shift back when it ends. The swap costs no layout
+  because both glyphs are drawn at the button's own `size-icon-*` token: the
+  root publishes one class and the icon and the spinner both read it. **An icon
+  on the other side is not taken.** A button with one leading icon and
+  `spinnerPlacement="end"` keeps the icon and gains a spinner at the end; taking
+  the only icon whichever side it sat on used to draw the spinner opposite the
+  side that was asked for. With no icon at that edge the spinner is inserted, as
+  it always was. Only a bare `Icon` is swapped; a `Button.StartContent` wraps
+  content of unknown height, and replacing one could resize the button.
+  `resolveSpinnerSwapIndex` is the pure decision and is unit-tested.
+- **`isLoading`** composes a `Spinner` in and blocks presses. Placement is
+  `spinnerPlacement`: `start` (default), `end`, or `only` — which drops the
+  children and centres the spinner in the footprint the button already has,
+  carrying the label onto `accessibilityLabel` so a screen reader still has a
+  name to read. `only` never changes the footprint — a square is a `size`, and
+  loading cannot reach one; use `size="icon-md"` when a square is what you want.
+- **Loading is not disabled.** `isLoading` blocks the press and announces the
+  button as *busy*, but keeps full contrast: the spinner already says the press
+  landed, and dimming reads as "this control is unavailable". `isDimmedWhileLoading`
+  opts into the faded treatment where a caller wants it.
+- **A stretched button does not change width while loading**, because `only`
+  keeps its footprint. In a *content-width* container — a `flex-row` — it still
+  shrinks to the spinner, and that snap is un-animated on purpose: Pressable's
+  `Animated.View` already runs a `useAnimatedStyle` on `opacity` and `transform`,
+  and a native layout transition on the same view fights it for prop ownership.
+  A caller who needs a stable width in a row pins it (`w-full`, `min-w-*`).
+- **A definite width defeats `alignItems: stretch`.** A stretch-aligned child
+  with a definite cross size resolves to cross-*start*, not centre — so any
+  control that conditionally takes a fixed width inside a gap column jumps to
+  the left edge unless it also sets `self-center`. This is what made an earlier
+  `only` implementation collapse a full-width button into a small box flush
+  left. Prefer not taking the width at all.
+
+## Button.Group
+
+Several controls joined into one run: `<Button.Group>` around the buttons, with
+`Button.Group.Separator` for a rule between two of them and `Button.Group.Text`
+for a chunk that says something rather than doing something. An
+[`Input`](../input/AGENTS.md) joins the same way.
+
+- **Position is computed in JavaScript, because React Native has no sibling
+  selector.** shadcn/ui squares a web button group's inner corners with
+  `[&>[data-slot]~[data-slot]]:rounded-l-none` and drops the seam border with
+  `border-l-0`. Neither selector exists here, and no parent `View` can reach a
+  child's style. So the root walks its children, works out each member's place
+  with `resolveGroupPositions`, and publishes it through a per-child context the
+  member reads. A provider is not a host component, so nothing is added to the
+  layout — Yoga sees exactly the children the group's `View` already had.
+- **A member wrapped in a context, never cloned with props.** `cloneElement`
+  reaches only a *direct* child, so a member a caller wrapped in a `View` or
+  produced from a helper would silently keep its round corners. Context reaches
+  any depth, which is also what lets a control this package has never heard of
+  join a run by reading `useButtonGroupItem()`.
+- **A joined member replaces its corner; it never layers a squaring class over
+  it.** This is the subtle one. Layering *renders* correctly — Uniwind
+  arbitrates a className string per style property in token order, and React
+  Native's corner cascade puts a per-corner radius above the uniform one — but
+  tailwind-merge annihilates a side class the moment any all-corner class is
+  emitted after it, and `tv` emits variants in declaration order. A surviving
+  `rounded-button-md` on the size axis would therefore delete the squaring pair
+  as soon as someone reordered two keys in `buttonVariants`, with nothing to see
+  in the diff. `cn.test.ts` pins the asymmetry in both directions.
+- **Horizontal squares on the logical axis; vertical squares on the physical
+  one. Never mix them.** `rounded-s-*` / `rounded-e-*` compile to
+  `border-start-start-radius` and friends, survive lightningcss, and flip under
+  RTL — which is what a horizontal run wants. Tailwind's `rounded-t-*` /
+  `rounded-b-*` are physical and need no flip. React Native resolves a physical
+  corner *above* a logical one, so a stray `rounded-t-*` on a horizontal member
+  would silently outrank the `rounded-s-*` beside it and round the wrong edge. A
+  test asserts neither orientation emits the other's form.
+- **The seam is a negative margin, not a dropped border.** Two adjacent
+  `outline` members would otherwise draw a two-point seam. `-ms-px` / `-mt-px`
+  pulls each member back over its neighbour so the two borders land as one
+  hairline. `border-s-0` was the alternative and is wrong twice: the base
+  reserves `border border-transparent` precisely so switching variant never
+  resizes the box, and dropping a point would make one member narrower than the
+  rest and shift its centred content half a point — and it would only be right
+  for the variants that draw a visible border, which the group cannot know
+  because a member may name its own. A margin moves the box and changes nothing
+  about it, so it is emitted for every seamed member regardless of paint.
+- **A separator takes no position and suppresses the seam after it.** It is a
+  rule, not a segment, so the buttons either side of one are still the run's
+  first and last and keep their rounded outer corners. And the member following
+  it does not overlap: a one-point rule under a one-point overlap is an
+  invisible rule. `resolveGroupPositions` and `resolveGroupSeams` are two walks
+  rather than one because they ask different questions — "how many of us are
+  there" and "what is immediately before me" — and both are pure, so the whole
+  matrix is reachable from `bun test`.
+- **Membership is a deny-list.** Anything that is not a separator is a member.
+  Not `child.type === Button`, for two reasons: it lets a custom control join,
+  and it means `button-group.tsx` never imports its own root for an identity
+  check — which would close a cycle (package AGENTS.md rule 3).
+- **A joined member fades rather than scaling.** `feedback` defaults to `scale`
+  on a lone button, which pulls a member's edges in by a point and a half while
+  its neighbours hold still — the seam the group exists to close tears open for
+  the length of the press. `resolveButtonFeedback` runs the usual nearest-wins
+  ladder (`own ?? group ?? default`) and only changes the last rung, so a caller
+  still gets `scale` by asking for it on one button or on the whole group.
+  `??` rather than `||`, so an explicit `none` is honoured instead of read as an
+  absence. `pressedScale` still beats both — that is `resolvePressedState`'s
+  documented contract and a second rule contradicting it would be worse than the
+  tear.
+- **The group owns the axes because it owns the shape.** `size` all but
+  outright, and `variant`, `isDisabled` and `feedback` as defaults a member may
+  override. Those three are published **raw**, so `undefined` means "the group
+  said nothing" and one member can disable itself inside a group that did not.
+  `Button`'s `variant` and `size` therefore come out of its destructure
+  *undefaulted*; a default there would swallow the group before it was ever
+  consulted.
+- **A group owns a member's step, but not its shape.** Those are one axis now
+  that a square footprint is a size rather than a flag, so resolving `size` to
+  the group's value outright would make a square member impossible inside a run:
+  the icon button ending a split button would silently grow a label's padding
+  and lose its width. `resolveGroupedButtonSize` therefore takes the step from
+  the group — controls of different heights do not join — and the shape from the
+  member, falling back to the group's shape when the member names no size. An
+  `icon-md` member of an `sm` group comes out `icon-sm`: square, and the same
+  height as everything beside it. A control with no square form of its own reads
+  `resolveButtonSizeStep` instead, which is exactly what a joined `Input` does.
+- **The group paints nothing.** No background, no border, no disabled fade. A
+  disabled group publishes `isDisabled` and each member fades itself; a group
+  fading as well would compound the two down to a quarter opacity. It carries no
+  `gap` either — a gap is the seam this component exists to close — and no
+  `overflow-hidden`, which would square off the very corners the position
+  compounds just rounded.
+- **No `accessibilityRole` on the group.** Announcing a control with no action
+  in front of every member helps nobody; the members are already buttons.
+- **Horizontal groups are content-width** (`self-start`), because that is what a
+  segmented control is. For a run that fills its parent, put `className="w-full"`
+  on the group and `className="flex-1"` on each member — **and make sure the
+  parent has a definite width**. Yoga resolves a percentage against the parent's
+  content box, so `w-full` inside a container that is itself content-sized
+  resolves to nothing and falls back to the content width: the group collapses
+  onto its buttons and a `flex-1` field between them is squeezed to a few points.
+  It looks like the group ignored `w-full`. It did not; there was no width to
+  take a percentage of.
+- **`Button.Group.Text` draws the button's own chrome**, not chrome of its own,
+  which is what keeps its height, padding and corner identical to the buttons
+  beside it — those come off one axis, and restating any of them here is how a
+  row stops lining up three tokens later. It falls back to `secondary` rather
+  than `primary` when nothing names a variant: a chunk that cannot be pressed
+  should not wear the group's action paint. A group that *does* name a variant
+  is followed, so an outline run reads as one piece.

package/src/components/button/button-end-content.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ButtonSlotProps } from "./button.types";
+import { buttonVariants } from "./button.variants";
+
+/**
+ * A centred wrapper for trailing content that is not an `Icon`.
+ *
+ * An `Icon` needs no wrapper — it inherits the button's icon size and its
+ * variant's colour from the root's `IconDefaultsProvider`.
+ */
+export function ButtonEndContent({ className, ...props }: ButtonSlotProps): ReactElement {
+	return <View className={buttonVariants().endContent({ className })} {...props} />;
+}
+ButtonEndContent.displayName = "DelacourUI.Button.EndContent";

package/src/components/button/button-group-separator.tsx

@@ -0,0 +1,37 @@
+import type { ReactElement } from "react";
+import { Separator } from "../separator";
+import { useButtonGroupPart } from "./button.context";
+import { BUTTON_GROUP_SEPARATOR_ORIENTATION, buttonVariants } from "./button.variants";
+
+export type ButtonGroupSeparatorProps = {
+	className?: string;
+};
+
+/**
+ * A rule between two members of a group.
+ *
+ * Runs across the group rather than along it — a line drawn along the run would
+ * sit under the members instead of between them — so it reads the group's
+ * orientation and inverts it. That inversion is a map in `button.variants.ts`
+ * rather than a `SeparatorOrientation` here, because that type lives beside a
+ * React Native import and the variants file has to stay parseable by `bun test`.
+ *
+ * A separator is deliberately **not** a member: it consumes no position, so the
+ * buttons either side of one are still the group's first and last and keep their
+ * rounded outer corners. It also suppresses the seam of the member after it — a
+ * one-point rule under a one-point overlap would be an invisible rule.
+ *
+ * The line takes its length from this wrapper, since a `Separator` is
+ * `self-stretch` on its long axis rather than a percentage of its parent.
+ */
+export function ButtonGroupSeparator({ className }: ButtonGroupSeparatorProps): ReactElement {
+	const { orientation } = useButtonGroupPart("Button.Group.Separator");
+
+	return (
+		<Separator
+			className={buttonVariants({ orientation }).groupSeparator({ className })}
+			orientation={BUTTON_GROUP_SEPARATOR_ORIENTATION[orientation]}
+		/>
+	);
+}
+ButtonGroupSeparator.displayName = "DelacourUI.Button.Group.Separator";

package/src/components/button/button-group-text.tsx

@@ -0,0 +1,101 @@
+import { Children, type ReactElement, type ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { IconDefaultsProvider } from "../icon";
+import { Text } from "../text";
+import { TextClassProvider } from "../text/text.context";
+import { useButtonGroupItemContext } from "./button.context";
+import {
+	BUTTON_FOREGROUND_TOKEN,
+	type ButtonVariant,
+	buttonVariants,
+	resolveGroupedButtonSize,
+} from "./button.variants";
+
+export type ButtonGroupTextProps = ViewProps & {
+	/** Paint for the chunk. Falls back to the group's, then to `secondary`. */
+	variant?: ButtonVariant;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * A chunk of a group that says something rather than doing something.
+ *
+ * A member like any other — it reads the same item context a `Button` does, so
+ * it squares the corners crossing its seams and overlaps its neighbour without
+ * knowing anything about where it sits.
+ *
+ * It draws the button's own chrome rather than chrome of its own, which is what
+ * keeps its height, padding and corner identical to the buttons beside it: those
+ * five values come off one axis in `buttonVariants`, and restating any of them
+ * here is how a row stops lining up three tokens later.
+ *
+ * `secondary` rather than `primary` when nothing names a variant, because a
+ * chunk that cannot be pressed should not wear the group's action paint. A group
+ * that *does* name one is followed, so an outline group reads as one piece.
+ *
+ * Bare text children are wrapped in a `Text`, since React Native cannot render a
+ * string outside one. Composed content inherits the same icon size and label
+ * treatment a button publishes, so an `Icon` beside the text needs nothing.
+ */
+export function ButtonGroupText({ variant, className, children, ...props }: ButtonGroupTextProps): ReactElement {
+	const item = useButtonGroupItemContext();
+	const resolvedVariant = variant ?? item?.variant ?? "secondary";
+	const slots = buttonVariants({
+		groupPosition: item?.position ?? "none",
+		isSeamed: item?.isSeamed ?? false,
+		orientation: item?.orientation ?? "horizontal",
+		size: resolveGroupedButtonSize(undefined, item?.size),
+		variant: resolvedVariant,
+	});
+
+	const label = slots.label();
+
+	return (
+		<View className={slots.root({ className })} {...props}>
+			<IconDefaultsProvider value={{ className: slots.icon(), color: BUTTON_FOREGROUND_TOKEN[resolvedVariant] }}>
+				<TextClassProvider value={label}>{wrapTextChildren(children, label)}</TextClassProvider>
+			</IconDefaultsProvider>
+		</View>
+	);
+}
+ButtonGroupText.displayName = "DelacourUI.Button.Group.Text";
+
+/**
+ * Wraps bare text children in a `Text`.
+ *
+ * React Native cannot render a string outside a `<Text>`, so
+ * `<Button.Group.Text>3 of 7</Button.Group.Text>` would otherwise crash.
+ * Consecutive strings and numbers are collected into a single one rather than
+ * one each — `Page {n}` is one piece of text, and wrapping the parts separately
+ * would space them apart by the root's gap.
+ *
+ * Lives beside its caller rather than in the group's root, which inserts
+ * nothing: a helper follows the component that uses it.
+ */
+function wrapTextChildren(children: ReactNode, className: string): ReactNode {
+	const output: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		output.push(
+			<Text className={className} key={`label-${output.length}`}>
+				{run.join("")}
+			</Text>
+		);
+		run = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output;
+}

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

@@ -0,0 +1,158 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import type { PressableFeedback } from "../pressable/pressable.variants";
+import { Separator } from "../separator";
+import {
+	type ButtonGroupContextValue,
+	type ButtonGroupItemContextValue,
+	ButtonGroupItemProvider,
+	ButtonGroupProvider,
+} from "./button.context";
+import {
+	type ButtonGroupOrientation,
+	type ButtonSize,
+	type ButtonVariant,
+	buttonVariants,
+	resolveGroupPositions,
+	resolveGroupSeams,
+} from "./button.variants";
+import { ButtonGroupSeparator } from "./button-group-separator";
+import { ButtonGroupText } from "./button-group-text";
+
+export type ButtonGroupProps = ViewProps & {
+	/** Which way the group runs. Members square the corners crossing the run. */
+	orientation?: ButtonGroupOrientation;
+	/** Shared by every member — controls of different heights do not join. */
+	size?: ButtonSize;
+	/** A default every member takes unless it names its own. */
+	variant?: ButtonVariant;
+	/** Disables every member that does not say otherwise. */
+	isDisabled?: boolean;
+	/** Press treatment for every member. Unset, a joined member fades rather than scaling. */
+	feedback?: PressableFeedback;
+	className?: string;
+	children?: ReactNode;
+};
+
+function ButtonGroupRoot({
+	orientation = "horizontal",
+	size = "md",
+	variant,
+	isDisabled,
+	feedback,
+	className,
+	children,
+	...props
+}: ButtonGroupProps): ReactElement {
+	const group = useMemo<ButtonGroupContextValue>(
+		() => ({ feedback, isDisabled, orientation, size, variant }),
+		[feedback, isDisabled, orientation, size, variant]
+	);
+
+	const items = useMemo(() => Children.toArray(children), [children]);
+
+	// One memo for the whole array rather than a hook per child, which a `.map()`
+	// cannot have. A member's value is a new object only when the group's axes or
+	// the members' order actually change.
+	const values = useMemo(() => {
+		const isMember = items.map(isGroupMember);
+		const positions = resolveGroupPositions(isMember);
+		const seams = resolveGroupSeams(isMember);
+
+		return positions.map<ButtonGroupItemContextValue | null>((position, index) =>
+			position === null ? null : { ...group, isSeamed: seams[index] === true, position }
+		);
+	}, [items, group]);
+
+	return (
+		<ButtonGroupProvider value={group}>
+			<View className={buttonVariants({ orientation }).group({ className })} {...props}>
+				{items.map((child, index) => {
+					const value = values[index];
+					if (!value) return child;
+					return (
+						<ButtonGroupItemProvider key={keyOf(child, index)} value={value}>
+							{child}
+						</ButtonGroupItemProvider>
+					);
+				})}
+			</View>
+		</ButtonGroupProvider>
+	);
+}
+
+/**
+ * Whether a child takes a position in the group.
+ *
+ * A deny-list rather than a check for `Button`, for two reasons. It lets any
+ * control join a group and style itself from `useButtonGroupItem()` — the whole
+ * point of the library's `useX()` hooks — and it means this file never imports
+ * its own root for an identity check, which would close a cycle (AGENTS.md rule
+ * 3).
+ *
+ * A hand-placed `Separator` is excluded alongside the group's own, the same
+ * tolerance `ListGroup` extends to one.
+ */
+function isGroupMember(child: ReactNode): boolean {
+	return isValidElement(child) && child.type !== ButtonGroupSeparator && child.type !== Separator;
+}
+
+/**
+ * A stable key for a wrapped child.
+ *
+ * `Children.toArray` has already assigned every child a key, so the wrapper
+ * reuses it rather than minting an index-based one — a group whose members are
+ * reordered or conditionally rendered would otherwise remount them.
+ */
+function keyOf(child: ReactNode, index: number): string {
+	return isValidElement(child) && child.key !== null ? child.key : `member-${index}`;
+}
+
+/**
+ * Several controls joined into one run, sharing a corner and a seam.
+ *
+ * The group owns the axes because it owns the shape: `size` outright, since
+ * controls of different heights do not join, and `variant`, `isDisabled` and
+ * `feedback` as defaults a member may still override. Those three are published
+ * raw, so `undefined` means "the group said nothing" and one member can disable
+ * itself inside a group that did not.
+ *
+ * Each member is wrapped in a context provider carrying its place in the run.
+ * That indirection is forced: React Native has no sibling selector, so the CSS
+ * shadcn/ui uses on the web — `[&>[data-slot]~[data-slot]]:rounded-l-none` —
+ * has no counterpart here and position has to be computed in JavaScript. A
+ * provider is not a host component, so nothing is added to the layout.
+ *
+ * A member squares the corners crossing each seam and overlaps its neighbour by
+ * a point, so two adjacent borders draw as one hairline. A group of one is
+ * indistinguishable from the control on its own.
+ *
+ * The group paints nothing itself — no background, no border, no disabled fade.
+ * A fade here would compound with the members' own down to a quarter opacity.
+ *
+ * Horizontal groups are content-width. For a run that fills its parent, put
+ * `className="w-full"` on the group and `className="flex-1"` on each member.
+ *
+ * @example
+ * <Button.Group variant="outline">
+ *   <Button onPress={archive}>Archive</Button>
+ *   <Button onPress={report}>Report</Button>
+ *   <Button onPress={snooze}>Snooze</Button>
+ * </Button.Group>
+ *
+ * @example
+ * <Button.Group>
+ *   <Button onPress={save}>Save</Button>
+ *   <Button.Group.Separator />
+ *   <Button accessibilityLabel="More" size="icon-md" onPress={openMenu}>
+ *     <Icon icon={IconChevronDown} />
+ *   </Button>
+ * </Button.Group>
+ */
+export const ButtonGroup = Object.assign(ButtonGroupRoot, {
+	/** A rule between two members. Takes no position, so the ends stay rounded. */
+	Separator: ButtonGroupSeparator,
+	/** A chunk that says something rather than doing something, joined like any member. */
+	Text: ButtonGroupText,
+	displayName: "DelacourUI.Button.Group",
+});