react-native-agenda-kit 0.1.0

package/src/expandable/DayCell.tsx

@@ -0,0 +1,97 @@
+/**
+ * One day in the MONTH GRID. Selection arrives as a plain prop from the committed
+ * date, and `memo` on primitive props means a commit re-renders two cells, not the
+ * month. (The week strip tracks a fling frame by frame with one pill instead.)
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { FONT_SIZE, RADIUS } from '../theme/tokens';
+import { memo } from 'react';
+import { Pressable, StyleSheet, View } from 'react-native';
+import { KitText } from '../core/KitText';
+import { DAY_CELL, DAY_LINE_HEIGHT, DAY_TEXT_MARGIN_TOP, DOT_MARGIN_TOP, DOT_SIZE } from './geometry';
+
+type Props = {
+  dayIndex: number;
+  label: string;
+  left: number;
+  top: number;
+  isToday: boolean;
+  isDisabled: boolean;
+  isSelected: boolean;
+  /** `null` = no dot, `''` = default colour. */
+  dot: string | null;
+  onPress: (dayIndex: number) => void;
+  /** The caller's spoken date; the bare number is read when absent. */
+  accessibilityLabel?: string;
+};
+
+const DayCellInner = ({
+  dayIndex,
+  label,
+  left,
+  top,
+  isToday,
+  isDisabled,
+  isSelected,
+  dot,
+  onPress,
+  accessibilityLabel,
+}: Props) => {
+  const styles = useKitStyles(makeStyles);
+  const state = isSelected ? 3 : isDisabled ? 2 : isToday ? 1 : 0;
+
+  return (
+    <Pressable
+      style={[styles.cell, { left, top }, isSelected ? styles.cellSelected : null]}
+      onPress={() => onPress(dayIndex)}
+      disabled={isDisabled}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={{ selected: isSelected, disabled: isDisabled }}
+    >
+      <KitText style={styles.text[state]}>{label}</KitText>
+      {dot !== null ? (
+        <View style={[styles.dot, isSelected || !dot ? styles.dotFill[state] : { backgroundColor: dot }]} />
+      ) : null}
+    </Pressable>
+  );
+};
+
+export const DayCell = memo(DayCellInner);
+DayCell.displayName = 'DayCell';
+
+/** `text` and `dotFill` are indexed by state: 0 plain, 1 today, 2 disabled, 3 selected. */
+const makeStyles = ({ colors, fonts }: KitStyleArgs) => {
+  const text = {
+    marginTop: DAY_TEXT_MARGIN_TOP,
+    fontFamily: fonts.regular,
+    fontSize: FONT_SIZE.sm,
+    lineHeight: DAY_LINE_HEIGHT,
+  } as const;
+  const s = StyleSheet.create({
+    cell: {
+      position: 'absolute',
+      width: DAY_CELL,
+      height: DAY_CELL,
+      borderRadius: RADIUS.full,
+      alignItems: 'center',
+    },
+    // The one accent use on the calendar — active selection: one accent, nowhere else.
+    cellSelected: { backgroundColor: colors.accentFill },
+    text: { ...text, color: colors.text },
+    textToday: { ...text, color: colors.accent },
+    textDisabled: { ...text, color: colors.textMuted },
+    textSelected: { ...text, color: colors.onAccentFill },
+    dot: { width: DOT_SIZE, height: DOT_SIZE, marginTop: DOT_MARGIN_TOP, borderRadius: RADIUS.full },
+    dotDefault: { backgroundColor: colors.accent },
+    dotSelected: { backgroundColor: colors.onAccentFill },
+  });
+  return {
+    cell: s.cell,
+    cellSelected: s.cellSelected,
+    dot: s.dot,
+    text: [s.text, s.textToday, s.textDisabled, s.textSelected],
+    dotFill: [s.dotDefault, s.dotDefault, s.dotDefault, s.dotSelected],
+  };
+};

package/src/expandable/ExpandableCalendar.tsx

@@ -0,0 +1,278 @@
+/**
+ * The expandable calendar — week strip closed, month grid open — and the body it
+ * pushes down.
+ *
+ * Nothing animates height. `progress` (0 closed, 1 open) moves and every layer
+ * reads it as a transform or opacity: the month layer fades in and slides from
+ * "selected week on top" to its natural place, the strip fades out, and the knob
+ * and fixed-height body translate by `progress · travel`, where `travel` belongs
+ * to the VISIBLE month and re-targets when that changes while open.
+ *
+ * The body renders `children` because it must read `progress`. A list drag closes
+ * an open calendar: the grid shows the committed date, the list the day under it.
+ * With a screen reader the calendar is a static open month grid — TalkBack ignores
+ * opacity, would read strip and grid both, and cannot perform the pan.
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { ANIMATION } from '../theme/tokens';
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Dimensions, StyleSheet, View, type LayoutChangeEvent } from 'react-native';
+import { GestureDetector } from 'react-native-gesture-handler';
+import Animated, {
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { useCalendarContext, useCalendarDate } from '../core/CalendarContext';
+import { clampIndex, dayIndexOf, ymdAt } from '../core/dateKey';
+import { KIT_EASING, kitDuration, useScreenReaderEnabled } from '../core/motion';
+import { clampNum } from '../core/worklets';
+import type { ExpandableCalendarProps } from '../types';
+import { buildCalendarCells, buildDots, cellLefts, pageOfIndex } from './calendarCells';
+import { calendarHeights, KNOB_CONTAINER_HEIGHT, MAX_WEEKS, WEEK_ROW_HEIGHT } from './geometry';
+import { Knob } from './Knob';
+import { MonthPager } from './MonthPager';
+import { snap, useExpandGesture } from './useExpandGesture';
+import { WeekStrip } from './WeekStrip';
+
+const POSITIONS = { CLOSED: 'closed', OPEN: 'open' } as const;
+const { closed: CLOSED_H, full: CALENDAR_H } = calendarHeights(MAX_WEEKS);
+/**
+ * Invisible, so the stale translateY is unseen; one object makes Reanimated skip the
+ * update. Opacity only: `updateProps` reassigns `transform` on the object it is given.
+ */
+const CLOSED_MONTH_STYLE = { opacity: 0 };
+
+const ExpandableCalendarInner = ({
+  initialPosition = 'closed',
+  onCalendarToggled,
+  style,
+  closeOnDayPress = true,
+  closeOnListScroll = true,
+  markedDates,
+  disablePan = false,
+  openThreshold,
+  closeThreshold,
+  knobAccessibilityLabel,
+  dayAccessibilityLabel,
+  monthShortLabels,
+  children,
+  ref,
+}: ExpandableCalendarProps) => {
+  const styles = useKitStyles(makeStyles);
+  const { range, store, dateRef, setDate, reduceMotion } = useCalendarContext();
+  const date = useCalendarDate();
+  const screenReader = useScreenReaderEnabled();
+  const { dayIndex, listDragSeq } = store;
+
+  const [layout, setLayout] = useState(() => ({ width: Dimensions.get('window').width, height: 0 }));
+  const [isOpen, setIsOpen] = useState(initialPosition === 'open');
+
+  const { labels, ordinalByIndex, pages } = useMemo(() => buildCalendarCells(range), [range]);
+  const dots = useMemo(() => buildDots(range, markedDates), [range, markedDates]);
+  const lefts = useMemo(() => cellLefts(layout.width), [layout.width]);
+  const a11yLabels = useMemo(
+    () =>
+      screenReader && dayAccessibilityLabel
+        ? range.ymdByIndex.map((ymd) => dayAccessibilityLabel(ymd))
+        : undefined,
+    [dayAccessibilityLabel, range, screenReader],
+  );
+
+  const [initialPage] = useState(() =>
+    pageOfIndex(pages, clampIndex(range, dayIndexOf(range, dateRef.current))),
+  );
+  const progress = useSharedValue(initialPosition === 'open' ? 1 : 0);
+  const visiblePage = useSharedValue(initialPage);
+  const travel = useSharedValue(calendarHeights(pages.weeksByPage[initialPage] ?? 5).travel);
+  const pagesSV = useSharedValue(pages);
+  const writtenPages = useRef(pages);
+  useLayoutEffect(() => {
+    if (writtenPages.current === pages) return;
+    writtenPages.current = pages;
+    pagesSV.value = pages;
+  }, [pages, pagesSV]);
+
+  const retarget = kitDuration(ANIMATION.base, reduceMotion);
+  useAnimatedReaction(
+    () => visiblePage.value,
+    (page, prev) => {
+      if (prev === null || page === prev) return;
+      const next = calendarHeights(pagesSV.value.weeksByPage[page] ?? 5).travel;
+      // Open: glide the body to the new month's bottom edge. Closed: record it for the next open.
+      travel.value =
+        progress.value > 0 ? withTiming(next, { duration: retarget, easing: KIT_EASING }) : next;
+    },
+  );
+
+  // Through a ref: the gesture's worklets capture `handleToggled`, so it never changes identity.
+  const onToggledRef = useRef(onCalendarToggled);
+  useLayoutEffect(() => {
+    onToggledRef.current = onCalendarToggled;
+  });
+  const handleToggled = useCallback((open: boolean) => {
+    setIsOpen(open);
+    onToggledRef.current?.(open);
+  }, []);
+
+  const { pan, snapTo, lastReported } = useExpandGesture({
+    progress,
+    travel,
+    enabled: !disablePan && !screenReader,
+    openThreshold,
+    closeThreshold,
+    reduceMotion,
+    initialOpen: initialPosition === 'open',
+    onToggled: handleToggled,
+  });
+  const toggle = useCallback(() => snapTo(), [snapTo]);
+
+  // Not foldable into the gesture's `initialOpen`/`enabled`: the flag resolves after
+  // mount, and `enabled` is also false for `disablePan`, which must not open.
+  useEffect(() => {
+    if (screenReader) snapTo(1);
+  }, [screenReader, snapTo]);
+
+  useAnimatedReaction(
+    () => listDragSeq.value,
+    (seq, prev) => {
+      // Only a CHANGE of the counter is a drag; its first reading is the mount.
+      if (prev === null || seq === prev || !closeOnListScroll || screenReader) return;
+      if (progress.value > 0) snap(progress, lastReported, 0, reduceMotion, handleToggled);
+    },
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({ toggleCalendarPosition: screenReader ? () => true : toggle }),
+    [screenReader, toggle],
+  );
+
+  const handleDayPress = useCallback(
+    (idx: number) => {
+      if (clampIndex(range, idx) !== idx) return;
+      setDate(ymdAt(range, idx), 'dayPress');
+      // Same tick as the date: no race between the agenda's scroll and the collapse.
+      if (closeOnDayPress && !screenReader && progress.value > 0) snapTo(0);
+    },
+    [closeOnDayPress, progress, range, screenReader, setDate, snapTo],
+  );
+
+  const monthStyle = useAnimatedStyle(() => {
+    const p = progress.value;
+    if (p === 0) return CLOSED_MONTH_STYLE;
+    const { gridStartByPage, weeksByPage } = pagesSV.value;
+    const page = visiblePage.value;
+    const row = clampNum(
+      Math.floor((dayIndex.value - (gridStartByPage[page] ?? 0)) / 7),
+      0,
+      (weeksByPage[page] ?? MAX_WEEKS) - 1,
+    );
+    return { opacity: p, transform: [{ translateY: -(1 - p) * row * WEEK_ROW_HEIGHT }] };
+  });
+  const weekStyle = useAnimatedStyle(() => ({ opacity: 1 - progress.value }));
+  const knobStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: CLOSED_H - KNOB_CONTAINER_HEIGHT + progress.value * travel.value }],
+  }));
+  const bodyStyle = useAnimatedStyle(() => ({
+    transform: [{ translateY: progress.value * travel.value }],
+  }));
+
+  const onLayout = useCallback((e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout;
+    setLayout((prev) =>
+      Math.abs(prev.width - width) < 0.5 && Math.abs(prev.height - height) < 0.5
+        ? prev
+        : { width, height },
+    );
+  }, []);
+
+  return (
+    <View style={[styles.region, style]} onLayout={onLayout}>
+      <GestureDetector gesture={pan}>
+        <View collapsable={false} style={styles.calendar}>
+          <MonthPager
+            width={layout.width}
+            lefts={lefts}
+            pages={pages}
+            pagesSV={pagesSV}
+            labels={labels}
+            a11yLabels={a11yLabels}
+            dots={dots}
+            selectedIndex={dayIndexOf(range, date)}
+            initialPage={initialPage}
+            visiblePage={visiblePage}
+            onDayPress={handleDayPress}
+            animatedStyle={monthStyle}
+            isOpen={isOpen}
+            screenReader={screenReader}
+          />
+          {screenReader ? null : (
+            <>
+              <WeekStrip
+                width={layout.width}
+                lefts={lefts}
+                labels={labels}
+                ordinals={ordinalByIndex}
+                monthShortLabels={monthShortLabels}
+                dots={dots}
+                onDayPress={handleDayPress}
+                animatedStyle={weekStyle}
+                interactive={!isOpen}
+              />
+              <Knob
+                animatedStyle={knobStyle}
+                onPress={toggle}
+                accessibilityLabel={knobAccessibilityLabel}
+              />
+            </>
+          )}
+        </View>
+      </GestureDetector>
+      <Animated.View
+        style={[styles.body, { height: Math.max(0, layout.height - CLOSED_H) }, bodyStyle]}
+      >
+        {children}
+      </Animated.View>
+    </View>
+  );
+};
+
+export const ExpandableCalendar = Object.assign(memo(ExpandableCalendarInner), {
+  positions: POSITIONS,
+});
+
+const makeStyles = ({ colors }: KitStyleArgs) =>
+  StyleSheet.create({
+    region: {
+      flex: 1,
+      overflow: 'hidden',
+      backgroundColor: colors.surface,
+    },
+    calendar: {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      right: 0,
+      height: CALENDAR_H,
+      backgroundColor: colors.surface,
+    },
+    body: {
+      position: 'absolute',
+      top: CLOSED_H,
+      left: 0,
+      right: 0,
+      backgroundColor: colors.surface,
+    },
+  });

package/src/expandable/Knob.tsx

@@ -0,0 +1,67 @@
+/**
+ * The drag band under the calendar. A tap toggles; a drag anywhere on the
+ * calendar (not just here) opens and closes — the band is the affordance, not
+ * the only hit area.
+ *
+ * A `Pressable`, not a `Gesture.Tap` raced against the pan. The tap belongs to
+ * the knob alone; racing a tap on the whole detector would make every day-cell
+ * tap also toggle the calendar.
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { RADIUS } from '../theme/tokens';
+import { memo } from 'react';
+import { Pressable, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import Animated, { type AnimatedStyle } from 'react-native-reanimated';
+import { KNOB_CONTAINER_HEIGHT, KNOB_HEIGHT, KNOB_WIDTH } from './geometry';
+
+type Props = {
+  animatedStyle: StyleProp<AnimatedStyle<StyleProp<ViewStyle>>>;
+  onPress: () => void;
+  accessibilityLabel?: string;
+};
+
+const KnobInner = ({ animatedStyle, onPress, accessibilityLabel }: Props) => {
+  const styles = useKitStyles(makeStyles);
+  return (
+    <Animated.View style={[styles.container, animatedStyle]}>
+      <Pressable
+        style={styles.hit}
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+      >
+        <View style={styles.knob} />
+      </Pressable>
+    </Animated.View>
+  );
+};
+
+export const Knob = memo(KnobInner);
+Knob.displayName = 'Knob';
+
+const makeStyles = ({ colors }: KitStyleArgs) =>
+  StyleSheet.create({
+    container: {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      right: 0,
+      height: KNOB_CONTAINER_HEIGHT,
+      backgroundColor: colors.surface,
+    },
+    hit: {
+      flex: 1,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    knob: {
+      width: KNOB_WIDTH,
+      height: KNOB_HEIGHT,
+      // A pill is the one shape `full` exists for — the one shape `full` exists for.
+      borderRadius: RADIUS.full,
+      // The library's default `expandableKnobColor` is #e8ecf0 — a slate grey,
+      // which reads as a tinted surface. `border` is the nearest true-neutral.
+      backgroundColor: colors.border,
+    },
+  });

package/src/expandable/MonthPager.tsx

@@ -0,0 +1,208 @@
+/**
+ * The open calendar: one month per page across the selectable window.
+ *
+ * Selection is the COMMITTED date as a plain prop, handed only to the page that
+ * holds it, so a commit re-renders at most two pages and two memo'd cells.
+ *
+ * Mounted pages derive from that same committed date. Closed, only its month
+ * exists: the layer is invisible, and every month crossing commits a date. Open,
+ * its two neighbours join so a swipe shows one; a swipe that lands commits the
+ * new month, which re-centres the window. A screen reader pages by scroll
+ * actions, so it gets every month. Moves page the pager instantly even while
+ * closed, so opening shows the right month.
+ */
+
+import { memo, useCallback, type ReactElement } from 'react';
+import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import Animated, { type AnimatedStyle, type SharedValue } from 'react-native-reanimated';
+import { useCalendarContext } from '../core/CalendarContext';
+import { clampIndex, ymdAt } from '../core/dateKey';
+import { pageOfIndex, type MonthPages } from './calendarCells';
+import { DayCell } from './DayCell';
+import { MAX_WEEKS, WEEK_ROW_HEIGHT, WEEK_ROW_V_MARGIN } from './geometry';
+import { PAGER_SCROLL_THROTTLE, useHorizontalPager } from './useHorizontalPager';
+
+const GRID_HEIGHT = MAX_WEEKS * WEEK_ROW_HEIGHT;
+
+type GridProps = {
+  page: number;
+  width: number;
+  lefts: number[];
+  gridStart: number;
+  weeks: number;
+  rawPageByIndex: number[];
+  labels: string[];
+  /** Spoken names by day index; only present while a screen reader runs. */
+  a11yLabels?: string[];
+  dots: (string | null)[];
+  /** −1 unless the selected day is in this page — keeps other pages memo-equal. */
+  selectedIndex: number;
+  todayIndex: number;
+  minIndex: number;
+  maxIndex: number;
+  onDayPress: (dayIndex: number) => void;
+};
+
+const MonthGrid = memo(
+  ({
+    page,
+    width,
+    lefts,
+    gridStart,
+    weeks,
+    rawPageByIndex,
+    labels,
+    a11yLabels,
+    dots,
+    selectedIndex,
+    todayIndex,
+    minIndex,
+    maxIndex,
+    onDayPress,
+  }: GridProps) => {
+    const cells: ReactElement[] = [];
+    for (let r = 0; r < weeks; r += 1) {
+      for (let c = 0; c < 7; c += 1) {
+        const i = gridStart + r * 7 + c;
+        // Days of the neighbouring months are blank, as the library's `hideExtraDays` draws them.
+        if (i < 0 || i >= labels.length || rawPageByIndex[i] !== page) continue;
+        cells.push(
+          <DayCell
+            key={i}
+            dayIndex={i}
+            label={labels[i]}
+            accessibilityLabel={a11yLabels?.[i]}
+            left={lefts[c]}
+            top={r * WEEK_ROW_HEIGHT + WEEK_ROW_V_MARGIN}
+            isToday={i === todayIndex}
+            isDisabled={i < minIndex || i > maxIndex}
+            isSelected={i === selectedIndex}
+            dot={dots[i]}
+            onPress={onDayPress}
+          />,
+        );
+      }
+    }
+    return <View style={[styles.grid, { left: page * width, width }]}>{cells}</View>;
+  },
+);
+MonthGrid.displayName = 'MonthGrid';
+
+type Props = {
+  width: number;
+  lefts: number[];
+  pages: MonthPages;
+  pagesSV: SharedValue<MonthPages>;
+  labels: string[];
+  a11yLabels?: string[];
+  dots: (string | null)[];
+  selectedIndex: number;
+  initialPage: number;
+  visiblePage: SharedValue<number>;
+  onDayPress: (dayIndex: number) => void;
+  animatedStyle: StyleProp<AnimatedStyle<StyleProp<ViewStyle>>>;
+  isOpen: boolean;
+  screenReader: boolean;
+};
+
+const MonthPagerInner = ({
+  width,
+  lefts,
+  pages,
+  pagesSV,
+  labels,
+  a11yLabels,
+  dots,
+  selectedIndex,
+  initialPage,
+  visiblePage,
+  onDayPress,
+  animatedStyle,
+  isOpen,
+  screenReader,
+}: Props) => {
+  const { range, setDate } = useCalendarContext();
+
+  /** A swipe landed on another month: select its first selectable day. */
+  const onMonthSettled = useCallback(
+    (page: number) => {
+      setDate(ymdAt(range, clampIndex(range, pages.monthStartByPage[page])), 'pageScroll', 'month');
+    },
+    [pages, range, setDate],
+  );
+
+  const pageOf = useCallback(
+    (idx: number) => {
+      'worklet';
+      return pageOfIndex(pagesSV.value, idx);
+    },
+    [pagesSV],
+  );
+
+  const pager = useHorizontalPager({
+    width,
+    initialPage,
+    origin: 'month',
+    pageOf,
+    page: visiblePage,
+    onSettled: onMonthSettled,
+  });
+
+  const interactive = isOpen || screenReader;
+  const committed = pageOfIndex(pages, clampIndex(range, selectedIndex));
+  const reach = isOpen ? 1 : 0;
+  const first = screenReader ? 0 : Math.max(0, committed - reach);
+  const last = screenReader ? pages.count - 1 : Math.min(pages.count - 1, committed + reach);
+
+  const grids: ReactElement[] = [];
+  for (let p = first; p <= last; p += 1) {
+    grids.push(
+      <MonthGrid
+        key={p}
+        page={p}
+        width={width}
+        lefts={lefts}
+        gridStart={pages.gridStartByPage[p]}
+        weeks={pages.weeksByPage[p]}
+        rawPageByIndex={pages.rawPageByIndex}
+        labels={labels}
+        a11yLabels={a11yLabels}
+        dots={dots}
+        selectedIndex={pages.rawPageByIndex[selectedIndex] === p ? selectedIndex : -1}
+        todayIndex={range.todayIndex}
+        minIndex={range.minIndex}
+        maxIndex={range.maxIndex}
+        onDayPress={onDayPress}
+      />,
+    );
+  }
+
+  return (
+    <Animated.View
+      pointerEvents={interactive ? 'auto' : 'none'}
+      style={[styles.root, { width }, animatedStyle]}
+    >
+      <Animated.ScrollView
+        ref={pager.ref}
+        horizontal
+        pagingEnabled
+        showsHorizontalScrollIndicator={false}
+        scrollEnabled={interactive}
+        onScroll={pager.onScroll}
+        scrollEventThrottle={PAGER_SCROLL_THROTTLE}
+        contentOffset={pager.contentOffset}
+        onLayout={pager.onLayout}
+      >
+        <View style={{ width: pages.count * width, height: GRID_HEIGHT }}>{grids}</View>
+      </Animated.ScrollView>
+    </Animated.View>
+  );
+};
+
+export const MonthPager = memo(MonthPagerInner);
+MonthPager.displayName = 'MonthPager';
+
+const styles = StyleSheet.create({
+  root: { position: 'absolute', top: 0, left: 0, height: GRID_HEIGHT },
+  grid: { position: 'absolute', top: 0, height: GRID_HEIGHT },
+});