@delacour/react-native-ui 0.1.0-alpha.4 → 0.2.0-alpha.20261010061731

package/src/components/progress/progress-fill.tsx

@@ -0,0 +1,152 @@
+import { type ReactElement, useEffect } from "react";
+import type { ViewProps } from "react-native";
+import Animated, {
+	cancelAnimation,
+	Easing,
+	ReduceMotion,
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withRepeat,
+	withTiming,
+} from "react-native-reanimated";
+import { useProgressPart } from "./progress.context";
+import {
+	fillTranslate,
+	indeterminateSegment,
+	PROGRESS_FILL_DURATION_MS,
+	PROGRESS_INDETERMINATE_DURATION_MS,
+	PROGRESS_INDETERMINATE_SEGMENT,
+	PROGRESS_PULSE,
+	progressVariants,
+} from "./progress.variants";
+
+export type ProgressFillProps = Omit<ViewProps, "children" | "style"> & {
+	className?: string;
+};
+
+/**
+ * The painted bar.
+ *
+ * **Everything it animates runs on the UI thread.** A new value is handed to
+ * `withTiming` once, from an effect, and the frames that follow never touch
+ * React — so an upload reporting ten times a second costs ten renders, not six
+ * hundred.
+ *
+ * **Determinate, it is a full-length bar parked left of the track** by what is
+ * still to go, and a `translateX` slides it in. A transform composites without a
+ * layout pass; an animated `width` would re-lay the bar out on every frame. The
+ * track clips what is parked.
+ *
+ * **Indeterminate, it is a segment sweeping across**, from wholly off the left
+ * edge to wholly off the right, so the loop's seam is never on screen. With the
+ * system's reduce-motion setting on, the sweep becomes the whole track breathing
+ * between two opacities instead: still visibly alive — which a status indicator
+ * must be, the same reasoning `Spinner` gives for opting out of the policy — but
+ * with nothing travelling across the screen.
+ *
+ * It is hidden until the track has been measured. A fill positioned against a
+ * width of 0 would flash at full length for the frame before layout lands.
+ */
+export function ProgressFill({ className, ...props }: ProgressFillProps): ReactElement {
+	const { ratio, isIndeterminate, color, size, trackSize } = useProgressPart("Progress.Fill");
+	const isReducedMotion = useReducedMotion();
+
+	// Seeded at the current ratio, so a bar that mounts at 60% is drawn at 60%
+	// rather than animating up from nothing every time a list row scrolls in.
+	const progress = useSharedValue(ratio);
+	const phase = useSharedValue(0);
+	const pulse = useSharedValue<number>(PROGRESS_PULSE.to);
+
+	useEffect(() => {
+		if (isIndeterminate) return;
+		progress.value = withTiming(ratio, {
+			duration: PROGRESS_FILL_DURATION_MS,
+			easing: Easing.out(Easing.cubic),
+		});
+	}, [isIndeterminate, progress, ratio]);
+
+	useEffect(() => {
+		if (!isIndeterminate) return;
+
+		if (isReducedMotion) {
+			pulse.value = PROGRESS_PULSE.to;
+			pulse.value = withRepeat(
+				withTiming(PROGRESS_PULSE.from, {
+					duration: PROGRESS_PULSE.durationMs,
+					easing: Easing.inOut(Easing.ease),
+					// Under the default `System` policy the timing completes instantly
+					// while reduce motion is on, and `withRepeat(-1)` would spin a
+					// zero-length animation forever — a frozen bar, which reads as hung.
+					reduceMotion: ReduceMotion.Never,
+				}),
+				-1,
+				true,
+				undefined,
+				// The repeat has a reduce-motion policy of its own, separate from the
+				// timing's. Left at `System`, it declines to start a reversing loop at
+				// all and stops a forward one after a single pass.
+				ReduceMotion.Never
+			);
+		} else {
+			phase.value = 0;
+			phase.value = withRepeat(
+				withTiming(1, {
+					duration: PROGRESS_INDETERMINATE_DURATION_MS,
+					easing: Easing.inOut(Easing.ease),
+					reduceMotion: ReduceMotion.Never,
+				}),
+				-1,
+				false,
+				undefined,
+				ReduceMotion.Never
+			);
+		}
+
+		// Without this the repeat outlives the bar, or the switch back to a value.
+		return () => {
+			cancelAnimation(phase);
+			cancelAnimation(pulse);
+			pulse.value = PROGRESS_PULSE.to;
+		};
+	}, [isIndeterminate, isReducedMotion, phase, pulse]);
+
+	const fillStyle = useAnimatedStyle(() => {
+		const track = trackSize.value;
+		const isMeasured = track > 0;
+
+		// The same keys every frame, so Reanimated is never asked to swap a style's
+		// shape when the bar flips between modes.
+		if (isIndeterminate && !isReducedMotion) {
+			const segment = indeterminateSegment({
+				phase: phase.value,
+				segment: PROGRESS_INDETERMINATE_SEGMENT,
+				trackSize: track,
+			});
+			return {
+				opacity: isMeasured ? 1 : 0,
+				transform: [{ translateX: segment.translate }],
+				width: segment.width,
+			};
+		}
+
+		if (isIndeterminate) {
+			return { opacity: isMeasured ? pulse.value : 0, transform: [{ translateX: 0 }], width: track };
+		}
+
+		return {
+			opacity: isMeasured ? 1 : 0,
+			transform: [{ translateX: fillTranslate({ ratio: progress.value, trackSize: track }) }],
+			width: track,
+		};
+	});
+
+	return (
+		<Animated.View
+			className={progressVariants({ color, isIndeterminate, size }).fill({ className })}
+			style={fillStyle}
+			{...props}
+		/>
+	);
+}
+ProgressFill.displayName = "DelacourUI.Progress.Fill";

package/src/components/progress/progress-header.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { useProgressPart } from "./progress.context";
+import { progressVariants } from "./progress.variants";
+
+export type ProgressHeaderProps = ViewProps;
+
+/**
+ * The row above the track: a label at the start, a readout at the end.
+ *
+ * A part rather than a `View` the caller writes because every labelled bar
+ * wants exactly this row, and a hand-written one drifts — a missing `gap` lets a
+ * long label run into the percentage.
+ */
+export function ProgressHeader({ className, ...props }: ProgressHeaderProps): ReactElement {
+	const { color, size, isIndeterminate } = useProgressPart("Progress.Header");
+	return <View className={progressVariants({ color, isIndeterminate, size }).header({ className })} {...props} />;
+}
+ProgressHeader.displayName = "DelacourUI.Progress.Header";

package/src/components/progress/progress-label.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useProgressPart } from "./progress.context";
+import { PROGRESS_OUTPUT_TEXT_SIZE, progressVariants } from "./progress.variants";
+
+export type ProgressLabelProps = TextPresetProps;
+
+/**
+ * What the bar is measuring — "Uploading", "Storage".
+ *
+ * Renders `Text.Label` and names a size step, never a scale of its own, so the
+ * weight and colour stay in the preset. It is left visible to assistive
+ * technology: the root is one accessible element, and a label inside it is what
+ * VoiceOver and TalkBack read as that element's name.
+ */
+export function ProgressLabel({ className, size, ...props }: ProgressLabelProps): ReactElement {
+	const { color, size: progressSize, isIndeterminate } = useProgressPart("Progress.Label");
+	return (
+		<Text.Label
+			className={progressVariants({ color, isIndeterminate, size: progressSize }).label({ className })}
+			numberOfLines={1}
+			size={size ?? PROGRESS_OUTPUT_TEXT_SIZE[progressSize]}
+			{...props}
+		/>
+	);
+}
+ProgressLabel.displayName = "DelacourUI.Progress.Label";

package/src/components/progress/progress-output.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useProgressPart } from "./progress.context";
+import type { ProgressRenderChildren } from "./progress.types";
+import { PROGRESS_OUTPUT_TEXT_SIZE, progressVariants } from "./progress.variants";
+
+export type ProgressOutputProps = Omit<TextPresetProps, "children"> & {
+	/** Custom content, or a function called with the bar's settled state. */
+	children?: ProgressRenderChildren;
+};
+
+/**
+ * The current value, formatted — `72%` by default.
+ *
+ * A function child is handed the bar's state, which is how a count reads
+ * `18 of 24` rather than a percentage.
+ *
+ * **Hidden from assistive technology on purpose.** The root already publishes
+ * the value as `accessibilityValue`, so a readout left visible inside it would be
+ * read twice — once as part of the element's name, once as its value.
+ *
+ * **An indeterminate bar has no value**, so the default readout renders nothing.
+ * A function child still runs, which is where a "Waiting…" belongs.
+ */
+export function ProgressOutput({ children, className, size, ...props }: ProgressOutputProps): ReactElement | null {
+	const { color, size: progressSize, isIndeterminate, renderProps } = useProgressPart("Progress.Output");
+
+	const content =
+		typeof children === "function"
+			? children(renderProps)
+			: (children ?? (isIndeterminate ? null : renderProps.formatted));
+
+	if (content === null || content === undefined) return null;
+
+	return (
+		<Text.Label
+			accessibilityElementsHidden
+			className={progressVariants({ color, isIndeterminate, size: progressSize }).output({ className })}
+			importantForAccessibility="no-hide-descendants"
+			size={size ?? PROGRESS_OUTPUT_TEXT_SIZE[progressSize]}
+			{...props}
+		>
+			{content}
+		</Text.Label>
+	);
+}
+ProgressOutput.displayName = "DelacourUI.Progress.Output";

package/src/components/progress/progress-track.tsx

@@ -0,0 +1,38 @@
+import { type ReactElement, type ReactNode, useCallback } from "react";
+import { type LayoutChangeEvent, View, type ViewProps } from "react-native";
+import { useProgressPart } from "./progress.context";
+import { progressVariants } from "./progress.variants";
+
+export type ProgressTrackProps = Omit<ViewProps, "children"> & {
+	/** The fill. */
+	children?: ReactNode;
+};
+
+/**
+ * The clipped, rounded groove the fill slides along.
+ *
+ * It measures its own width into the shared value the fill reads, because the
+ * fill is positioned by a transform in points and a transform cannot name a
+ * percentage. The clip is what turns a full-length bar parked off to the left
+ * into a bar that appears to grow — see `progressVariants`.
+ */
+export function ProgressTrack({ className, onLayout, ...props }: ProgressTrackProps): ReactElement {
+	const { color, size, isIndeterminate, trackSize } = useProgressPart("Progress.Track");
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			trackSize.value = event.nativeEvent.layout.width;
+			onLayout?.(event);
+		},
+		[onLayout, trackSize]
+	);
+
+	return (
+		<View
+			className={progressVariants({ color, isIndeterminate, size }).track({ className })}
+			onLayout={handleLayout}
+			{...props}
+		/>
+	);
+}
+ProgressTrack.displayName = "DelacourUI.Progress.Track";

package/src/components/progress/progress.context.tsx

@@ -0,0 +1,79 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { ProgressRenderProps } from "./progress.types";
+import type { ProgressColor, ProgressSize } from "./progress.variants";
+
+/**
+ * What a progress bar's parts read.
+ *
+ * **The track and the fill read only `ratio`, `isIndeterminate`, `color`, `size`
+ * and `trackSize`.** That is deliberate: a meter is the same track and the same
+ * fill with a different root deciding the ratio and the colour, so a root that
+ * publishes this shape can reuse `Progress.Track` and `Progress.Fill` as they
+ * stand. Nothing the parts draw reaches back to how the ratio was arrived at.
+ */
+export type ProgressContextValue = {
+	/** Where the value sits in the range, clamped to 0–1, on the JS thread. */
+	ratio: number;
+	/** Loops a segment along the track instead of showing a value. */
+	isIndeterminate: boolean;
+	color: ProgressColor;
+	size: ProgressSize;
+	/** The track's own width, from its `onLayout`. `0` until it has been measured. */
+	trackSize: SharedValue<number>;
+	/** The settled state `Progress.Output` formats and a render function is handed. */
+	renderProps: ProgressRenderProps;
+};
+
+const ProgressContext = createContext<ProgressContextValue | null>(null);
+
+/**
+ * Supplies one progress bar's state to its own parts.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./progress` — that import would close a cycle, and
+ * Metro serves a partially initialised module for a cycle.
+ */
+export function ProgressProvider({
+	value,
+	children,
+}: {
+	value: ProgressContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ProgressContext value={value}>{children}</ProgressContext>;
+}
+ProgressProvider.displayName = "DelacourUI.Progress.Provider";
+
+/** The enclosing progress bar's state, or null outside a `<Progress>`. */
+export function useProgressContext(): ProgressContextValue | null {
+	return use(ProgressContext);
+}
+
+/**
+ * Reads the enclosing progress bar's state.
+ *
+ * For a custom readout or a custom fill that has to match the bar it sits in.
+ * Throws outside one — use {@link useProgressContext} where the bar is optional.
+ */
+export function useProgress(): ProgressContextValue {
+	const context = useProgressContext();
+	if (!context) {
+		throw new Error("useProgress must be called inside a <Progress>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing bar'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 useProgress}, whose error names the hook rather than a part.
+ */
+export function useProgressPart(component: string): ProgressContextValue {
+	const context = useProgressContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Progress>.`);
+	}
+	return context;
+}

package/src/components/progress/progress.tsx

@@ -0,0 +1,171 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { useSharedValue } from "react-native-reanimated";
+import { type ProgressContextValue, ProgressProvider } from "./progress.context";
+import type { ProgressRenderProps } from "./progress.types";
+import {
+	formatProgressValue,
+	PROGRESS_MAX_VALUE,
+	PROGRESS_MIN_VALUE,
+	type ProgressColor,
+	type ProgressSize,
+	progressRatio,
+	progressVariants,
+	resolveProgressAccessibility,
+	resolveProgressAxes,
+} from "./progress.variants";
+import { ProgressFill } from "./progress-fill";
+import { ProgressHeader } from "./progress-header";
+import { ProgressLabel } from "./progress-label";
+import { ProgressOutput } from "./progress-output";
+import { ProgressTrack } from "./progress-track";
+
+export type ProgressProps = Omit<ViewProps, "children"> & {
+	/** How far along, between `minValue` and `maxValue`. Ignored while indeterminate. */
+	value?: number;
+	minValue?: number;
+	maxValue?: number;
+	/** Loops a segment along the track, for work whose length is not known yet. */
+	isIndeterminate?: boolean;
+	/**
+	 * Passed to `Intl.NumberFormat` by `Progress.Output` and the spoken value.
+	 * With none, or a `percent` style, the readout is the share of the range.
+	 */
+	formatOptions?: Intl.NumberFormatOptions;
+	/** Replaces the formatted readout, on screen and to assistive technology. */
+	valueLabel?: string;
+	/** What the filled part of the track means. */
+	color?: ProgressColor;
+	size?: ProgressSize;
+	/** The anatomy. With none, the bar draws a bare track and fill. */
+	children?: ReactNode;
+};
+
+function ProgressRoot({
+	value = PROGRESS_MIN_VALUE,
+	minValue = PROGRESS_MIN_VALUE,
+	maxValue = PROGRESS_MAX_VALUE,
+	isIndeterminate,
+	formatOptions,
+	valueLabel,
+	color,
+	size,
+	className,
+	children,
+	...props
+}: ProgressProps): ReactElement {
+	const axes = resolveProgressAxes({ color, isIndeterminate, size });
+	const trackSize = useSharedValue(0);
+
+	const ratio = progressRatio(value, minValue, maxValue);
+
+	const formatted = useMemo(
+		() => valueLabel ?? formatProgressValue({ formatOptions, maxValue, minValue, value }),
+		[formatOptions, maxValue, minValue, value, valueLabel]
+	);
+
+	const accessibility = useMemo(
+		() =>
+			resolveProgressAccessibility({
+				formatOptions,
+				isIndeterminate: axes.isIndeterminate,
+				maxValue,
+				minValue,
+				value,
+				valueLabel,
+			}),
+		[axes.isIndeterminate, formatOptions, maxValue, minValue, value, valueLabel]
+	);
+
+	const renderProps = useMemo<ProgressRenderProps>(
+		() => ({ formatted, isIndeterminate: axes.isIndeterminate, maxValue, minValue, ratio, value }),
+		[axes.isIndeterminate, formatted, maxValue, minValue, ratio, value]
+	);
+
+	const context = useMemo<ProgressContextValue>(
+		() => ({
+			color: axes.color,
+			isIndeterminate: axes.isIndeterminate,
+			ratio,
+			renderProps,
+			size: axes.size,
+			trackSize,
+		}),
+		[axes.color, axes.isIndeterminate, axes.size, ratio, renderProps, trackSize]
+	);
+
+	// A bare `<Progress value={40} />` draws the bar. A compound root with no
+	// default anatomy draws nothing at all, which is a failure with no error.
+	const content = children ?? (
+		<ProgressTrack>
+			<ProgressFill />
+		</ProgressTrack>
+	);
+
+	return (
+		<ProgressProvider value={context}>
+			<View
+				accessibilityRole="progressbar"
+				accessibilityState={{ busy: accessibility.busy }}
+				accessibilityValue={accessibility.value}
+				accessible
+				className={progressVariants(axes).root({ className })}
+				{...props}
+			>
+				{content}
+			</View>
+		</ProgressProvider>
+	);
+}
+
+/**
+ * How far a task has got — or, indeterminate, that it is under way.
+ *
+ * The anatomy is written out: a `Progress.Track` holding a `Progress.Fill`, with
+ * an optional `Progress.Header` above it carrying a `Progress.Label` and a
+ * `Progress.Output`. A bare `<Progress value={40} />` draws the track and fill on
+ * its own.
+ *
+ * **The fill animates on the UI thread.** A new value starts one timing and the
+ * frames never touch React. `isIndeterminate` loops a segment along the track
+ * instead, and with the system's reduce-motion setting on it breathes in place
+ * rather than travelling.
+ *
+ * **It is one accessible element with the `progressbar` role.** The range and
+ * the value are published as `accessibilityValue`, spoken as `72%` over 0–100
+ * and as `18 of 24` over any other range; a `Progress.Label` inside it is its
+ * name. An indeterminate bar reports `busy` and no value.
+ *
+ * It is not a control, so there is no disabled or invalid state and it takes
+ * nothing from an enclosing `Field`. A bar that has failed is `color="destructive"`.
+ *
+ * @example
+ * <Progress value={40} />
+ *
+ * @example
+ * <Progress color="success" value={uploaded} maxValue={total} formatOptions={{ style: "unit", unit: "megabyte" }}>
+ *   <Progress.Header>
+ *     <Progress.Label>Uploading</Progress.Label>
+ *     <Progress.Output />
+ *   </Progress.Header>
+ *   <Progress.Track>
+ *     <Progress.Fill />
+ *   </Progress.Track>
+ * </Progress>
+ *
+ * @example
+ * <Progress accessibilityLabel="Syncing" isIndeterminate />
+ */
+export const Progress = Object.assign(ProgressRoot, {
+	/** The row above the track: a label at the start, a readout at the end. */
+	Header: ProgressHeader,
+	/** What the bar is measuring. Read as the bar's accessible name. */
+	Label: ProgressLabel,
+	/** The value, formatted. Give it a function to word it yourself. */
+	Output: ProgressOutput,
+	/** The clipped groove the fill slides along. */
+	Track: ProgressTrack,
+	/** The painted bar — a value, or a looping segment while indeterminate. */
+	Fill: ProgressFill,
+	displayName: "DelacourUI.Progress",
+});

package/src/components/progress/progress.types.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+
+/**
+ * What a render function inside a progress bar is handed.
+ *
+ * Shared by the root's context and `Progress.Output`, which is what puts it here
+ * rather than in either one's own file — two consumers is the bar a
+ * `{name}.types.ts` entry has to clear. See AGENTS.md.
+ */
+export type ProgressRenderProps = {
+	/** The value as given, unclamped — the readout is the caller's to word. */
+	value: number;
+	minValue: number;
+	maxValue: number;
+	/** Where the value sits in the range, clamped to 0–1. */
+	ratio: number;
+	/** The readout's default text: `valueLabel`, or the formatted value. */
+	formatted: string;
+	isIndeterminate: boolean;
+};
+
+/** A part whose children may be written out or computed from the bar's state. */
+export type ProgressRenderChildren = ReactNode | ((props: ProgressRenderProps) => ReactNode);