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

package/src/components/collapsible/collapsible.tsx

@@ -0,0 +1,167 @@
+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,
+	collapsibleTravelTarget,
+	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);
+
+	// Whether the panel has ever reported a height — React state, never a JS-thread
+	// read of `contentHeight`, which can lag the write. See `collapsibleTravelTarget`
+	// and `onMeasured` on the context.
+	const [isMeasured, setMeasured] = useState(false);
+	const onMeasured = useCallback(() => setMeasured(true), []);
+
+	// The first open of a panel that has never mounted has no height to travel
+	// against, so that run waits and the measurement that follows brings it back.
+	useEffect(() => {
+		const target = collapsibleTravelTarget({ isMeasured, isOpen });
+		if (target === null) return;
+
+		progress.value = withSpring(target, COLLAPSIBLE_SPRING);
+
+		return () => cancelAnimation(progress);
+	}, [isMeasured, isOpen, 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,338 @@
+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,
+	accordionTravelTarget,
+	accordionVariants,
+} from "../accordion/accordion.variants";
+import { CONTENT_HEIGHT_READ, jsThreadSource } from "../accordion/accordion.variants.test";
+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,
+	collapsibleTravelTarget,
+	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()));
+		}
+	});
+});
+
+describe("collapsibleTravelTarget", () => {
+	test("an open waits for the panel's first measurement", () => {
+		expect(collapsibleTravelTarget({ isOpen: true, isMeasured: false })).toBeNull();
+	});
+
+	test("an open travels to 1 once the panel has measured", () => {
+		expect(collapsibleTravelTarget({ isOpen: true, isMeasured: true })).toBe(1);
+	});
+
+	test("a close never waits, measured or not", () => {
+		expect(collapsibleTravelTarget({ isOpen: false, isMeasured: false })).toBe(0);
+		expect(collapsibleTravelTarget({ isOpen: false, isMeasured: true })).toBe(0);
+	});
+
+	test("agrees with the accordion's rule on every input", () => {
+		for (const isOpen of [false, true]) {
+			for (const isMeasured of [false, true]) {
+				expect(collapsibleTravelTarget({ isOpen, isMeasured })).toBe(
+					accordionTravelTarget({ isExpanded: isOpen, isMeasured })
+				);
+			}
+		}
+	});
+});
+
+describe("the measured height is never read on the JS thread", () => {
+	// `Accordion`'s Release-build bug, in the same two files: a JS-thread read straight after the
+	// panel's `onLayout` wrote the height can still see `COLLAPSIBLE_UNMEASURED`.
+	test.each(["collapsible.tsx", "collapsible-content.tsx"])("%s", (file) => {
+		expect(jsThreadSource(join(import.meta.dirname, file))).not.toMatch(CONTENT_HEIGHT_READ);
+	});
+});