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

package/src/components/provider/provider.tsx

@@ -1,9 +1,9 @@
-import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";
 import type { ReactElement, ReactNode } from "react";
 import type { StyleProp, ViewStyle } from "react-native";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { KeyboardProvider } from "react-native-keyboard-controller";
 import { initialWindowMetrics, type Metrics, SafeAreaProvider } from "react-native-safe-area-context";
+import { CalmMotionProvider } from "../../hooks/use-calm-motion";
 import { KeyboardStateSync } from "../../hooks/use-keyboard-state-sync";
 
 export type DelacourProviderProps = {
@@ -21,6 +21,16 @@ export type DelacourProviderProps = {
 	 * `null` is a value here rather than an absence.
 	 */
 	initialMetrics?: Metrics | null;
+	/**
+	 * Hold every decorative loop still — a skeleton's shimmer or pulse — whatever
+	 * the OS reduce-motion setting says. Defaults to `false`.
+	 *
+	 * For an E2E build. A test runner that waits for the screen to stop moving
+	 * before each gesture (Argent, Detox, Maestro) pays its whole timeout on any
+	 * screen holding a loop that never ends. Motion that *is* the behaviour — a
+	 * `Spinner`, an indeterminate `Progress` — keeps moving either way.
+	 */
+	isMotionCalm?: boolean;
 	/**
 	 * Style for the outermost `GestureHandlerRootView`.
 	 *
@@ -52,15 +62,23 @@ export type DelacourProviderProps = {
  *    `will` events, so a keyboard that vanishes without one — an interactive
  *    dismiss interrupted by navigation, a stack pop, an app suspend — leaves
  *    every screen in the app believing it is still open.
- * 5. `BottomSheetModalProvider` — the host every `BottomSheet` portals into. It
- *    goes innermost because it draws ABOVE the app and reads every layer over
- *    it: the gesture root for the pan, the safe area for its insets, and the
- *    keyboard values a sheet's footer rides. It wraps `{children}` and nothing
- *    else moves, which is what a new layer here always looks like.
+ * 5. `CalmMotionProvider` — the app's `isMotionCalm`, for `useCalmMotion()`.
+ *    Pure context, no native view, so it wraps `{children}` alone — innermost,
+ *    where a new layer goes.
  *
- * `KeyboardStateSync` stays a SIBLING of it rather than a child. The repair is
- * global and has to run for the whole app's lifetime; inside a layer that can
- * remount it would be torn down with it.
+ * **`BottomSheetProvider` is not here, and the app mounts it.** The sheet's
+ * engine, `@delacour/react-native-bottom-sheet`, is an optional peer of this
+ * library: importing it from the recommended root would make every app resolve
+ * it, sheet or no sheet. So the provider is exported from
+ * `@delacour/react-native-ui/bottom-sheet` and goes innermost, inside this and
+ * around the navigator — it reads the gesture root for its pans, the safe area
+ * for its insets and the keyboard values a sheet's footer rides, and it draws
+ * above the app, so it wraps `{children}` and nothing else moves. That is what
+ * a new layer here always looks like, one package along.
+ *
+ * `KeyboardStateSync` is a sibling of `{children}` rather than a wrapper. The
+ * repair is global and has to run for the whole app's lifetime; inside a layer
+ * that can remount it would be torn down with it.
  *
  * There are no per-layer escape hatches and no layer-named props on purpose.
  * An app that needs a different stack composes the providers by hand; they are
@@ -69,13 +87,16 @@ export type DelacourProviderProps = {
  * @example
  * // expo-router root layout. The css import must stay the first statement.
  * import "../styles/global.css";
+ * import { BottomSheetProvider } from "@delacour/react-native-ui/bottom-sheet";
  * import { DelacourProvider } from "@delacour/react-native-ui/provider";
  * import { Stack } from "expo-router";
  *
  * export default function RootLayout() {
  *   return (
  *     <DelacourProvider>
- *       <Stack screenOptions={{ headerShown: false }} />
+ *       <BottomSheetProvider>
+ *         <Stack screenOptions={{ headerShown: false }} />
+ *       </BottomSheetProvider>
  *     </DelacourProvider>
  *   );
  * }
@@ -85,10 +106,16 @@ export type DelacourProviderProps = {
  * // app that launches into a rotated or split-screen window and cannot
  * // tolerate one stale frame.
  * <DelacourProvider initialMetrics={null}>{children}</DelacourProvider>
+ *
+ * @example
+ * // An E2E build: decorative loops hold still so the test runner never waits
+ * // out a shimmer. `IS_E2E` is the app's own build flag.
+ * <DelacourProvider isMotionCalm={IS_E2E}>{children}</DelacourProvider>
  */
 export function DelacourProvider({
 	children,
 	initialMetrics = initialWindowMetrics,
+	isMotionCalm = false,
 	style,
 }: DelacourProviderProps): ReactElement {
 	return (
@@ -96,7 +123,7 @@ export function DelacourProvider({
 			<SafeAreaProvider initialMetrics={initialMetrics}>
 				<KeyboardProvider>
 					<KeyboardStateSync />
-					<BottomSheetModalProvider>{children}</BottomSheetModalProvider>
+					<CalmMotionProvider isMotionCalm={isMotionCalm}>{children}</CalmMotionProvider>
 				</KeyboardProvider>
 			</SafeAreaProvider>
 		</GestureHandlerRootView>

package/src/components/radio/AGENTS.md

@@ -78,16 +78,14 @@ sit in `radio.variants.ts` beside the pure resolver that reads them. See
   A test asserts the `dot` slot claims neither `opacity-*` nor `scale-*` in any
   cell: a class fighting a `useAnimatedStyle` for the same property is a dot that
   never appears, with no error anywhere.
-- **The disabled fade lands on the ring and the label, never on the root.** The
-  `root` slot is worn by `Pressable`'s own `Animated.View`, whose
-  `useAnimatedStyle` writes `opacity` on every frame — at rest, 1. An
-  `opacity-50` class on that node is overwritten before it is ever drawn,
-  silently, so the row would stay at full contrast while behaving as disabled.
-  The ring and the label are ordinary descendants, so their opacity multiplies
-  with the root's instead of fighting it. The group must not fade either, or a
-  disabled group would compound `opacity-50` with each of its rows and land at a
-  quarter opacity. Tests pin both halves. This is the failure `Switch`, `Tabs`
-  and `Accordion` all cite back here.
+- **The disabled fade lands on the ring and the label, never on the root.** It
+  was placed there because [`Pressable`](../pressable/AGENTS.md)'s animated
+  style used to overwrite an `opacity-50` on the root; `Pressable` now
+  multiplies a className's opacity into its press, so the root *could* fade,
+  but the fade stays on the parts: an `opacity-50` on the root as well would
+  compound with them and land at a quarter. The group must not fade either, for
+  the same reason. Tests pin both halves. `Switch`, `Tabs` and `Accordion` all
+  cite back here.
 - **The ring is drawn from `View`s rather than a Central Icon.** Rule 5 governs
   icons and [Spinner](../spinner/AGENTS.md)'s arc is the precedent for
   primitives; here the set has no ring-with-a-centred-dot glyph at all. Two

package/src/components/radio/radio.variants.test.ts

@@ -192,10 +192,9 @@ describe("the root slot", () => {
 		expect([...gaps]).toEqual([...gaps].sort((a, b) => a - b));
 	});
 
-	// `root` is worn by Pressable's own Animated.View, whose useAnimatedStyle
-	// writes `opacity` every frame. A class here is overwritten before it is
-	// drawn — silently — so the fade has to live on the children instead.
-	test("never carries an opacity, which Pressable's animated style would overwrite", () => {
+	// The fade lives on the ring and the label; an `opacity-50` on the root as
+	// well would compound with them and land at a quarter.
+	test("never carries an opacity, which would compound with its children's", () => {
 		for (const cell of CELLS) {
 			expect(radioVariants(cell).root()).not.toMatch(/\bopacity-/);
 		}
@@ -397,8 +396,8 @@ describe("a trailing indicator", () => {
 });
 
 describe("a disabled radio", () => {
-	// The ring and the label are ordinary descendants of the pressable, so their
-	// opacity multiplies with the root's rather than being overwritten by it.
+	// The ring and the label carry the fade; the root stays clear so the two
+	// never compound.
 	test("fades its ring and its label", () => {
 		expect(radioVariants({ isDisabled: true }).indicator()).toContain("opacity-50");
 		expect(cls(radioVariants({ isDisabled: true }).label())).toContain("opacity-50");

package/src/components/radio/radio.variants.ts

@@ -119,13 +119,12 @@ export const radioVariants = tv({
 		// caller's `justify-between` because the root already knows where the
 		// indicator landed — see {@link resolveIndicatorPlacement}.
 		isIndicatorTrailing: { true: { root: "justify-between" }, false: {} },
-		// The fade lands on the children, never on the `root`, and that is not a
-		// style choice. `root` is worn by `Pressable`'s own `Animated.View`, whose
-		// `useAnimatedStyle` writes `opacity` on every frame — at rest, 1. An
-		// `opacity-50` class on that node is overwritten before it is ever drawn,
-		// silently, so the row stays at full contrast while behaving as disabled.
-		// The ring and the label are ordinary descendants, so their opacity
-		// multiplies with the root's instead of fighting it.
+		// The fade lands on the children, never on the `root`. `root` is worn by
+		// `Pressable`'s own `Animated.View`, which now multiplies a className's
+		// opacity into its press — but the ring and the label fading on their own
+		// keeps the row's hit area at full contrast and lets each part be tuned,
+		// so it stays here. Putting `opacity-50` on the root as well would
+		// compound with these and land at a quarter.
 		//
 		// The group must not fade either, or a disabled group would compound
 		// `opacity-50` with each of its rows and land at a quarter opacity.

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";