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

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

@@ -0,0 +1,116 @@
+import { type ReactElement, useCallback } from "react";
+import { type AccessibilityActionEvent, View, type ViewProps } from "react-native";
+import { IconChevronDownSmall } from "../../icons/central";
+import { Icon } from "../icon";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { useCalendarPart } from "./calendar.context";
+import { formatMonthYear, formatYear } from "./calendar.date";
+import { calendarVariants, resolvePartTestID } from "./calendar.variants";
+
+export type CalendarCaptionProps = Omit<ViewProps, "children"> & {
+	className?: string;
+};
+
+const PAGE_ACTIONS = [
+	{ name: "decrement", label: "Previous" },
+	{ name: "increment", label: "Next" },
+];
+
+/**
+ * The month and year above the grid.
+ *
+ * With `captionLayout="picker"` it is a button: in the grid it opens the months view, in the
+ * months view the years view, and in the years view it returns to the grid. With `"label"` it is
+ * text.
+ *
+ * **It is where a screen-reader user pages.** A grid of buttons cannot itself be an adjustable
+ * element — iOS and Android both fold an accessible container's children into it, and the days
+ * would become unreachable — so the caption carries the increment and decrement actions instead:
+ * swipe up or down on "October 2026" to move a month. As a plain label it takes the `adjustable`
+ * role outright; as a button the two actions sit beside its activation.
+ */
+export function CalendarCaption({ className, ...props }: CalendarCaptionProps): ReactElement {
+	const {
+		canGoNext,
+		canGoPrev,
+		captionLayout,
+		goNext,
+		goPrev,
+		isDisabled,
+		locale,
+		setView,
+		size,
+		testID,
+		variant,
+		view,
+		visibleMonth,
+		yearSpan,
+	} = useCalendarPart("Calendar.Caption");
+	const slots = calendarVariants({ size, variant });
+
+	const text =
+		view === "days"
+			? formatMonthYear(visibleMonth, locale)
+			: view === "months"
+				? formatYear(visibleMonth.year, locale)
+				: `${formatYear(yearSpan.from, locale)} – ${formatYear(yearSpan.to, locale)}`;
+
+	const handleAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			if (event.nativeEvent.actionName === "increment" && canGoNext) goNext();
+			if (event.nativeEvent.actionName === "decrement" && canGoPrev) goPrev();
+		},
+		[canGoNext, canGoPrev, goNext, goPrev]
+	);
+
+	const handlePress = useCallback(() => {
+		setView(view === "days" ? "months" : view === "months" ? "years" : "days");
+	}, [setView, view]);
+
+	const label = <Text className={slots.captionText()}>{text}</Text>;
+
+	if (captionLayout === "label") {
+		return (
+			<View
+				accessibilityActions={PAGE_ACTIONS}
+				accessibilityLabel={text}
+				accessibilityRole="adjustable"
+				accessible
+				className={slots.caption({ className })}
+				onAccessibilityAction={handleAction}
+				testID={resolvePartTestID(testID, "caption")}
+				{...props}
+			>
+				{label}
+			</View>
+		);
+	}
+
+	const hint =
+		view === "days"
+			? "Opens the month and year picker"
+			: view === "months"
+				? "Opens the year list"
+				: "Returns to the month";
+
+	return (
+		<Pressable
+			accessibilityActions={PAGE_ACTIONS}
+			accessibilityHint={hint}
+			accessibilityLabel={text}
+			className={slots.caption({ className })}
+			disabled={isDisabled}
+			feedback="fade"
+			haptic="selection"
+			onAccessibilityAction={handleAction}
+			onPress={handlePress}
+			testID={resolvePartTestID(testID, "caption")}
+			{...props}
+		>
+			{label}
+			<Icon color="muted-foreground" icon={IconChevronDownSmall} size="sm" />
+		</Pressable>
+	);
+}
+CalendarCaption.displayName = "DelacourUI.Calendar.Caption";

package/src/components/calendar/calendar-day.tsx

@@ -0,0 +1,103 @@
+import { type ReactElement, type ReactNode, useCallback } from "react";
+import { View } from "react-native";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { useCalendarPart } from "./calendar.context";
+import { type CalendarDate, formatDate, isSameMonth, serialiseDate } from "./calendar.date";
+import { type CalendarDayState, calendarVariants, resolveDayState, resolvePartTestID } from "./calendar.variants";
+
+/** What a function child of `Calendar.Day` is handed. */
+export type CalendarDayRenderProps = CalendarDayState & {
+	date: CalendarDate;
+	/** The class the default number is drawn with — size, weight and colour for this state. */
+	labelClassName: string;
+};
+
+export type CalendarDayProps = {
+	/** The day this cell draws. */
+	date: CalendarDate;
+	/**
+	 * Custom content inside the circle, in place of the number. A function is handed the day's
+	 * state, so a price under the number can take the selected colour with it.
+	 */
+	children?: ReactNode | ((props: CalendarDayRenderProps) => ReactNode);
+	className?: string;
+};
+
+/** The state words a screen reader adds after the date. */
+function describeState(state: CalendarDayState): string | undefined {
+	const parts: string[] = [];
+	if (state.isToday) parts.push("Today");
+	if (state.rangeRole === "start") parts.push("Range start");
+	if (state.rangeRole === "end") parts.push("Range end");
+	return parts.length > 0 ? parts.join(", ") : undefined;
+}
+
+/**
+ * One day: its column share, the range band behind it, and the circle with the number.
+ *
+ * **The whole cell is the target**, not the circle — a column on a phone is wider than the
+ * circle is tall, and the gap between two circles belongs to whichever day it sits beside.
+ *
+ * The band is drawn for a range's start, middle and end and never for a lone day, which is a
+ * circle with nothing to join. An outside day with `showOutsideDays` off is an empty cell of the
+ * same height, so the grid's rows never move.
+ *
+ * Announced as a button with the full date — "Monday 5 October 2026" — plus today and the range
+ * end it is, and `selected` and `disabled` as accessibility state.
+ */
+export function CalendarDay({ date, children, className }: CalendarDayProps): ReactElement {
+	const calendar = useCalendarPart("Calendar.Day");
+	const state = resolveDayState({
+		cell: { date, isOutside: !isSameMonth(date, calendar.visibleMonth), weekIndex: 0, dayIndex: 0 },
+		isCalendarDisabled: calendar.isDisabled,
+		isDisabled: calendar.isDateDisabled,
+		isReadOnly: calendar.isReadOnly,
+		selectOutsideDays: calendar.selectOutsideDays,
+		selection: calendar.selection,
+		showOutsideDays: calendar.showOutsideDays,
+		today: calendar.today,
+	});
+	const slots = calendarVariants({
+		isDisabled: state.isDisabled,
+		isInvalid: calendar.isInvalid,
+		isOutside: state.isOutside,
+		isToday: state.isToday,
+		rangeRole: state.rangeRole ?? "none",
+		size: calendar.size,
+		tone: state.tone,
+		variant: calendar.variant,
+	});
+
+	const { select } = calendar;
+	const handlePress = useCallback(() => select(date), [date, select]);
+
+	if (state.isHidden) {
+		return <View className={slots.cell({ className })} importantForAccessibility="no-hide-descendants" />;
+	}
+
+	const labelClassName = slots.dayLabel();
+	const content =
+		typeof children === "function"
+			? children({ ...state, date, labelClassName })
+			: (children ?? <Text className={labelClassName}>{date.day}</Text>);
+	const showsBand = state.rangeRole !== null && state.rangeRole !== "only";
+
+	return (
+		<Pressable
+			accessibilityHint={describeState(state)}
+			accessibilityLabel={formatDate(date, { locale: calendar.locale, style: "full" })}
+			accessibilityState={{ selected: state.isSelected }}
+			className={slots.cell({ className })}
+			disabled={!state.isPressable}
+			feedback="fade"
+			haptic="selection"
+			onPress={handlePress}
+			testID={resolvePartTestID(calendar.testID, `day-${serialiseDate(date)}`)}
+		>
+			{showsBand ? <View className={slots.band()} /> : null}
+			<View className={slots.dayBase()}>{content}</View>
+		</Pressable>
+	);
+}
+CalendarDay.displayName = "DelacourUI.Calendar.Day";

package/src/components/calendar/calendar-grid.tsx

@@ -0,0 +1,183 @@
+import { type ReactElement, type ReactNode, useCallback, useLayoutEffect, useMemo, useRef } from "react";
+import { type LayoutChangeEvent, View, type ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	Easing,
+	useAnimatedStyle,
+	useSharedValue,
+	withSequence,
+	withSpring,
+	withTiming,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
+import { playHaptic } from "../pressable";
+import { useCalendarPart } from "./calendar.context";
+import { type CalendarCell, formatMonthYear, monthGrid, serialiseDate } from "./calendar.date";
+import { calendarVariants, resolvePageDirection } from "./calendar.variants";
+import { CalendarDay } from "./calendar-day";
+import { CalendarPicker } from "./calendar-picker";
+
+export type CalendarGridProps = Omit<ViewProps, "children"> & {
+	className?: string;
+	/** Draws one cell. Omitted, a `Calendar.Day` for its date. */
+	renderDay?: (cell: CalendarCell) => ReactNode;
+};
+
+/** How far a sideways drag travels before the grid claims it, and a vertical one before it gives up. */
+const PAN_ACTIVATE_X = 12;
+const PAN_FAIL_Y = 12;
+
+/** How far a drag past a bound still follows the finger, as a fraction — enough to feel the edge. */
+const BOUND_RESISTANCE = 0.2;
+
+const SLIDE = { duration: 200, easing: Easing.out(Easing.cubic) } as const;
+const SETTLE_SPRING = { damping: 20, stiffness: 260 } as const;
+
+/**
+ * The six weeks of the visible month, and the surface a swipe pages on.
+ *
+ * **Paging is a slide out and a slide in.** A released swipe slides the old month off the side it
+ * was dragged towards, the month changes, and the new one slides in from the other side — the
+ * same entrance the arrows give it. Both off-screen positions are clipped, so the frame where the
+ * month swaps is never seen. With calm motion on, both slides are skipped and the page simply
+ * swaps; the page change itself is behaviour, not decoration, and always happens.
+ *
+ * **A drag towards a bound resists** rather than moving freely, then settles back with a light
+ * impact haptic — the edge is felt instead of the month silently refusing to turn.
+ *
+ * **The grid claims a sideways drag and gives up a vertical one**, so it lives inside a scrolling
+ * screen or a sheet without stealing the scroll.
+ *
+ * It also hosts `Calendar.Picker` over itself while a jump view is open, and hides its weeks
+ * rather than unmounting them, so the calendar's height never moves.
+ */
+export function CalendarGrid({ className, renderDay, ...props }: CalendarGridProps): ReactElement {
+	const calendar = useCalendarPart("Calendar.Grid");
+	const {
+		canGoNext,
+		canGoPrev,
+		goNext,
+		goPrev,
+		isDisabled,
+		label,
+		locale,
+		pageDirection,
+		size,
+		swipeToPage,
+		variant,
+		view,
+	} = calendar;
+	const { visibleMonth, weekStartsOn } = calendar;
+	const slots = calendarVariants({ size, variant });
+	const isCalm = useCalmMotion();
+
+	const width = useSharedValue(0);
+	const translateX = useSharedValue(0);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			width.value = event.nativeEvent.layout.width;
+		},
+		[width]
+	);
+
+	const page = useCallback((direction: -1 | 1) => (direction === 1 ? goNext() : goPrev()), [goNext, goPrev]);
+
+	const pan = useMemo(
+		() =>
+			Gesture.Pan()
+				.enabled(swipeToPage && view === "days" && !isDisabled)
+				.activeOffsetX([-PAN_ACTIVATE_X, PAN_ACTIVATE_X])
+				.failOffsetY([-PAN_FAIL_Y, PAN_FAIL_Y])
+				.onUpdate((event) => {
+					"worklet";
+					const blocked = (event.translationX > 0 && !canGoPrev) || (event.translationX < 0 && !canGoNext);
+					translateX.value = blocked ? event.translationX * BOUND_RESISTANCE : event.translationX;
+				})
+				.onEnd((event) => {
+					"worklet";
+					const direction = resolvePageDirection({
+						canGoNext,
+						canGoPrev,
+						translationX: event.translationX,
+						velocityX: event.velocityX,
+						width: width.value,
+					});
+
+					if (direction === 0) {
+						const blocked = (event.translationX > 0 && !canGoPrev) || (event.translationX < 0 && !canGoNext);
+						if (blocked) playHaptic("light");
+						translateX.value = withSpring(0, SETTLE_SPRING);
+						return;
+					}
+
+					playHaptic("selection");
+					if (isCalm) {
+						translateX.value = 0;
+						scheduleOnRN(page, direction);
+						return;
+					}
+					translateX.value = withTiming(-direction * width.value, SLIDE, (finished) => {
+						"worklet";
+						if (finished) scheduleOnRN(page, direction);
+					});
+				})
+				.onFinalize((_event, success) => {
+					"worklet";
+					if (!success) translateX.value = withSpring(0, SETTLE_SPRING);
+				}),
+		[canGoNext, canGoPrev, isCalm, isDisabled, page, swipeToPage, translateX, view, width]
+	);
+
+	// The new month slides in from the side the old one left by. Skipped on the first render — a
+	// calendar does not animate onto the screen — and for a jump, which has no side.
+	const monthKey = serialiseDate(visibleMonth);
+	const previousKey = useRef(monthKey);
+	useLayoutEffect(() => {
+		if (previousKey.current === monthKey) return;
+		previousKey.current = monthKey;
+		if (isCalm || pageDirection === 0 || width.value <= 0) {
+			translateX.value = 0;
+			return;
+		}
+		translateX.value = withSequence(withTiming(pageDirection * width.value, { duration: 0 }), withTiming(0, SLIDE));
+	}, [isCalm, monthKey, pageDirection, translateX, width]);
+
+	const slideStyle = useAnimatedStyle(() => ({ transform: [{ translateX: translateX.value }] }));
+
+	const weeks = useMemo(() => monthGrid(visibleMonth, weekStartsOn), [visibleMonth, weekStartsOn]);
+	const isPicking = view !== "days";
+
+	return (
+		<View className={slots.grid({ className })} onLayout={handleLayout} {...props}>
+			<GestureDetector gesture={pan}>
+				<Animated.View
+					accessibilityElementsHidden={isPicking}
+					accessibilityLabel={label ?? formatMonthYear(visibleMonth, locale)}
+					role="grid"
+					className={isPicking ? "opacity-0" : undefined}
+					importantForAccessibility={isPicking ? "no-hide-descendants" : "auto"}
+					pointerEvents={isPicking ? "none" : "auto"}
+					style={slideStyle}
+				>
+					{weeks.map((week) => (
+						<View className={slots.week()} key={serialiseDate(week[0]?.date ?? visibleMonth)}>
+							{week.map((cell) =>
+								renderDay ? (
+									<View className="flex-1" key={serialiseDate(cell.date)}>
+										{renderDay(cell)}
+									</View>
+								) : (
+									<CalendarDay date={cell.date} key={serialiseDate(cell.date)} />
+								)
+							)}
+						</View>
+					))}
+				</Animated.View>
+			</GestureDetector>
+			{isPicking ? <CalendarPicker /> : null}
+		</View>
+	);
+}
+CalendarGrid.displayName = "DelacourUI.Calendar.Grid";

package/src/components/calendar/calendar-header.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { useCalendarPart } from "./calendar.context";
+import { calendarVariants } from "./calendar.variants";
+import { CalendarCaption } from "./calendar-caption";
+import { CalendarNav } from "./calendar-nav";
+
+export type CalendarHeaderProps = ViewProps & {
+	className?: string;
+};
+
+/**
+ * The row above the grid: the previous arrow, the caption and the next arrow.
+ *
+ * Omit `children` for that default; pass them to rearrange it — both arrows on one side, say, or
+ * a caption with a "Today" button beside it.
+ */
+export function CalendarHeader({ className, children, ...props }: CalendarHeaderProps): ReactElement {
+	const { size, variant } = useCalendarPart("Calendar.Header");
+	const slots = calendarVariants({ size, variant });
+
+	return (
+		<View className={slots.header({ className })} {...props}>
+			{children ?? (
+				<>
+					<CalendarNav direction="prev" />
+					<CalendarCaption />
+					<CalendarNav direction="next" />
+				</>
+			)}
+		</View>
+	);
+}
+CalendarHeader.displayName = "DelacourUI.Calendar.Header";

package/src/components/calendar/calendar-nav.tsx

@@ -0,0 +1,51 @@
+import type { ReactElement } from "react";
+import { IconChevronLeft, IconChevronRight } from "../../icons/central";
+import { Button, type ButtonProps } from "../button";
+import { Icon } from "../icon";
+import { useCalendarPart } from "./calendar.context";
+import { resolvePartTestID } from "./calendar.variants";
+
+export type CalendarNavProps = Omit<ButtonProps, "children" | "onPress"> & {
+	/** Which way the arrow pages. */
+	direction: "prev" | "next";
+	/** The arrow's accessible name. Defaults to "Previous month" / "Next month" — or year, in the months view. */
+	label?: string;
+};
+
+/**
+ * One paging arrow: a ghost icon button that disables itself at the bound it points at.
+ *
+ * In the month grid it pages a month; in the months view, a year; in the years view, where the
+ * list scrolls instead, it is disabled. A disabled calendar disables it too — a read-only one
+ * does not, because looking at another month changes nothing.
+ */
+export function CalendarNav({ direction, label, isDisabled, ...props }: CalendarNavProps): ReactElement {
+	const {
+		canGoNext,
+		canGoPrev,
+		goNext,
+		goPrev,
+		isDisabled: calendarDisabled,
+		testID,
+		view,
+	} = useCalendarPart("Calendar.Nav");
+	const isPrev = direction === "prev";
+	const canGo = (isPrev ? canGoPrev : canGoNext) && view !== "years";
+	const unit = view === "months" ? "year" : "month";
+
+	return (
+		<Button
+			accessibilityLabel={label ?? `${isPrev ? "Previous" : "Next"} ${unit}`}
+			haptic="selection"
+			isDisabled={isDisabled ?? (calendarDisabled || !canGo)}
+			onPress={isPrev ? goPrev : goNext}
+			size="icon-sm"
+			testID={resolvePartTestID(testID, direction)}
+			variant="ghost"
+			{...props}
+		>
+			<Icon icon={isPrev ? IconChevronLeft : IconChevronRight} />
+		</Button>
+	);
+}
+CalendarNav.displayName = "DelacourUI.Calendar.Nav";

package/src/components/calendar/calendar-picker.tsx

@@ -0,0 +1,128 @@
+import { type ReactElement, useCallback, useMemo, useRef } from "react";
+import { type LayoutChangeEvent, ScrollView, View, type ViewProps } from "react-native";
+import Animated, { FadeIn, FadeOut } from "react-native-reanimated";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
+import { cn } from "../../lib/cn";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { useCalendarPart } from "./calendar.context";
+import { compareMonths, formatYear, monthNames } from "./calendar.date";
+import { calendarVariants, isMonthInBounds, resolvePartTestID } from "./calendar.variants";
+
+export type CalendarPickerProps = Omit<ViewProps, "children"> & {
+	className?: string;
+};
+
+const CROSSFADE_MS = 150;
+
+/**
+ * The months and years jump views, laid over the grid while one is open.
+ *
+ * **Months** is twelve names in a three-column grid: a tap shows that month and returns to the
+ * days. **Years** is a scrolling three-column list over the calendar's year span, opened already
+ * scrolled to the visible year: a tap returns to the months view in that year, so a birth date
+ * is three taps — caption, caption, year — then a month and a day.
+ *
+ * A month outside the paging bounds is disabled. The view crossfades with the grid it covers,
+ * and with calm motion on it simply appears.
+ *
+ * Rendered by `Calendar.Grid`, which sizes it — it fills the grid's own box, so opening it never
+ * changes the calendar's height. Exported for a custom grid that wants to host it itself.
+ */
+export function CalendarPicker({ className, ...props }: CalendarPickerProps): ReactElement {
+	const calendar = useCalendarPart("Calendar.Picker");
+	const { goToMonth, isDisabled, locale, monthBounds, setView, size, variant, view, visibleMonth, yearSpan } = calendar;
+	const isCalm = useCalmMotion();
+	const slots = calendarVariants({ size, variant });
+
+	const names = useMemo(() => monthNames(locale, "short"), [locale]);
+	const years = useMemo(() => {
+		const list: number[] = [];
+		for (let year = yearSpan.from; year <= yearSpan.to; year += 1) list.push(year);
+		return list;
+	}, [yearSpan.from, yearSpan.to]);
+
+	const scroller = useRef<ScrollView>(null);
+	const hasScrolled = useRef(false);
+	const handleCurrentLayout = useCallback((event: LayoutChangeEvent) => {
+		if (hasScrolled.current) return;
+		hasScrolled.current = true;
+		scroller.current?.scrollTo({ animated: false, y: event.nativeEvent.layout.y });
+	}, []);
+
+	const pickMonth = useCallback(
+		(month: number) => {
+			goToMonth({ day: 1, month, year: visibleMonth.year });
+			setView("days");
+		},
+		[goToMonth, setView, visibleMonth.year]
+	);
+
+	const pickYear = useCallback(
+		(year: number) => {
+			goToMonth({ day: 1, month: visibleMonth.month, year });
+			setView("months");
+		},
+		[goToMonth, setView, visibleMonth.month]
+	);
+
+	const fade = isCalm ? undefined : FadeIn.duration(CROSSFADE_MS);
+	const fadeOut = isCalm ? undefined : FadeOut.duration(CROSSFADE_MS);
+
+	return (
+		<Animated.View className={cn("absolute inset-0", className)} entering={fade} exiting={fadeOut} {...props}>
+			{view === "months" ? (
+				<View accessibilityRole="list" className={slots.pickerGrid()}>
+					{names.map((name, index) => {
+						const month = index + 1;
+						const isCurrent = month === visibleMonth.month;
+						const inBounds = isMonthInBounds({ day: 1, month, year: visibleMonth.year }, monthBounds);
+						const item = calendarVariants({ size, tone: isCurrent ? "selected" : "plain", variant });
+						return (
+							<Pressable
+								accessibilityState={{ selected: isCurrent }}
+								className={item.pickerItem({ className: inBounds ? undefined : "opacity-40" })}
+								disabled={isDisabled || !inBounds}
+								feedback="fade"
+								haptic="selection"
+								key={name}
+								onPress={() => pickMonth(month)}
+								testID={resolvePartTestID(calendar.testID, `month-${month}`)}
+							>
+								<Text className={item.pickerItemLabel()}>{name}</Text>
+							</Pressable>
+						);
+					})}
+				</View>
+			) : (
+				<ScrollView ref={scroller} showsVerticalScrollIndicator={false}>
+					<View accessibilityRole="list" className={slots.pickerGrid()}>
+						{years.map((year) => {
+							const isCurrent = year === visibleMonth.year;
+							const item = calendarVariants({ size, tone: isCurrent ? "selected" : "plain", variant });
+							const inBounds =
+								(!monthBounds.first || compareMonths({ day: 1, month: 12, year }, monthBounds.first) >= 0) &&
+								(!monthBounds.last || compareMonths({ day: 1, month: 1, year }, monthBounds.last) <= 0);
+							return (
+								<Pressable
+									accessibilityState={{ selected: isCurrent }}
+									className={item.pickerItem({ className: inBounds ? undefined : "opacity-40" })}
+									disabled={isDisabled || !inBounds}
+									feedback="fade"
+									haptic="selection"
+									key={year}
+									onLayout={isCurrent ? handleCurrentLayout : undefined}
+									onPress={() => pickYear(year)}
+									testID={resolvePartTestID(calendar.testID, `year-${year}`)}
+								>
+									<Text className={item.pickerItemLabel()}>{formatYear(year, locale)}</Text>
+								</Pressable>
+							);
+						})}
+					</View>
+				</ScrollView>
+			)}
+		</Animated.View>
+	);
+}
+CalendarPicker.displayName = "DelacourUI.Calendar.Picker";

package/src/components/calendar/calendar-weekdays.tsx

@@ -0,0 +1,48 @@
+import { type ReactElement, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { Text } from "../text";
+import { useCalendarPart } from "./calendar.context";
+import { weekdayLabels } from "./calendar.date";
+import { calendarVariants } from "./calendar.variants";
+
+export type CalendarWeekdaysProps = Omit<ViewProps, "children"> & {
+	className?: string;
+	/** How the names are drawn. The accessible name is always the full one. */
+	format?: "narrow" | "short";
+};
+
+/**
+ * The row of weekday names, in the grid's column order and the calendar's locale.
+ *
+ * Each column says its short name and is announced by its full one, so a screen reader reads
+ * "Monday" rather than "Mon" — or "M", which is two different days. Hidden, not removed, while a
+ * jump view is open, so the calendar's height holds still.
+ */
+export function CalendarWeekdays({ className, format = "short", ...props }: CalendarWeekdaysProps): ReactElement {
+	const { locale, size, variant, view, weekStartsOn } = useCalendarPart("Calendar.Weekdays");
+	const slots = calendarVariants({ size, variant });
+	const isHidden = view !== "days";
+
+	const names = useMemo(
+		() => ({ shown: weekdayLabels(locale, weekStartsOn, format), spoken: weekdayLabels(locale, weekStartsOn, "long") }),
+		[format, locale, weekStartsOn]
+	);
+
+	return (
+		<View
+			accessibilityElementsHidden={isHidden}
+			className={slots.weekdays({ className: [isHidden ? "opacity-0" : undefined, className] })}
+			importantForAccessibility={isHidden ? "no-hide-descendants" : "auto"}
+			{...props}
+		>
+			{names.shown.map((name, index) => (
+				<View className={slots.weekday()} key={names.spoken[index]}>
+					<Text accessibilityLabel={names.spoken[index]} className={slots.weekdayLabel()}>
+						{name}
+					</Text>
+				</View>
+			))}
+		</View>
+	);
+}
+CalendarWeekdays.displayName = "DelacourUI.Calendar.Weekdays";