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

package/src/components/slider/slider-thumb.tsx

@@ -0,0 +1,161 @@
+import { type ComponentProps, type ReactElement, useCallback } from "react";
+import type { AccessibilityActionEvent, LayoutChangeEvent, ViewProps } from "react-native";
+import Animated, { useAnimatedStyle, useDerivedValue, withSpring } from "react-native-reanimated";
+import { useSliderPart } from "./slider.context";
+import {
+	formatSliderValue,
+	progressOf,
+	SLIDER_THUMB_ANIMATION,
+	SLIDER_THUMB_SPRING,
+	sliderVariants,
+} from "./slider.variants";
+
+/** What one press of an assistive increment moves the value by, when `step` is continuous. */
+const CONTINUOUS_ACCESSIBILITY_STEPS = 10;
+
+export type SliderThumbProps = Omit<ViewProps, "children" | "style"> & {
+	/** Which value this thumb drives. `0` unless the slider holds a range. */
+	index?: number;
+	className?: string;
+	/**
+	 * Passed to the knob inside the capsule.
+	 *
+	 * A prop rather than a `classNames` map, which is the shape `Radio.Indicator`
+	 * already uses for its dot: one escape hatch, named after the thing it reaches,
+	 * and it carries every `View` prop rather than only a class.
+	 */
+	knobProps?: Omit<ComponentProps<typeof Animated.View>, "children" | "className" | "style"> & { className?: string };
+};
+
+/**
+ * The grab handle.
+ *
+ * **It holds no gesture of its own**, which is the design rather than an
+ * omission. One `Gesture.Pan()` on the track drives every thumb: a press 40pt
+ * along an empty groove should still lift the thumb it is about to move, and a
+ * per-thumb gesture could not know that. It would also nest a descendant handler
+ * inside the track's, leaving two recognisers to negotiate for one drag.
+ *
+ * **One animated style, one node.** The position and the grabbed scale are two
+ * entries in a single `transform`, because two `useAnimatedStyle` calls on one
+ * view fight for the same prop and the later one silently wins — the rule
+ * `Radio.Indicator` states, and the reason `Pressable` cannot be the thing that
+ * moves here.
+ *
+ * The scale is a `useDerivedValue` rather than a branch inside the position
+ * style: it depends only on which thumb is being dragged, so deriving it
+ * separately means the spring is evaluated when the grab changes rather than on
+ * every frame of the drag.
+ *
+ * **It is invisible until the track has been measured.** Both layouts arrive a
+ * commit or two after mount, and a thumb drawn before then sits at a garbage
+ * offset for a frame — which reads as a flicker on every mount.
+ *
+ * **The accessibility surface lives here**, and it is the whole of the control
+ * for anyone not using a finger. `adjustable` plus a value is what VoiceOver and
+ * TalkBack read; the increment and decrement actions are what their swipe
+ * gestures call. Without them a slider with no gesture on its thumb would have no
+ * assistive path to its value at all.
+ */
+export function SliderThumb({ index = 0, className, knobProps, ...props }: SliderThumbProps): ReactElement {
+	const {
+		positions,
+		trackSize,
+		thumbSize,
+		activeIndex,
+		values,
+		minValue,
+		maxValue,
+		step,
+		formatOptions,
+		orientation,
+		color,
+		size,
+		isInvalid,
+		isDisabled,
+		updateValue,
+	} = useSliderPart("Slider.Thumb");
+	const isVertical = orientation === "vertical";
+	const slots = sliderVariants({ color, isDisabled, isInvalid, orientation, size });
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			// Every thumb writes the same number — they are one size — so the last
+			// one to lay out wins with the value all of them hold.
+			thumbSize.value = isVertical ? event.nativeEvent.layout.height : event.nativeEvent.layout.width;
+		},
+		[isVertical, thumbSize]
+	);
+
+	// The capsule carries the position and the knob carries the squeeze, on two
+	// different nodes. Two animated styles on *one* node fight for the same prop
+	// and the later one silently wins — the rule `Radio.Indicator` states — and
+	// scaling the capsule would push it past the track it sits flush inside.
+	const thumbStyle = useAnimatedStyle(() => {
+		const measured = trackSize.value;
+		const travel = measured - thumbSize.value;
+		const progress = progressOf(positions.value[index] ?? minValue, minValue, maxValue);
+		const offset = travel <= 0 ? 0 : progress * travel;
+
+		return {
+			opacity: measured > 0 ? 1 : 0,
+			// A vertical slider counts up from the bottom, so the handle is anchored
+			// there and travels the other way. This sign and `valueFromOffset`'s
+			// inversion are the only two places the axis turns around.
+			transform: isVertical ? [{ translateY: -offset }] : [{ translateX: offset }],
+		};
+	});
+
+	// Derived rather than branched inside the style above: it depends only on which
+	// thumb is being dragged, so the spring is evaluated when the grab changes
+	// rather than on every frame of the drag.
+	const scale = useDerivedValue(() =>
+		withSpring(
+			activeIndex.value === index ? SLIDER_THUMB_ANIMATION.grabbedScale : SLIDER_THUMB_ANIMATION.restScale,
+			SLIDER_THUMB_SPRING
+		)
+	);
+	const knobStyle = useAnimatedStyle(() => ({ transform: [{ scale: scale.value }] }));
+
+	const value = values[index] ?? minValue;
+	const nudge = step > 0 ? step : (maxValue - minValue) / CONTINUOUS_ACCESSIBILITY_STEPS;
+
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			const direction = event.nativeEvent.actionName === "increment" ? 1 : -1;
+			updateValue(index, value + direction * nudge);
+		},
+		[index, nudge, updateValue, value]
+	);
+
+	return (
+		<Animated.View
+			accessibilityActions={ACCESSIBILITY_ACTIONS}
+			accessibilityRole="adjustable"
+			accessibilityState={{ disabled: isDisabled }}
+			accessibilityValue={{
+				max: maxValue,
+				min: minValue,
+				now: value,
+				text: formatSliderValue([value], formatOptions),
+			}}
+			accessible
+			className={slots.thumb({ className })}
+			onAccessibilityAction={handleAccessibilityAction}
+			onLayout={handleLayout}
+			style={thumbStyle}
+			{...props}
+		>
+			<Animated.View {...knobProps} className={slots.knob({ className: knobProps?.className })} style={knobStyle} />
+		</Animated.View>
+	);
+}
+SliderThumb.displayName = "DelacourUI.Slider.Thumb";
+
+/**
+ * The two actions an assistive swipe on an `adjustable` maps to.
+ *
+ * Module scope on purpose: a fresh array each render is a new prop every commit,
+ * and React Native sends the whole accessibility config across on any change.
+ */
+const ACCESSIBILITY_ACTIONS = [{ name: "increment" }, { name: "decrement" }] as const;

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

@@ -0,0 +1,233 @@
+import { type ReactElement, useCallback, useMemo } from "react";
+import type { LayoutChangeEvent, ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { playHaptic } from "../pressable";
+import { useSliderPart } from "./slider.context";
+import type { SliderRenderChildren } from "./slider.types";
+import {
+	clampThumb,
+	nearestThumbIndex,
+	shouldTickHaptic,
+	sliderVariants,
+	snapToStep,
+	valueFromOffset,
+} from "./slider.variants";
+
+export type SliderTrackProps = Omit<ViewProps, "children" | "style"> & {
+	/**
+	 * The fill and the thumbs. A function is called with the slider's settled
+	 * state, which is how a range maps over its own values.
+	 */
+	children?: SliderRenderChildren;
+	className?: string;
+};
+
+/**
+ * The groove the thumbs run along, and the surface the drag is claimed on.
+ *
+ * This is where the whole gesture lives. One `Gesture.Pan()` drives every thumb:
+ * touching down grabs the nearest one and moves it to the finger, and from there
+ * the drag tracks it. One rule rather than a tap mode and a drag mode — the
+ * alternative, dragging the handle only, is what iOS's own slider does and it is
+ * a poor trade on a wide track, where the thumb is usually nowhere near where you
+ * are pointing.
+ *
+ * **The value is written in `onBegin`, not only in `onUpdate`.** A pan activates
+ * on the first *movement*, so a stationary tap never reaches `onStart` or
+ * `onUpdate` at all — a slider that only computed there would tick, lift its
+ * thumb and then not move it. `onFinalize` is likewise where the drag is reported
+ * as finished, because it is the one callback that fires on every path, including
+ * the one where the pan never activated.
+ *
+ * **`minDistance(0)` is what wins the touch from a scroll view.**
+ * `Screen.ScrollArea` renders React Native's own `ScrollView`, not Gesture
+ * Handler's, so there is no handler to negotiate with — the two race, and a pan
+ * that activates on the first move beats a scroll view's ten-point slop on both
+ * platforms. It is also why there is no `activeOffsetX` here: waiting for the
+ * axis to declare itself would hand the scroll the first move and put a dead zone
+ * at the start of every drag. `blocksExternalGesture` is not the answer either —
+ * it resolves a ref to a handler tag, a plain `ScrollView` has none, and the call
+ * is dropped without an error.
+ *
+ * **`shouldCancelWhenOutside(false)`** where `Pressable`'s tap sets it `true`:
+ * dragging a thumb to the far end routinely leaves the track's bounds, and the
+ * value must keep tracking rather than the gesture giving up.
+ *
+ * The mirror back to React is deliberately thin. `positions` is written on the UI
+ * thread at the display's refresh rate; only a *changed* set of snapped values is
+ * scheduled across, so a whole-track drag at the default step is a few dozen
+ * commits rather than one per frame.
+ */
+export function SliderTrack({ children, className, ...props }: SliderTrackProps): ReactElement {
+	const {
+		positions,
+		trackSize,
+		thumbSize,
+		activeIndex,
+		minValue,
+		maxValue,
+		step,
+		haptic,
+		orientation,
+		color,
+		size,
+		isInvalid,
+		isDisabled,
+		commitValues,
+		commitEnd,
+		setDragging,
+		renderProps,
+	} = useSliderPart("Slider.Track");
+	const isVertical = orientation === "vertical";
+
+	// What the last haptic reported, and where the finger was when it did. Both
+	// feed `shouldTickHaptic`, which is what keeps a flick across a fine step scale
+	// from firing a hundred times.
+	const lastTick = useSharedValue(Number.NaN);
+	const lastTickPosition = useSharedValue(0);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			trackSize.value = isVertical ? event.nativeEvent.layout.height : event.nativeEvent.layout.width;
+		},
+		[isVertical, trackSize]
+	);
+
+	const gesture = useMemo(() => {
+		// Declared here rather than at module scope, and called only from the two
+		// callbacks below. A worklet defined beside its callers in one scope is
+		// captured by ordinary closure; a module-scope one binds at import time, in
+		// source order, which is how a helper ends up `undefined` on the UI thread.
+		const applyTouch = (along: number, forIndex: number, isGrab: boolean) => {
+			"worklet";
+			const thumb = thumbSize.value;
+			const travel = trackSize.value - thumb;
+			// The touch is read in the thumb's own frame — its centre, not its left
+			// edge — so the handle stays inside the groove at both ends.
+			const position = along - thumb / 2;
+			const raw = valueFromOffset({ position, travel, minValue, maxValue, isVertical });
+			const snapped = snapToStep(raw, step, minValue, maxValue);
+			const current = positions.value;
+			const next = clampThumb(snapped, current, forIndex, minValue, maxValue);
+
+			if (next !== current[forIndex]) {
+				const updated = [...current];
+				updated[forIndex] = next;
+				positions.value = updated;
+			}
+
+			// The grab itself always confirms, the way a press does. After that the
+			// ticks are the step crossings, rate-limited by distance travelled.
+			if (isGrab) {
+				lastTick.value = next;
+				lastTickPosition.value = position;
+				if (haptic !== false) playHaptic(haptic);
+				return;
+			}
+
+			if (
+				haptic !== false &&
+				shouldTickHaptic({
+					lastPosition: lastTickPosition.value,
+					lastSnapped: lastTick.value,
+					maxValue,
+					minValue,
+					position,
+					snapped: next,
+					step,
+				})
+			) {
+				playHaptic(haptic);
+				lastTick.value = next;
+				lastTickPosition.value = position;
+			}
+		};
+
+		return Gesture.Pan()
+			.enabled(!isDisabled)
+			.minDistance(0)
+			.shouldCancelWhenOutside(false)
+			.onBegin((event) => {
+				"worklet";
+				const along = isVertical ? event.y : event.x;
+				const thumb = thumbSize.value;
+				const raw = valueFromOffset({
+					isVertical,
+					maxValue,
+					minValue,
+					position: along - thumb / 2,
+					travel: trackSize.value - thumb,
+				});
+				const index = nearestThumbIndex(positions.value, raw);
+				activeIndex.value = index;
+				scheduleOnRN(setDragging, true);
+				applyTouch(along, index, true);
+			})
+			.onUpdate((event) => {
+				"worklet";
+				const index = activeIndex.value;
+				if (index < 0) return;
+				applyTouch(isVertical ? event.y : event.x, index, false);
+			})
+			.onFinalize(() => {
+				"worklet";
+				activeIndex.value = -1;
+				// Order matters: the root must have stopped treating this as a live
+				// drag before `commitEnd` asks it to re-sync. `scheduleOnRN` keeps
+				// them in the order they were queued.
+				scheduleOnRN(setDragging, false);
+				scheduleOnRN(commitEnd, [...positions.value]);
+			});
+	}, [
+		activeIndex,
+		commitEnd,
+		haptic,
+		isDisabled,
+		isVertical,
+		lastTick,
+		lastTickPosition,
+		maxValue,
+		minValue,
+		positions,
+		setDragging,
+		step,
+		thumbSize,
+		trackSize,
+	]);
+
+	// The one hop from the UI thread back to React, and it is gated element-wise:
+	// `useAnimatedReaction` re-runs on every write, and `positions` is a fresh
+	// array each time, so identity says nothing about whether the value moved.
+	useAnimatedReaction(
+		() => positions.value,
+		(current, previous) => {
+			if (previous !== null && current.length === previous.length) {
+				let changed = false;
+				for (let index = 0; index < current.length; index++) {
+					if (current[index] !== previous[index]) {
+						changed = true;
+						break;
+					}
+				}
+				if (!changed) return;
+			}
+			scheduleOnRN(commitValues, [...current]);
+		},
+		[commitValues]
+	);
+
+	const slots = sliderVariants({ color, isDisabled, isInvalid, orientation, size });
+
+	return (
+		<GestureDetector gesture={gesture}>
+			<Animated.View className={slots.touchArea()} {...props}>
+				<Animated.View className={slots.track({ className })} onLayout={handleLayout}>
+					{typeof children === "function" ? children(renderProps) : children}
+				</Animated.View>
+			</Animated.View>
+		</GestureDetector>
+	);
+}
+SliderTrack.displayName = "DelacourUI.Slider.Track";

package/src/components/slider/slider.context.tsx

@@ -0,0 +1,118 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { HapticFeedback } from "../pressable";
+import type { SliderRenderProps } from "./slider.types";
+import type { SliderColor, SliderOrientation, SliderSize } from "./slider.variants";
+
+export type SliderContextValue = {
+	/**
+	 * Every thumb's value, snapped, on the **JS thread**.
+	 *
+	 * What `Slider.Output` and the accessibility props read. The live position a
+	 * finger is dragging lives in {@link SliderContextValue.positions} instead —
+	 * these two agree at rest and lag by a mirror hop during a drag, which is the
+	 * whole reason the drag never waits on React.
+	 */
+	values: number[];
+	minValue: number;
+	maxValue: number;
+	/** The increment the values snap to. `0` is continuous. */
+	step: number;
+	orientation: SliderOrientation;
+	color: SliderColor;
+	size: SliderSize;
+	isDisabled: boolean;
+	isInvalid: boolean;
+	/** Passed to `Intl.NumberFormat` by `Slider.Output`. */
+	formatOptions?: Intl.NumberFormatOptions;
+	/** Played as the value crosses a step. `false` silences it. */
+	haptic: false | HapticFeedback;
+	/**
+	 * Every thumb's live value, on the **UI thread**.
+	 *
+	 * One shared value holding the whole array rather than one per thumb, because
+	 * a thumb count is data and hooks cannot be called in a loop. Reassign it —
+	 * `positions.value = next` — and never write an element in place: an array
+	 * element has no setter behind it, so `positions.value[0] = x` updates nothing
+	 * and fails silently.
+	 */
+	positions: SharedValue<number[]>;
+	/** The track's own length, from its `onLayout`. `0` until it has been measured. */
+	trackSize: SharedValue<number>;
+	/** A thumb's diameter, from its `onLayout`. `0` until it has been measured. */
+	thumbSize: SharedValue<number>;
+	/** Which thumb is being dragged, or `-1` when none is. */
+	activeIndex: SharedValue<number>;
+	/**
+	 * Writes one thumb's value from the **JS thread**, snapping and clamping it
+	 * first.
+	 *
+	 * The one path into the value that does not go through the pan — an
+	 * accessibility increment has no gesture behind it.
+	 */
+	updateValue: (index: number, next: number) => void;
+	/**
+	 * Tells the root a drag has started or finished.
+	 *
+	 * The root stops syncing the shared value from React state while this is true.
+	 * Without it the mirror hop back from the UI thread would round-trip through a
+	 * render and land on the thumb a frame late, dragging it backwards on every
+	 * commit — a jitter that only shows up on a fast drag.
+	 */
+	setDragging: (dragging: boolean) => void;
+	/** Reports a drag's new values. Called from the pan's mirror, never in render. */
+	commitValues: (next: number[]) => void;
+	/** Reports the values a drag settled on, once, on release. */
+	commitEnd: (next: number[]) => void;
+	/** The settled state a render function is handed. */
+	renderProps: SliderRenderProps;
+};
+
+const SliderContext = createContext<SliderContextValue | null>(null);
+
+/**
+ * Supplies one slider's settled state to its own parts.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./slider`. 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 SliderProvider({ value, children }: { value: SliderContextValue; children: ReactNode }): ReactElement {
+	return <SliderContext value={value}>{children}</SliderContext>;
+}
+SliderProvider.displayName = "DelacourUI.Slider.Provider";
+
+/** The enclosing slider's state, or null outside a `<Slider>`. */
+export function useSliderContext(): SliderContextValue | null {
+	return use(SliderContext);
+}
+
+/**
+ * Reads the enclosing slider's settled state.
+ *
+ * For a custom readout or a custom thumb that has to match the slider it sits in.
+ * Throws outside one — use {@link useSliderContext} where the slider is optional.
+ */
+export function useSlider(): SliderContextValue {
+	const context = useSliderContext();
+	if (!context) {
+		throw new Error("useSlider must be called inside a <Slider>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing slider'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 useSlider}, whose error message names the hook rather than
+ * a part.
+ */
+export function useSliderPart(component: string): SliderContextValue {
+	const context = useSliderContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Slider>.`);
+	}
+	return context;
+}