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

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

@@ -0,0 +1,104 @@
+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 { useAccordionItemPart, useAccordionPart } from "./accordion.context";
+import { ACCORDION_INDICATOR_ROTATION, ACCORDION_INDICATOR_TOKEN, accordionVariants } from "./accordion.variants";
+
+/** What a render-function indicator is handed. */
+export type AccordionIndicatorState = { isExpanded: boolean };
+
+export type AccordionIndicatorProps = 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 item's settled state.
+	 *
+	 * The function form exists so a swapping glyph needs no component of its own:
+	 * reading `isExpanded` means calling a hook, and a hook cannot be called in the
+	 * parent's JSX. `Slider.Track` takes a function for the same reason.
+	 *
+	 * It matters more than convenience here. A trigger finds its indicator by
+	 * element type, so an indicator 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 at all.
+	 */
+	children?: ReactNode | ((state: AccordionIndicatorState) => ReactNode);
+};
+
+/**
+ * The glyph saying an item opens, turning as it does.
+ *
+ * Composed into a trigger that holds none, so a bare `<Accordion.Trigger>` is
+ * already complete — `Radio`'s rule for its indicator, and the same reasoning: an
+ * item has exactly one, so a caller who wrote none wants the default.
+ *
+ * **The rotation interpolates off the item's own `progress`**, the very value the
+ * panel's height reads, so the glyph and the panel are in phase by construction
+ * rather than by two springs tuned to match. It also means a custom glyph turns
+ * exactly like the default one — pass anything as children and it rotates, unless
+ * `isAnimated={false}` says otherwise.
+ *
+ * The rotation lives on this node rather than on the trigger's because
+ * `Pressable`'s own root `Animated.View` already owns `transform` through a
+ * `useAnimatedStyle` of its own, and two animated styles on one node fight for
+ * the same prop.
+ *
+ * Its subtree inherits the accordion's glyph step and the muted token, so a
+ * composed `<Icon>` needs nothing said at the call site.
+ *
+ * @example
+ * <Accordion.Indicator isAnimated={false}>
+ *   {({ isExpanded }) => <Icon icon={isExpanded ? IconMinusSmall : IconPlusSmall} />}
+ * </Accordion.Indicator>
+ */
+export function AccordionIndicator({
+	isAnimated = true,
+	className,
+	children,
+	...props
+}: AccordionIndicatorProps): ReactElement {
+	const { size } = useAccordionPart("Accordion.Indicator");
+	const { isExpanded, progress } = useAccordionItemPart("Accordion.Indicator");
+
+	const slots = accordionVariants({ size });
+	const glyphClassName = slots.glyph();
+
+	const rotationStyle = useAnimatedStyle(() => ({
+		transform: [
+			{
+				rotate: `${interpolate(
+					progress.value,
+					[0, 1],
+					[ACCORDION_INDICATOR_ROTATION.collapsed, ACCORDION_INDICATOR_ROTATION.expanded]
+				)}deg`,
+			},
+		],
+	}));
+
+	const iconDefaults = useMemo<IconDefaults>(
+		() => ({ className: glyphClassName, color: ACCORDION_INDICATOR_TOKEN }),
+		[glyphClassName]
+	);
+
+	return (
+		<Animated.View className={slots.indicator({ className })} style={isAnimated ? rotationStyle : undefined} {...props}>
+			<IconDefaultsProvider value={iconDefaults}>{renderGlyph(children, isExpanded)}</IconDefaultsProvider>
+		</Animated.View>
+	);
+}
+AccordionIndicator.displayName = "DelacourUI.Accordion.Indicator";
+
+/** The caller's glyph, the state they asked for, or the default chevron. */
+function renderGlyph(
+	children: ReactNode | ((state: AccordionIndicatorState) => ReactNode),
+	isExpanded: boolean
+): ReactNode {
+	if (typeof children === "function") return children({ isExpanded });
+	return children ?? <Icon icon={IconChevronBottom} />;
+}

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

@@ -0,0 +1,78 @@
+import { type ReactElement, type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+import { View, type ViewProps } from "react-native";
+import { cancelAnimation, useSharedValue, withSpring } from "react-native-reanimated";
+import { type AccordionItemContextValue, AccordionItemProvider, useAccordionPart } from "./accordion.context";
+import {
+	ACCORDION_SPRING,
+	ACCORDION_UNMEASURED,
+	accordionVariants,
+	isItemExpanded,
+	resolveAccordionItemAxes,
+} from "./accordion.variants";
+
+export type AccordionItemProps = Omit<ViewProps, "children"> & {
+	/** What this item is called in the accordion's value. Must be unique within one. */
+	value: string;
+	/** Blocks the trigger and fades the row. Inherited from the enclosing accordion. */
+	isDisabled?: boolean;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * One section of an accordion: a trigger, and the panel it discloses.
+ *
+ * Owns the two shared values every animated style on this item reads —
+ * `progress` and the panel's measured height — and the one spring that drives
+ * them. One source for the height, the fade and the indicator's rotation, so the
+ * three cannot drift out of step by a frame.
+ *
+ * `progress` is seeded from the settled state rather than from zero, so an item
+ * mounted open does not animate itself open on its first paint — `Switch`'s rule.
+ *
+ * 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.
+ */
+export function AccordionItem({ value, isDisabled, className, children, ...props }: AccordionItemProps): ReactElement {
+	const { expanded, isDisabled: accordionDisabled, size } = useAccordionPart("Accordion.Item");
+	const axes = resolveAccordionItemAxes({ own: { isDisabled }, root: { isDisabled: accordionDisabled } });
+	const isExpanded = isItemExpanded(expanded, value);
+
+	const progress = useSharedValue(isExpanded ? 1 : 0);
+	const contentHeight = useSharedValue(ACCORDION_UNMEASURED);
+
+	// Bumped the first time this item's panel reports a height, purely to make the
+	// effect below run again. See `onMeasured` on the item context for why the
+	// panel must not start the spring itself.
+	const [measurements, setMeasurements] = useState(0);
+	const onMeasured = useCallback(() => setMeasurements((count) => count + 1), []);
+
+	// `measurements` is not read in the body — being unread is the whole point of
+	// it, the way `settledDrags` is for a `Switch`. The first expand of a panel
+	// that has never been mounted has no height to travel against, so this run
+	// bails; the measurement that follows is what brings it back.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the extra dependency is the re-run trigger, see above
+	useEffect(() => {
+		if (isExpanded && contentHeight.value === ACCORDION_UNMEASURED) return;
+
+		progress.value = withSpring(isExpanded ? 1 : 0, ACCORDION_SPRING);
+
+		// Without this an item unmounted mid-travel leaves its spring running.
+		return () => cancelAnimation(progress);
+	}, [contentHeight, isExpanded, measurements, progress]);
+
+	const context = useMemo<AccordionItemContextValue>(
+		() => ({ contentHeight, isDisabled: axes.isDisabled, isExpanded, onMeasured, progress, value }),
+		[axes.isDisabled, contentHeight, isExpanded, onMeasured, progress, value]
+	);
+
+	return (
+		<AccordionItemProvider value={context}>
+			<View className={accordionVariants({ isDisabled: axes.isDisabled, size }).item({ className })} {...props}>
+				{children}
+			</View>
+		</AccordionItemProvider>
+	);
+}
+AccordionItem.displayName = "DelacourUI.Accordion.Item";

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

@@ -0,0 +1,18 @@
+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 primary line — what the item is called.
+ *
+ * Carries its own colour and type scale, read from the accordion's context: a
+ * React Native `View` does not cascade colour to a `Text` descendant, so the
+ * trigger cannot set it on their behalf.
+ */
+export function AccordionTitle({ className, ...props }: AccordionTextProps): ReactElement {
+	const { size } = useAccordionPart("Accordion.Title");
+	return <Text className={accordionVariants({ size }).title({ className })} {...props} />;
+}
+AccordionTitle.displayName = "DelacourUI.Accordion.Title";

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

@@ -0,0 +1,148 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { View } from "react-native";
+import { type IconDefaults, IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { useAccordionItemPart, useAccordionPart } from "./accordion.context";
+import { ACCORDION_FOREGROUND_TOKEN, accordionVariants } from "./accordion.variants";
+import { AccordionDescription } from "./accordion-description";
+import { AccordionIndicator } from "./accordion-indicator";
+import { AccordionTitle } from "./accordion-title";
+
+export type AccordionTriggerProps = Omit<PressableProps, "children" | "disabled" | "onPress"> & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The row that opens and closes an item.
+ *
+ * A `Pressable`, so `feedback`, `haptic`, `pressedScale` and the rest come from
+ * there rather than being restated here. Two defaults differ: `fade`, because a
+ * full-bleed row that scales reads as the whole card flexing rather than as one
+ * row responding — `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. `haptic={false}` silences it.
+ *
+ * `onPress` is the one prop `Omit`ed rather than forwarded: the press **is** the
+ * toggle, and a side effect belongs on the accordion's `onValueChange`. The trade
+ * `Checkbox` already makes.
+ *
+ * It assembles its own row — titles and descriptions stack in a column, an
+ * indicator is moved to the end, and one is composed in when the children hold
+ * none — so the anatomy needs no wrapper part between a trigger and its text.
+ *
+ * `accessibilityState.expanded` is the only thing added to what `Pressable`
+ * already announces. There is deliberately no separate heading element wrapping
+ * it: state set in two places is state a screen reader reads out twice.
+ */
+export function AccordionTrigger({
+	feedback = "fade",
+	haptic = "selection",
+	className,
+	children,
+	...props
+}: AccordionTriggerProps): ReactElement {
+	const { size, toggle } = useAccordionPart("Accordion.Trigger");
+	const { isDisabled, isExpanded, value } = useAccordionItemPart("Accordion.Trigger");
+
+	const slots = accordionVariants({ size });
+	const columnClassName = slots.triggerContent();
+	const glyphClassName = slots.glyph();
+
+	const handlePress = useCallback(() => toggle(value), [toggle, value]);
+
+	const content = useMemo(() => composeRow(children, columnClassName), [children, columnClassName]);
+
+	const iconDefaults = useMemo<IconDefaults>(
+		() => ({ className: glyphClassName, color: ACCORDION_FOREGROUND_TOKEN }),
+		[glyphClassName]
+	);
+
+	return (
+		<Pressable
+			accessibilityState={{ expanded: isExpanded }}
+			className={slots.trigger({ className })}
+			disabled={isDisabled}
+			feedback={feedback}
+			haptic={haptic}
+			onPress={handlePress}
+			{...props}
+		>
+			<IconDefaultsProvider value={iconDefaults}>{content}</IconDefaultsProvider>
+		</Pressable>
+	);
+}
+AccordionTrigger.displayName = "DelacourUI.Accordion.Trigger";
+
+/**
+ * Arranges a trigger's children into the row the anatomy describes.
+ *
+ * Three things happen, and each has a call site it saves:
+ *
+ * - **Bare strings become a title.** React Native crashes on a raw string outside
+ *   a `<Text>`, so `<Accordion.Trigger>Shipping</Accordion.Trigger>` would red-box.
+ *   Consecutive strings collapse into one, because `Item {index}` is a single
+ *   piece of text and wrapping the parts separately would stack them.
+ * - **Titles and descriptions stack in a column.** They are the only children that
+ *   belong on top of each other; anything else — a leading `Icon`, a `Badge` — is
+ *   left where it was written, as a sibling on the row. That is what makes a
+ *   `Accordion.TriggerContent` part unnecessary rather than merely absent.
+ * - **The indicator goes last, and is composed in when there is none.** So a
+ *   trigger reads as its content and still ends with the glyph that says it opens.
+ *
+ * Lives here rather than with the root: it is the trigger that arranges its own
+ * children, and importing it from `./accordion` would close a cycle. See AGENTS.md.
+ */
+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(<AccordionTitle key={`title-${column.length}`}>{run.join("")}</AccordionTitle>);
+		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 === AccordionIndicator) {
+			hasIndicator = true;
+			trailing.push(child);
+			continue;
+		}
+
+		if (isValidElement(child) && (child.type === AccordionTitle || child.type === AccordionDescription)) {
+			column.push(child);
+			continue;
+		}
+
+		flushColumn();
+		row.push(child);
+	}
+
+	flushRun();
+	flushColumn();
+
+	if (!hasIndicator) trailing.push(<AccordionIndicator key="indicator" />);
+
+	return [...row, ...trailing];
+}

package/src/components/accordion/accordion.context.tsx

@@ -0,0 +1,153 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { AccordionSize, AccordionVariant } from "./accordion.variants";
+
+export type AccordionContextValue = {
+	variant: AccordionVariant;
+	size: AccordionSize;
+	/** Every item is inert. An item's own `isDisabled` still overrides it, either way. */
+	isDisabled: boolean;
+	/** Which items are open, on the **JS thread**. */
+	expanded: readonly string[];
+	/** Opens or closes one item. Stable for the accordion's lifetime. */
+	toggle: (value: string) => void;
+};
+
+export type AccordionItemContextValue = {
+	/** What this item is called in the accordion's expanded set. */
+	value: string;
+	isDisabled: boolean;
+	/** Whether this item is open, on the **JS thread** — what accessibility reads. */
+	isExpanded: boolean;
+	/**
+	 * How far open this item is, on the **UI thread**: `0` closed, `1` open.
+	 *
+	 * The one value every animated style on this item reads — the panel's height,
+	 * the panel's opacity and the indicator's rotation. One source rather than
+	 * three, so they cannot drift out of step by a frame.
+	 *
+	 * It agrees with {@link AccordionItemContextValue.isExpanded} at rest and
+	 * disagrees for the whole of a spring, which is what keeps the animation off
+	 * the JS thread entirely.
+	 */
+	progress: SharedValue<number>;
+	/**
+	 * The panel's natural height in points, from its own `onLayout`.
+	 *
+	 * Holds {@link ACCORDION_UNMEASURED} until a panel has reported, which is not
+	 * the same as a panel that measured zero: the item's spring waits on the first
+	 * measurement rather than travelling against a height that is not there yet.
+	 */
+	contentHeight: SharedValue<number>;
+	/**
+	 * Told by the panel that it has measured itself for the first time.
+	 *
+	 * Internal machinery, and the reason the item is the **only** owner of the
+	 * spring. The panel cannot start the travel itself: `onLayout` is dispatched
+	 * from the native side and can land either side of React's effects, so a panel
+	 * that started its own spring would sometimes have it cancelled a moment later
+	 * by the cleanup of the effect it raced. This hands the item a reason to re-run
+	 * instead — `Slider`'s and `Switch`'s `settledDrags`, for the same reason: a
+	 * counter whose only job is to give an effect something to fire on.
+	 */
+	onMeasured: () => void;
+};
+
+const AccordionContext = createContext<AccordionContextValue | null>(null);
+const AccordionItemContext = createContext<AccordionItemContextValue | null>(null);
+
+/**
+ * Supplies one accordion's axes and its selection to every item beneath it.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./accordion`. That import would close a cycle, and
+ * Metro serves a partially initialised module for a cycle — leaving the context
+ * `undefined` at import time and red-boxing the app on a cold start.
+ */
+export function AccordionProvider({
+	value,
+	children,
+}: {
+	value: AccordionContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <AccordionContext value={value}>{children}</AccordionContext>;
+}
+AccordionProvider.displayName = "DelacourUI.Accordion.Provider";
+
+/** Supplies one item's own state and shared values to its trigger, indicator and panel. */
+export function AccordionItemProvider({
+	value,
+	children,
+}: {
+	value: AccordionItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <AccordionItemContext value={value}>{children}</AccordionItemContext>;
+}
+AccordionItemProvider.displayName = "DelacourUI.Accordion.ItemProvider";
+
+/** The enclosing accordion's state, or null outside an `<Accordion>`. */
+export function useAccordionContext(): AccordionContextValue | null {
+	return use(AccordionContext);
+}
+
+/**
+ * Reads the enclosing accordion's axes and selection.
+ *
+ * Lets a custom child style itself to match, or drive the selection, without the
+ * accordion having to pass props down through every item. Throws outside an
+ * `<Accordion>` — use {@link useAccordionContext} where the enclosing accordion is
+ * optional.
+ */
+export function useAccordion(): AccordionContextValue {
+	const context = useAccordionContext();
+	if (!context) {
+		throw new Error("useAccordion must be called inside an <Accordion>.");
+	}
+	return context;
+}
+
+/** The enclosing item's state, or null outside an `<Accordion.Item>`. */
+export function useAccordionItemContext(): AccordionItemContextValue | null {
+	return use(AccordionItemContext);
+}
+
+/**
+ * Reads the enclosing item's state.
+ *
+ * This is what a custom indicator reaches for: `isExpanded` to swap a glyph, or
+ * `progress` to animate against exactly the travel the panel is running. Throws
+ * outside an `<Accordion.Item>`.
+ */
+export function useAccordionItem(): AccordionItemContextValue {
+	const context = useAccordionItemContext();
+	if (!context) {
+		throw new Error("useAccordionItem must be called inside an <Accordion.Item>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing accordion's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useAccordion}, whose error message names the hook rather
+ * than a part.
+ */
+export function useAccordionPart(component: string): AccordionContextValue {
+	const context = useAccordionContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <Accordion>.`);
+	}
+	return context;
+}
+
+/** The enclosing item's state, for a compound part that cannot work without one. */
+export function useAccordionItemPart(component: string): AccordionItemContextValue {
+	const context = useAccordionItemContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <Accordion.Item>.`);
+	}
+	return context;
+}