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

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

package/src/components/calendar/calendar.context.tsx

@@ -0,0 +1,108 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { CalendarDate, CalendarSelectionState, Weekday } from "./calendar.date";
+import type { CalendarCaptionLayout } from "./calendar.types";
+import type { CalendarRangeRole, CalendarSize, CalendarVariant, CalendarView } from "./calendar.variants";
+
+export type CalendarContextValue = {
+	mode: CalendarSelectionState["mode"];
+	variant: CalendarVariant;
+	size: CalendarSize;
+	/** The tag names are formatted in, or `undefined` for the device's own. */
+	locale: string | undefined;
+	/** The first column's weekday, resolved — never `auto`. */
+	weekStartsOn: Weekday;
+	/** The first of the month the grid shows. */
+	visibleMonth: CalendarDate;
+	/**
+	 * Which way the last page went: `1` forward, `-1` back, `0` for a jump or the first render. The
+	 * grid reads it to slide the new month in from the side it came from.
+	 */
+	pageDirection: -1 | 0 | 1;
+	/** The body's view: the month grid, or a jump view. */
+	view: CalendarView;
+	setView: (view: CalendarView) => void;
+	/** Shows the month `date` falls in, held inside the month bounds. */
+	goToMonth: (date: CalendarDate) => void;
+	/** One month back. In the months view, one year. */
+	goPrev: () => void;
+	/** One month forward. In the months view, one year. */
+	goNext: () => void;
+	canGoPrev: boolean;
+	canGoNext: boolean;
+	/** The first and last months paging reaches; `null` is unbounded. */
+	monthBounds: { first: CalendarDate | null; last: CalendarDate | null };
+	/** The years the year view lists. */
+	yearSpan: { from: number; to: number };
+	/** Whether a day cannot be picked — bounds and matchers, not the calendar's own state. */
+	isDateDisabled: (date: CalendarDate) => boolean;
+	isDateSelected: (date: CalendarDate) => boolean;
+	/** Where a day sits in the range, or `null`. Always `null` outside range mode. */
+	rangeRole: (date: CalendarDate) => CalendarRangeRole | null;
+	/** The selection, by mode. */
+	selection: CalendarSelectionState;
+	/** Applies a tap on `date` to the selection. Ignored while disabled, read-only, or on a disabled day. */
+	select: (date: CalendarDate) => void;
+	today: CalendarDate;
+	isDisabled: boolean;
+	isInvalid: boolean;
+	isReadOnly: boolean;
+	showOutsideDays: boolean;
+	selectOutsideDays: boolean;
+	swipeToPage: boolean;
+	captionLayout: CalendarCaptionLayout;
+	/** The calendar's own `testID`, which its parts derive theirs from — see `resolvePartTestID`. */
+	testID: string | undefined;
+	/** The enclosing `Field.Label`'s text, for the grid's accessible name. */
+	label: string | null;
+};
+
+const CalendarContext = createContext<CalendarContextValue | null>(null);
+
+/**
+ * Supplies one calendar's state to its own parts.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can read it without
+ * importing `./calendar` and closing a cycle (AGENTS.md rule 3).
+ */
+export function CalendarProvider({
+	value,
+	children,
+}: {
+	value: CalendarContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <CalendarContext value={value}>{children}</CalendarContext>;
+}
+CalendarProvider.displayName = "DelacourUI.Calendar.Provider";
+
+/** The enclosing calendar's state, or null outside a `<Calendar>` — for another folder's control. */
+export function useCalendarContext(): CalendarContextValue | null {
+	return use(CalendarContext);
+}
+
+/**
+ * Reads the enclosing calendar's state.
+ *
+ * For a custom day or header that has to match the calendar it sits in. Throws outside one — use
+ * {@link useCalendarContext} where the calendar is optional.
+ */
+export function useCalendar(): CalendarContextValue {
+	const context = useCalendarContext();
+	if (!context) {
+		throw new Error("useCalendar must be called inside a <Calendar>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing calendar's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useCalendarPart(component: string): CalendarContextValue {
+	const context = useCalendarContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Calendar>.`);
+	}
+	return context;
+}