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

package/src/components/rating/rating-stars.tsx

@@ -0,0 +1,219 @@
+import { type ReactElement, useCallback, useEffect, useMemo, useState } from "react";
+import { type AccessibilityActionEvent, type LayoutChangeEvent, View, type ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import { useSharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { playHaptic } from "../pressable";
+import { useRatingPart } from "./rating.context";
+import {
+	describeRating,
+	ratingFromOffset,
+	ratingVariants,
+	resolveRatingPaint,
+	shouldClearRating,
+	starFillOf,
+	stepRating,
+} from "./rating.variants";
+import { RatingStar } from "./rating-star";
+
+export type RatingStarsProps = Omit<ViewProps, "children" | "style"> & {
+	className?: string;
+};
+
+/**
+ * The row of stars, the surface the gesture is claimed on, and the whole
+ * accessibility surface.
+ *
+ * **It is not a `Pressable`, and neither is a star.** The reasons are
+ * `Slider.Track`'s: `Pressable`'s tap fires `onPress` on every touch-to-set, and a
+ * `Pressable` per star would nest five taps inside the row's pan and leave them
+ * to negotiate for one drag. One `Gesture.Pan()` on the row reads the star under
+ * the finger, on touch-down and throughout the drag. What is inherited is the
+ * vocabulary — `playHaptic` from `pressable.tsx`, the one haptic switch.
+ *
+ * **The value is written in `onBegin`**, because a pan activates on the first
+ * movement and a stationary tap would otherwise never set anything.
+ * `minDistance(0)` wins the touch from an enclosing scroll view, and
+ * `shouldCancelWhenOutside(false)` keeps a drag past the last star tracking it.
+ * `onFinalize` is where a clear is decided and the gesture reported finished,
+ * because it is the one callback that fires on every path.
+ *
+ * **The stars render from React state; the gesture reads a shared value.** A
+ * rating crosses at most a handful of stops in a drag, so a commit per crossing
+ * is a handful of commits and no mirror on the UI thread is worth its code. The
+ * shared value exists so the worklet can tell a crossing from a repeat without
+ * waiting on a render, and it is re-synced from React whenever the gesture ends —
+ * which is what snaps a controlled rating back when its parent rejects a value.
+ *
+ * **To assistive technology the row is one `adjustable` control.** Its value is
+ * spoken as "3.5 out of 5" and a swipe up or down steps it. A read-only rating
+ * is an `image` with the same value: something to read, not something to set.
+ */
+export function RatingStars({ className, onLayout, ...props }: RatingStarsProps): ReactElement {
+	const {
+		value,
+		count,
+		step,
+		color,
+		size,
+		isDisabled,
+		isInvalid,
+		isReadOnly,
+		allowClear,
+		haptic,
+		setValue,
+		commitEnd,
+	} = useRatingPart("Rating.Stars");
+	const slots = ratingVariants({ isDisabled, size });
+	const paint = resolveRatingPaint({ color, isInvalid });
+	const fillColor = useThemeColor(paint.fill);
+	const emptyColor = useThemeColor(paint.empty);
+	const isInteractive = !isDisabled && !isReadOnly;
+
+	const width = useSharedValue(0);
+	const current = useSharedValue(value);
+	const startValue = useSharedValue(value);
+	const startX = useSharedValue(0);
+	const travel = useSharedValue(0);
+
+	// Bumped when a gesture ends, purely to re-run the sync below. A controlled
+	// parent that rejects a value leaves `value` unchanged, so without the token
+	// the shared value would keep the rejected one and the next tap would compare
+	// against a number nobody holds.
+	const [settledGestures, setSettledGestures] = useState(0);
+	const settle = useCallback(() => setSettledGestures((settledCount) => settledCount + 1), []);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: the token is the re-run trigger, see above
+	useEffect(() => {
+		current.value = value;
+	}, [current, value, settledGestures]);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			width.value = event.nativeEvent.layout.width;
+			onLayout?.(event);
+		},
+		[onLayout, width]
+	);
+
+	const gesture = useMemo(() => {
+		// Beside its callers rather than at module scope, so it is captured by
+		// ordinary closure — see Slider's AGENTS.md on module-scope worklets.
+		const applyTouch = (x: number, isGrab: boolean) => {
+			"worklet";
+			const next = ratingFromOffset({ count, position: x, step, width: width.value });
+			if (next <= 0) return;
+
+			const changed = next !== current.value;
+			if (changed) {
+				current.value = next;
+				scheduleOnRN(setValue, next);
+			}
+			if (haptic !== false && (isGrab || changed)) playHaptic(haptic);
+		};
+
+		return Gesture.Pan()
+			.enabled(isInteractive)
+			.minDistance(0)
+			.shouldCancelWhenOutside(false)
+			.onBegin((event) => {
+				"worklet";
+				startValue.value = current.value;
+				startX.value = event.x;
+				travel.value = 0;
+				applyTouch(event.x, true);
+			})
+			.onUpdate((event) => {
+				"worklet";
+				const moved = Math.abs(event.x - startX.value);
+				if (moved > travel.value) travel.value = moved;
+				applyTouch(event.x, false);
+			})
+			.onFinalize(() => {
+				"worklet";
+				if (
+					shouldClearRating({
+						allowClear,
+						startValue: startValue.value,
+						touchedValue: current.value,
+						travel: travel.value,
+					})
+				) {
+					current.value = 0;
+					scheduleOnRN(setValue, 0);
+					if (haptic !== false) playHaptic(haptic);
+				}
+				scheduleOnRN(commitEnd, current.value);
+				scheduleOnRN(settle);
+			});
+	}, [
+		allowClear,
+		commitEnd,
+		count,
+		current,
+		haptic,
+		isInteractive,
+		setValue,
+		settle,
+		startValue,
+		startX,
+		step,
+		travel,
+		width,
+	]);
+
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			if (!isInteractive) return;
+			const direction = event.nativeEvent.actionName === "increment" ? 1 : -1;
+			const next = stepRating(value, direction, step, count);
+			if (next === value) return;
+			setValue(next);
+			commitEnd(next);
+		},
+		[commitEnd, count, isInteractive, setValue, step, value]
+	);
+
+	const glyphClassName = slots.glyph();
+	const clipClassName = slots.clip();
+	const cellClassName = slots.cell();
+	const stars = Array.from({ length: count }, (_, index) => index);
+
+	return (
+		<GestureDetector gesture={gesture}>
+			<View
+				accessibilityActions={isReadOnly ? undefined : ACCESSIBILITY_ACTIONS}
+				accessibilityLabel="Rating"
+				accessibilityRole={isReadOnly ? "image" : "adjustable"}
+				accessibilityState={{ disabled: isDisabled }}
+				accessibilityValue={{ max: count, min: 0, now: value, text: describeRating(value, count) }}
+				accessible
+				className={slots.stars({ className })}
+				onAccessibilityAction={handleAccessibilityAction}
+				onLayout={handleLayout}
+				{...props}
+			>
+				{stars.map((index) => (
+					<View className={cellClassName} key={index}>
+						<RatingStar
+							clipClassName={clipClassName}
+							emptyColor={emptyColor}
+							fill={starFillOf(index, value)}
+							fillColor={fillColor}
+							glyphClassName={glyphClassName}
+						/>
+					</View>
+				))}
+			</View>
+		</GestureDetector>
+	);
+}
+RatingStars.displayName = "DelacourUI.Rating.Stars";
+
+/**
+ * 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.
+ */
+const ACCESSIBILITY_ACTIONS = [{ name: "increment" }, { name: "decrement" }] as const;

package/src/components/rating/rating.context.tsx

@@ -0,0 +1,79 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { HapticFeedback } from "../pressable";
+import type { RatingColor, RatingSize } from "./rating.variants";
+
+/** What a render function inside a rating is handed. */
+export type RatingRenderProps = {
+	/** The value, clamped to the count but not snapped — a read-only 3.7 stays 3.7. */
+	value: number;
+	/** How many stars the row draws. */
+	count: number;
+	/** The increment a touch snaps to. */
+	step: number;
+	isDisabled: boolean;
+	isInvalid: boolean;
+	isReadOnly: boolean;
+};
+
+export type RatingContextValue = RatingRenderProps & {
+	color: RatingColor;
+	size: RatingSize;
+	/** A tap on the value already held clears it back to zero. */
+	allowClear: boolean;
+	/** Played on grab, on every star crossed and on a clear. `false` silences it. */
+	haptic: false | HapticFeedback;
+	/**
+	 * Writes a new value from the **JS thread**. Called from the gesture's mirror,
+	 * from an assistive action and from a clear — never in render.
+	 */
+	setValue: (next: number) => void;
+	/** Reports the value a gesture or an assistive action settled on, once. */
+	commitEnd: (next: number) => void;
+	/** The settled state a render function is handed. */
+	renderProps: RatingRenderProps;
+};
+
+const RatingContext = createContext<RatingContextValue | null>(null);
+
+/**
+ * Supplies one rating'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 `./rating` and closing a cycle (AGENTS.md rule 3).
+ */
+export function RatingProvider({ value, children }: { value: RatingContextValue; children: ReactNode }): ReactElement {
+	return <RatingContext value={value}>{children}</RatingContext>;
+}
+RatingProvider.displayName = "DelacourUI.Rating.Provider";
+
+/** The enclosing rating's state, or null outside a `<Rating>`. */
+export function useRatingContext(): RatingContextValue | null {
+	return use(RatingContext);
+}
+
+/**
+ * Reads the enclosing rating's settled state.
+ *
+ * For a custom readout that has to match the rating it sits beside. Throws
+ * outside one — use {@link useRatingContext} where the rating is optional.
+ */
+export function useRating(): RatingContextValue {
+	const context = useRatingContext();
+	if (!context) {
+		throw new Error("useRating must be called inside a <Rating>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing rating's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useRatingPart(component: string): RatingContextValue {
+	const context = useRatingContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Rating>.`);
+	}
+	return context;
+}

package/src/components/rating/rating.tsx

@@ -0,0 +1,163 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { useFieldContext } from "../field/field.context";
+import type { HapticFeedback } from "../pressable";
+import { type RatingContextValue, RatingProvider, type RatingRenderProps } from "./rating.context";
+import {
+	clampRating,
+	normalizeRatingCount,
+	normalizeRatingStep,
+	type RatingColor,
+	type RatingSize,
+	ratingVariants,
+	resolveRatingAxes,
+} from "./rating.variants";
+import { RatingOutput } from "./rating-output";
+import { RatingStars } from "./rating-stars";
+
+export type RatingProps = Omit<ViewProps, "children"> & {
+	/** Controlled value. Any number is drawn; only `step` limits what a touch can set. */
+	value?: number;
+	/** Starting value while uncontrolled. */
+	defaultValue?: number;
+	/** How many stars. A fraction rounds down; anything that is not a count falls back to 5. */
+	maxValue?: number;
+	/** The increment a touch snaps to — `1` for whole stars, `0.5` for halves. Must divide one star. */
+	step?: number;
+	/** What a filled star means. */
+	color?: RatingColor;
+	size?: RatingSize;
+	/** Blocks the gesture and fades the control. Inherited from an enclosing `Field`. */
+	isDisabled?: boolean;
+	/** Paints the stars destructive. Inherited from an enclosing `Field`. */
+	isInvalid?: boolean;
+	/** Shows the score without taking a touch, and without fading. */
+	isReadOnly?: boolean;
+	/** A tap on the value already held clears it back to zero. */
+	allowClear?: boolean;
+	/** Played on grab, on every star crossed and on a clear. `false` silences it. */
+	haptic?: false | HapticFeedback;
+	/** Fires on every change during a drag. */
+	onChange?: (value: number) => void;
+	/** Fires once, when the gesture ends. Where a network write belongs. */
+	onChangeEnd?: (value: number) => void;
+	children?: ReactNode;
+};
+
+function RatingRoot({
+	value,
+	defaultValue = 0,
+	maxValue,
+	step,
+	color,
+	size,
+	isDisabled,
+	isInvalid,
+	isReadOnly,
+	allowClear = false,
+	haptic = "selection",
+	onChange,
+	onChangeEnd,
+	className,
+	children,
+	...props
+}: RatingProps): ReactElement {
+	const field = useFieldContext();
+	const axes = resolveRatingAxes({ field, own: { color, isDisabled, isInvalid, isReadOnly, size } });
+	const count = normalizeRatingCount(maxValue);
+	const settledStep = normalizeRatingStep(step);
+
+	const [current, setCurrent] = useControllableState<number>({ defaultValue, onChange, value });
+	const settled = clampRating(current, count);
+
+	const commitEnd = useCallback((next: number) => onChangeEnd?.(next), [onChangeEnd]);
+
+	const renderProps = useMemo<RatingRenderProps>(
+		() => ({
+			count,
+			isDisabled: axes.isDisabled,
+			isInvalid: axes.isInvalid,
+			isReadOnly: axes.isReadOnly,
+			step: settledStep,
+			value: settled,
+		}),
+		[axes.isDisabled, axes.isInvalid, axes.isReadOnly, count, settled, settledStep]
+	);
+
+	const context = useMemo<RatingContextValue>(
+		() => ({
+			...renderProps,
+			allowClear,
+			color: axes.color,
+			commitEnd,
+			haptic,
+			renderProps,
+			setValue: setCurrent,
+			size: axes.size,
+		}),
+		[allowClear, axes.color, axes.size, commitEnd, haptic, renderProps, setCurrent]
+	);
+
+	return (
+		<RatingProvider value={context}>
+			<View className={ratingVariants({ isDisabled: axes.isDisabled, size: axes.size }).root({ className })} {...props}>
+				{children}
+			</View>
+		</RatingProvider>
+	);
+}
+
+/**
+ * A row of stars that reads or sets a score.
+ *
+ * The anatomy is written out: a `Rating.Stars` row, with an optional
+ * `Rating.Output` beside or below it. The root is a plain column, so a readout
+ * on the same line is a `className="flex-row items-center"` away.
+ *
+ * **The whole row is the target.** Touching down takes the star under the
+ * finger, and dragging along the row follows it — one rule, not a tap mode and a
+ * drag mode. `step={0.5}` splits every star at its centre. `allowClear` lets a
+ * tap on the value already held withdraw the rating.
+ *
+ * **Any value is drawn; only a touch is snapped.** A read-only average of 3.7
+ * fills three stars and seven tenths of the fourth, while a finger on the same
+ * control can land only on the stops `step` allows. A non-finite value draws as
+ * zero rather than breaking the row.
+ *
+ * **State works either way from one hook**: pass `value` to control it, or
+ * `defaultValue` and let it hold its own. `onChange` fires as a drag crosses
+ * each star; `onChangeEnd` fires once when the gesture ends.
+ *
+ * `isInvalid` and `isDisabled` cascade in from an enclosing `Field`, and an
+ * explicit prop still wins. `isReadOnly` is the rating's own: it takes no touch
+ * and does not fade, because a score on a review card is content, not a control
+ * that happens to be off.
+ *
+ * To assistive technology the row is one `adjustable` control whose swipe up and
+ * down step the value — see `Rating.Stars`.
+ *
+ * @example
+ * <Rating defaultValue={3}>
+ *   <Rating.Stars accessibilityLabel="Your rating" />
+ * </Rating>
+ *
+ * @example
+ * <Rating allowClear onChange={setScore} step={0.5} value={score}>
+ *   <Rating.Stars accessibilityLabel="Rate this recipe" />
+ *   <Rating.Output />
+ * </Rating>
+ *
+ * @example
+ * <Rating className="flex-row items-center gap-2" isReadOnly size="sm" value={4.3}>
+ *   <Rating.Stars accessibilityLabel="Average rating" />
+ *   <Rating.Output>{({ value }) => `${value.toFixed(1)} · 128 reviews`}</Rating.Output>
+ * </Rating>
+ */
+export const Rating = Object.assign(RatingRoot, {
+	/** The row of stars — the drag surface, and the whole accessibility surface. */
+	Stars: RatingStars,
+	/** The value, formatted. Give it a function to label it yourself. */
+	Output: RatingOutput,
+	displayName: "DelacourUI.Rating",
+});