@delacour/react-native-ui 0.2.0-alpha.20261016011950 → 0.3.0-alpha.20261017084646

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.2.0-alpha.20261016011950",
+	"version": "0.3.0-alpha.20261017084646",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -41,6 +41,7 @@
 		"./button": "./src/components/button/index.ts",
 		"./calendar": "./src/components/calendar/index.ts",
 		"./card": "./src/components/card/index.ts",
+		"./carousel": "./src/components/carousel/index.ts",
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
 		"./chip": "./src/components/chip/index.ts",
@@ -100,6 +101,7 @@
 		"./lib/keyboard-animation": "./src/lib/keyboard-animation.ts",
 		"./lib/merge-props": "./src/lib/merge-props.ts",
 		"./lib/navigation-theme": "./src/lib/navigation-theme.ts",
+		"./lib/paging": "./src/lib/paging.ts",
 		"./lib/slot": "./src/lib/slot.tsx",
 		"./lib/tv": "./src/lib/tv.ts",
 		"./icons/central": "./src/icons/central.ts"

package/src/components/carousel/AGENTS.md

@@ -0,0 +1,182 @@
+# Carousel
+
+A swipeable run of slides on one fractional position — peeking, looping,
+vertical, autoplaying. Compound root plus `Carousel.Content`, `Carousel.Item`,
+`Carousel.Caption`, `Carousel.Dots`, `Carousel.Previous`, `Carousel.Next` and
+`Carousel.Controls`, and a `useCarousel()` hook for custom controls.
+
+`import { Carousel } from "@delacour/react-native-ui/carousel";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/carousel` |
+| `carousel.tsx` | Root + the `Object.assign` surface — owns the index, the reconcile and autoplay |
+| `carousel-content.tsx` | `Carousel.Content` — the viewport, the Item walk, the window, the pan, the adjustable element |
+| `carousel-item.tsx` | `Carousel.Item` — one absolutely placed slide and its animated style |
+| `carousel-caption.tsx` | `Carousel.Caption` — a `Text` on a scrim, faded by its slide's offset |
+| `carousel-dots.tsx` | `Carousel.Dots` and the internal dot — decoration driven by `position` |
+| `carousel-previous.tsx` | `Carousel.Previous` — an icon `Button` |
+| `carousel-next.tsx` | `Carousel.Next` — an icon `Button` |
+| `carousel-controls.tsx` | `Carousel.Controls` — a row (a column when vertical), layout only |
+| `carousel.context.tsx` | Four contexts split by rate of change, with their hooks |
+| `carousel.types.ts` | Prop types shared by two or more parts |
+| `carousel.variants.ts` | Pure `tv()` slots, constants and the geometry, coverflow, dot and a11y resolvers |
+| `carousel.variants.test.ts` | |
+| `use-carousel-autoplay.ts` | The JS interval and every reason it does not run |
+
+The paging maths — wrapped offsets, rubber band, pan origin and position, settle
+target, visible window — is **not here**. It lives in
+[`src/lib/paging.ts`](../../lib/paging.ts), because `ImageViewer` pages through
+the same kind of run and neither component should import the other. Keep that
+file stable: its functions are the contract both consume.
+
+## Design
+
+- **Variants**: `track` (flat slides side by side) and `coverflow` (slides turn,
+  shrink and fade with their distance from the centre — `resolveCoverflow`).
+  **Orientations**: `horizontal`, `vertical`, which also turn the controls row
+  and the dots into columns. **Tone** (dots only): `default`, and `overlay` for
+  dots sitting on a photo — `primary-foreground`, never a raw white. **No size
+  axis**: a slide's size is `itemSize`, in points, because it is a layout
+  measurement and not a step on the type scale.
+- **`itemSize` is the peek.** Omitted, a slide is the viewport's length and its
+  neighbours sit a gap off-screen. Smaller, the active slide is centred
+  (`resolveItemInset`) and the neighbours show either side. Larger than the
+  viewport, it is clamped to it — a slide that overflows its own viewport cannot
+  be centred.
+- **Slides are found by walking `Content`'s direct children**, as `ListGroup`
+  finds its rows and `Tabs` its panels. The walk is the count, the order and the
+  window, so it is one place. An Item behind a wrapper is not found, and a
+  development warning says so: a slide that silently vanishes is worse than a
+  warning.
+- **No `variant="stack"` or fan layout in v1.** Both are a different
+  `resolve*` transform on the same position; they wait until `coverflow` has
+  proven that seam.
+- **No virtualised `data` / `renderItem`.** This holds a handful of hand-written
+  slides. A feed is a list (`@legendapp/list`).
+
+## Value flow
+
+- **The whole component is one shared value**, `position`, a float slide index.
+  A drag writes it, a spring settles it, and every slide's transform, every dot's
+  width and every caption's opacity is a reading of it. Two clocks is how a dot
+  ends up a frame behind the slide it marks.
+- **`onIndexChange` fires once per gesture, from the pan's `onFinalize`**, before
+  the spring lands — never per frame and never on crossing a midpoint. A per-frame
+  report re-renders every slide mid-drag; `Tabs` paid for that lesson.
+- **The reconcile effect registers no cleanup.** The commit that re-runs it is
+  usually the one the gesture just caused, and the gesture has already started the
+  settle spring. A cleanup that cancelled it would leave the effect's `none`
+  branch nothing to restart, and the run would freeze between two slides. `Tabs`
+  shipped that bug once; this copies its fix, not `Checkbox`'s `cancelAnimation`.
+- **A rejected controlled change springs back.** Every commit also bumps a
+  reducer token, so a controlled parent that refuses the change — and therefore
+  re-renders nothing — still re-runs the reconcile, which springs to the index the
+  parent kept. `Tabs` and `Switch` carry the same token.
+- **The pan's settle records its target before it commits** (`commitFromPan`), so
+  an accepted change makes the reconcile a no-op and the fling keeps its momentum.
+- **A shrinking run never leaves a dead index.** The drawn index is clamped into
+  `[0, count - 1]` and the clamp is reported through `onIndexChange` once. A count
+  change jumps rather than springs: the slides under the old position are gone.
+- **Loop has no clones.** Each slide's offset is `resolveWrappedOffset` — the
+  short way round on a ring — so the first slide sits beside the last and nothing
+  ever jumps back. `position` is unbounded while looping; the reconcile aims at
+  `resolveNearestPosition`, so `scrollTo` and the arrows take the short way.
+
+## Gesture
+
+- **The pan claims its axis and yields the other**: `activeOffset` ±10 on the
+  travel axis under `failOffset` ±10 across it. That is what lets a horizontal
+  carousel sit in `Screen.ScrollArea` and a `Pressable` in a slide still tap. Not
+  `blocksExternalGesture` — React Native's `ScrollView` has no handler tag.
+- **The origin is back-computed at activation** (`resolvePanOrigin`), or the slide
+  jumps by the 10 points it took to activate. A grab mid-spring resumes from where
+  the slide is.
+- **The spring is cancelled in `onStart`, never `onBegin`.** Most touches fail on
+  the cross axis; cancelling on touch-down would freeze the run for every vertical
+  scroll that began on it.
+- **The settle is in `onFinalize`**, the one callback on END, FAILED and
+  CANCELLED, guarded by an `isDragging` flag so a tap that never activated does not
+  retarget anything.
+- **A flick moves at most one slide.** `resolveSettleTarget` commits on 300 pt/s
+  or a quarter of a pitch, and never further than the next slide, however hard the
+  throw. Past a non-looping end the drag is a rubber band capped at half a slide.
+- **Worklets call only self-contained worklets.** Every `lib/paging` and
+  `carousel.variants` function used on the UI thread is marked `"worklet"` and
+  calls nothing else — a module-scope worklet calling another crashes the UI
+  thread (`pressable/AGENTS.md`). Axis-dependent choices (`translationX` or `Y`,
+  `width` or `height`) are made once on the JS thread and captured as keys.
+
+## Rendering
+
+- **Slides are absolutely placed and moved by transform, never by layout.** One
+  `onLayout` on the viewport measures it; the geometry (`viewport`, `size`,
+  `pitch`, `inset`) is computed on the JS thread and published as **one** shared
+  value, so the UI thread never reads a pitch from one layout and a size from
+  another. Until it lands, slides draw at `opacity: 0` — the first paint never
+  shows them stacked at the origin.
+- **Only the window is mounted**: `windowSize` (default 2) slides either side of
+  the committed index, wrapped when looping. Slides outside it are unmounted from
+  the committed index on the JS thread, and any mounted slide further out than
+  the window is `display: none` on the UI thread before React catches up.
+- **Dots stretch by width, not `scaleX`** — a scaled `rounded-full` is an ellipse
+  (`Tabs.Indicator`'s reason). Past `maxDots` (default 7) the row is a window
+  centred on the active dot.
+- **The caption fades with its slide's offset**, full on the active slide and
+  gone one slide out, so a peeking neighbour shows its picture and not its words.
+  Colour sits on the `Text` (rule 1); the frame carries layout and the scrim.
+
+## Autoplay
+
+- **Stops for good on the first touch** — the pan's `onBegin`, an arrow or a
+  caller's `scrollTo` — and at the end of a run that does not loop. Content that
+  keeps moving after the user took hold of it is fighting them.
+- **Never runs under reduce motion, the app's `isMotionCalm`, or a screen
+  reader** (WCAG 2.2.2). The screen reader is subscribed, not sampled.
+- **Pauses while the app is backgrounded.** A carousel scrolled off-screen keeps
+  ticking: detecting that cheaply is not possible, so it is documented rather than
+  solved.
+- **A tick is one more caller of the reconcile**, not a second clock.
+
+## Accessibility
+
+- **`Carousel.Content` is the adjustable element**, not the root, so the arrows
+  stay reachable in their own right. Its value is "2 of 5"
+  (`resolveCarouselA11yValue`); `increment`/`decrement` map to `next`/`previous`,
+  and the OS reads the new value.
+- **Off-screen slides are hidden from assistive tech** unless the carousel peeks,
+  when every mounted slide is visible and stays reachable
+  (`resolveSlideAccessibility`).
+- **Dots are decoration**: hidden from assistive tech and not tappable — at six
+  points they are far below a 44-point target. The arrows are the control, labelled
+  "Previous slide" / "Next slide", disabled at the ends unless looping.
+- **Reduce motion** settles by a 150 ms timing instead of a spring, collapses
+  coverflow to the track transform, and disables autoplay.
+
+## Cross-category
+
+- **No Pagination import.** `Carousel.Dots` is a minimal internal indicator; a
+  later Pagination component may wrap or replace it.
+- **No Image component required.** Slides are caller-supplied children.
+
+## Notes
+
+- **A demo has to stretch.** The root is `w-full`; inside a shrink-wrapped parent
+  that resolves to zero, the viewport measures 0 and no slide shows. Every demo
+  sets `align: "stretch"`, as every container demo does.
+- **Simulator check, 2026-10-05** (iPhone 17 sim, dev client): track, peek
+  centring, coverflow and vertical draw correctly; a ~290 pt fling moves exactly
+  one slide; the arrows step and `Next` disables at the non-looping end, where
+  further swipes rubber-band back; loop wraps both ways with no jump; autoplay
+  advances and stops for good after a swipe; a controlled `index` jumps from an
+  outside button and a swipe reports back through `onIndexChange`.
+- **Not yet verified on a device**: release mid-drag then scroll the page; inside
+  `Screen.ScrollArea`; a `Pressable` in a slide; VoiceOver's adjust gesture and
+  the "n of m" announcement; autoplay off under Reduce Motion / VoiceOver; a
+  Release build.
+- **Previews** (2026-10-06, dev client, iPhone 17 Pro): `hero-track`, `coverflow` and
+  `controls` are clips whose flows return to the first slide; `peek` and
+  `vertical` are stills. The photos load from the network, so check every poster
+  after a capture — the first `peek` poster caught its active slide still empty.

package/src/components/carousel/carousel-caption.tsx

@@ -0,0 +1,43 @@
+import type { ReactElement } from "react";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { resolveWrappedOffset } from "../../lib/paging";
+import { Text, type TextProps } from "../text";
+import {
+	useCarouselMotionPart,
+	useCarouselOptionsPart,
+	useCarouselPart,
+	useCarouselSlidePart,
+} from "./carousel.context";
+import { carouselVariants, resolveCaptionOpacity } from "./carousel.variants";
+
+export type CarouselCaptionProps = TextProps & {
+	className?: string;
+};
+
+/**
+ * A slide's caption, pinned to its foot on a scrim so it reads over a photo.
+ *
+ * Fades with its slide's offset from `position` — full on the active slide, gone
+ * one slide out — so a peeking neighbour shows its picture and not its words. The
+ * colour sits on the `Text` (rule 1); the frame carries layout and the scrim only.
+ */
+export function CarouselCaption({ className, ...props }: CarouselCaptionProps): ReactElement {
+	const { count } = useCarouselPart("Carousel.Caption");
+	const { loop, orientation, variant } = useCarouselOptionsPart("Carousel.Caption");
+	const { position } = useCarouselMotionPart("Carousel.Caption");
+	const { index } = useCarouselSlidePart("Carousel.Caption");
+
+	const animatedStyle = useAnimatedStyle(() => {
+		const offset = loop ? resolveWrappedOffset(index, position.value, count) : index - position.value;
+		return { opacity: resolveCaptionOpacity(offset) };
+	}, [count, index, loop]);
+
+	const slots = carouselVariants({ orientation, variant });
+
+	return (
+		<Animated.View className={slots.captionFrame()} pointerEvents="none" style={animatedStyle}>
+			<Text className={slots.caption({ className })} numberOfLines={2} {...props} />
+		</Animated.View>
+	);
+}
+CarouselCaption.displayName = "DelacourUI.Carousel.Caption";

package/src/components/carousel/carousel-content.tsx

@@ -0,0 +1,276 @@
+import {
+	Children,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	useCallback,
+	useLayoutEffect,
+	useMemo,
+	useState,
+} from "react";
+import type { AccessibilityActionEvent, LayoutChangeEvent, ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { cancelAnimation, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { cn } from "../../lib/cn";
+import { resolvePanOrigin, resolvePanPosition, resolveSettleTarget, resolveVisibleRange } from "../../lib/paging";
+import {
+	CarouselSlideProvider,
+	useCarouselMotionPart,
+	useCarouselOptionsPart,
+	useCarouselPart,
+} from "./carousel.context";
+import {
+	CAROUSEL_CALM_DURATION_MS,
+	CAROUSEL_PAN,
+	CAROUSEL_SPRING,
+	carouselVariants,
+	resolveCarouselA11yValue,
+	resolveItemInset,
+	resolveItemPitch,
+	resolveItemSize,
+} from "./carousel.variants";
+import { CarouselItem } from "./carousel-item";
+
+export type CarouselContentProps = ViewProps & {
+	/** `Carousel.Item` elements, as direct children. Their source order is the order of record. */
+	children: ReactNode;
+	/** Horizontal only. Sets the viewport's height from its width; a vertical carousel needs a height class. */
+	aspectRatio?: number;
+	className?: string;
+};
+
+/**
+ * The clipped viewport the slides are placed in, the surface the pan is claimed
+ * on, and the element assistive tech adjusts.
+ *
+ * **It walks its direct children for `Carousel.Item`s**, as `ListGroup` finds its
+ * rows and `Tabs` its panels: the walk is the count, the order and the window. An
+ * Item behind a wrapper is not found, so a wrapper is warned about in development
+ * rather than silently dropping slides.
+ *
+ * **Only the window is mounted** — `windowSize` slides either side of the
+ * committed index, wrapped when looping — so a run of thirty photos decodes five.
+ *
+ * **The pan claims its axis and yields the other**: `activeOffset` on the travel
+ * axis under `failOffset` across it, so a horizontal carousel scrolls inside
+ * `Screen.ScrollArea` and a `Pressable` in a slide still taps. Not
+ * `blocksExternalGesture` — React Native's `ScrollView` has no handler tag.
+ *
+ * **It is the adjustable element**, not the root, so `Carousel.Previous` and
+ * `Carousel.Next` stay reachable in their own right. A VoiceOver or TalkBack
+ * swipe up or down moves a slide and the OS reads the new "2 of 5".
+ */
+export function CarouselContent({
+	children,
+	aspectRatio,
+	className,
+	style,
+	onLayout,
+	...props
+}: CarouselContentProps): ReactElement {
+	const { index, count, next, previous } = useCarouselPart("Carousel.Content");
+	const {
+		accessibilityLabel,
+		gap,
+		isDisabled,
+		isScrollEnabled,
+		itemSize,
+		isCalm,
+		loop,
+		orientation,
+		setCount,
+		variant,
+		windowSize,
+	} = useCarouselOptionsPart("Carousel.Content");
+	const { commitFromPan, geometry, position, stopAutoplay } = useCarouselMotionPart("Carousel.Content");
+
+	const items = useMemo(() => collectItems(children), [children]);
+
+	useLayoutEffect(() => {
+		setCount(items.length);
+	}, [items.length, setCount]);
+
+	const isHorizontal = orientation === "horizontal";
+	const [viewport, setViewport] = useState(0);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			onLayout?.(event);
+			const { height, width } = event.nativeEvent.layout;
+			const length = isHorizontal ? width : height;
+			setViewport(length);
+		},
+		[isHorizontal, onLayout]
+	);
+
+	// The geometry is computed here, on the JS thread, and published as one shared
+	// value — one write, so the UI thread never reads a pitch from one layout and a
+	// size from another.
+	useLayoutEffect(() => {
+		geometry.value = {
+			inset: resolveItemInset(viewport, itemSize),
+			pitch: resolveItemPitch(viewport, itemSize, gap),
+			size: resolveItemSize(viewport, itemSize),
+			viewport,
+		};
+	}, [gap, geometry, itemSize, viewport]);
+
+	const isPeek = itemSize !== undefined && viewport > 0 && itemSize < viewport;
+
+	const panStart = useSharedValue(0);
+	// Whether the pan actually activated. `onFinalize` fires for every touch,
+	// including the taps and cross-axis scrolls that never did, and must not
+	// retarget a spring it never disturbed.
+	const isDragging = useSharedValue(false);
+
+	const panGesture = useMemo(() => {
+		const activate = [-CAROUSEL_PAN.activate, CAROUSEL_PAN.activate] as [number, number];
+		const fail = [-CAROUSEL_PAN.fail, CAROUSEL_PAN.fail] as [number, number];
+		const translationKey = isHorizontal ? "translationX" : "translationY";
+		const velocityKey = isHorizontal ? "velocityX" : "velocityY";
+		const pan = Gesture.Pan().enabled(!isDisabled && isScrollEnabled && count > 1);
+		const axis = isHorizontal
+			? pan.activeOffsetX(activate).failOffsetY(fail)
+			: pan.activeOffsetY(activate).failOffsetX(fail);
+
+		return (
+			axis
+				// Autoplay stops for good on the first touch, activated or not.
+				.onBegin(() => {
+					"worklet";
+					scheduleOnRN(stopAutoplay);
+				})
+				// The spring is cancelled on ACTIVATION, never on touch-down: most
+				// touches go on to fail against the cross axis, and cancelling for one
+				// of those would freeze the run between two slides with nothing to
+				// restart it. `Tabs` found that by dragging, then scrolling the page.
+				.onStart((event) => {
+					"worklet";
+					cancelAnimation(position);
+					isDragging.value = true;
+					panStart.value = resolvePanOrigin(position.value, event[translationKey], geometry.value.pitch);
+				})
+				.onUpdate((event) => {
+					"worklet";
+					position.value = resolvePanPosition({
+						count,
+						loop,
+						pitch: geometry.value.pitch,
+						start: panStart.value,
+						translation: event[translationKey],
+					});
+				})
+				// `onFinalize`, the one callback on every path out — END, FAILED and
+				// CANCELLED — so a drag the OS cancels still settles.
+				.onFinalize((event, success) => {
+					"worklet";
+					if (!isDragging.value) return;
+					isDragging.value = false;
+
+					const pitch = geometry.value.pitch;
+					const velocity = success ? event[velocityKey] : 0;
+					const destination = resolveSettleTarget({
+						count,
+						loop,
+						pitch,
+						position: position.value,
+						startIndex: Math.round(panStart.value),
+						velocity,
+					});
+
+					if (isCalm) {
+						position.value = withTiming(destination, { duration: CAROUSEL_CALM_DURATION_MS });
+					} else {
+						const slidesPerSecond = pitch > 0 ? -velocity / pitch : 0;
+						position.value = withSpring(destination, { ...CAROUSEL_SPRING, velocity: slidesPerSecond });
+					}
+
+					scheduleOnRN(commitFromPan, destination);
+				})
+		);
+	}, [
+		commitFromPan,
+		count,
+		geometry,
+		isCalm,
+		isDisabled,
+		isDragging,
+		isHorizontal,
+		isScrollEnabled,
+		loop,
+		panStart,
+		position,
+		stopAutoplay,
+	]);
+
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			if (isDisabled) return;
+			if (event.nativeEvent.actionName === "increment") next();
+			else if (event.nativeEvent.actionName === "decrement") previous();
+		},
+		[isDisabled, next, previous]
+	);
+
+	const visible = resolveVisibleRange(index, items.length, loop, windowSize);
+	const slots = carouselVariants({ orientation, variant });
+
+	return (
+		<GestureDetector gesture={panGesture}>
+			<Animated.View
+				accessibilityActions={count > 1 ? ACCESSIBILITY_ACTIONS : undefined}
+				accessibilityLabel={accessibilityLabel}
+				accessibilityRole="adjustable"
+				accessibilityState={{ disabled: isDisabled }}
+				accessibilityValue={{ text: resolveCarouselA11yValue(index, count) }}
+				accessible
+				className={cn(slots.viewport(), className)}
+				onAccessibilityAction={handleAccessibilityAction}
+				onLayout={handleLayout}
+				style={[isHorizontal && aspectRatio !== undefined ? { aspectRatio } : null, style]}
+				{...props}
+			>
+				{visible.map((slide) => (
+					<CarouselSlideProvider
+						key={slideKey(items[slide], slide)}
+						value={{ index: slide, isActive: slide === index, isPeek }}
+					>
+						{items[slide]}
+					</CarouselSlideProvider>
+				))}
+			</Animated.View>
+		</GestureDetector>
+	);
+}
+CarouselContent.displayName = "DelacourUI.Carousel.Content";
+
+/** The two actions an assistive swipe on an `adjustable` maps to. */
+const ACCESSIBILITY_ACTIONS = [{ name: "increment" }, { name: "decrement" }];
+
+/**
+ * The `Carousel.Item`s among `children`, in source order.
+ *
+ * `Children.toArray` drops the nulls a conditional slide leaves and keys what it
+ * keeps. Anything else is warned about in development: a wrapper around an Item
+ * hides it from the walk, and a slide that silently vanishes is worse than a
+ * warning.
+ */
+function collectItems(children: ReactNode): ReactElement[] {
+	const items: ReactElement[] = [];
+	for (const child of Children.toArray(children)) {
+		if (isValidElement(child) && child.type === CarouselItem) {
+			items.push(child);
+		} else if (process.env.NODE_ENV !== "production") {
+			console.warn(
+				"Carousel.Content: only Carousel.Item elements are slides, and they must be direct children. A wrapper hides the slide inside it."
+			);
+		}
+	}
+	return items;
+}
+
+/** A slide's key: the caller's, which `Children.toArray` has already made unique, or its index. */
+function slideKey(item: ReactElement | undefined, slide: number): string {
+	return item?.key ?? `slide-${slide}`;
+}

package/src/components/carousel/carousel-controls.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useCarouselOptionsPart } from "./carousel.context";
+import type { CarouselSlotProps } from "./carousel.types";
+import { carouselVariants } from "./carousel.variants";
+
+export type CarouselControlsProps = CarouselSlotProps;
+
+/**
+ * A row for `Carousel.Previous` · `Carousel.Dots` · `Carousel.Next`, spread to the
+ * ends — a column when the carousel is vertical. Layout only; it reads no state.
+ */
+export function CarouselControls({ className, ...props }: CarouselControlsProps): ReactElement {
+	const { orientation, variant } = useCarouselOptionsPart("Carousel.Controls");
+	return <View className={carouselVariants({ orientation, variant }).controls({ className })} {...props} />;
+}
+CarouselControls.displayName = "DelacourUI.Carousel.Controls";

package/src/components/carousel/carousel-dots.tsx

@@ -0,0 +1,120 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import Animated, { type SharedValue, useAnimatedStyle } from "react-native-reanimated";
+import { resolveWrappedOffset } from "../../lib/paging";
+import { useCarouselMotionPart, useCarouselOptionsPart, useCarouselPart } from "./carousel.context";
+import {
+	CAROUSEL_DEFAULT_MAX_DOTS,
+	type CarouselDotTone,
+	type CarouselOrientation,
+	carouselVariants,
+	resolveCaptionOpacity,
+	resolveDotLength,
+	resolveDotsWindow,
+} from "./carousel.variants";
+
+export type CarouselDotsProps = ViewProps & {
+	/** Cap on dots drawn; beyond it a sliding window of this many. Default 7. */
+	maxDots?: number;
+	/** `overlay` draws light dots for sitting on photos. Default `default`. */
+	tone?: CarouselDotTone;
+	className?: string;
+};
+
+/**
+ * One dot per slide, the active one stretched to a pill — a reading of `position`,
+ * so the pill travels with a finger rather than jumping on release.
+ *
+ * **Decoration, not a control.** The group is hidden from assistive tech, because
+ * the adjustable viewport already says "2 of 5", and the dots are not tappable:
+ * at six points they are far below a 44-point target. The arrows are the control.
+ *
+ * Past `maxDots` the row is a window centred on the active dot, chosen from the
+ * committed index. Renders nothing with one slide or none.
+ */
+export function CarouselDots({
+	maxDots = CAROUSEL_DEFAULT_MAX_DOTS,
+	tone = "default",
+	className,
+	...props
+}: CarouselDotsProps): ReactElement | null {
+	const { count, index } = useCarouselPart("Carousel.Dots");
+	const { loop, orientation, variant } = useCarouselOptionsPart("Carousel.Dots");
+	const { position } = useCarouselMotionPart("Carousel.Dots");
+
+	if (count <= 1) return null;
+
+	const { start, end } = resolveDotsWindow(count, index, maxDots);
+	const slots = carouselVariants({ orientation, tone, variant });
+	const dots: number[] = [];
+	for (let dot = start; dot < end; dot++) dots.push(dot);
+
+	return (
+		<View
+			accessibilityElementsHidden
+			className={slots.dots({ className })}
+			importantForAccessibility="no-hide-descendants"
+			pointerEvents="none"
+			{...props}
+		>
+			{dots.map((dot) => (
+				<CarouselDot
+					activeClassName={slots.dotActive()}
+					className={slots.dot()}
+					count={count}
+					index={dot}
+					key={dot}
+					loop={loop}
+					orientation={orientation}
+					position={position}
+				/>
+			))}
+		</View>
+	);
+}
+CarouselDots.displayName = "DelacourUI.Carousel.Dots";
+
+type CarouselDotProps = {
+	index: number;
+	count: number;
+	loop: boolean;
+	orientation: CarouselOrientation;
+	position: SharedValue<number>;
+	className: string;
+	activeClassName: string;
+};
+
+/**
+ * One dot. Its length along the row and its active fill's opacity both follow its
+ * offset from `position`; width rather than `scaleX`, because a scaled
+ * `rounded-full` is an ellipse.
+ */
+function CarouselDot({
+	index,
+	count,
+	loop,
+	orientation,
+	position,
+	className,
+	activeClassName,
+}: CarouselDotProps): ReactElement {
+	const isHorizontal = orientation === "horizontal";
+
+	const dotStyle = useAnimatedStyle(() => {
+		const offset = loop ? resolveWrappedOffset(index, position.value, count) : index - position.value;
+		const length = resolveDotLength(offset);
+		return isHorizontal ? { width: length } : { height: length };
+	}, [count, index, isHorizontal, loop]);
+
+	const fillStyle = useAnimatedStyle(() => {
+		const offset = loop ? resolveWrappedOffset(index, position.value, count) : index - position.value;
+		return { opacity: resolveCaptionOpacity(offset) };
+	}, [count, index, loop]);
+
+	return (
+		<Animated.View className={className} style={dotStyle}>
+			<Animated.View className={activeClassName} style={fillStyle} />
+		</Animated.View>
+	);
+}
+CarouselDot.displayName = "DelacourUI.Carousel.Dots.Dot";