@delacour/react-native-ui 0.1.0-alpha.20260925062901 → 0.1.0-alpha.20260925063207

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925062901",
+	"version": "0.1.0-alpha.20260925063207",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -41,6 +41,7 @@
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
 		"./chip": "./src/components/chip/index.ts",
+		"./collapsible": "./src/components/collapsible/index.ts",
 		"./empty-state": "./src/components/empty-state/index.ts",
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
@@ -91,7 +92,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925062901",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925063207",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/collapsible/AGENTS.md

@@ -0,0 +1,92 @@
+# Collapsible
+
+One section of content, shown and hidden by its own trigger. Compound root plus
+`Collapsible.Trigger`, `Collapsible.Title`, `Collapsible.Description`,
+`Collapsible.Indicator` and `Collapsible.Content`. It is a single
+[Accordion](../accordion/AGENTS.md) item without the group — the same row, the
+same measured panel, the same spring — so read that file's **The measured panel**
+section first. What follows is only where a standalone disclosure differs.
+
+`import { Collapsible } from "@delacour/react-native-ui/collapsible";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/collapsible` |
+| `collapsible.tsx` | Root — owns the open state, `progress`, the measured height and the spring; the `Object.assign` |
+| `collapsible-trigger.tsx` | `Collapsible.Trigger`, and the row it assembles from its children |
+| `collapsible-title.tsx` | `Collapsible.Title` |
+| `collapsible-description.tsx` | `Collapsible.Description` |
+| `collapsible-indicator.tsx` | `Collapsible.Indicator`, the one rotation |
+| `collapsible-content.tsx` | `Collapsible.Content` — the measured clip |
+| `collapsible.context.tsx` | `CollapsibleContext`, `useCollapsible` and the internal part hook |
+| `collapsible.types.ts` | `CollapsibleTextProps`, shared by the title, description and trigger |
+| `collapsible.variants.ts` | Pure `tv()` slots, the constants, the toggle and the accessibility resolver — no RN imports |
+| `collapsible.variants.test.ts` | |
+
+## Design
+
+- **It looks exactly like a one-item `Accordion`, and a test holds it there.**
+  Variants (`default`, `secondary`, `tertiary`, `transparent`), sizes (`sm`,
+  `md`, `lg`), the trigger's metrics, the type scale, the glyph step and the
+  panel's inset are `Accordion`'s class for class. A collapsible and an accordion
+  on one screen are the same control at two scales; if either retunes, the test
+  fails until the other follows.
+- **Its constants are restated, not imported from `../accordion`.** The registry
+  derives an item's dependencies from its imports, so importing even the
+  accordion's leaf would make `delacour add collapsible` copy an accordion in
+  too. The spring, fade, rotation, variants, sizes and glyph step are written
+  again here and pinned equal by `collapsible.variants.test.ts` — the test file
+  is the only thing that imports both, and tests are not shipped.
+- **The root owns the state and the travel.** With no item layer, what
+  `Accordion.Item` owns — `progress`, `contentHeight`, the spring, the
+  `onMeasured` re-run counter — lives on the root. The race that counter closes
+  (`onLayout` landing either side of React's effects) is the same one, so the
+  panel reports its first measurement and never starts the spring itself.
+- **The disabled fade lands on the root.** Never on the trigger, which is a
+  `Pressable` whose `Animated.View` writes `opacity` every frame; the accordion
+  fades its item for the same reason, and a collapsible's root is its item.
+
+## State
+
+- **`isOpen` / `defaultOpen` / `onOpenChange`, `BottomSheet`'s names.** One
+  boolean through `useControllableState`, so it is controlled or uncontrolled
+  from one hook and `onOpenChange` hears the trigger and `toggle()` alike.
+- **Disabled refuses the tap in both directions.** `toggleCollapsibleOpen`
+  returns the current state while disabled, so a disabled section that is open
+  stays open. A disabled control is one that cannot be used, not one that undoes
+  itself. The trigger is also a disabled `Pressable`; the pure rule is the second
+  line, and it is what keeps a caller's own `useCollapsible().toggle()` honest.
+- **A refused toggle reports nothing.** The root compares the next state with
+  the current and skips `setOpen`, so `onOpenChange` never fires for a change
+  that did not happen.
+- **`toggle` and the change callback are ref-backed**, so the context keeps its
+  identity across a caller passing a fresh arrow. `Accordion`'s trampoline.
+
+## The trigger
+
+- **A `Pressable` with `fade` and `haptic="selection"`**, `Accordion.Trigger`'s
+  two defaults for its two reasons. `onPress` is `Omit`ed: the press *is* the
+  toggle, and a side effect belongs on `onOpenChange`, which also hears changes
+  the trigger never sees.
+- **It assembles its own row** — bare strings become one `Collapsible.Title`,
+  titles and descriptions stack in a column, anything else stays on the row, and
+  the indicator moves to the end or is composed in when absent. Same rule, same
+  limitation: an indicator must be a *direct* `Collapsible.Indicator` child, so
+  the indicator takes a render function (`({ isOpen }) => …`) rather than asking
+  for a wrapper.
+
+## Accessibility
+
+- **`resolveCollapsibleAccessibility` is the one source.** The trigger announces
+  `expanded` and `disabled` from it; the panel takes
+  `accessibilityElementsHidden` and `importantForAccessibility` from it. Pure, so
+  `bun test` holds the matrix.
+- **A closed panel is out of the tree, not just clipped.** It stays mounted after
+  its first open, and mounted content is content a screen reader reads. A
+  disabled but open panel is still on screen and still read.
+- **The root is a plain `View` with no role**, the accordion's rule.
+- **Reduce motion is Reanimated's default `System` policy.** With it on, the
+  spring completes instantly: the panel snaps between its two states. The state
+  is carried by whether the panel is there, so that is the right degradation.

package/src/components/collapsible/collapsible-content.tsx

@@ -0,0 +1,100 @@
+import { type ReactElement, type ReactNode, useCallback, useState } from "react";
+import { type LayoutChangeEvent, StyleSheet, View, type ViewProps } from "react-native";
+import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
+import { useCollapsiblePart } from "./collapsible.context";
+import {
+	COLLAPSIBLE_CONTENT_FADE,
+	COLLAPSIBLE_UNMEASURED,
+	collapsibleVariants,
+	resolveCollapsibleAccessibility,
+} from "./collapsible.variants";
+
+export type CollapsibleContentProps = Omit<ViewProps, "style"> & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The body the trigger discloses.
+ *
+ * **Its height is measured and animated, never laid out.** The outer view clips,
+ * and its height runs from zero to whatever the inner view reported, so the
+ * animation lives on this one node and whatever sits below follows it through
+ * ordinary layout — nothing on the screen has to opt into anything.
+ *
+ * **The content mounts on first open and stays mounted**, so a form keeps what was
+ * typed and a list keeps where it was scrolled across every later close. A closed
+ * panel is therefore taken out of the accessibility tree and stops taking touches,
+ * rather than merely clipped to zero.
+ *
+ * It reports its first measurement and never starts the travel itself — the root
+ * owns the spring alone. See `onMeasured` on the context.
+ *
+ * `className` lands on the inner, measured layer, so padding set there is part of
+ * what the panel measures.
+ */
+export function CollapsibleContent({ className, children, ...props }: CollapsibleContentProps): ReactElement {
+	const { contentHeight, isDisabled, isOpen, onMeasured, progress, size } = useCollapsiblePart("Collapsible.Content");
+	const slots = collapsibleVariants({ size });
+	const { content: a11y } = resolveCollapsibleAccessibility({ isDisabled, isOpen });
+
+	// Adjusted during render rather than in an effect, so the panel mounts in the
+	// same commit as the tap that opened it.
+	const [hasOpened, setHasOpened] = useState(isOpen);
+	if (isOpen && !hasOpened) setHasOpened(true);
+
+	const [isMeasured, setMeasured] = useState(false);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const wasMeasured = contentHeight.value > COLLAPSIBLE_UNMEASURED;
+			contentHeight.value = event.nativeEvent.layout.height;
+			if (wasMeasured) return;
+			setMeasured(true);
+			onMeasured();
+		},
+		[contentHeight, onMeasured]
+	);
+
+	const clipStyle = useAnimatedStyle(() => ({
+		height: progress.value * Math.max(contentHeight.value, 0),
+		opacity: interpolate(
+			progress.value,
+			[0, COLLAPSIBLE_CONTENT_FADE.start, COLLAPSIBLE_CONTENT_FADE.end, 1],
+			[0, 0, 1, 1]
+		),
+	}));
+
+	// Never `auto` while measuring: the clip is stretched over the collapsible for
+	// that commit, and an invisible layer over the trigger is a tap that goes nowhere.
+	const pointerEvents = isOpen && isMeasured ? "auto" : "none";
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden={a11y.accessibilityElementsHidden}
+			className={slots.content()}
+			importantForAccessibility={a11y.importantForAccessibility}
+			pointerEvents={pointerEvents}
+			style={isMeasured ? clipStyle : collapsibleStyleSheet.measuring}
+		>
+			{hasOpened ? (
+				<View className={slots.contentInner({ className })} onLayout={handleLayout} {...props}>
+					{children}
+				</View>
+			) : null}
+		</Animated.View>
+	);
+}
+CollapsibleContent.displayName = "DelacourUI.Collapsible.Content";
+
+const collapsibleStyleSheet = StyleSheet.create({
+	/**
+	 * What the clip wears until the panel has reported a height.
+	 *
+	 * Absolutely positioned and transparent, so nothing on screen moves while it
+	 * measures — and deliberately not `height: 0`, because an out-of-flow child
+	 * mounted into a zero-height parent never fires `onLayout` at all. Found on a
+	 * simulator by `Accordion.Content`, which carries the same sheet.
+	 */
+	measuring: { bottom: 0, left: 0, opacity: 0, position: "absolute", right: 0, top: 0 },
+});

package/src/components/collapsible/collapsible-description.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCollapsiblePart } from "./collapsible.context";
+import type { CollapsibleTextProps } from "./collapsible.types";
+import { collapsibleVariants } from "./collapsible.variants";
+
+/**
+ * The trigger's secondary line, a step down in scale and on the muted token.
+ *
+ * Stacks under the title inside the column the trigger assembles, so the two
+ * need no wrapper part between them.
+ */
+export function CollapsibleDescription({ className, ...props }: CollapsibleTextProps): ReactElement {
+	const { size } = useCollapsiblePart("Collapsible.Description");
+	return <Text className={collapsibleVariants({ size }).description({ className })} {...props} />;
+}
+CollapsibleDescription.displayName = "DelacourUI.Collapsible.Description";

package/src/components/collapsible/collapsible-indicator.tsx

@@ -0,0 +1,92 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import type { ViewProps } from "react-native";
+import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
+import { IconChevronBottom } from "../../icons/central";
+import { Icon, type IconDefaults, IconDefaultsProvider } from "../icon";
+import { useCollapsiblePart } from "./collapsible.context";
+import {
+	COLLAPSIBLE_INDICATOR_ROTATION,
+	COLLAPSIBLE_INDICATOR_TOKEN,
+	collapsibleVariants,
+} from "./collapsible.variants";
+
+/** What a render-function indicator is handed. */
+export type CollapsibleIndicatorState = { isOpen: boolean };
+
+export type CollapsibleIndicatorProps = Omit<ViewProps, "children" | "style"> & {
+	/**
+	 * Turn with the panel. Set `false` for a glyph that *swaps* rather than
+	 * rotates — a plus becoming a minus reads as broken when it also spins.
+	 */
+	isAnimated?: boolean;
+	className?: string;
+	/**
+	 * A glyph, or a function handed the settled state.
+	 *
+	 * The function form exists so a swapping glyph needs no component of its own.
+	 * The trigger finds its indicator by element type, so one wrapped in a
+	 * component of the caller's own is invisible to it and a second, default one is
+	 * composed in beside it — handing the state over removes the reason to write
+	 * that wrapper.
+	 */
+	children?: ReactNode | ((state: CollapsibleIndicatorState) => ReactNode);
+};
+
+/**
+ * The glyph saying the section opens, turning as it does.
+ *
+ * Composed into a trigger that holds none, so a bare `<Collapsible.Trigger>` is
+ * already complete.
+ *
+ * **The rotation interpolates off the collapsible's own `progress`**, the value
+ * the panel's height reads, so the glyph and the panel are in phase by
+ * construction — and a custom glyph turns exactly like the default one. The
+ * rotation lives on this node rather than the trigger's because `Pressable`
+ * already owns `transform` there.
+ *
+ * @example
+ * <Collapsible.Indicator isAnimated={false}>
+ *   {({ isOpen }) => <Icon icon={isOpen ? IconMinusSmall : IconPlusSmall} />}
+ * </Collapsible.Indicator>
+ */
+export function CollapsibleIndicator({
+	isAnimated = true,
+	className,
+	children,
+	...props
+}: CollapsibleIndicatorProps): ReactElement {
+	const { isOpen, progress, size } = useCollapsiblePart("Collapsible.Indicator");
+
+	const slots = collapsibleVariants({ size });
+	const glyphClassName = slots.glyph();
+
+	const rotationStyle = useAnimatedStyle(() => ({
+		transform: [
+			{
+				rotate: `${interpolate(
+					progress.value,
+					[0, 1],
+					[COLLAPSIBLE_INDICATOR_ROTATION.collapsed, COLLAPSIBLE_INDICATOR_ROTATION.expanded]
+				)}deg`,
+			},
+		],
+	}));
+
+	const iconDefaults = useMemo<IconDefaults>(
+		() => ({ className: glyphClassName, color: COLLAPSIBLE_INDICATOR_TOKEN }),
+		[glyphClassName]
+	);
+
+	return (
+		<Animated.View className={slots.indicator({ className })} style={isAnimated ? rotationStyle : undefined} {...props}>
+			<IconDefaultsProvider value={iconDefaults}>{renderGlyph(children, isOpen)}</IconDefaultsProvider>
+		</Animated.View>
+	);
+}
+CollapsibleIndicator.displayName = "DelacourUI.Collapsible.Indicator";
+
+/** The caller's glyph, the state they asked for, or the default chevron. */
+function renderGlyph(children: CollapsibleIndicatorProps["children"], isOpen: boolean): ReactNode {
+	if (typeof children === "function") return children({ isOpen });
+	return children ?? <Icon icon={IconChevronBottom} />;
+}

package/src/components/collapsible/collapsible-title.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useCollapsiblePart } from "./collapsible.context";
+import type { CollapsibleTextProps } from "./collapsible.types";
+import { collapsibleVariants } from "./collapsible.variants";
+
+/**
+ * The trigger's primary line — what the section is called.
+ *
+ * Carries its own colour and type scale, read from the collapsible's context: a
+ * React Native `View` does not cascade colour to a `Text` descendant.
+ */
+export function CollapsibleTitle({ className, ...props }: CollapsibleTextProps): ReactElement {
+	const { size } = useCollapsiblePart("Collapsible.Title");
+	return <Text className={collapsibleVariants({ size }).title({ className })} {...props} />;
+}
+CollapsibleTitle.displayName = "DelacourUI.Collapsible.Title";

package/src/components/collapsible/collapsible-trigger.tsx

@@ -0,0 +1,133 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import { View } from "react-native";
+import { type IconDefaults, IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { useCollapsiblePart } from "./collapsible.context";
+import {
+	COLLAPSIBLE_FOREGROUND_TOKEN,
+	collapsibleVariants,
+	resolveCollapsibleAccessibility,
+} from "./collapsible.variants";
+import { CollapsibleDescription } from "./collapsible-description";
+import { CollapsibleIndicator } from "./collapsible-indicator";
+import { CollapsibleTitle } from "./collapsible-title";
+
+export type CollapsibleTriggerProps = Omit<PressableProps, "children" | "disabled" | "onPress"> & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The row that opens and closes the section.
+ *
+ * A `Pressable`, so `feedback`, `haptic` and the rest are inherited. Two defaults
+ * differ, for `Accordion.Trigger`'s reasons: `fade`, because a full-bleed row that
+ * scales reads as the whole card flexing, and `haptic="selection"`, because the
+ * press is a state toggle.
+ *
+ * `onPress` is `Omit`ed rather than forwarded: the press **is** the toggle, and a
+ * side effect belongs on the root's `onOpenChange`, which also hears a controlled
+ * change the trigger never sees.
+ *
+ * It assembles its own row — titles and descriptions stack in a column, anything
+ * else stays where it was written, an indicator moves to the end, and one is
+ * composed in when the children hold none.
+ */
+export function CollapsibleTrigger({
+	feedback = "fade",
+	haptic = "selection",
+	className,
+	children,
+	...props
+}: CollapsibleTriggerProps): ReactElement {
+	const { isDisabled, isOpen, size, toggle } = useCollapsiblePart("Collapsible.Trigger");
+	const { trigger: a11y } = resolveCollapsibleAccessibility({ isDisabled, isOpen });
+
+	const slots = collapsibleVariants({ size });
+	const columnClassName = slots.triggerContent();
+	const glyphClassName = slots.glyph();
+
+	const content = useMemo(() => composeRow(children, columnClassName), [children, columnClassName]);
+
+	const iconDefaults = useMemo<IconDefaults>(
+		() => ({ className: glyphClassName, color: COLLAPSIBLE_FOREGROUND_TOKEN }),
+		[glyphClassName]
+	);
+
+	return (
+		<Pressable
+			accessibilityState={{ expanded: a11y.expanded }}
+			className={slots.trigger({ className })}
+			disabled={a11y.disabled}
+			feedback={feedback}
+			haptic={haptic}
+			onPress={toggle}
+			{...props}
+		>
+			<IconDefaultsProvider value={iconDefaults}>{content}</IconDefaultsProvider>
+		</Pressable>
+	);
+}
+CollapsibleTrigger.displayName = "DelacourUI.Collapsible.Trigger";
+
+/**
+ * Arranges the trigger's children into its row.
+ *
+ * Bare strings become one `Collapsible.Title` (a raw string outside a `<Text>`
+ * red-boxes), titles and descriptions stack in a column, anything else stays on
+ * the row where it was written, and the indicator goes last — composed in when
+ * there is none. `Accordion.Trigger`'s arrangement, rule for rule.
+ */
+function composeRow(children: ReactNode, columnClassName: string): ReactNode {
+	const items = Children.toArray(children);
+	const row: ReactNode[] = [];
+	const trailing: ReactNode[] = [];
+	let column: ReactNode[] = [];
+	let run: (string | number)[] = [];
+	let hasIndicator = false;
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		column.push(<CollapsibleTitle key={`title-${column.length}`}>{run.join("")}</CollapsibleTitle>);
+		run = [];
+	};
+
+	const flushColumn = () => {
+		if (column.length === 0) return;
+		row.push(
+			<View className={columnClassName} key={`content-${row.length}`}>
+				{column}
+			</View>
+		);
+		column = [];
+	};
+
+	for (const child of items) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+
+		if (isValidElement(child) && child.type === CollapsibleIndicator) {
+			hasIndicator = true;
+			trailing.push(child);
+			continue;
+		}
+
+		if (isValidElement(child) && (child.type === CollapsibleTitle || child.type === CollapsibleDescription)) {
+			column.push(child);
+			continue;
+		}
+
+		flushColumn();
+		row.push(child);
+	}
+
+	flushRun();
+	flushColumn();
+
+	if (!hasIndicator) trailing.push(<CollapsibleIndicator key="indicator" />);
+
+	return [...row, ...trailing];
+}

package/src/components/collapsible/collapsible.context.tsx

@@ -0,0 +1,86 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { CollapsibleSize, CollapsibleVariant } from "./collapsible.variants";
+
+export type CollapsibleContextValue = {
+	variant: CollapsibleVariant;
+	size: CollapsibleSize;
+	/** The trigger is inert and the surface faded. An open section stays open. */
+	isDisabled: boolean;
+	/** Whether the panel is open, on the **JS thread** — what accessibility reads. */
+	isOpen: boolean;
+	/** Opens or closes the panel. Refused while disabled. Stable for the collapsible's lifetime. */
+	toggle: () => void;
+	/**
+	 * How far open the panel is, on the **UI thread**: `0` closed, `1` open.
+	 *
+	 * The one value every animated style reads — the panel's height, its opacity
+	 * and the indicator's rotation — so they cannot drift out of step by a frame.
+	 */
+	progress: SharedValue<number>;
+	/** The panel's natural height in points, or {@link COLLAPSIBLE_UNMEASURED} until it has reported. */
+	contentHeight: SharedValue<number>;
+	/**
+	 * Told by the panel that it has measured itself for the first time.
+	 *
+	 * Internal machinery: the root is the only owner of the spring, and this gives
+	 * its effect a reason to re-run once there is a height to travel against. The
+	 * panel cannot start the spring itself — `onLayout` lands either side of
+	 * React's effects, and a spring started there is sometimes cancelled by the
+	 * cleanup of the effect it raced. `Accordion.Item`'s `onMeasured`, verbatim.
+	 */
+	onMeasured: () => void;
+};
+
+const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+/**
+ * Supplies one collapsible's axes, state and shared values to its parts.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./collapsible` — which would close a cycle.
+ */
+export function CollapsibleProvider({
+	value,
+	children,
+}: {
+	value: CollapsibleContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <CollapsibleContext value={value}>{children}</CollapsibleContext>;
+}
+CollapsibleProvider.displayName = "DelacourUI.Collapsible.Provider";
+
+/** The enclosing collapsible's state, or null outside a `<Collapsible>`. */
+export function useCollapsibleContext(): CollapsibleContextValue | null {
+	return use(CollapsibleContext);
+}
+
+/**
+ * Reads the enclosing collapsible's state.
+ *
+ * What a custom child reaches for: `isOpen` to swap a glyph or a label,
+ * `progress` to animate against exactly the travel the panel is running, or
+ * `toggle` to open it from somewhere other than the trigger. Throws outside a
+ * `<Collapsible>` — use {@link useCollapsibleContext} where one is optional.
+ */
+export function useCollapsible(): CollapsibleContextValue {
+	const context = useCollapsibleContext();
+	if (!context) {
+		throw new Error("useCollapsible must be called inside a <Collapsible>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing collapsible's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useCollapsiblePart(component: string): CollapsibleContextValue {
+	const context = useCollapsibleContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Collapsible>.`);
+	}
+	return context;
+}

package/src/components/collapsible/collapsible.tsx

@@ -0,0 +1,165 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { View, type ViewProps } from "react-native";
+import { cancelAnimation, useSharedValue, withSpring } from "react-native-reanimated";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { type CollapsibleContextValue, CollapsibleProvider } from "./collapsible.context";
+import {
+	COLLAPSIBLE_DEFAULT_SIZE,
+	COLLAPSIBLE_DEFAULT_VARIANT,
+	COLLAPSIBLE_SPRING,
+	COLLAPSIBLE_UNMEASURED,
+	type CollapsibleSize,
+	type CollapsibleVariant,
+	collapsibleVariants,
+	toggleCollapsibleOpen,
+} from "./collapsible.variants";
+import { CollapsibleContent } from "./collapsible-content";
+import { CollapsibleDescription } from "./collapsible-description";
+import { CollapsibleIndicator } from "./collapsible-indicator";
+import { CollapsibleTitle } from "./collapsible-title";
+import { CollapsibleTrigger } from "./collapsible-trigger";
+
+export type CollapsibleProps = Omit<ViewProps, "children"> & {
+	variant?: CollapsibleVariant;
+	size?: CollapsibleSize;
+	/** Controlled open state. Leave it off and the collapsible holds its own. */
+	isOpen?: boolean;
+	/** Initial open state while uncontrolled. */
+	defaultOpen?: boolean;
+	/** Called with the next state whenever the trigger (or `toggle()`) opens or closes it. */
+	onOpenChange?: (isOpen: boolean) => void;
+	/**
+	 * Stops the trigger opening or closing it, fades the surface and announces the
+	 * trigger disabled. An open section stays open.
+	 */
+	isDisabled?: boolean;
+	className?: string;
+	children?: ReactNode;
+};
+
+function CollapsibleRoot({
+	variant = COLLAPSIBLE_DEFAULT_VARIANT,
+	size = COLLAPSIBLE_DEFAULT_SIZE,
+	isOpen: isOpenProp,
+	defaultOpen = false,
+	onOpenChange,
+	isDisabled = false,
+	className,
+	children,
+	...props
+}: CollapsibleProps): ReactElement {
+	// A ref-backed trampoline, so a caller passing a fresh arrow every render does
+	// not change the context's identity and re-render every part.
+	const changeRef = useRef(onOpenChange);
+	changeRef.current = onOpenChange;
+	const handleChange = useCallback((next: boolean) => changeRef.current?.(next), []);
+
+	const [isOpen, setOpen] = useControllableState<boolean>({
+		defaultValue: defaultOpen,
+		onChange: handleChange,
+		value: isOpenProp,
+	});
+
+	// Read by `toggle` rather than closed over, so one stable callback serves the
+	// collapsible for its whole life.
+	const stateRef = useRef({ isDisabled, isOpen });
+	stateRef.current = { isDisabled, isOpen };
+
+	const toggle = useCallback(() => {
+		const current = stateRef.current;
+		const next = toggleCollapsibleOpen(current);
+		// Refused: a disabled tap must not report an `onOpenChange` for a change
+		// that did not happen.
+		if (next === current.isOpen) return;
+		setOpen(next);
+	}, [setOpen]);
+
+	// Seeded from the settled state, so a collapsible mounted open does not
+	// animate itself open on its first paint.
+	const progress = useSharedValue(isOpen ? 1 : 0);
+	const contentHeight = useSharedValue(COLLAPSIBLE_UNMEASURED);
+
+	// Bumped the first time the panel reports a height, purely to re-run the
+	// effect below. See `onMeasured` on the context.
+	const [measurements, setMeasurements] = useState(0);
+	const onMeasured = useCallback(() => setMeasurements((count) => count + 1), []);
+
+	// The first open of a panel that has never mounted has no height to travel
+	// against, so that run bails and the measurement that follows brings it back.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `measurements` is the re-run trigger, see above
+	useEffect(() => {
+		if (isOpen && contentHeight.value === COLLAPSIBLE_UNMEASURED) return;
+
+		progress.value = withSpring(isOpen ? 1 : 0, COLLAPSIBLE_SPRING);
+
+		return () => cancelAnimation(progress);
+	}, [contentHeight, isOpen, measurements, progress]);
+
+	const context = useMemo<CollapsibleContextValue>(
+		() => ({ contentHeight, isDisabled, isOpen, onMeasured, progress, size, toggle, variant }),
+		[contentHeight, isDisabled, isOpen, onMeasured, progress, size, toggle, variant]
+	);
+
+	return (
+		<CollapsibleProvider value={context}>
+			<View className={collapsibleVariants({ isDisabled, size, variant }).root({ className })} {...props}>
+				{children}
+			</View>
+		</CollapsibleProvider>
+	);
+}
+
+/**
+ * One section of content, shown and hidden by its own trigger.
+ *
+ * The standalone form of an accordion item — the same row, the same measured
+ * panel, the same spring — for a single disclosure that belongs to nothing else:
+ * "Show details", an order summary, the advanced half of a form.
+ *
+ * **The panel's height is measured and animated**, so the animation lives on the
+ * panel's own node and whatever sits below follows it with nothing opted in. Its
+ * height, its fade and the indicator's rotation all run off one shared value, so
+ * they cannot drift by a frame, and a tap mid-travel reverses the spring rather
+ * than restarting it.
+ *
+ * **The panel mounts on first open and stays mounted**, so what was typed or
+ * scrolled inside it survives every later close. A closed panel is taken out of
+ * the accessibility tree and stops taking touches.
+ *
+ * **State works either way from one hook**: pass `isOpen` to control it, or
+ * `defaultOpen` (or nothing) and let it hold its own. `onOpenChange` hears both.
+ *
+ * `isDisabled` stops the trigger and fades the surface. It does not close a
+ * section that is already open — a disabled control is one that cannot be used,
+ * not one that undoes itself.
+ *
+ * @example
+ * <Collapsible>
+ *   <Collapsible.Trigger>
+ *     <Collapsible.Title>What is included</Collapsible.Title>
+ *     <Collapsible.Description>Three items</Collapsible.Description>
+ *   </Collapsible.Trigger>
+ *   <Collapsible.Content>
+ *     <Text.Paragraph>Unlimited projects, 100 GB of storage, email support.</Text.Paragraph>
+ *   </Collapsible.Content>
+ * </Collapsible>
+ *
+ * @example
+ * <Collapsible isOpen={isOpen} onOpenChange={setOpen} variant="transparent">
+ *   <Collapsible.Trigger>Advanced</Collapsible.Trigger>
+ *   <Collapsible.Content>{fields}</Collapsible.Content>
+ * </Collapsible>
+ */
+export const Collapsible = Object.assign(CollapsibleRoot, {
+	/** The row that opens the section. A `Pressable`, so it inherits the whole vocabulary. */
+	Trigger: CollapsibleTrigger,
+	/** The trigger's primary line. Bare string children become one automatically. */
+	Title: CollapsibleTitle,
+	/** The trigger's secondary line, stacked under the title. */
+	Description: CollapsibleDescription,
+	/** The glyph that turns as the panel opens. Composed in when a trigger holds none. */
+	Indicator: CollapsibleIndicator,
+	/** The measured, clipped panel. Mounts on first open and stays mounted. */
+	Content: CollapsibleContent,
+	displayName: "DelacourUI.Collapsible",
+});

package/src/components/collapsible/collapsible.types.ts

@@ -0,0 +1,9 @@
+import type { TextProps } from "react-native";
+
+/**
+ * The shape of the trigger's two text lines, `Title` and `Description`.
+ *
+ * Shared by both parts and by the trigger, which wraps bare string children in a
+ * `Collapsible.Title` — three modules, so it lives in a leaf.
+ */
+export type CollapsibleTextProps = TextProps & { className?: string };

package/src/components/collapsible/collapsible.variants.test.ts

@@ -0,0 +1,302 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { declarationCount } from "../../styles/theme-tokens.test";
+import {
+	ACCORDION_CONTENT_FADE,
+	ACCORDION_GLYPH_STEP,
+	ACCORDION_INDICATOR_ROTATION,
+	ACCORDION_SIZES,
+	ACCORDION_SPRING,
+	ACCORDION_VARIANTS,
+	accordionVariants,
+} from "../accordion/accordion.variants";
+import { ICON_SIZES } from "../icon/icon.variants";
+import {
+	COLLAPSIBLE_CONTENT_FADE,
+	COLLAPSIBLE_DEFAULT_SIZE,
+	COLLAPSIBLE_DEFAULT_VARIANT,
+	COLLAPSIBLE_FOREGROUND_TOKEN,
+	COLLAPSIBLE_GLYPH_STEP,
+	COLLAPSIBLE_INDICATOR_ROTATION,
+	COLLAPSIBLE_INDICATOR_TOKEN,
+	COLLAPSIBLE_SIZES,
+	COLLAPSIBLE_SPRING,
+	COLLAPSIBLE_UNMEASURED,
+	COLLAPSIBLE_VARIANTS,
+	collapsibleVariants,
+	resolveCollapsibleAccessibility,
+	toggleCollapsibleOpen,
+} from "./collapsible.variants";
+
+const TOKENS_CSS = readFileSync(join(import.meta.dirname, "../../styles/tokens.css"), "utf-8");
+
+/** The minimum a touch target may be, in points. Apple's number, and Android's. */
+const MINIMUM_TARGET = 44;
+
+/** Tailwind's spacing step, in points — `min-h-12` is twelve of them. */
+const SPACING_STEP = 4;
+
+/** A `--spacing-*` token's value in points, read from `tokens.css`. */
+function spacingPx(token: string): number {
+	const match = TOKENS_CSS.match(new RegExp(`--spacing-${token}:\\s*(\\d+)px`));
+	if (!match) throw new Error(`tokens.css declares no --spacing-${token}`);
+	return Number(match[1]);
+}
+
+/** A slot's class string, with `tv`'s empty-slot `undefined` flattened. */
+function cls(value: string | undefined): string {
+	return value ?? "";
+}
+
+/** The points a `px-4` / `min-h-14` utility resolves to. */
+function utilityPx(value: string, prefix: string): number {
+	const match = value.match(new RegExp(`\\b${prefix}-(\\d+(?:\\.\\d+)?)\\b`));
+	if (!match) throw new Error(`no \`${prefix}-*\` in "${value}"`);
+	return Number(match[1]) * SPACING_STEP;
+}
+
+type Size = (typeof COLLAPSIBLE_SIZES)[number];
+
+/** Every slot for one size, at the default variant, enabled. */
+function slotsFor(size: Size) {
+	return collapsibleVariants({ isDisabled: false, size, variant: COLLAPSIBLE_DEFAULT_VARIANT });
+}
+
+/** Every slot a `View` wears, for one size. A `Text` slot carries a treatment on purpose. */
+function viewSlots(size: Size): string[] {
+	const slots = slotsFor(size);
+	return [
+		cls(slots.root()),
+		cls(slots.trigger()),
+		cls(slots.triggerContent()),
+		cls(slots.indicator()),
+		cls(slots.content()),
+		cls(slots.contentInner()),
+	];
+}
+
+describe("toggleCollapsibleOpen", () => {
+	test("a tap flips the state", () => {
+		expect(toggleCollapsibleOpen({ isDisabled: false, isOpen: false })).toBe(true);
+		expect(toggleCollapsibleOpen({ isDisabled: false, isOpen: true })).toBe(false);
+	});
+
+	test("a disabled collapsible refuses the tap in both directions", () => {
+		// Disabled means the control cannot be used, not that it undoes itself: an
+		// open section stays open, and a closed one stays closed.
+		expect(toggleCollapsibleOpen({ isDisabled: true, isOpen: false })).toBe(false);
+		expect(toggleCollapsibleOpen({ isDisabled: true, isOpen: true })).toBe(true);
+	});
+});
+
+describe("resolveCollapsibleAccessibility", () => {
+	test("the trigger announces expanded and disabled from the settled state", () => {
+		expect(resolveCollapsibleAccessibility({ isDisabled: false, isOpen: true })).toEqual({
+			trigger: { disabled: false, expanded: true },
+			content: { accessibilityElementsHidden: false, importantForAccessibility: "auto" },
+		});
+	});
+
+	test("a closed panel is taken out of the accessibility tree", () => {
+		// The panel stays mounted after its first expand, so without this a screen
+		// reader would read out a section that is not on screen.
+		expect(resolveCollapsibleAccessibility({ isDisabled: false, isOpen: false }).content).toEqual({
+			accessibilityElementsHidden: true,
+			importantForAccessibility: "no-hide-descendants",
+		});
+	});
+
+	test("disabling a section does not hide it", () => {
+		// An open, disabled section is still content on screen.
+		const resolved = resolveCollapsibleAccessibility({ isDisabled: true, isOpen: true });
+		expect(resolved.trigger.disabled).toBe(true);
+		expect(resolved.content.accessibilityElementsHidden).toBe(false);
+	});
+});
+
+describe("collapsibleVariants defaults", () => {
+	test("the tv's defaults are the constants the component falls back to", () => {
+		expect(cls(collapsibleVariants({}).trigger())).toBe(cls(slotsFor(COLLAPSIBLE_DEFAULT_SIZE).trigger()));
+		expect(cls(collapsibleVariants({}).root())).toBe(
+			cls(collapsibleVariants({ size: COLLAPSIBLE_DEFAULT_SIZE, variant: COLLAPSIBLE_DEFAULT_VARIANT }).root())
+		);
+		expect(COLLAPSIBLE_SIZES).toContain(COLLAPSIBLE_DEFAULT_SIZE);
+		expect(COLLAPSIBLE_VARIANTS).toContain(COLLAPSIBLE_DEFAULT_VARIANT);
+	});
+});
+
+describe("collapsibleVariants geometry", () => {
+	test("the content is inset to the trigger's padding at every size", () => {
+		// A panel whose text started at a different margin than the title above it
+		// reads as two columns rather than one disclosure.
+		for (const size of COLLAPSIBLE_SIZES) {
+			const slots = slotsFor(size);
+			expect(utilityPx(cls(slots.contentInner()), "px")).toBe(utilityPx(cls(slots.trigger()), "px"));
+		}
+	});
+
+	test("a trigger is a real touch target at every size", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			expect(utilityPx(cls(slotsFor(size).trigger()), "min-h")).toBeGreaterThanOrEqual(MINIMUM_TARGET);
+		}
+	});
+
+	test("the size ladder ascends", () => {
+		const heights = COLLAPSIBLE_SIZES.map((size) => utilityPx(cls(slotsFor(size).trigger()), "min-h"));
+		expect(heights).toEqual([...heights].sort((a, b) => a - b));
+		expect(new Set(heights).size).toBe(heights.length);
+	});
+
+	test("every glyph step is a size the icon scale has", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			const step = COLLAPSIBLE_GLYPH_STEP[size];
+			expect(ICON_SIZES).toContain(step);
+			expect(cls(slotsFor(size).glyph())).toBe(`size-icon-${step}`);
+			expect(spacingPx(`icon-${step}`)).toBeGreaterThan(0);
+		}
+	});
+});
+
+describe("collapsibleVariants slots", () => {
+	test("no slot a View wears carries a text treatment", () => {
+		// A React Native View does not cascade colour to a Text descendant. Rule 1.
+		for (const size of COLLAPSIBLE_SIZES) {
+			for (const value of viewSlots(size)) {
+				expect(value).not.toMatch(/\b(text|font)-/);
+			}
+		}
+	});
+
+	test("the title and description carry the treatment instead", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			const slots = slotsFor(size);
+			expect(cls(slots.title())).toMatch(/\btext-/);
+			expect(cls(slots.description())).toMatch(/\btext-/);
+		}
+	});
+
+	test("the root clips, so an expanding panel keeps the rounded corners", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			expect(cls(slotsFor(size).root())).toMatch(/\boverflow-hidden\b/);
+		}
+	});
+
+	test("the content clips, because its height is animated below its content's", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			expect(cls(slotsFor(size).content())).toMatch(/\boverflow-hidden\b/);
+		}
+	});
+
+	test("the measured layer is out of flow and spans the width", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			const inner = cls(slotsFor(size).contentInner());
+			for (const utility of ["absolute", "top-0", "left-0", "right-0"]) {
+				expect(inner).toMatch(new RegExp(`\\b${utility}\\b`));
+			}
+		}
+	});
+
+	test("the trigger spans the surface and its text column can shrink", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			const slots = slotsFor(size);
+			expect(cls(slots.trigger())).toMatch(/\bw-full\b/);
+			expect(cls(slots.triggerContent())).toMatch(/\bflex-1\b/);
+			expect(cls(slots.triggerContent())).toMatch(/\bmin-w-0\b/);
+		}
+	});
+
+	test("the disabled fade lands on the root, never on the trigger", () => {
+		// The trigger is a `Pressable`, whose root Animated.View writes `opacity`
+		// every frame — a class there is overwritten silently.
+		for (const size of COLLAPSIBLE_SIZES) {
+			const slots = collapsibleVariants({ isDisabled: true, size, variant: COLLAPSIBLE_DEFAULT_VARIANT });
+			expect(cls(slots.root())).toMatch(/\bopacity-50\b/);
+			expect(cls(slots.trigger())).not.toMatch(/\bopacity-/);
+		}
+	});
+
+	test("every variant paints a distinct root, and nothing else", () => {
+		const roots = COLLAPSIBLE_VARIANTS.map((variant) =>
+			cls(collapsibleVariants({ isDisabled: false, size: COLLAPSIBLE_DEFAULT_SIZE, variant }).root())
+		);
+		expect(new Set(roots).size).toBe(roots.length);
+		for (const variant of COLLAPSIBLE_VARIANTS) {
+			const slots = collapsibleVariants({ isDisabled: false, size: COLLAPSIBLE_DEFAULT_SIZE, variant });
+			expect(cls(slots.trigger())).toBe(cls(slotsFor(COLLAPSIBLE_DEFAULT_SIZE).trigger()));
+			expect(cls(slots.contentInner())).toBe(cls(slotsFor(COLLAPSIBLE_DEFAULT_SIZE).contentInner()));
+		}
+	});
+
+	test("nothing draws a shadow", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			for (const value of viewSlots(size)) {
+				expect(value).not.toMatch(/\bshadow/);
+			}
+		}
+	});
+});
+
+describe("collapsible colour tokens", () => {
+	test("every token it names is declared in both themes", () => {
+		for (const token of [COLLAPSIBLE_FOREGROUND_TOKEN, COLLAPSIBLE_INDICATOR_TOKEN]) {
+			expect(declarationCount(token)).toBe(2);
+		}
+	});
+
+	test("the indicator is quieter than the title beside it", () => {
+		expect(COLLAPSIBLE_INDICATOR_TOKEN).not.toBe(COLLAPSIBLE_FOREGROUND_TOKEN);
+	});
+});
+
+describe("collapsible animation", () => {
+	test("the panel settles without overshooting its own measured height", () => {
+		const ratio = COLLAPSIBLE_SPRING.damping / (2 * Math.sqrt(COLLAPSIBLE_SPRING.stiffness * COLLAPSIBLE_SPRING.mass));
+		expect(ratio).toBeGreaterThanOrEqual(1);
+		expect(ratio).toBeLessThan(2);
+	});
+
+	test("unmeasured is a height no layout can report", () => {
+		expect(COLLAPSIBLE_UNMEASURED).toBeLessThan(0);
+	});
+
+	test("the fade runs ahead of the height, inside the travel", () => {
+		const { start, end } = COLLAPSIBLE_CONTENT_FADE;
+		expect(start).toBeGreaterThanOrEqual(0);
+		expect(end).toBeGreaterThan(start);
+		expect(end).toBeLessThan(1);
+	});
+});
+
+describe("collapsible and accordion move alike", () => {
+	// Restated rather than imported, so `delacour add collapsible` does not copy an
+	// accordion in with it — and pinned here, so the two disclosures on one screen
+	// cannot drift apart in feel, metrics or paint.
+	test("the same spring, fade and indicator travel", () => {
+		expect(COLLAPSIBLE_SPRING).toEqual(ACCORDION_SPRING);
+		expect(COLLAPSIBLE_CONTENT_FADE).toEqual(ACCORDION_CONTENT_FADE);
+		expect(COLLAPSIBLE_INDICATOR_ROTATION).toEqual(ACCORDION_INDICATOR_ROTATION);
+	});
+
+	test("the same axes", () => {
+		expect([...COLLAPSIBLE_VARIANTS]).toEqual([...ACCORDION_VARIANTS]);
+		expect([...COLLAPSIBLE_SIZES]).toEqual([...ACCORDION_SIZES]);
+		expect(COLLAPSIBLE_GLYPH_STEP).toEqual(ACCORDION_GLYPH_STEP);
+	});
+
+	test("the same trigger, panel and surface at every size and variant", () => {
+		for (const size of COLLAPSIBLE_SIZES) {
+			const own = slotsFor(size);
+			const accordion = accordionVariants({ isDisabled: false, size, variant: "default" });
+			expect(cls(own.trigger())).toBe(cls(accordion.trigger()));
+			expect(cls(own.contentInner())).toBe(cls(accordion.contentInner()));
+			expect(cls(own.title())).toBe(cls(accordion.title()));
+			expect(cls(own.description())).toBe(cls(accordion.description()));
+		}
+		for (const variant of COLLAPSIBLE_VARIANTS) {
+			const own = collapsibleVariants({ isDisabled: false, size: COLLAPSIBLE_DEFAULT_SIZE, variant });
+			const accordion = accordionVariants({ isDisabled: false, size: COLLAPSIBLE_DEFAULT_SIZE, variant });
+			expect(cls(own.root())).toBe(cls(accordion.root()));
+		}
+	});
+});

package/src/components/collapsible/collapsible.variants.ts

@@ -0,0 +1,207 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { IconSize } from "../icon/icon.variants";
+
+/**
+ * How the surface is painted.
+ *
+ * `ListGroup`'s and `Accordion`'s set, because a collapsible is the same kind of
+ * surface and the three sit beside each other on a screen. A test pins the set
+ * against `Accordion`'s.
+ */
+export const COLLAPSIBLE_VARIANTS = ["default", "secondary", "tertiary", "transparent"] as const;
+
+export const COLLAPSIBLE_SIZES = ["sm", "md", "lg"] as const;
+
+export type CollapsibleVariant = (typeof COLLAPSIBLE_VARIANTS)[number];
+export type CollapsibleSize = (typeof COLLAPSIBLE_SIZES)[number];
+
+/** The axes a collapsible falls back to when nothing names one. Pinned against `defaultVariants`. */
+export const COLLAPSIBLE_DEFAULT_VARIANT: CollapsibleVariant = "default";
+export const COLLAPSIBLE_DEFAULT_SIZE: CollapsibleSize = "md";
+
+/**
+ * The step every glyph in a collapsible is drawn at — the indicator, or an icon a
+ * caller composes into the trigger. One step, so a chevron and a leading glyph on
+ * the same row are the same mark. The `glyph` slot writes the class out, because
+ * Tailwind's scanner is static, and a test pins the two together.
+ */
+export const COLLAPSIBLE_GLYPH_STEP: Record<CollapsibleSize, IconSize> = { sm: "xs", md: "sm", lg: "md" };
+
+/** Theme token an `Icon` composed into the trigger inherits. */
+export const COLLAPSIBLE_FOREGROUND_TOKEN = "foreground";
+
+/** Theme token the indicator inherits — a step quieter than the title, and a test pins that the two differ. */
+export const COLLAPSIBLE_INDICATOR_TOKEN = "muted-foreground";
+
+/**
+ * The one spring a collapsible runs.
+ *
+ * **The panel's height, its opacity and the indicator's rotation all read it**,
+ * off a single `progress` shared value, so they cannot drift out of step by a
+ * frame. **Critically damped**, because an overshoot in *height* draws the panel
+ * taller than its content measured and flashes the surface behind it at the end
+ * of every expand.
+ *
+ * Restated rather than imported from `Accordion`, so `delacour add collapsible`
+ * copies one folder and not two. A test pins the two equal, so the two
+ * disclosures cannot drift apart in feel.
+ */
+export const COLLAPSIBLE_SPRING = { damping: 26, mass: 0.4, stiffness: 400 } as const;
+
+/** Where the indicator points at each end of the travel, in degrees — a half turn. */
+export const COLLAPSIBLE_INDICATOR_ROTATION = { collapsed: 0, expanded: 180 } as const;
+
+/**
+ * What the measured height holds before the panel has ever reported its layout.
+ *
+ * Negative rather than zero: a panel that measured `0` is a real answer, and
+ * treating it as "still waiting" would never start the spring. Only a value no
+ * layout can produce can mean *unmeasured*, so the height style floors it.
+ */
+export const COLLAPSIBLE_UNMEASURED = -1;
+
+/**
+ * The window of the travel the panel's opacity ramps across — ahead of the
+ * height, so the content is legible for most of an expand rather than half
+ * transparent at its midpoint.
+ */
+export const COLLAPSIBLE_CONTENT_FADE = { start: 0.1, end: 0.6 } as const;
+
+/**
+ * Styling for every part of a collapsible.
+ *
+ * One slotted `tv()`, because the parts cannot import the root without closing a
+ * cycle (AGENTS.md rule 3) yet all of them read the same `size`.
+ *
+ * **The slots are `Accordion`'s, class for class**, and a test asserts it: a
+ * collapsible is one accordion item without the group, and the two on one screen
+ * have to read as the same control. What differs is where the state lives, not
+ * how it looks.
+ *
+ * **The disabled fade lands on `root`**, never on `trigger`. The trigger is a
+ * `Pressable`, whose `Animated.View` writes `opacity` every frame, so a class on
+ * that node is overwritten silently. A collapsible has no item layer between the
+ * two, so the root wears it.
+ *
+ * **`overflow-hidden` on `root`** keeps an expanding panel inside the rounded
+ * corner; **on `content`** it is the disclosure itself, since that slot's height
+ * is an animated style running below its content's.
+ *
+ * **`contentInner` is out of flow**, so its height is purely its content's and can
+ * never be fed back the clip's own animated one. `left-0 right-0` is the other
+ * half: an absolute child is content-width without it, and a paragraph would
+ * measure as a single unwrapped line.
+ *
+ * No slot worn by a `View` carries `text-*` (rule 1). Free of React Native
+ * imports so it stays reachable from `bun test`.
+ */
+export const collapsibleVariants = tv({
+	slots: {
+		/** The clipped, rounded surface. Wears the disabled fade. */
+		root: "overflow-hidden border border-transparent",
+		/** The row that opens the panel. A `Pressable`, so it carries no opacity of its own. */
+		trigger: "w-full flex-row items-center",
+		/** The trigger's text column, taking whatever width the indicator leaves. */
+		triggerContent: "min-w-0 flex-1 justify-center gap-0.5",
+		/** The box the indicator turns inside. Its rotation is an animated style. */
+		indicator: "items-center justify-center",
+		/** Edge length any glyph in a collapsible inherits. */
+		glyph: "",
+		/** The trigger's primary line. Carries its own colour — a `View` cannot cascade one. */
+		title: "font-medium text-foreground",
+		/** The trigger's secondary line, a step down in scale and on the muted token. */
+		description: "text-muted-foreground",
+		/** The clip. Its height is an animated style, never a class. */
+		content: "w-full overflow-hidden",
+		/** The measured layer, out of flow so no clip height can squash what it reports. */
+		contentInner: "absolute top-0 right-0 left-0",
+	},
+	variants: {
+		variant: {
+			default: { root: "border-border bg-card" },
+			secondary: { root: "bg-secondary" },
+			tertiary: { root: "bg-tertiary" },
+			transparent: { root: "bg-transparent" },
+		},
+		size: {
+			sm: {
+				root: "rounded-md",
+				trigger: "min-h-12 gap-2.5 px-3 py-3",
+				contentInner: "px-3 pb-3",
+				glyph: "size-icon-xs",
+				title: "text-sm",
+				description: "text-xs",
+			},
+			md: {
+				root: "rounded-md",
+				trigger: "min-h-14 gap-3 px-4 py-3.5",
+				contentInner: "px-4 pb-4",
+				glyph: "size-icon-sm",
+				title: "text-base",
+				description: "text-sm",
+			},
+			lg: {
+				root: "rounded-md",
+				trigger: "min-h-16 gap-3.5 px-5 py-4",
+				contentInner: "px-5 pb-5",
+				glyph: "size-icon-md",
+				title: "text-lg",
+				description: "text-base",
+			},
+		},
+		// The empty `false` branch is load-bearing typing: a map with only `true`
+		// types the prop as `true` rather than `boolean`.
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	defaultVariants: {
+		variant: COLLAPSIBLE_DEFAULT_VARIANT,
+		size: COLLAPSIBLE_DEFAULT_SIZE,
+		isDisabled: false,
+	},
+});
+
+export type CollapsibleVariantProps = VariantProps<typeof collapsibleVariants>;
+
+/** The state a collapsible settles at rest. */
+export type CollapsibleState = { isOpen: boolean; isDisabled: boolean };
+
+/**
+ * The whole state transition a tap on the trigger makes.
+ *
+ * A disabled collapsible refuses the tap **in both directions** — it does not
+ * close a section that is already open. A disabled control is one that cannot be
+ * used, not one that undoes itself. The trigger is also a disabled `Pressable`,
+ * so this is the second line rather than the first; it is what keeps a tap that
+ * slips through the gesture layer, or a caller's own `toggle()`, honest.
+ */
+export function toggleCollapsibleOpen({ isOpen, isDisabled }: CollapsibleState): boolean {
+	return isDisabled ? isOpen : !isOpen;
+}
+
+/** What the trigger and the panel tell assistive technology. */
+export type CollapsibleAccessibility = {
+	trigger: { expanded: boolean; disabled: boolean };
+	content: {
+		accessibilityElementsHidden: boolean;
+		importantForAccessibility: "auto" | "no-hide-descendants";
+	};
+};
+
+/**
+ * Settles what the trigger and the panel announce, from the settled state.
+ *
+ * **A closed panel is taken out of the tree**, not merely clipped to zero. The
+ * panel stays mounted after its first expand, and mounted content is content a
+ * screen reader reads — so a closed one has to say it is not there. Disabling a
+ * section does not hide it: an open, disabled panel is still on screen.
+ */
+export function resolveCollapsibleAccessibility({ isOpen, isDisabled }: CollapsibleState): CollapsibleAccessibility {
+	return {
+		trigger: { disabled: isDisabled, expanded: isOpen },
+		content: {
+			accessibilityElementsHidden: !isOpen,
+			importantForAccessibility: isOpen ? "auto" : "no-hide-descendants",
+		},
+	};
+}

package/src/components/collapsible/index.ts

@@ -0,0 +1,32 @@
+export { Collapsible, type CollapsibleProps } from "./collapsible";
+export {
+	type CollapsibleContextValue,
+	CollapsibleProvider,
+	useCollapsible,
+	useCollapsibleContext,
+} from "./collapsible.context";
+export type { CollapsibleTextProps } from "./collapsible.types";
+export {
+	COLLAPSIBLE_CONTENT_FADE,
+	COLLAPSIBLE_DEFAULT_SIZE,
+	COLLAPSIBLE_DEFAULT_VARIANT,
+	COLLAPSIBLE_FOREGROUND_TOKEN,
+	COLLAPSIBLE_GLYPH_STEP,
+	COLLAPSIBLE_INDICATOR_ROTATION,
+	COLLAPSIBLE_INDICATOR_TOKEN,
+	COLLAPSIBLE_SIZES,
+	COLLAPSIBLE_SPRING,
+	COLLAPSIBLE_UNMEASURED,
+	COLLAPSIBLE_VARIANTS,
+	type CollapsibleAccessibility,
+	type CollapsibleSize,
+	type CollapsibleState,
+	type CollapsibleVariant,
+	type CollapsibleVariantProps,
+	collapsibleVariants,
+	resolveCollapsibleAccessibility,
+	toggleCollapsibleOpen,
+} from "./collapsible.variants";
+export type { CollapsibleContentProps } from "./collapsible-content";
+export type { CollapsibleIndicatorProps, CollapsibleIndicatorState } from "./collapsible-indicator";
+export type { CollapsibleTriggerProps } from "./collapsible-trigger";