@delacour/react-native-ui 0.1.0-alpha.20260925063207 → 0.1.0-alpha.20260925063807

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925063207",
+	"version": "0.1.0-alpha.20260925063807",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -53,11 +53,13 @@
 		"./progress": "./src/components/progress/index.ts",
 		"./provider": "./src/components/provider/index.ts",
 		"./radio": "./src/components/radio/index.ts",
+		"./rating": "./src/components/rating/index.ts",
 		"./screen": "./src/components/screen/index.ts",
 		"./separator": "./src/components/separator/index.ts",
 		"./skeleton": "./src/components/skeleton/index.ts",
 		"./slider": "./src/components/slider/index.ts",
 		"./spinner": "./src/components/spinner/index.ts",
+		"./steps": "./src/components/steps/index.ts",
 		"./surface": "./src/components/surface/index.ts",
 		"./switch": "./src/components/switch/index.ts",
 		"./tabs": "./src/components/tabs/index.ts",
@@ -92,7 +94,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925063207",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925063807",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/rating/AGENTS.md

@@ -0,0 +1,143 @@
+# Rating
+
+A row of stars that reads or sets a score. Compound root plus `Rating.Stars` and
+`Rating.Output`. Read-only or interactive, in whole or fractional steps, set by a
+tap or a drag along the row.
+
+`import { Rating } from "@delacour/react-native-ui/rating";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/rating` |
+| `rating.tsx` | Root + the `Object.assign` compound surface |
+| `rating-stars.tsx` | `Rating.Stars` — owns the pan, the measurement, the haptic and the accessibility surface |
+| `rating-star.tsx` | One star: an empty glyph and a clipped filled one. Internal |
+| `rating-output.tsx` | `Rating.Output`, the `Text.Label` readout |
+| `rating.context.tsx` | `RatingContext`, `useRating()`, `useRatingContext()`, `useRatingPart()`, `RatingRenderProps` |
+| `rating.variants.ts` | Pure `tv()` slots, the value maths and the paint resolver, no RN imports |
+| `rating.variants.test.ts` | |
+
+There is no `rating.types.ts`: `RatingRenderProps` is the one shared type and it
+is part of the context's own shape, so it lives beside it.
+
+## Design
+
+- **Colours**: `default`, `primary`, `success`, `warning`, `destructive`, `info` —
+  Slider's set. The default is **`warning`**, not `default`: a star is read as
+  amber before it is read as a star, and a row of ink stars reads as a set of
+  icons rather than a score. **Sizes**: `sm`, `md`, `lg`, which are `icon-lg`,
+  `icon-xl` and `icon-2xl` on the icon scale — a star is a mark, the way a
+  checkbox's tick is.
+- **The anatomy is written out**, `Rating.Stars` and an optional
+  `Rating.Output`, rather than a `showValue` boolean. A readout beside the stars,
+  under them, or formatted as "4.3 · 128 reviews" is three layouts one boolean
+  could not express; the root is a column and a `flex-row` class puts it inline.
+- **`maxValue` is the star count and `step` the precision**, the names `Slider`
+  uses for the same two ideas. A fraction of a count rounds *down*; anything
+  that is not a count falls back to five. A step must divide one star — `0.5`
+  and `0.25` do, `0.3` does not — and falls back to whole stars otherwise,
+  because a rating is usually fed a number from a server rather than a literal.
+
+## Value
+
+- **Any value is drawn; only a touch is snapped.** `clampRating` holds the value
+  inside zero and the count and does not snap, so a read-only average of 3.7
+  fills seven tenths of the fourth star. `step` constrains what a finger can set.
+  A non-finite value draws as zero — a star whose width came out of `NaN` is a
+  row that lies about its score.
+- **A touch rounds up to the next stop.** Any touch inside a star's cell takes
+  that star, and with half stars its left half is the half. A touch exactly on a
+  cell's edge belongs to the star before it; the epsilon in `ratingFromOffset` is
+  what stops `Math.ceil` and binary floating point disagreeing there.
+- **A drag past the first star holds the lowest stop; it does not clear.** A drag
+  that overshoots the start is someone rating one star, not someone withdrawing
+  a rating. Clearing is its own gesture.
+- **`allowClear` is a tap on the value already held**, decided in `onFinalize` by
+  `shouldClearRating`. It reads the travel since touch-down, so a drag that
+  wanders off and comes back to the same star is a drag rather than a clear, and
+  `RATING_TAP_SLOP` is the line between them.
+- **The fills sum back to the value.** `starFillOf` gives every star before the
+  value a full fill, every star after it none and the one it lands in the
+  remainder, and a test sums them.
+
+## Drawing
+
+- **The star is an SVG path drawn here, not an icon.** Central Icons is an
+  outlined set: a filled star, and the clipped half of one, has no glyph there.
+  The path is ten vertices, stroked in its own fill colour with round joins, which
+  softens the points to sit beside the rounded icon set.
+- **A partial star is two layers and a clip, not a gradient.** The empty glyph
+  sits underneath and the filled one is inside a `View` whose width is the fill as
+  a percentage, with `overflow-hidden`. The filled glyph keeps the full glyph's
+  size — the window narrows, never the star. A hard-stop gradient would draw the
+  same thing, but its stops are paint props re-parsed on every change.
+- **The glyph's size is a class on a `View`, and the `Svg` fills it at `100%`.**
+  That keeps the icon scale the one source of the size without wrapping `Svg` in
+  `withUniwind`, which rule 7 forbids.
+- **The colour is a token read with `useThemeColor`, not a class.** A path's
+  `fill` is a paint prop no `className` reaches. `RATING_FILL_TOKEN` names the
+  token per colour and `resolveRatingPaint` settles it, so the whole paint matrix
+  is reachable from `bun test`, which also checks every token it names exists in
+  both variants of `theme.css`.
+- **An empty star is `muted-foreground` at 40% — the same chrome at every colour.**
+  No token sits where an empty star needs to: `border` and `input` vanish against
+  a light card, and `muted-foreground` at full strength reads as a disabled
+  filled star. The opacity is on the whole `Svg` view, not on the path's
+  `fillOpacity` and `strokeOpacity` — half the stroke overlaps the fill, and two
+  translucent paints draw a darker ring round every empty star.
+- **Invalid outranks the colour on the empty stars too.** A required rating left
+  at zero has no filled star to turn red, so the outlines carry the signal or
+  there is none.
+
+## Gesture
+
+- **Neither the row nor a star is a `Pressable`**, for the reasons
+  [Slider](../slider/AGENTS.md) gives for its track: a tap-to-set would fire
+  `onPress` every time, and a `Pressable` per star would nest five taps inside the
+  row's pan. One `Gesture.Pan()` on the row reads the star under the finger. What
+  is inherited is `playHaptic`, the one haptic switch.
+- **The value is written in `onBegin`**, because a pan activates on the first
+  movement and a stationary tap would never reach `onUpdate`. `minDistance(0)`
+  wins the touch from an enclosing scroll view and `shouldCancelWhenOutside(false)`
+  keeps a drag past the last star tracking — both exactly as `Slider.Track`.
+- **Each star's cell carries the gap as padding**, so every cell is the same width
+  and a star's half is the half of its cell. A `gap-*` on the row would leave dead
+  space between cells that belongs to no star.
+- **The row is padded on the cross axis only**, to 44pt at every size, and a test
+  asserts the sum. The main axis is not padded: the value is read straight off
+  the touch's offset along the row, and a gutter there would shift every value.
+- **The stars render from React state; the gesture reads a shared value.** Unlike
+  a slider, a rating crosses a handful of stops in a whole drag, so a commit per
+  crossing is a handful of commits and there is no UI-thread mirror to pay for.
+  The shared value exists so the worklet can tell a crossing from a repeat
+  without waiting on a render. It is re-synced from React on every gesture's end,
+  through a token that exists only to re-run the effect — without it a controlled
+  parent that rejects a value leaves the shared value holding it.
+- **The haptic ticks on grab, on every star crossed and on a clear.** There is no
+  distance rate limit as there is on `Slider`: the stops are a star apart, so a
+  flick across ten of them is ten ticks a hand can feel.
+
+## Accessibility
+
+- **The row is one `adjustable` control, not five buttons.** Its value is spoken
+  as "3.5 out of 5" and a swipe up or down calls `stepRating`, which lands a value
+  between stops on the *next* stop in the direction asked rather than a whole
+  step past it. Five buttons would make a screen-reader user visit every star to
+  learn one number.
+- **A read-only rating is an `image` with the same value** — something to read,
+  not something to set, and no actions.
+- **`Rating.Output` is hidden from assistive technology**, because the row already
+  speaks the value and a second, terser reading one swipe later is noise.
+- **Pass `accessibilityLabel` to `Rating.Stars`**, not the root. It defaults to
+  "Rating", which is correct and says nothing about *what* is being rated.
+
+## Axes
+
+- **The ladder is two rungs**, the rating's own props then an enclosing
+  [Field](../field/AGENTS.md), as on `Slider`. A `Field` reaches the two *state*
+  axes only, and a test pins that it cannot acquire a paint axis.
+- **`isReadOnly` is the rating's own and does not fade.** A score on a review card
+  is content, not a control that happens to be off, so it takes no touch and no
+  assistive actions but keeps full strength. `isDisabled` is the one that fades.

package/src/components/rating/index.ts

@@ -0,0 +1,43 @@
+export { Rating, type RatingProps } from "./rating";
+export {
+	type RatingContextValue,
+	RatingProvider,
+	type RatingRenderProps,
+	useRating,
+	useRatingContext,
+} from "./rating.context";
+export {
+	clampRating,
+	describeRating,
+	formatRatingValue,
+	normalizeRatingCount,
+	normalizeRatingStep,
+	RATING_COLORS,
+	RATING_COUNT,
+	RATING_DEFAULT_COLOR,
+	RATING_DEFAULT_SIZE,
+	RATING_EMPTY_OPACITY,
+	RATING_FILL_TOKEN,
+	RATING_OUTPUT_TEXT_SIZE,
+	RATING_SIZES,
+	RATING_STAR_PATH,
+	RATING_STAR_STROKE,
+	RATING_STEP,
+	RATING_TAP_SLOP,
+	type RatingAxes,
+	type RatingColor,
+	type RatingFieldAxes,
+	type RatingOwnAxes,
+	type RatingPaint,
+	type RatingSize,
+	type RatingVariantProps,
+	ratingFromOffset,
+	ratingVariants,
+	resolveRatingAxes,
+	resolveRatingPaint,
+	shouldClearRating,
+	starFillOf,
+	stepRating,
+} from "./rating.variants";
+export type { RatingOutputProps } from "./rating-output";
+export type { RatingStarsProps } from "./rating-stars";

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

@@ -0,0 +1,39 @@
+import type { ReactElement, ReactNode } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { type RatingRenderProps, useRatingPart } from "./rating.context";
+import { formatRatingValue, RATING_OUTPUT_TEXT_SIZE, ratingVariants } from "./rating.variants";
+
+export type RatingOutputProps = Omit<TextPresetProps, "children"> & {
+	/** Custom content, or a function called with the rating's settled state. */
+	children?: ReactNode | ((props: RatingRenderProps) => ReactNode);
+};
+
+/**
+ * The value, formatted — `4`, or `3.5`.
+ *
+ * Renders `Text.Label` and names a size step, never a scale of its own, the rule
+ * `Slider.Output` follows: the preset owns the weight and the colour, and the
+ * readout still tracks the rating's size.
+ *
+ * It is hidden from assistive technology. `Rating.Stars` already speaks the
+ * value as "3.5 out of 5", and a second, terser reading of the same number one
+ * swipe later is noise.
+ */
+export function RatingOutput({ children, className, size, ...props }: RatingOutputProps): ReactElement {
+	const context = useRatingPart("Rating.Output");
+	const content =
+		typeof children === "function" ? children(context.renderProps) : (children ?? formatRatingValue(context.value));
+
+	return (
+		<Text.Label
+			accessibilityElementsHidden
+			className={ratingVariants({ size: context.size }).output({ className })}
+			importantForAccessibility="no-hide-descendants"
+			size={size ?? RATING_OUTPUT_TEXT_SIZE[context.size]}
+			{...props}
+		>
+			{content}
+		</Text.Label>
+	);
+}
+RatingOutput.displayName = "DelacourUI.Rating.Output";

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

@@ -0,0 +1,70 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import Svg, { Path } from "react-native-svg";
+import { RATING_EMPTY_OPACITY, RATING_STAR_PATH, RATING_STAR_STROKE } from "./rating.variants";
+
+export type RatingStarProps = {
+	/** How much of the star is filled, 0–1. */
+	fill: number;
+	/** The resolved colour of the filled part. */
+	fillColor: string | undefined;
+	/** The resolved colour of the empty star, drawn at {@link RATING_EMPTY_OPACITY}. */
+	emptyColor: string | undefined;
+	/** The `size-icon-*` box the glyph fills. */
+	glyphClassName: string;
+	/** The clip window's class. Its width is set here, from `fill`. */
+	clipClassName: string;
+};
+
+/**
+ * One star: an empty glyph, and a filled one clipped to `fill` of its width.
+ *
+ * **Two layers rather than a gradient.** A hard-stop linear gradient on one path
+ * would draw the half star too, but its stops are paint props that React Native
+ * SVG re-parses on every change, and a clip is a `View` width the layout engine
+ * already animates cheaply. The filled glyph inside the clip keeps the full
+ * glyph's size — it is the *window* that narrows, never the star.
+ *
+ * Both glyphs are sized by a `size-icon-*` class on a `View` and fill it at
+ * `100%`, which keeps the icon scale the single source of the size without
+ * wrapping `Svg` in `withUniwind` (rule 7).
+ *
+ * Internal: `Rating.Stars` renders one per count, and nothing outside reaches it.
+ */
+export function RatingStar({
+	fill,
+	fillColor,
+	emptyColor,
+	glyphClassName,
+	clipClassName,
+}: RatingStarProps): ReactElement {
+	return (
+		<View className={glyphClassName}>
+			<StarGlyph color={emptyColor} opacity={RATING_EMPTY_OPACITY} />
+			{fill > 0 ? (
+				<View className={clipClassName} style={{ width: `${fill * 100}%` }}>
+					<View className={glyphClassName}>
+						<StarGlyph color={fillColor} opacity={1} />
+					</View>
+				</View>
+			) : null}
+		</View>
+	);
+}
+RatingStar.displayName = "DelacourUI.Rating.Stars.Star";
+
+/**
+ * The path itself, filled and stroked in one colour so the points come out rounded.
+ *
+ * The opacity is the whole view's, not the path's `fillOpacity` and
+ * `strokeOpacity`: half the stroke overlaps the fill, and two translucent paints
+ * over one another draw a darker ring round every empty star.
+ */
+function StarGlyph({ color, opacity }: { color: string | undefined; opacity: number }): ReactElement {
+	return (
+		<Svg height="100%" style={{ opacity }} viewBox="0 0 24 24" width="100%">
+			<Path d={RATING_STAR_PATH} fill={color} stroke={color} strokeLinejoin="round" strokeWidth={RATING_STAR_STROKE} />
+		</Svg>
+	);
+}
+StarGlyph.displayName = "DelacourUI.Rating.Stars.Star.Glyph";

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;
+}