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

package/README.md

@@ -0,0 +1,113 @@
+# @delacour/react-native-ui
+
+A React Native component library. Styling is
+[Uniwind](https://github.com/kirillzyusko/uniwind) — Tailwind v4 for React
+Native; interaction is Reanimated and Gesture Handler; haptics are Pulsar.
+
+The package **ships raw `.tsx` with no build step.** Uniwind's transform has to
+run inside the consuming app's Metro pipeline, so a precompiled build would
+arrive with its classNames already dead.
+
+## Install
+
+```bash
+bun add @delacour/react-native-ui@alpha
+```
+
+Native modules are **peer dependencies**, because two copies of a native module
+register twice and break at runtime. The complete list — native modules through
+`expo install`, the rest through your package manager — is derived from the
+components' own imports and kept on the
+[Installation page](https://ui.delacour.co.nz/docs/native/getting-started/installation).
+Four peers are optional and resolve only if you import the subpath that needs them:
+
+| Peer | Needed for |
+| --- | --- |
+| `expo-router` | `@delacour/react-native-ui/expo/navigation-theme` |
+| `@legendapp/list` | `Screen.LegendList` and `Screen.ChatList` |
+| `react-native-screens` | native stack navigation |
+| `@delacour/react-native-charts` | `Chart` |
+
+Granular exports are what make that safe: an app that never imports a subpath
+never makes Metro resolve its peers.
+
+## Setup
+
+**1. Styles.** In your app's `global.css`:
+
+```css
+@import '@delacour/react-native-ui/styles';
+@source '../../../../packages/native-ui/src';
+```
+
+Use the real workspace path, not a `node_modules` one — Bun symlinks workspace
+packages and Tailwind's scanner cannot follow symlinks, so classes would be
+silently dropped from production builds.
+
+**2. Provider.** Wrap the app's root:
+
+```tsx
+import { DelacourProvider } from "@delacour/react-native-ui/provider";
+
+<DelacourProvider>{children}</DelacourProvider>;
+```
+
+That is the gesture root every `Pressable` needs above it, the safe-area provider
+and keyboard provider `Screen` reads, the bottom-sheet modal provider, and the
+keyboard state sync that keeps them honest.
+
+## Usage
+
+There is **no package-wide barrel.** Import from the subpath:
+
+```tsx
+import { Button } from "@delacour/react-native-ui/button";
+import { Icon } from "@delacour/react-native-ui/icon";
+import { IconArrowRight } from "@delacour/react-native-ui/icons/central";
+
+// The icon inherits the button's size and its variant's colour.
+<Button haptic="selection" onPress={next}>
+  <Button.Label>Continue</Button.Label>
+  <Icon icon={IconArrowRight} />
+</Button>;
+```
+
+## Components
+
+| Component | Import | |
+| --- | --- | --- |
+| Accordion | `@delacour/react-native-ui/accordion` | Selection modes, measured panels, indicators |
+| Badge | `@delacour/react-native-ui/badge` | Variants, colours, sizes, dismiss |
+| BottomSheet | `@delacour/react-native-ui/bottom-sheet` | Overlay, snap points, sticky footer, keyboard |
+| Button | `@delacour/react-native-ui/button` | Variants, sizes, icons, loading |
+| Checkbox | `@delacour/react-native-ui/checkbox` | Colours, sizes, indeterminate, groups |
+| Field | `@delacour/react-native-ui/field` | Form layout, grouping, state cascade |
+| Icon | `@delacour/react-native-ui/icon` | Central Icons, with inherited size and colour |
+| Input | `@delacour/react-native-ui/input` | Variants, sizes, prefix and suffix |
+| ListGroup | `@delacour/react-native-ui/list-group` | Grouped rows, dividers, slots |
+| Pressable | `@delacour/react-native-ui/pressable` | Gestures, haptics, `asChild` |
+| Radio | `@delacour/react-native-ui/radio` | Groups, selection, sizes, orientation |
+| Screen | `@delacour/react-native-ui/screen` | Navbar, footer, scrollables, keyboard |
+| Separator | `@delacour/react-native-ui/separator` | Orientations, insets, weight |
+| Slider | `@delacour/react-native-ui/slider` | Range, orientation, colours, steps |
+| Spinner | `@delacour/react-native-ui/spinner` | Sizes, colours, custom glyphs |
+| Switch | `@delacour/react-native-ui/switch` | Drag or tap, colours, sizes, end content |
+| Tabs | `@delacour/react-native-ui/tabs` | Variants, sizes, swipe, scrolling |
+| Text | `@delacour/react-native-ui/text` | Type scale, presets, inline nesting |
+| DelacourProvider | `@delacour/react-native-ui/provider` | The app's root layer stack |
+
+Also exported: `hooks/*`, `lib/*`, `expo/navigation-theme`, `icons/central`, and
+the `styles/*` CSS entries.
+
+## Theming
+
+Tokens are CSS variables under `@variant light` / `@variant dark`. Components
+reference semantic names — `bg-background`, `text-muted-foreground` — never a raw
+palette colour or a `dark:` prefix. For a prop needing a colour *value* rather
+than a class, use `useThemeColor`.
+
+## Documentation
+
+[`AGENTS.md`](AGENTS.md) is the reference — the rules, the patterns, and the
+reasoning behind each decision. Each component has its own alongside its source
+in [`src/components`](src/components).

package/package.json

@@ -0,0 +1,125 @@
+{
+	"name": "@delacour/react-native-ui",
+	"version": "0.1.0-alpha.3",
+	"description": "React Native UI components \u2014 Uniwind, Reanimated, Gesture Handler",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/delacournz/delacour-ui.git",
+		"directory": "packages/native-ui"
+	},
+	"keywords": [
+		"react-native",
+		"expo",
+		"ui",
+		"components",
+		"uniwind",
+		"tailwind",
+		"reanimated"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		"./styles": "./src/styles/index.css",
+		"./styles/base": "./src/styles/base.css",
+		"./styles/tokens": "./src/styles/tokens.css",
+		"./styles/theme": "./src/styles/theme.css",
+		"./accordion": "./src/components/accordion/index.ts",
+		"./badge": "./src/components/badge/index.ts",
+		"./bottom-sheet": "./src/components/bottom-sheet/index.ts",
+		"./button": "./src/components/button/index.ts",
+		"./chart": "./src/components/chart/index.ts",
+		"./checkbox": "./src/components/checkbox/index.ts",
+		"./field": "./src/components/field/index.ts",
+		"./icon": "./src/components/icon/index.ts",
+		"./input": "./src/components/input/index.ts",
+		"./list-group": "./src/components/list-group/index.ts",
+		"./pressable": "./src/components/pressable/index.ts",
+		"./provider": "./src/components/provider/index.ts",
+		"./radio": "./src/components/radio/index.ts",
+		"./screen": "./src/components/screen/index.ts",
+		"./separator": "./src/components/separator/index.ts",
+		"./slider": "./src/components/slider/index.ts",
+		"./spinner": "./src/components/spinner/index.ts",
+		"./switch": "./src/components/switch/index.ts",
+		"./tabs": "./src/components/tabs/index.ts",
+		"./text": "./src/components/text/index.ts",
+		"./expo/navigation-theme": "./src/expo/navigation-theme.tsx",
+		"./hooks/use-controllable-state": "./src/hooks/use-controllable-state.ts",
+		"./hooks/use-keyboard-state-sync": "./src/hooks/use-keyboard-state-sync.tsx",
+		"./hooks/use-navigation-theme": "./src/hooks/use-navigation-theme.ts",
+		"./hooks/use-theme-color": "./src/hooks/use-theme-color.ts",
+		"./lib/cn": "./src/lib/cn.ts",
+		"./lib/color": "./src/lib/color.ts",
+		"./lib/compose-refs": "./src/lib/compose-refs.ts",
+		"./lib/keyboard-animation": "./src/lib/keyboard-animation.ts",
+		"./lib/merge-props": "./src/lib/merge-props.ts",
+		"./lib/navigation-theme": "./src/lib/navigation-theme.ts",
+		"./lib/slot": "./src/lib/slot.tsx",
+		"./lib/tv": "./src/lib/tv.ts",
+		"./icons/central": "./src/icons/central.ts"
+	},
+	"scripts": {
+		"check": "biome check ./src",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"gen-exports": "bun scripts/gen-exports.ts"
+	},
+	"dependencies": {
+		"clsx": "^2.1.1",
+		"tailwind-merge": "^3.6.0",
+		"tailwind-variants": "^3.3.1"
+	},
+	"peerDependencies": {
+		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
+		"@delacour/react-native-charts": ">=0.1.0-alpha.4",
+		"@gorhom/bottom-sheet": "^5.2.8",
+		"@legendapp/list": ">=3.3",
+		"expo-linear-gradient": ">=15",
+		"expo-router": ">=57",
+		"react": ">=19",
+		"react-native": ">=0.81",
+		"react-native-gesture-handler": ">=2.28",
+		"react-native-keyboard-controller": ">=1.18",
+		"react-native-pulsar": "^1.7.0",
+		"react-native-reanimated": ">=4",
+		"react-native-safe-area-context": ">=5",
+		"react-native-screens": ">=4.16",
+		"react-native-svg": ">=15",
+		"react-native-worklets": ">=0.5",
+		"tailwindcss": "^4",
+		"uniwind": "^1.11.0"
+	},
+	"peerDependenciesMeta": {
+		"@delacour/react-native-charts": {
+			"optional": true
+		},
+		"@legendapp/list": {
+			"optional": true
+		},
+		"expo-router": {
+			"optional": true
+		},
+		"react-native-screens": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@delacour/biome-config": "workspace:*",
+		"@delacour/react-native-charts": "workspace:*",
+		"@delacour/tsconfig": "workspace:*",
+		"@types/bun": "^1.3.8",
+		"@types/react": "catalog:",
+		"expo-router": "~57.0.15",
+		"typescript": "^5.9.3"
+	}
+}

package/src/components/accordion/AGENTS.md

@@ -0,0 +1,192 @@
+# Accordion
+
+Rows that each disclose a panel. Compound root plus `Accordion.Item`,
+`Accordion.Trigger`, `Accordion.Title`, `Accordion.Description`,
+`Accordion.Indicator` and `Accordion.Content`. It takes
+[ListGroup](../list-group/AGENTS.md)'s axes and its divider insertion outright,
+so read that section first — what follows is only where a disclosure differs from
+a list of rows.
+
+`import { Accordion } from "@delacour/react-native-ui/accordion";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/accordion` |
+| `accordion.tsx` | Root, the selection narrow, the divider insertion, the `Object.assign` |
+| `accordion-item.tsx` | `Accordion.Item` — owns `progress`, the measured height and the spring |
+| `accordion-trigger.tsx` | `Accordion.Trigger`, and the row it assembles from its children |
+| `accordion-title.tsx` | `Accordion.Title` |
+| `accordion-description.tsx` | `Accordion.Description` |
+| `accordion-indicator.tsx` | `Accordion.Indicator`, the one rotation |
+| `accordion-content.tsx` | `Accordion.Content` — the measured clip |
+| `accordion.context.tsx` | `AccordionContext` and `AccordionItemContext`, with their hooks |
+| `accordion.types.ts` | Prop types shared by two or more parts |
+| `accordion.variants.ts` | Pure `tv()` slots + the selection maths, no RN imports |
+| `accordion.variants.test.ts` | |
+
+## Design
+
+- **Variants**: `default`, `secondary`, `tertiary`, `transparent`. **Sizes**:
+  `sm`, `md`, `lg` — driving the trigger's metrics, the title and description
+  type scale, the indicator's glyph step, the panel's padding *and* the divider
+  inset. Six numbers on one axis rather than in six places that can drift, and
+  the tests pin the inset against the trigger's own padding as a **pair**.
+- **The corner is `rounded-md`, the 0.8 step of the shared ramp.** shadcn puts a
+  grouped surface a step or two below a card, so a group reads as a control
+  surface rather than as one. Size does not move it, and neither does a button's
+  own corner — `--radius-button-*` is a capsule at half its height and outside
+  this ramp. See the corner-scale note in
+  [the package AGENTS.md](../../../AGENTS.md).
+- **The variant paints the root and nothing else.** Only the root has a surface;
+  a trigger or a panel that also changed with it would be a second source for one
+  colour. A test asserts every variant's root is distinct, because two cells
+  collapsing means a caller can set the axis and see nothing change.
+
+## The measured panel
+
+- **A panel's height is measured, never laid out.** `Accordion.Content` clips,
+  and its height is an animated style running from zero to whatever its inner
+  view's `onLayout` reported. The alternative — unmounting the content and
+  letting a `LinearTransition` reflow the tree — makes every sibling on the
+  screen a participant in this component's animation, and other implementations
+  of this control document exactly that as a requirement. Here the animation is
+  contained to the accordion's own node: a real height is changing, so whatever
+  sits below follows it smoothly through ordinary layout, without opting into
+  anything and without a transition painted on it.
+- **The measured layer is out of flow.** `contentInner` is absolutely positioned,
+  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.
+- **One shared value per item drives three properties** — the panel's height, the
+  panel's opacity and the indicator's rotation, all off `progress` through one
+  `ACCORDION_SPRING`. `Switch`'s rule, and the failure it prevents is visible:
+  two springs a few hundred stiffness apart leave the chevron lagging the panel
+  on every tap. A test pins that both read the same constant.
+- **The spring is critically damped**, which is `Switch`'s reason turned inside
+  out. A switch damps its thumb because an overshoot squashes against a capsule
+  that clips it; a panel damps its height because an overshoot draws the panel
+  *taller* than its content measured, flashing the surface behind it for a frame
+  at the end of every expand.
+- **The fade runs ahead of the height.** Opacity ramps across
+  `ACCORDION_CONTENT_FADE` rather than tracking `progress` linearly, because a
+  panel half transparent at the midpoint of every expand reads as content
+  struggling to arrive rather than as a panel opening.
+- **A panel mounts on first expand and stays mounted.** Nothing renders until an
+  item is first opened, so a screen of collapsed panels costs an empty view each;
+  once opened, the subtree survives every later collapse with its scroll
+  position, its form state and its media intact. `hasExpanded` is adjusted during
+  render rather than in an effect, so the panel mounts in the same commit as the
+  tap — waiting a frame would put the first measurement, and therefore the start
+  of the travel, one frame later still.
+- **That is what the three accessibility props on the clip are for.** Mounted
+  content is content a screen reader reads and a finger reaches, so a collapsed
+  panel sets `accessibilityElementsHidden`, `importantForAccessibility` and
+  `pointerEvents`. A component that unmounted its content never has to think
+  about this; the trade is worth making, but it is not free.
+- **The first expand starts from the panel's own layout, not from the item's
+  effect.** A panel that has never mounted has no height to travel against, so
+  springing on the state change would run the whole animation at zero and jump
+  the moment a measurement arrived. The item's effect skips exactly that one
+  case and `accordion-content.tsx`'s `onLayout` starts it instead. Every later
+  toggle, in either direction, is the item's.
+- **`ACCORDION_UNMEASURED` is negative, and that is load-bearing.** A panel that
+  measured `0` is a real answer — content that rendered nothing — and an item
+  treating it as "still waiting" would never start its spring, leaving the
+  indicator pointing the wrong way. Only a value no layout can produce can mean
+  *unmeasured*, so the height style floors it.
+
+## Selection
+
+- **`selectionMode` is a true discriminated union**, so `single` with an array
+  `defaultValue` is a compile error. Intersecting the union with a widened
+  `defaultValue?: string | string[]` defeats it entirely — every member re-admits
+  both shapes, and `onValueChange` ends up typed as a function *returning* a
+  union rather than a union of functions, which is what forces a cast in the
+  toggle. `AccordionRoot` is nothing but the narrow, and it happens **before
+  anything is destructured**; destructure first and the correlation is gone.
+- **The state is one internal `string[]` whichever mode is in play.**
+  `useControllableState` cannot be called conditionally, and two hooks would be
+  two pieces of state for one answer, so the caller's shape is converted at the
+  boundary — `toExpandedList` on the way in, a narrow on `selectionMode` on the
+  way out. `value={null}` in single mode is a controlled *empty*, not an absence,
+  which is why `undefined` is preserved rather than normalised away.
+- **`isCollapsible` bounds the set, never a single item.** In `multiple` mode an
+  item still closes while another is open and only the last one is refused.
+  Reading it as "no item may ever close" makes a multiple accordion **add-only** —
+  a control that fills up and never empties — and that is the bug this rule
+  exists to name.
+- **A refused tap returns its own input, by identity.** `toggleExpandedValue`
+  hands back the array it was given when the rules reject the change, so the root
+  can skip it: a rejected tap must not re-render and must not report an
+  `onValueChange` for a change that did not happen. A real change is always a new
+  array, because React bails out of a re-render on an unchanged reference.
+- **`toggle` and the change callback are both ref-backed trampolines**, so the
+  accordion's context keeps its identity across every expansion and across a
+  caller passing a fresh arrow. Without them every item re-renders on every
+  toggle, which is what the implementations that hand a fresh object literal to
+  their provider actually do.
+
+## The trigger
+
+- **A trigger is a `Pressable`**, so `feedback`, `haptic` and the rest are
+  inherited rather than restated. Two defaults differ: `fade`, because a
+  full-bleed row that scales reads as the whole card flexing — `ListGroup.Item`'s
+  reason — and `haptic="selection"`, because an item is a state toggle and the
+  panel landing is the confirmation, which is `Checkbox`'s and `Switch`'s.
+  `onPress` is the one prop `Omit`ed rather than forwarded: the press *is* the
+  toggle, and a side effect belongs on `onValueChange`. `Checkbox`'s trade.
+- **The disabled fade lands on the item, never on the trigger.** The trigger is a
+  `Pressable`, whose root `Animated.View` writes `opacity` every frame through a
+  `useAnimatedStyle` of its own — a class on that node is overwritten silently,
+  the failure `Switch` and `Radio` both record. A test sweeps for it.
+- **The trigger assembles its own row.** Titles and descriptions stack in a
+  column, anything else — a leading `Icon`, a `Badge` — stays where it was
+  written as a row sibling, and the indicator is moved to the end and composed in
+  when the children hold none. That is what makes an `Accordion.TriggerContent`
+  part unnecessary rather than merely absent. Bare string children are wrapped in
+  an `Accordion.Title`, consecutive strings collapsing into one — the same rule,
+  and the same reason, as `Button`.
+- **The indicator rotates off the item's own `progress`**, so a *custom* glyph
+  turns exactly like the default one. Passing children and silently dropping the
+  animated style is a real trap in other implementations of this control, and the
+  opt-out here is explicit: `isAnimated={false}`, for a plus becoming a minus,
+  which reads as broken when it also spins. The rotation lives on the indicator's
+  node rather than the trigger's because `Pressable` already owns `transform`
+  there.
+- **An indicator has to be a direct `Accordion.Indicator` child of the trigger.**
+  The trigger finds it 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 — two glyphs on the row, with nothing to explain them.
+  `hasThumbChild` carries the same limitation for `Switch`. What closes it here
+  is that the indicator takes a **render function**, handed the item's settled
+  state: reading `isExpanded` means calling a hook, a hook cannot be called in
+  the parent's JSX, and that is the only thing a wrapper was ever for.
+  `Slider.Track` takes a function for the same reason.
+- **The indicator takes `muted-foreground`, a step quieter than the title.** The
+  chevron is chrome saying the row opens; the title is the content. A test pins
+  that the two tokens differ.
+
+## Accessibility and structure
+
+- **There is no separate heading element.** Wrapping the trigger in one and
+  setting `aria-expanded` there as well as `accessibilityState.expanded` on the
+  button inside is state written twice, and a screen reader reads it out twice.
+  `Pressable` already supplies the role, `accessible` and the state merge.
+- **The root is a plain `View` with no role.** Announcing a container as a
+  control puts an actionless element in front of every child — `Checkbox.Group`'s
+  rule.
+- **Dividers are inserted, not written out**, `ListGroup`'s implementation
+  verbatim in shape: `Children.toArray` drops the nulls a conditional item leaves
+  behind, and a hand-placed `Separator` suppresses the automatic one on either
+  side. Counting indices against the raw children instead — `index < count - 1` —
+  miscounts a conditional item and breaks outright on a fragment.
+- **Reduce motion is left at Reanimated's default `System` policy**, with
+  `Switch`, `Checkbox` and `Radio` and against `Spinner`. The state is carried by
+  whether the panel is *there*, so completing instantly is the right degradation.
+- **An item is expected to hold an `Accordion.Content`.** One without a panel has
+  nothing to measure and therefore nothing to travel against, so its indicator
+  stays put — which is the right outcome for a row that discloses nothing, and is
+  stated here rather than guarded against.

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

@@ -0,0 +1,125 @@
+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 { useAccordionItemPart, useAccordionPart } from "./accordion.context";
+import { ACCORDION_CONTENT_FADE, ACCORDION_UNMEASURED, accordionVariants } from "./accordion.variants";
+
+export type AccordionContentProps = Omit<ViewProps, "style"> & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The panel an item 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. The animation
+ * therefore lives on this one node: whatever sits below follows it through
+ * ordinary layout, with nothing to opt into. The alternative — unmounting the
+ * content and letting a whole-tree layout transition reflow the screen — makes
+ * every sibling on the page a participant in this component's animation.
+ *
+ * The inner view is **out of flow**, so its height is its content's and can never
+ * be fed back the clip's own animated one. In flow it is laid out against that
+ * height, and a panel measured while the clip sits at zero reports its padding and
+ * nothing else.
+ *
+ * **The content mounts on first expand and stays mounted.** Nothing renders until
+ * an item is first opened, so a screen of collapsed panels costs an empty view
+ * each; once opened, the subtree survives every later collapse with its scroll
+ * position, its form state and its media intact. A panel that unmounted would
+ * destroy all three on every tap.
+ *
+ * That is what the three accessibility props are for. Mounted content is content a
+ * screen reader will read and a finger can reach, so a collapsed panel has to say
+ * it is not there — an unmounting accordion never has to think about this.
+ *
+ * **It reports its first measurement and never starts the travel itself.** The
+ * item owns the spring alone; see `onMeasured` on the item context for the race
+ * that rule exists to close.
+ */
+export function AccordionContent({ className, children, ...props }: AccordionContentProps): ReactElement {
+	const { size } = useAccordionPart("Accordion.Content");
+	const { contentHeight, isExpanded, onMeasured, progress } = useAccordionItemPart("Accordion.Content");
+	const slots = accordionVariants({ size });
+
+	// Adjusted during render rather than in an effect, so the panel mounts in the
+	// same commit as the tap that opened it. Waiting a frame would put the first
+	// measurement — and therefore the start of the travel — one frame later still.
+	const [hasExpanded, setHasExpanded] = useState(isExpanded);
+	if (isExpanded && !hasExpanded) setHasExpanded(true);
+
+	// Whether this panel has ever reported a height. Until it has, the clip must
+	// not constrain anything — see `accordionStyleSheet.measuring` below.
+	const [isMeasured, setMeasured] = useState(false);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const wasMeasured = contentHeight.value > ACCORDION_UNMEASURED;
+			contentHeight.value = event.nativeEvent.layout.height;
+
+			// The panel reports its first measurement and stops there — it must not
+			// start the travel itself. `onLayout` is dispatched from the native side
+			// and can land either side of React's effects, so a spring started here
+			// is sometimes cancelled a moment later by the cleanup of the item's
+			// effect it raced, leaving the panel shut and the indicator pointing the
+			// wrong way. Telling the item instead leaves one owner of the spring.
+			if (wasMeasured) return;
+			setMeasured(true);
+			onMeasured();
+		},
+		[contentHeight, onMeasured]
+	);
+
+	// Height and opacity off the one `progress`, never off a timing of their own —
+	// so there is no second clock the panel's position can drift from. The fade
+	// closes before the height does, which is what keeps the content legible for
+	// most of the travel rather than half transparent at its midpoint.
+	const clipStyle = useAnimatedStyle(() => ({
+		height: progress.value * Math.max(contentHeight.value, 0),
+		opacity: interpolate(
+			progress.value,
+			[0, ACCORDION_CONTENT_FADE.start, ACCORDION_CONTENT_FADE.end, 1],
+			[0, 0, 1, 1]
+		),
+	}));
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden={!isExpanded}
+			className={slots.content()}
+			importantForAccessibility={isExpanded ? "auto" : "no-hide-descendants"}
+			// Never `auto` while measuring: the clip is stretched over its own item
+			// for that commit, and an invisible layer over a trigger is a tap that
+			// goes nowhere.
+			pointerEvents={isExpanded && isMeasured ? "auto" : "none"}
+			style={isMeasured ? clipStyle : accordionStyleSheet.measuring}
+		>
+			{hasExpanded ? (
+				<View className={slots.contentInner({ className })} onLayout={handleLayout} {...props}>
+					{children}
+				</View>
+			) : null}
+		</Animated.View>
+	);
+}
+AccordionContent.displayName = "DelacourUI.Accordion.Content";
+
+const accordionStyleSheet = StyleSheet.create({
+	/**
+	 * What the clip wears until its panel has reported a height.
+	 *
+	 * Absolutely positioned over its own item, so it is out of the item's layout and
+	 * nothing on screen moves while it measures, and transparent, so nothing shows
+	 * either. What matters is what it is *not*: it is not `height: 0`. A clip
+	 * already at zero squashes an in-flow child to its padding, and never fires
+	 * `onLayout` at all for an out-of-flow one — its frame is empty, so no layout
+	 * event is emitted and the measurement arrives only when something unrelated
+	 * forces a relayout, minutes later or never. Both were found on a simulator.
+	 *
+	 * The switch to the animated clip happens on the commit the measurement lands,
+	 * while `progress` is still zero — so the panel goes from taking no space to
+	 * taking none, and the travel starts from there.
+	 */
+	measuring: { bottom: 0, left: 0, opacity: 0, position: "absolute", right: 0, top: 0 },
+});

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

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useAccordionPart } from "./accordion.context";
+import type { AccordionTextProps } from "./accordion.types";
+import { accordionVariants } from "./accordion.variants";
+
+/**
+ * The trigger's secondary line, a step down in scale and on the muted token.
+ *
+ * Sits under the title inside the trigger's own text column, which the trigger
+ * assembles — so the two stack without a wrapper part between them.
+ */
+export function AccordionDescription({ className, ...props }: AccordionTextProps): ReactElement {
+	const { size } = useAccordionPart("Accordion.Description");
+	return <Text className={accordionVariants({ size }).description({ className })} {...props} />;
+}
+AccordionDescription.displayName = "DelacourUI.Accordion.Description";