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

package/src/components/collapsible/AGENTS.md

@@ -0,0 +1,97 @@
+# 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` | `collapsibleTravelTarget`, pinned equal to the accordion's, and the JS-thread `contentHeight.value` sweep |
+
+## 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
+  `isMeasured` state `onMeasured` flips — lives on the root. The race it 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.
+- **Nothing on the JS thread reads `contentHeight.value`** — the accordion's
+  Release-build bug, in the same shape: a JS read can lag the panel's queued
+  write, see `COLLAPSIBLE_UNMEASURED`, and leave the panel shut. "Measured" is
+  React state and the decision is `collapsibleTravelTarget`; the test sweeps both
+  files. See the accordion's AGENTS.md.
+- **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,97 @@
+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, 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) => {
+			contentHeight.value = event.nativeEvent.layout.height;
+			// "First" is this component's own state, never `contentHeight.value`: the
+			// write above is queued onto the UI runtime, and a read straight after it
+			// can still see the old value.
+			if (isMeasured) return;
+			setMeasured(true);
+			onMeasured();
+		},
+		[contentHeight, isMeasured, 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,91 @@
+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. Read on the UI runtime only, by the height style — a JS-thread read
+	 * can lag the panel's write. See {@link onMeasured}.
+	 */
+	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 flips
+	 * its `isMeasured` state — the reason its effect re-runs once there is a height
+	 * to travel against, and how it knows, never by reading `contentHeight`. 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;
+}