react-native-bigger-calendar 0.1.0

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "react-native-bigger-calendar",
+  "version": "0.1.0",
+  "description": "A generic, themeable month/week/day calendar for React Native with pinch-to-zoom, virtualized paging, and a render-prop event API.",
+  "keywords": [
+    "react-native",
+    "calendar",
+    "timetable",
+    "agenda",
+    "month-view",
+    "week-view",
+    "day-view",
+    "reanimated",
+    "expo"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/afonsojramos/react-native-bigger-calendar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/afonsojramos/react-native-bigger-calendar/issues"
+  },
+  "homepage": "https://github.com/afonsojramos/react-native-bigger-calendar#readme",
+  "sideEffects": false,
+  "source": "./src/index.tsx",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "react-native": "./src/index.tsx",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "!**/__tests__",
+    "!**/__mocks__"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@legendapp/list": ">=3",
+    "date-fns": ">=3",
+    "react": ">=18",
+    "react-native": ">=0.74",
+    "react-native-gesture-handler": ">=2.16",
+    "react-native-reanimated": ">=4.0.0 <5",
+    "react-native-worklets": ">=0.5"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@babel/preset-env": "^7.25.0",
+    "@babel/preset-react": "^7.25.0",
+    "@babel/preset-typescript": "^7.25.0",
+    "@legendapp/list": "^3.0.6",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^19.2.17",
+    "babel-jest": "^29.7.0",
+    "date-fns": "4.4.0",
+    "jest": "^29.7.0",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "react-native-gesture-handler": "~2.31.1",
+    "react-native-reanimated": "4.3.1",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.5.0"
+  }
+}

package/src/components/Calendar.tsx

@@ -0,0 +1,147 @@
+import { useMemo } from 'react';
+import { useSharedValue } from 'react-native-reanimated';
+import { CalendarThemeProvider, mergeTheme, type PartialCalendarTheme } from '../theme';
+import type {
+  CalendarEvent,
+  CalendarMode,
+  EventKeyExtractor,
+  RenderEvent,
+  WeekStartsOn,
+} from '../types';
+import { DefaultEvent } from './DefaultEvent';
+import { MonthPager } from './MonthPager';
+import { DEFAULT_HOUR_HEIGHT, TimeGrid } from './TimeGrid';
+
+export type CalendarProps<T> = {
+  events: CalendarEvent<T>[];
+  mode: CalendarMode;
+  date: Date;
+  onChangeDate: (date: Date) => void;
+  onPressEvent: (event: CalendarEvent<T>) => void;
+  /** Tap a day cell (month mode) — e.g. drill into the day view. */
+  onPressDay?: (date: Date) => void;
+  /** Tap the "+N more" overflow label in a month cell. */
+  onPressMore?: (events: CalendarEvent<T>[], date: Date) => void;
+  /** Tap empty space on the week/day grid; receives the date+time pressed. */
+  onPressCell?: (date: Date) => void;
+  /** Max events shown per month cell before they collapse into "+N more". */
+  maxVisibleEventCount?: number;
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn;
+  /** Replace the built-in event box. Return a `flex: 1` element. */
+  renderEvent?: RenderEvent<T>;
+  /** Stable key per event. Defaults to start-time + index. */
+  keyExtractor?: EventKeyExtractor<T>;
+  /** Partial theme merged over the defaults. */
+  theme?: PartialCalendarTheme;
+  /** Externally-owned per-hour row height (week/day). Created internally if omitted. */
+  cellHeight?: ReturnType<typeof useSharedValue<number>>;
+  /** Initial per-hour row height in px (week/day). Default 64. */
+  hourHeight?: number;
+  minHourHeight?: number;
+  maxHourHeight?: number;
+  hourColumnWidth?: number;
+  /** First hour shown on the week/day grid (0–23). Default 0. */
+  minHour?: number;
+  /** Last hour shown on the week/day grid, exclusive (1–24). Default 24. */
+  maxHour?: number;
+  /** Show hour labels in 12-hour AM/PM form. Default false (24h). */
+  ampm?: boolean;
+  /** Initial vertical scroll, in minutes from midnight (week/day). */
+  scrollOffsetMinutes?: number;
+  /** Show the current-time line on the week/day grid. Default true. */
+  showNowIndicator?: boolean;
+  /** BCP-47 locale for weekday labels. Defaults to the device locale. */
+  locale?: string;
+  /**
+   * Allow a fling to carry across several pages before snapping. Default false:
+   * one day/week/month per swipe.
+   */
+  freeSwipe?: boolean;
+  /** Custom header above the week/day grid. Receives the visible days. */
+  renderTimeGridHeader?: (days: Date[]) => React.ReactNode;
+};
+
+// Derive a key purely from event data so identity is stable across reorders and
+// list mutations. Supply your own `keyExtractor` returning a real id when events
+// can share an identical start/end/title.
+const defaultKeyExtractor: EventKeyExtractor<unknown> = (event) =>
+  `${event.start.toISOString()}|${event.end.toISOString()}|${event.title ?? ''}`;
+
+export function Calendar<T>({
+  events,
+  mode,
+  date,
+  onChangeDate,
+  onPressEvent,
+  onPressDay,
+  onPressMore,
+  onPressCell,
+  maxVisibleEventCount = 2,
+  weekStartsOn = 0,
+  renderEvent = DefaultEvent,
+  keyExtractor = defaultKeyExtractor as EventKeyExtractor<T>,
+  theme,
+  cellHeight: cellHeightProp,
+  hourHeight = DEFAULT_HOUR_HEIGHT,
+  minHourHeight,
+  maxHourHeight,
+  hourColumnWidth,
+  minHour,
+  maxHour,
+  ampm,
+  scrollOffsetMinutes,
+  showNowIndicator,
+  locale,
+  freeSwipe,
+  renderTimeGridHeader,
+}: CalendarProps<T>) {
+  const mergedTheme = useMemo(() => mergeTheme(theme), [theme]);
+  const internalCellHeight = useSharedValue(hourHeight);
+  const cellHeight = cellHeightProp ?? internalCellHeight;
+
+  return (
+    <CalendarThemeProvider value={mergedTheme}>
+      {mode === 'month' ? (
+        <MonthPager
+          date={date}
+          events={events}
+          maxVisibleEventCount={maxVisibleEventCount}
+          weekStartsOn={weekStartsOn}
+          renderEvent={renderEvent}
+          keyExtractor={keyExtractor}
+          onPressDay={onPressDay}
+          onPressEvent={onPressEvent}
+          onPressMore={onPressMore}
+          onChangeDate={onChangeDate}
+          freeSwipe={freeSwipe}
+        />
+      ) : (
+        <TimeGrid
+          mode={mode}
+          date={date}
+          events={events}
+          cellHeight={cellHeight}
+          hourHeight={hourHeight}
+          weekStartsOn={weekStartsOn}
+          renderEvent={renderEvent}
+          keyExtractor={keyExtractor}
+          scrollOffsetMinutes={scrollOffsetMinutes}
+          hourColumnWidth={hourColumnWidth}
+          minHour={minHour}
+          maxHour={maxHour}
+          ampm={ampm}
+          minHourHeight={minHourHeight}
+          maxHourHeight={maxHourHeight}
+          showNowIndicator={showNowIndicator}
+          locale={locale}
+          freeSwipe={freeSwipe}
+          onPressEvent={onPressEvent}
+          onPressCell={onPressCell}
+          onChangeDate={onChangeDate}
+          renderHeader={renderTimeGridHeader}
+        />
+      )}
+    </CalendarThemeProvider>
+  );
+}

package/src/components/DefaultEvent.tsx

@@ -0,0 +1,57 @@
+import { format } from 'date-fns';
+import { StyleSheet, Text, TouchableOpacity } from 'react-native';
+import { useCalendarTheme } from '../theme';
+import type { RenderEventArgs } from '../types';
+
+/**
+ * The built-in event renderer: a filled, rounded box showing the event title
+ * and (on the day/week grid) its time range. Pass your own `renderEvent` to
+ * `<Calendar>` to replace it entirely.
+ */
+export function DefaultEvent<T>({ event, mode, onPress }: RenderEventArgs<T>) {
+  const theme = useCalendarTheme();
+  const showTime = mode !== 'month';
+
+  return (
+    <TouchableOpacity
+      style={[styles.box, { backgroundColor: theme.colors.eventBackground }]}
+      onPress={onPress}
+      activeOpacity={0.7}
+      accessibilityRole="button"
+      accessibilityLabel={event.title}
+    >
+      {event.title ? (
+        <Text
+          style={[theme.text.eventTitle, { color: theme.colors.eventText }]}
+          numberOfLines={mode === 'day' ? undefined : 1}
+          ellipsizeMode="tail"
+          allowFontScaling={false}
+        >
+          {event.title}
+        </Text>
+      ) : null}
+      {showTime ? (
+        <Text
+          style={[styles.time, { color: theme.colors.eventText }]}
+          numberOfLines={1}
+          allowFontScaling={false}
+        >
+          {`${format(event.start, 'HH:mm')} - ${format(event.end, 'HH:mm')}`}
+        </Text>
+      ) : null}
+    </TouchableOpacity>
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    flex: 1,
+    borderRadius: 6,
+    paddingVertical: 2,
+    paddingHorizontal: 4,
+    overflow: 'hidden',
+  },
+  time: {
+    fontSize: 11,
+  },
+});

package/src/components/MonthPager.tsx

@@ -0,0 +1,165 @@
+import {
+  LegendList,
+  type LegendListRef,
+  type LegendListRenderItemProps,
+  type OnViewableItemsChangedInfo,
+} from '@legendapp/list/react-native';
+import { addMonths, differenceInCalendarMonths, startOfMonth } from 'date-fns';
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { StyleSheet, useWindowDimensions, View } from 'react-native';
+import type { CalendarEvent, EventKeyExtractor, RenderEvent, WeekStartsOn } from '../types';
+import { MonthView } from './MonthView';
+
+// Months rendered either side of the current page. LegendList virtualises, so
+// only a few mount at once; a wide window (5 years each way) means the user
+// effectively never runs out of months to swipe. Items are keyed by month and
+// never recycled.
+const PAGE_WINDOW = 60;
+// A page must be ~fully on screen before it becomes the committed month, so
+// paging commits once per settle rather than mid-swipe.
+const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
+
+export type MonthPagerProps<T> = {
+  date: Date;
+  events: CalendarEvent<T>[];
+  maxVisibleEventCount: number;
+  weekStartsOn: WeekStartsOn;
+  renderEvent: RenderEvent<T>;
+  keyExtractor: EventKeyExtractor<T>;
+  onPressDay?: (date: Date) => void;
+  onPressEvent: (event: CalendarEvent<T>) => void;
+  onPressMore?: (events: CalendarEvent<T>[], date: Date) => void;
+  onChangeDate: (date: Date) => void;
+  freeSwipe?: boolean;
+};
+
+function MonthPagerInner<T>({
+  date,
+  events,
+  maxVisibleEventCount,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  onPressDay,
+  onPressEvent,
+  onPressMore,
+  onChangeDate,
+  freeSwipe = false,
+}: MonthPagerProps<T>) {
+  const { width, height } = useWindowDimensions();
+  const listRef = useRef<LegendListRef>(null);
+  // Horizontal list items need an explicit cross-axis height; seed it with the
+  // window height (so it renders immediately and in tests) and refine to the
+  // exact area on layout. Without this the grid collapses to 0px.
+  const [pageHeight, setPageHeight] = useState(height);
+
+  // A fixed window of months, anchored once and aligned to the month start. The
+  // array never shifts as the date changes, so paging never re-renders a page's
+  // content — LegendList virtualises and keys by month.
+  const [anchorDate] = useState(date);
+  const anchor = useMemo(() => startOfMonth(anchorDate), [anchorDate]);
+  const monthDates = useMemo(
+    () => Array.from({ length: PAGE_WINDOW * 2 + 1 }, (_, i) => addMonths(anchor, i - PAGE_WINDOW)),
+    [anchor],
+  );
+  const indexOfMonth = useCallback(
+    (target: Date) => differenceInCalendarMonths(startOfMonth(target), anchor) + PAGE_WINDOW,
+    [anchor],
+  );
+
+  // The committed month's page is the centred/active one. Derived (not stored)
+  // so it always reflects the date. `viewedIndexRef` tracks where the list
+  // actually sits, letting us tell swipe-driven month changes from external ones.
+  const activeIndex = indexOfMonth(date);
+  const viewedIndexRef = useRef(activeIndex);
+
+  const handleViewableItemsChanged = useCallback(
+    (info: OnViewableItemsChangedInfo<Date>) => {
+      const settled = info.viewableItems.find((token) => token.isViewable);
+      if (settled?.index == null || settled.index === viewedIndexRef.current) return;
+      viewedIndexRef.current = settled.index;
+      if (settled.item) onChangeDate(settled.item);
+    },
+    [onChangeDate],
+  );
+
+  // Realign the list when the month changes from outside a swipe (e.g. a "today"
+  // button). Swipe-driven changes already match.
+  useEffect(() => {
+    if (activeIndex === viewedIndexRef.current) return;
+    viewedIndexRef.current = activeIndex;
+    listRef.current?.scrollToIndex({ index: activeIndex, animated: false });
+  }, [activeIndex]);
+
+  const snapToIndices = useMemo(() => monthDates.map((_, index) => index), [monthDates]);
+  const keyExtractorList = useCallback((item: Date) => item.toISOString(), []);
+  const getFixedItemSize = useCallback(() => width, [width]);
+  const renderItem = useCallback(
+    ({ item }: LegendListRenderItemProps<Date>) => (
+      <View style={{ width, height: pageHeight }}>
+        <MonthView
+          date={item}
+          events={events}
+          maxVisibleEventCount={maxVisibleEventCount}
+          weekStartsOn={weekStartsOn}
+          renderEvent={renderEvent}
+          keyExtractor={keyExtractor}
+          onPressDay={onPressDay}
+          onPressEvent={onPressEvent}
+          onPressMore={onPressMore}
+        />
+      </View>
+    ),
+    [
+      width,
+      pageHeight,
+      events,
+      maxVisibleEventCount,
+      weekStartsOn,
+      renderEvent,
+      keyExtractor,
+      onPressDay,
+      onPressEvent,
+      onPressMore,
+    ],
+  );
+
+  return (
+    <View style={styles.pager} onLayout={(event) => setPageHeight(event.nativeEvent.layout.height)}>
+      <LegendList
+        // Remount when the measured page height changes so the list adopts the
+        // corrected item height. Without this the list can keep the oversized
+        // initial (window-height) seed and clip the last week row.
+        key={pageHeight}
+        ref={listRef}
+        style={styles.pagerList}
+        data={monthDates}
+        horizontal
+        recycleItems={false}
+        keyExtractor={keyExtractorList}
+        getFixedItemSize={getFixedItemSize}
+        // Default: native paging — each page is the viewport width, so a swipe
+        // hard-stops at the adjacent month and can't fling past it. With
+        // `freeSwipe`, momentum carries across months and snaps to a boundary.
+        pagingEnabled={!freeSwipe}
+        snapToIndices={freeSwipe ? snapToIndices : undefined}
+        initialScrollIndex={activeIndex}
+        showsHorizontalScrollIndicator={false}
+        viewabilityConfig={PAGE_VIEWABILITY}
+        onViewableItemsChanged={handleViewableItemsChanged}
+        renderItem={renderItem}
+      />
+    </View>
+  );
+}
+
+export const MonthPager = memo(MonthPagerInner) as typeof MonthPagerInner;
+
+const styles = StyleSheet.create({
+  pager: {
+    flex: 1,
+  },
+  pagerList: {
+    flex: 1,
+  },
+});

package/src/components/MonthView.tsx

@@ -0,0 +1,178 @@
+import {
+  eachDayOfInterval,
+  endOfMonth,
+  endOfWeek,
+  format,
+  isSameMonth,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+} from 'date-fns';
+import { memo, useMemo } from 'react';
+import { StyleSheet, Text, TouchableOpacity, View } from 'react-native';
+import { useCalendarTheme } from '../theme';
+import type { CalendarEvent, EventKeyExtractor, RenderEvent, WeekStartsOn } from '../types';
+import { getIsToday, isWeekend } from '../utils/dates';
+import { eventDayKeys } from '../utils/layout';
+
+const chunkIntoWeeks = (days: Date[]): Date[][] => {
+  const weeks: Date[][] = [];
+  for (let index = 0; index < days.length; index += 7) {
+    weeks.push(days.slice(index, index + 7));
+  }
+  return weeks;
+};
+
+export type MonthViewProps<T> = {
+  date: Date;
+  events: CalendarEvent<T>[];
+  maxVisibleEventCount: number;
+  weekStartsOn: WeekStartsOn;
+  renderEvent: RenderEvent<T>;
+  keyExtractor: EventKeyExtractor<T>;
+  onPressDay?: (date: Date) => void;
+  onPressEvent: (event: CalendarEvent<T>) => void;
+  onPressMore?: (events: CalendarEvent<T>[], date: Date) => void;
+};
+
+function MonthViewInner<T>({
+  date,
+  events,
+  maxVisibleEventCount,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  onPressDay,
+  onPressEvent,
+  onPressMore,
+}: MonthViewProps<T>) {
+  const theme = useCalendarTheme();
+  const RenderEventComponent = renderEvent;
+
+  const weeks = useMemo(() => {
+    const start = startOfWeek(startOfMonth(date), { weekStartsOn });
+    const end = endOfWeek(endOfMonth(date), { weekStartsOn });
+    return chunkIntoWeeks(eachDayOfInterval({ start, end }));
+  }, [date, weekStartsOn]);
+
+  // Group events by calendar day once per `events` change, rather than scanning
+  // the whole list inside every one of the (up to) 42 day cells on each render.
+  // Multi-day events are indexed under every day they span.
+  const eventsByDay = useMemo(() => {
+    const map = new Map<string, CalendarEvent<T>[]>();
+    for (const event of events) {
+      for (const key of eventDayKeys(event)) {
+        const existing = map.get(key);
+        if (existing) existing.push(event);
+        else map.set(key, [event]);
+      }
+    }
+    return map;
+  }, [events]);
+
+  const renderDay = (day: Date) => {
+    const dayEvents = eventsByDay.get(startOfDay(day).toISOString()) ?? [];
+    const isCurrentMonth = isSameMonth(day, date);
+    const isToday = getIsToday(day);
+    const hiddenCount = dayEvents.length - maxVisibleEventCount;
+
+    const dateColor = isToday
+      ? theme.colors.todayText
+      : isCurrentMonth
+        ? theme.colors.text
+        : theme.colors.textDisabled;
+
+    // Summarise the cell for screen readers: full date, today marker, and how
+    // many events it holds (the chips inside are grouped under this cell).
+    const eventCount = dayEvents.length;
+    const accessibilityLabel = `${format(day, 'EEEE, d LLLL yyyy')}${isToday ? ', today' : ''}, ${eventCount} ${eventCount === 1 ? 'event' : 'events'}`;
+
+    return (
+      <TouchableOpacity
+        key={day.toISOString()}
+        style={[
+          styles.dayCell,
+          { borderColor: theme.colors.gridLine },
+          isWeekend(day) && { backgroundColor: theme.colors.weekendBackground },
+        ]}
+        onPress={onPressDay ? () => onPressDay(day) : undefined}
+        disabled={!onPressDay}
+        accessibilityRole={onPressDay ? 'button' : undefined}
+        accessibilityLabel={accessibilityLabel}
+      >
+        <View
+          style={[
+            styles.dateBadge,
+            isToday && {
+              backgroundColor: theme.colors.todayBackground,
+              borderRadius: theme.todayBadgeRadius,
+            },
+          ]}
+        >
+          <Text style={[theme.text.dateCell, { color: dateColor }]} allowFontScaling={false}>
+            {format(day, 'd')}
+          </Text>
+        </View>
+        {dayEvents.slice(0, maxVisibleEventCount).map((event, index) => (
+          <View key={keyExtractor(event, index)} style={styles.monthEvent}>
+            <RenderEventComponent event={event} mode="month" onPress={() => onPressEvent(event)} />
+          </View>
+        ))}
+        {hiddenCount > 0 ? (
+          <Text
+            style={[theme.text.more, styles.moreLabel, { color: theme.colors.textMuted }]}
+            onPress={onPressMore ? () => onPressMore(dayEvents, day) : undefined}
+            accessibilityRole="button"
+            accessibilityLabel={`Show ${hiddenCount} more events`}
+            allowFontScaling={false}
+          >
+            {`${hiddenCount} More`}
+          </Text>
+        ) : null}
+      </TouchableOpacity>
+    );
+  };
+
+  return (
+    <View style={styles.container}>
+      {weeks.map((week) => (
+        <View style={styles.weekRow} key={week[0].toISOString()}>
+          {week.map((day) => renderDay(day))}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+export const MonthView = memo(MonthViewInner) as typeof MonthViewInner;
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  weekRow: {
+    flex: 1,
+    flexDirection: 'row',
+  },
+  dayCell: {
+    flex: 1,
+    alignItems: 'center',
+    paddingTop: 4,
+    gap: 2,
+    overflow: 'hidden',
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderRightWidth: StyleSheet.hairlineWidth,
+  },
+  dateBadge: {
+    justifyContent: 'center',
+    alignItems: 'center',
+    height: 24,
+    width: 24,
+  },
+  monthEvent: {
+    width: '92%',
+  },
+  moreLabel: {
+    marginTop: 2,
+  },
+});