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

package/src/components/bottom-sheet/bottom-sheet.variants.ts

@@ -13,45 +13,23 @@ export const BOTTOM_SHEET_OVERLAY_TOKEN = "overlay";
 /**
  * The backdrop's opacity at full appearance.
  *
- * **1, not gorhom's 0.5.** The alpha lives in `--overlay`, so leaving the
- * library default in place would multiply the two and land the scrim at roughly
- * a fifth of what the theme asked for. One source for the alpha, and it is the
- * token — which is also what lets the two theme variants differ.
+ * **1.** The alpha lives in `--overlay`, so any other number here would multiply
+ * against it and land the scrim somewhere the theme did not ask for. One source
+ * for the alpha, and it is the token — which is also what lets the two theme
+ * variants differ.
  */
 export const BOTTOM_SHEET_OVERLAY_OPACITY = 1;
 
 /**
- * The snap indices the scrim appears and disappears on.
+ * The snap point indices the scrim appears and disappears on.
  *
- * gorhom defaults to `{ appearsOnIndex: 1, disappearsOnIndex: 0 }`, which suits
- * a persistent sheet that rests collapsed on the screen and only dims the app
- * once it is expanded. A modal sheet has no resting state: it is either
- * presented or gone, so the scrim belongs from the FIRST snap point (`0`) and
- * is only absent when the sheet is closed (`-1`).
+ * A modal sheet has no resting state: it is either presented or gone, so the
+ * scrim belongs from the FIRST snap point (`0`) and is only absent when the sheet
+ * is closed (`-1`). These are the engine's own defaults too; they are named
+ * here so the test that pins them has something to read.
  */
 export const BOTTOM_SHEET_BACKDROP_INDICES = { appearsOnIndex: 0, disappearsOnIndex: -1 } as const;
 
-/**
- * Keyboard behaviour every `BottomSheet.Container` starts from.
- *
- * A const rather than three defaults spelled inline, so `bun test` pins them and
- * a retune is one edit rather than three.
- *
- * - `interactive` — the sheet grows to keep its content above the keyboard,
- *   following it frame by frame rather than snapping once it has settled.
- * - `restore` — blurring returns the sheet to the snap point it was on. Without
- *   it a sheet that grew for the keyboard stays grown over empty screen.
- * - `adjustResize` — gorhom's own default is `adjustPan`, which leaves the
- *   Android window height alone and slides the whole view up, so a sheet's
- *   footer lands off-screen. `resize` is already what Expo configures and what
- *   `KeyboardProvider` requires, so this is the value that matches the window.
- */
-export const BOTTOM_SHEET_KEYBOARD_DEFAULTS = {
-	keyboardBehavior: "interactive",
-	keyboardBlurBehavior: "restore",
-	android_keyboardInputMode: "adjustResize",
-} as const;
-
 /**
  * Slop around `BottomSheet.Close`.
  *
@@ -62,22 +40,23 @@ export const BOTTOM_SHEET_KEYBOARD_DEFAULTS = {
 export const BOTTOM_SHEET_CLOSE_HIT_SLOP = 8;
 
 /**
- * The padding a pinned footer keeps whatever the keyboard is doing.
+ * The padding a pinned footer's measured box carries.
  *
- * A number rather than a `p-4`, and for `SCREEN_FOOTER_PADDING`'s reason: the
- * footer's bottom padding is an animated value — the safe-area band collapses
- * into it as the keyboard arrives — and a class cannot carry one. Its top
- * padding is written the same way so the two cannot drift.
+ * A number rather than a `p-4`, because it is handed to the engine's `padding`
+ * prop: the engine measures the footer's inner box into the dynamic snap point,
+ * and padding written there is counted where a class on the outer view would
+ * not be. The horizontal gutter still comes from the `stickyFooter` slot, which
+ * is merged after it.
  */
 export const BOTTOM_SHEET_FOOTER_PADDING = 16;
 
 /**
  * The gap between the last of the content and a pinned footer.
  *
- * Also a number, because the reserve it belongs to is computed at runtime from
- * the footer's measured height. Without it the last row of a list sits flush
- * against the footer's hairline, which reads as content clipped rather than
- * content ended.
+ * Also a number, because it is the engine's `footerGap` — added to the spacer it
+ * reserves under the body from the footer's measured height. Without it the last
+ * row of a list sits flush against the footer's hairline, which reads as content
+ * clipped rather than content ended.
  */
 export const BOTTOM_SHEET_FOOTER_GAP = 16;
 
@@ -85,7 +64,7 @@ export const bottomSheetVariants = tv({
 	slots: {
 		/**
 		 * The scrim. Carries the colour and nothing else — the fade is an animated
-		 * opacity gorhom drives off the sheet's own position.
+		 * opacity the engine drives off the sheet's own index.
 		 */
 		overlay: "bg-overlay",
 		/**
@@ -94,7 +73,8 @@ export const bottomSheetVariants = tv({
 		 * surface token nothing else in the package had claimed.
 		 *
 		 * Only the top corners round. The bottom edge runs off the screen, and a
-		 * radius there shows as two notches of the app behind it.
+		 * radius there shows as two notches of the app behind it. The `detached`
+		 * variant is the exception — a floating card has a visible bottom edge.
 		 */
 		background: "rounded-t-2xl bg-popover",
 		handle: "items-center justify-center pt-3 pb-1",
@@ -102,6 +82,14 @@ export const bottomSheetVariants = tv({
 		content: "gap-4 px-screen-gutter pt-2",
 		/** A scrollable body's content container. Same treatment as `content`. */
 		scrollContent: "gap-4 px-screen-gutter pt-2",
+		/**
+		 * A multi-step body. The gutter only: the engine measures each `Step`, not
+		 * the box around the stack, so vertical padding here would be height the
+		 * sheet never counts.
+		 */
+		steps: "px-screen-gutter",
+		/** One step of a multi-step body — `content` less the gutter `steps` already carries. */
+		step: "gap-4 pt-2",
 		footer: "gap-3 px-screen-gutter pt-4",
 		/**
 		 * A pinned footer draws OVER the content, so unlike the inline one it has
@@ -110,9 +98,8 @@ export const bottomSheetVariants = tv({
 		 * to overlap blank space. The same reason `Screen.Footer`'s backing lives
 		 * inside its sticky view.
 		 *
-		 * It carries no vertical padding: that is an animated style, because the
-		 * safe-area band inside it collapses as the keyboard arrives. See
-		 * {@link BOTTOM_SHEET_FOOTER_PADDING}.
+		 * It carries no vertical padding: that is the engine's `padding` prop, so
+		 * the measured box counts it. See {@link BOTTOM_SHEET_FOOTER_PADDING}.
 		 */
 		stickyFooter: "gap-3 border-border border-t bg-popover px-screen-gutter",
 		close: "absolute top-4 right-4 z-10",
@@ -131,90 +118,27 @@ export const bottomSheetVariants = tv({
 		 */
 		title: "pr-8",
 	},
+	variants: {
+		/**
+		 * A floating card. Every corner is on screen, so every corner rounds;
+		 * `rounded-2xl` replaces `rounded-t-2xl` through tailwind-merge rather
+		 * than stacking beside it.
+		 */
+		detached: {
+			true: {
+				background: "rounded-2xl",
+			},
+		},
+	},
 });
 
 /**
- * There is no `description` or `scrollView` slot.
+ * There is no `description`, `panel`, `portal` or `scrollView` slot.
  *
- * Neither has any layout of its own — a description is a `Text.Paragraph` in a
- * gap column and a scroll view fills whatever it is given — and `tv` emits
- * `undefined` for a slot whose class string is empty, so a slot that says
- * nothing is a slot no test can assert against. Those two parts merge the
- * caller's `className` with `cn()` instead.
+ * None has any layout of its own — a description is a `Text.Paragraph` in a
+ * gap column, the panel is a transparent frame the engine positions, a scroll
+ * view fills whatever it is given — and `tv` emits `undefined` for a slot whose
+ * class string is empty, so a slot that says nothing is a slot no test can
+ * assert against. Those parts merge the caller's `className` with `cn()` instead.
  */
 export type BottomSheetVariantProps = VariantProps<typeof bottomSheetVariants>;
-
-/** Where a `BottomSheet.Footer` among a container's children has to be rendered. */
-export type BottomSheetFooterPlacement = "sticky" | "inline" | "none";
-
-/** One child of a `BottomSheet.Container`, reduced to what the placement turns on. */
-export type BottomSheetFooterFlag = {
-	isFooter: boolean;
-	isSticky: boolean;
-};
-
-/**
- * Whether a container's children hold a footer, and where it has to go.
- *
- * gorhom takes a footer as a `footerComponent` render prop rather than as a
- * child, so a sticky one has to be lifted out of the tree it was written in and
- * handed over; an inline one simply stays put. This is the decision, kept pure
- * so `bun test` reaches the whole matrix — the walk over `Children.toArray` that
- * produces the flags lives with its caller, the way `withIndicator` does in
- * `radio.tsx`.
- *
- * A single sticky footer anywhere in the children wins, because two footers is
- * not a state worth expressing and the pinned one is the one a caller meant.
- */
-export function resolveFooterPlacement(flags: readonly BottomSheetFooterFlag[]): BottomSheetFooterPlacement {
-	let hasFooter = false;
-
-	for (const flag of flags) {
-		if (!flag.isFooter) continue;
-		if (flag.isSticky) return "sticky";
-		hasFooter = true;
-	}
-
-	return hasFooter ? "inline" : "none";
-}
-
-/**
- * The safe-area band `BottomSheet.Content` and `BottomSheet.ScrollView` reserve.
- *
- * Exactly one thing in the sheet pays for the home indicator. A pinned footer is
- * the bottom-most thing there is, and its own box carries the band so its surface
- * reaches the bottom of the screen — gorhom then adds that whole measured height
- * to the content's reserve, so the content asking for the band as well would
- * count it twice and leave a gap the height of the indicator above the footer.
- * With no pinned footer the content IS the bottom-most thing and takes it.
- */
-export function resolveSheetBottomInset({
-	hasStickyFooter,
-	bottom,
-}: {
-	hasStickyFooter: boolean;
-	bottom: number;
-}): number {
-	return hasStickyFooter ? 0 : bottom;
-}
-
-/**
- * The padding at the end of `BottomSheet.ScrollView`'s content.
- *
- * A scroll view does not reserve a pinned footer the way `BottomSheet.Content`
- * does — its FRAME stops at the footer's top edge instead, so the scroll
- * indicator and the overscroll bounce end there too rather than running on
- * underneath it. That leaves the content only the gap to hold it off the
- * footer's hairline. With no pinned footer the content is the bottom-most thing
- * in the sheet and takes the safe-area band, as {@link resolveSheetBottomInset}
- * has it.
- */
-export function resolveSheetScrollEndPadding({
-	hasStickyFooter,
-	bottom,
-}: {
-	hasStickyFooter: boolean;
-	bottom: number;
-}): number {
-	return hasStickyFooter ? BOTTOM_SHEET_FOOTER_GAP : resolveSheetBottomInset({ bottom, hasStickyFooter });
-}

package/src/components/bottom-sheet/index.ts

@@ -1,40 +1,62 @@
-export { BottomSheet, type BottomSheetProps } from "./bottom-sheet";
 export {
-	type BottomSheetContainerContextValue,
-	BottomSheetContainerProvider,
+	type BottomSheetAnimatedValue,
 	type BottomSheetContextValue,
-	type BottomSheetHandle,
-	type BottomSheetPortalContextValue,
-	BottomSheetPortalProvider,
-	BottomSheetProvider,
+	type BottomSheetHostProps,
+	type BottomSheetPortalProps,
+	type BottomSheetRef,
+	type BottomSheetRegistryValue,
+	type BottomSheetTextInputHandlers,
+	defineSheetMachine,
+	type SheetEvent,
+	type SheetMachine,
+	type SheetMachineConfig,
+	type SheetMachineSnapshot,
+	type SheetStepController,
+	type SheetStepTransition,
 	useBottomSheet,
-	useBottomSheetContainerContext,
-	useBottomSheetContext,
-	useBottomSheetPortalContext,
-} from "./bottom-sheet.context";
+	useBottomSheetAnimated,
+	useBottomSheetRegistry,
+	useBottomSheetTextInput,
+	useOptionalBottomSheet,
+	useOptionalBottomSheet as useBottomSheetContext,
+	useSheetMachine,
+	useSheetStep,
+} from "@delacour/react-native-bottom-sheet";
+export { resolveSheetBottomInset, resolveSheetScrollEndPadding } from "@delacour/react-native-bottom-sheet/core";
+export { BottomSheet, type BottomSheetProps } from "./bottom-sheet";
 export {
 	BOTTOM_SHEET_BACKDROP_INDICES,
 	BOTTOM_SHEET_CLOSE_HIT_SLOP,
 	BOTTOM_SHEET_FOOTER_GAP,
 	BOTTOM_SHEET_FOOTER_PADDING,
-	BOTTOM_SHEET_KEYBOARD_DEFAULTS,
 	BOTTOM_SHEET_OVERLAY_OPACITY,
 	BOTTOM_SHEET_OVERLAY_TOKEN,
-	type BottomSheetFooterFlag,
-	type BottomSheetFooterPlacement,
 	type BottomSheetVariantProps,
 	bottomSheetVariants,
-	resolveFooterPlacement,
-	resolveSheetBottomInset,
 } from "./bottom-sheet.variants";
+export type { BottomSheetBackgroundProps } from "./bottom-sheet-background";
 export type { BottomSheetCloseProps } from "./bottom-sheet-close";
 export type { BottomSheetContainerProps } from "./bottom-sheet-container";
 export type { BottomSheetContentProps } from "./bottom-sheet-content";
 export type { BottomSheetDescriptionProps } from "./bottom-sheet-description";
+export type { BottomSheetFlatListProps } from "./bottom-sheet-flat-list";
 export type { BottomSheetFooterProps } from "./bottom-sheet-footer";
+export type { BottomSheetHandleProps } from "./bottom-sheet-handle";
+export type { BottomSheetLegendListProps } from "./bottom-sheet-legend-list";
 export type { BottomSheetOverlayProps } from "./bottom-sheet-overlay";
-export type { BottomSheetPortalProps } from "./bottom-sheet-portal";
+export { BottomSheetProvider, type BottomSheetProviderProps } from "./bottom-sheet-provider";
 export type { BottomSheetScrollViewProps } from "./bottom-sheet-scroll-view";
+export type { BottomSheetSectionListProps } from "./bottom-sheet-section-list";
+export type { BottomSheetStepProps, BottomSheetStepsProps } from "./bottom-sheet-steps";
+export type { BottomSheetTextInputProps } from "./bottom-sheet-text-input";
 export type { BottomSheetTitleProps } from "./bottom-sheet-title";
 export type { BottomSheetTriggerProps } from "./bottom-sheet-trigger";
 export { type BottomSheetInputHandlers, useBottomSheetInput } from "./use-bottom-sheet-input";
+
+/**
+ * The imperative handle a `BottomSheet` ref exposes.
+ *
+ * @deprecated The engine's name is `BottomSheetRef`; this alias stays for the
+ * callers that typed the old name and goes with the next major.
+ */
+export type BottomSheetHandle = import("@delacour/react-native-bottom-sheet").BottomSheetRef;

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

@@ -1,125 +1,26 @@
-import { useBottomSheetInternal } from "@gorhom/bottom-sheet";
-import { type RefCallback, useCallback, useRef } from "react";
-import { type BlurEvent, type FocusEvent, findNodeHandle, TextInput } from "react-native";
+import { type BottomSheetTextInputHandlers, useBottomSheetTextInput } from "@delacour/react-native-bottom-sheet";
 
-/**
- * `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>;
-};
+export type BottomSheetInputHandlers = BottomSheetTextInputHandlers;
 
 /**
- * Makes this package's `Input` behave like a text field the sheet owns.
+ * Registers a text field as the sheet's own, so the keyboard it raises is the
+ * sheet's to lift for.
  *
- * Spread the result onto any `TextInput` inside a `BottomSheet`:
+ * The engine's `useBottomSheetTextInput()` under the name this library shipped
+ * it as. Spread the result onto any `Input` or `TextInput`:
  *
  * ```tsx
- * <Input {...useBottomSheetInput()} placeholder="Name" />
+ * const sheetInput = useBottomSheetInput();
+ * <Input {...sheetInput} 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:
+ * All three handlers matter: `ref` puts the field's native node in the sheet's
+ * registry, `onFocus` claims the keyboard, and `onBlur` gives it up — unless
+ * focus moved to another registered field in the same sheet, which is what
+ * keeps a tap from one field to the next from reading as a close and a reopen.
+ * Outside a sheet the handlers are inert, so a form shared between a screen
+ * and a sheet needs no branch.
  *
- * - `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>
+ * `BottomSheet.TextInput` is this over `Input`, for the plain case.
  */
-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 };
-}
+export const useBottomSheetInput: () => BottomSheetInputHandlers = useBottomSheetTextInput;

package/src/components/button/AGENTS.md

@@ -194,20 +194,54 @@ for a chunk that says something rather than doing something. An
 - **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
+  `gap` while attached — 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.
+- **`isAttached={false}` shares the props and drops the shape.** A toolbar of
+  `Find · Export · Share` wants one `variant` and one `size` without becoming a
+  segmented control. Detached, `resolveGroupPositions` places every member
+  `only` — the lone member's existing position, which draws the lone button's
+  `rounded-button-*` — rather than minting a fourth sentinel, and
+  `resolveGroupSeams` returns no seams, so nothing overlaps into the gap. The gap
+  is `gap-2` on either axis, a `tv` variant on the `group` slot and never inline.
+  `Button.Group.Separator` still renders, as a rule between spaced members.
+- **A detached member presses with `scale` again.** The fade exists only because
+  a scaling member tears its seam, and a detached run has none.
+  `resolveButtonFeedback` takes `isAttached` as a fourth argument, defaulting to
+  `true`, rather than turning into an options object: its positional signature
+  is public, `Input` and the existing tests call it, and the new rung is the only
+  thing that changed.
+- **`isFullWidth` splits the parent equally, not by content.** A
+  `Monthly · Annual · One-off` picker sized to its labels moves its dividers when
+  the copy changes, and a wider segment reads as more important. The group trades
+  `self-start` for `w-full self-stretch` — declared after `orientation` in
+  `buttonVariants`, so tailwind-merge drops `self-start` rather than keeping it —
+  and every member of a horizontal run gets `flex-1 basis-0`. **`basis-0` is the
+  part that matters**: with `flex-1` alone Yoga shares out only the space left
+  after each member's content width, and the widths still follow the labels.
+- **A member learns it stretches from context, as `isStretched`.**
+  `resolveGroupMemberStretch` decides it once per group, it rides on the
+  per-member context beside `position` and `isSeamed`, and `Button` feeds it to
+  an `isStretched` variant on its own `tv`. No `cloneElement`, for the reason
+  above. A caller's `className="flex-none"` on one member still wins — the
+  variant is merged before the caller's class. `Button.Group.Text` and the
+  separator do **not** stretch: a caption and a rule keep their content width
+  and the buttons share what is left. `Input` does not read it yet; a caller
+  sizes a joined field with its own `className`.
+- **`isFullWidth` on a vertical group widens the group and does nothing else.**
+  Its members already stretch on the cross axis, and `basis-0` on the main axis
+  of a column with no definite height would collapse every member to nothing —
+  so `isStretched` is `false` there by construction.
+- **Horizontal groups are content-width by default** (`self-start`), because
+  that is what a segmented control is. `isFullWidth` fills the parent — **and the
+  parent must have 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 `isFullWidth`. 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
@@ -215,3 +249,9 @@ for a chunk that says something rather than doing something. An
   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.
+
+- **`material="etched"` is opt-in and per fill.** `primary` takes `shadow-etched-primary` (a white
+  inset top edge at 16%); `secondary`, `tertiary` and `outline` take the light/dark edge
+  (`shadow-etched dark:shadow-etched-dark`); `ghost`, `destructive` and `destructive-soft` stay flat
+  — a ghost has no surface to lift and a signal colour does not take a second highlight. The press
+  scale is already 0.97. The tokens live in `tokens.css`.

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

@@ -13,6 +13,7 @@ import {
 	type ButtonSize,
 	type ButtonVariant,
 	buttonVariants,
+	resolveGroupMemberStretch,
 	resolveGroupPositions,
 	resolveGroupSeams,
 } from "./button.variants";
@@ -30,6 +31,18 @@ export type ButtonGroupProps = ViewProps & {
 	isDisabled?: boolean;
 	/** Press treatment for every member. Unset, a joined member fades rather than scaling. */
 	feedback?: PressableFeedback;
+	/**
+	 * Join the members into one shape. On by default, because that is what a group is. Off keeps the
+	 * inherited `variant` / `size` / `isDisabled` / `feedback` and drops the joined shape: every
+	 * member keeps its own corner, no seam overlap, and the run takes a `gap`.
+	 */
+	isAttached?: boolean;
+	/**
+	 * Span the parent and split it equally between members. Horizontal only — a vertical group
+	 * already stretches its members, so there it only widens the group. The parent needs a
+	 * definite width.
+	 */
+	isFullWidth?: boolean;
 	className?: string;
 	children?: ReactNode;
 };
@@ -40,13 +53,15 @@ function ButtonGroupRoot({
 	variant,
 	isDisabled,
 	feedback,
+	isAttached = true,
+	isFullWidth = false,
 	className,
 	children,
 	...props
 }: ButtonGroupProps): ReactElement {
 	const group = useMemo<ButtonGroupContextValue>(
-		() => ({ feedback, isDisabled, orientation, size, variant }),
-		[feedback, isDisabled, orientation, size, variant]
+		() => ({ feedback, isAttached, isDisabled, isFullWidth, orientation, size, variant }),
+		[feedback, isAttached, isDisabled, isFullWidth, orientation, size, variant]
 	);
 
 	const items = useMemo(() => Children.toArray(children), [children]);
@@ -56,17 +71,18 @@ function ButtonGroupRoot({
 	// the members' order actually change.
 	const values = useMemo(() => {
 		const isMember = items.map(isGroupMember);
-		const positions = resolveGroupPositions(isMember);
-		const seams = resolveGroupSeams(isMember);
+		const positions = resolveGroupPositions(isMember, group);
+		const seams = resolveGroupSeams(isMember, group);
+		const isStretched = resolveGroupMemberStretch(group);
 
 		return positions.map<ButtonGroupItemContextValue | null>((position, index) =>
-			position === null ? null : { ...group, isSeamed: seams[index] === true, position }
+			position === null ? null : { ...group, isSeamed: seams[index] === true, isStretched, position }
 		);
 	}, [items, group]);
 
 	return (
 		<ButtonGroupProvider value={group}>
-			<View className={buttonVariants({ orientation }).group({ className })} {...props}>
+			<View className={buttonVariants({ isAttached, isFullWidth, orientation }).group({ className })} {...props}>
 				{items.map((child, index) => {
 					const value = values[index];
 					if (!value) return child;
@@ -130,8 +146,14 @@ function keyOf(child: ReactNode, index: number): string {
  * 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.
+ * Horizontal groups are content-width. `isFullWidth` spans the parent and
+ * splits it equally between members — `flex-1 basis-0` on each, published as
+ * `isStretched` on the member's context — whatever their labels say. The parent
+ * needs a definite width for there to be anything to split.
+ *
+ * `isAttached={false}` keeps the shared axes and drops the shape: every member
+ * draws its own corner, nothing overlaps, the run takes a gap, and an unset
+ * `feedback` goes back to the lone button's `scale`.
  *
  * @example
  * <Button.Group variant="outline">
@@ -141,6 +163,20 @@ function keyOf(child: ReactNode, index: number): string {
  * </Button.Group>
  *
  * @example
+ * <Button.Group isAttached={false} size="sm" variant="outline">
+ *   <Button onPress={find}>Find</Button>
+ *   <Button onPress={exportFile}>Export</Button>
+ *   <Button onPress={share}>Share</Button>
+ * </Button.Group>
+ *
+ * @example
+ * <Button.Group isFullWidth variant="outline">
+ *   <Button onPress={monthly}>Monthly</Button>
+ *   <Button onPress={annual}>Annual</Button>
+ *   <Button onPress={once}>One-off</Button>
+ * </Button.Group>
+ *
+ * @example
  * <Button.Group>
  *   <Button onPress={save}>Save</Button>
  *   <Button.Group.Separator />