react-native-bigger-calendar 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# react-native-bigger-calendar
+
+A generic, themeable **month / week / day** calendar for React Native.
+
+- 📆 Three views — month grid, week and day time-grids
+- 🤏 Pinch-to-zoom on the week/day grid (UI thread, no re-renders)
+- ♾️ Virtualized, snap-paging months/weeks/days via [`@legendapp/list`](https://legendapp.com/open-source/list/)
+- 🧩 Bring-your-own event type (`CalendarEvent<T>`) and a `renderEvent` escape hatch
+- 🎨 Fully themeable, with sensible defaults (no styling library required)
+
+## Install
+
+```sh
+npm install react-native-bigger-calendar
+```
+
+### Peer dependencies
+
+This library relies on the following being installed in your app:
+
+```sh
+npm install react-native-reanimated react-native-gesture-handler @legendapp/list
+```
+
+Make sure Reanimated and Gesture Handler are set up per their own docs (Babel
+plugin, `GestureHandlerRootView` at the root of your app).
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Calendar, type CalendarEvent } from 'react-native-bigger-calendar';
+
+type MyEvent = { id: string; color: string };
+
+const events: CalendarEvent<MyEvent>[] = [
+  {
+    id: '1',
+    color: '#1F6FEB',
+    title: 'Lecture',
+    start: new Date(2026, 5, 19, 10, 0),
+    end: new Date(2026, 5, 19, 11, 30),
+  },
+];
+
+export function MyCalendar() {
+  const [mode, setMode] = useState<'month' | 'week' | 'day'>('week');
+  const [date, setDate] = useState(new Date());
+
+  return (
+    <Calendar
+      mode={mode}
+      date={date}
+      events={events}
+      weekStartsOn={1}
+      onChangeDate={setDate}
+      onPressEvent={(event) => console.log(event.id)}
+      onPressDay={(day) => {
+        setDate(day);
+        setMode('day');
+      }}
+    />
+  );
+}
+```
+
+### Custom events
+
+The built-in renderer draws a simple titled box. Pass `renderEvent` — **a React
+component**, not a callback — to take full control. Because it's rendered as a
+component, it may use hooks. On the week/day grid you also receive `boxHeight`, a
+Reanimated shared value tracking the live pixel height of the box (driven by
+pinch-zoom), so you can reveal detail progressively without re-rendering:
+
+```tsx
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+import { Pressable, Text } from 'react-native';
+import type { RenderEventArgs } from 'react-native-bigger-calendar';
+
+// Define the component once (don't inline it, or it remounts every render).
+function MyEvent({ event, boxHeight, onPress }: RenderEventArgs<MyEvent>) {
+  const detailStyle = useAnimatedStyle(() => ({
+    display: (boxHeight?.value ?? Infinity) >= 84 ? 'flex' : 'none',
+  }));
+  return (
+    <Pressable style={{ flex: 1, backgroundColor: event.color }} onPress={onPress}>
+      <Text>{event.title}</Text>
+      <Animated.View style={detailStyle}>
+        <Text>{event.start.toLocaleTimeString()}</Text>
+      </Animated.View>
+    </Pressable>
+  );
+}
+
+<Calendar /* ... */ renderEvent={MyEvent} />;
+```
+
+### Theming
+
+```tsx
+<Calendar
+  // ...
+  theme={{
+    colors: { todayBackground: '#E5484D', nowIndicator: '#E5484D' },
+    text: { dayNumber: { fontSize: 24, fontWeight: '800' } },
+  }}
+/>
+```
+
+See `CalendarTheme` for the full set of tokens. Anything you omit falls back to
+`defaultTheme`.
+
+### Week/day grid options
+
+```tsx
+<Calendar
+  mode="week"
+  // ...
+  minHour={7}            // window the grid to 07:00–21:00
+  maxHour={21}
+  ampm                   // 12-hour hour labels ("7 AM")
+  onPressCell={(date) => createEventAt(date)} // tap empty space -> date+time
+/>
+```
+
+- `minHour` / `maxHour` clamp the visible hours (defaults `0` / `24`); events and
+  the now-line outside the window are hidden, and the initial scroll is adjusted.
+- `ampm` switches hour labels to 12-hour AM/PM (default 24h).
+- `onPressCell(date)` fires when empty grid space is tapped, with the date+time
+  under the touch — handy for "create event". (Event taps still go to `onPressEvent`.)
+- `freeSwipe` (default `false`) controls paging: by default one day/week/month
+  moves per swipe; set it to allow a fling to carry across several pages (still
+  snapping to a page boundary). Applies to all modes.
+
+## Components
+
+`<Calendar>` is the batteries-included entry point. The building blocks it wraps
+are also exported for advanced layouts:
+
+| Export | Description |
+| --- | --- |
+| `Calendar` | Top-level component; switches between month/week/day. |
+| `MonthView` | A single month grid. |
+| `MonthPager` | Horizontally-paged, virtualized months. |
+| `TimeGrid` | Paged, pinch-zoomable week/day time-grid. |
+| `DefaultEvent` | The built-in event renderer. |
+| `useCalendarTheme` | Read the active theme inside a custom renderer. |
+
+## Notes & limitations
+
+- **Multi-day events** are supported: pass one event and it appears on every day
+  it spans. On the week/day grid each day shows the clipped segment (so a
+  23:00→01:00 event renders 23:00–24:00, then 00:00–01:00), and `renderEvent`
+  receives `continuesBefore`/`continuesAfter` so you can draw continuation hints.
+  A dedicated all-day lane (and an explicit `allDay` flag) is not yet provided.
+- **`weekStartsOn` defaults to `0` (Sunday).** Pass `1` for Monday-first.
+- **Controlled `date`.** The calendar is controlled: echo `onChangeDate` back
+  into the `date` prop, or paging and the "today" realign won't track.
+- **External `cellHeight`.** If you own `cellHeight`, drive zoom through the
+  pinch gesture. Programmatic writes outside a pinch won't propagate to
+  off-screen pages until the next gesture settles.
+- **Stable props.** Pass stable `renderEvent`/`keyExtractor`/`on*` references
+  (module scope or `useCallback`) so the memoized inner views can skip renders.
+
+## Example app
+
+A runnable Expo demo lives in [`example/`](./example) — month/week/day modes, a
+multi-day event, drill-into-day on tap, and one-page paging.
+
+```sh
+cd example
+npm install
+npx expo run:ios   # or: npx expo run:android
+```
+
+It consumes the library straight from `../src` (via the example's
+`metro.config.js`), so edits to the package hot-reload into the demo. A custom
+dev build is required (Reanimated worklets aren't available in Expo Go).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,302 @@
+import { ComponentType } from "react";
+import { SharedValue, useSharedValue } from "react-native-reanimated";
+import { TextStyle } from "react-native";
+
+//#region src/theme.d.ts
+/**
+ * The full set of colours, text styles and metrics the calendar paints with.
+ * Supply a `Partial<CalendarTheme>` to `<Calendar theme={...} />`; missing keys
+ * fall back to {@link defaultTheme}, so you only override what you care about.
+ */
+interface CalendarTheme {
+  colors: {
+    /** Hour lines, day separators and month-cell borders. */gridLine: string; /** Background tint behind weekend columns/cells. */
+    weekendBackground: string; /** Fill of the "today" badge (and any today highlight). */
+    todayBackground: string; /** Text on top of the today badge. */
+    todayText: string; /** The current-time indicator line on the week/day grid. */
+    nowIndicator: string; /** Default text colour (day numbers, weekday labels). */
+    text: string; /** Muted text (hour labels, "+N more"). */
+    textMuted: string; /** Dimmed text for days outside the current month. */
+    textDisabled: string; /** Background of the built-in default event box. */
+    eventBackground: string; /** Text colour inside the built-in default event box. */
+    eventText: string;
+  };
+  text: {
+    /** Large day number in the week/day header. */dayNumber: TextStyle; /** Short weekday label ("Mon") in headers. */
+    weekday: TextStyle; /** Date number inside a month cell. */
+    dateCell: TextStyle; /** Hour labels down the left of the time grid. */
+    hourLabel: TextStyle; /** The "+N more" overflow label in month cells. */
+    more: TextStyle; /** Title inside the built-in default event box. */
+    eventTitle: TextStyle;
+  };
+  /** Corner radius of the today badge. Use a large value for a circle. */
+  todayBadgeRadius: number;
+}
+declare const defaultTheme: CalendarTheme;
+/** Deep-merge a partial theme over {@link defaultTheme}. */
+declare function mergeTheme(theme?: PartialCalendarTheme): CalendarTheme;
+type PartialCalendarTheme = {
+  colors?: Partial<CalendarTheme['colors']>;
+  text?: Partial<CalendarTheme['text']>;
+  todayBadgeRadius?: number;
+};
+declare const CalendarThemeProvider: import("react").Provider<CalendarTheme>;
+declare const useCalendarTheme: () => CalendarTheme;
+//#endregion
+//#region src/types.d.ts
+type CalendarMode = 'day' | 'week' | 'month';
+/**
+ * The minimal shape every calendar event must have. Layout (positioning,
+ * overlap resolution, paging) only ever reads `start`/`end`; `title` is used by
+ * the built-in default renderer. Anything else lives in your own type and is
+ * threaded through untouched via the `T` generic.
+ */
+interface ICalendarEvent {
+  start: Date;
+  end: Date;
+  title?: string;
+}
+/**
+ * An event carrying arbitrary extra fields `T` alongside the required shape.
+ * `ICalendarEvent` is authoritative: keys it reserves (`start`/`end`/`title`)
+ * cannot be re-typed by `T`.
+ */
+type CalendarEvent<T = unknown> = ICalendarEvent & Omit<T, keyof ICalendarEvent>;
+type RenderEventArgs<T = unknown> = {
+  event: CalendarEvent<T>;
+  mode: CalendarMode;
+  /**
+   * Live pixel height of the event box on the week/day grid, driven on the UI
+   * thread by pinch-to-zoom. Use it to reveal detail progressively as the box
+   * grows. `undefined` in month mode, where events render at a fixed size.
+   */
+  boxHeight?: SharedValue<number>;
+  /**
+   * On the week/day grid, true when this is a clipped segment of a multi-day
+   * event that started on an earlier day / continues onto a later day. Lets a
+   * renderer draw "continues" affordances. `undefined` in month mode.
+   */
+  continuesBefore?: boolean;
+  continuesAfter?: boolean;
+  onPress: () => void;
+};
+/**
+ * A component that renders a single event. It is rendered as a real component
+ * (not called as a function), so it may safely use hooks — including Reanimated
+ * hooks driven by `boxHeight`. Render an element that fills its container
+ * (`flex: 1`); the calendar positions and sizes the wrapping box for you.
+ */
+type RenderEvent<T = unknown> = ComponentType<RenderEventArgs<T>>;
+/** Build a stable key for an event. Defaults to start-time + index. */
+type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) => string;
+/** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
+type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+//#endregion
+//#region src/components/Calendar.d.ts
+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;
+};
+declare function Calendar<T>({
+  events,
+  mode,
+  date,
+  onChangeDate,
+  onPressEvent,
+  onPressDay,
+  onPressMore,
+  onPressCell,
+  maxVisibleEventCount,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  theme,
+  cellHeight: cellHeightProp,
+  hourHeight,
+  minHourHeight,
+  maxHourHeight,
+  hourColumnWidth,
+  minHour,
+  maxHour,
+  ampm,
+  scrollOffsetMinutes,
+  showNowIndicator,
+  locale,
+  freeSwipe,
+  renderTimeGridHeader
+}: CalendarProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/components/MonthView.d.ts
+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;
+};
+declare function MonthViewInner<T>({
+  date,
+  events,
+  maxVisibleEventCount,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  onPressDay,
+  onPressEvent,
+  onPressMore
+}: MonthViewProps<T>): import("react").JSX.Element;
+declare const MonthView: typeof MonthViewInner;
+//#endregion
+//#region src/components/MonthPager.d.ts
+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;
+};
+declare function MonthPagerInner<T>({
+  date,
+  events,
+  maxVisibleEventCount,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  onPressDay,
+  onPressEvent,
+  onPressMore,
+  onChangeDate,
+  freeSwipe
+}: MonthPagerProps<T>): import("react").JSX.Element;
+declare const MonthPager: typeof MonthPagerInner;
+//#endregion
+//#region src/components/TimeGrid.d.ts
+declare const DEFAULT_HOUR_HEIGHT = 64;
+type TimeGridProps<T> = {
+  mode: 'day' | 'week';
+  date: Date;
+  events: CalendarEvent<T>[];
+  cellHeight: SharedValue<number>; /** Initial per-hour row height in px; seeds scroll/zoom without reading the shared value during render. */
+  hourHeight?: number;
+  weekStartsOn: WeekStartsOn;
+  renderEvent: RenderEvent<T>;
+  keyExtractor: EventKeyExtractor<T>;
+  scrollOffsetMinutes?: number;
+  hourColumnWidth?: number; /** First hour shown (0–23). Default 0. */
+  minHour?: number; /** Last hour shown, exclusive (1–24). Default 24. */
+  maxHour?: number; /** Show hour labels in 12-hour AM/PM form. Default false (24h). */
+  ampm?: boolean;
+  minHourHeight?: number;
+  maxHourHeight?: number;
+  showNowIndicator?: boolean;
+  locale?: string;
+  freeSwipe?: boolean;
+  onPressEvent: (event: CalendarEvent<T>) => void;
+  onPressCell?: (date: Date) => void;
+  onChangeDate: (date: Date) => void; /** Optional header above the grid (e.g. weekday labels). Rendered full-width. */
+  renderHeader?: (days: Date[]) => React.ReactNode;
+};
+declare function TimeGridInner<T>({
+  mode,
+  date,
+  events,
+  cellHeight,
+  hourHeight,
+  weekStartsOn,
+  renderEvent,
+  keyExtractor,
+  scrollOffsetMinutes,
+  hourColumnWidth,
+  minHour,
+  maxHour,
+  ampm,
+  minHourHeight,
+  maxHourHeight,
+  showNowIndicator,
+  locale,
+  freeSwipe,
+  onPressEvent,
+  onPressCell,
+  onChangeDate,
+  renderHeader
+}: TimeGridProps<T>): import("react").JSX.Element;
+declare const TimeGrid: typeof TimeGridInner;
+//#endregion
+//#region src/components/DefaultEvent.d.ts
+/**
+ * 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.
+ */
+declare function DefaultEvent<T>({
+  event,
+  mode,
+  onPress
+}: RenderEventArgs<T>): import("react").JSX.Element;
+//#endregion
+//#region src/utils/dates.d.ts
+/** The seven dates of the week containing `date`, starting on `weekStartsOn`. */
+declare const getWeekDays: (date: Date, weekStartsOn: WeekStartsOn) => Date[];
+declare const isWeekend: (date: Date) => boolean;
+declare const getIsToday: (date: Date) => boolean;
+declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
+/** Minutes elapsed since midnight (0–1439). */
+declare const minutesIntoDay: (date: Date) => number;
+//#endregion
+//#region src/utils/layout.d.ts
+type PositionedEvent<T> = {
+  event: CalendarEvent<T>; /** Hours from midnight to the event's segment start on this day (fractional). */
+  startHours: number; /** Segment duration in hours on this day (clamped to a small minimum). */
+  durationHours: number; /** Zero-based column index within its overlap cluster. */
+  column: number; /** Total columns in this event's overlap cluster. */
+  columns: number; /** True when the segment is clipped because the event continues before/after this day. */
+  continuesBefore: boolean;
+  continuesAfter: boolean;
+};
+/**
+ * Lay out a single day's events: events that overlap in time are split into
+ * side-by-side columns. Multi-day events are clipped to the portion that falls
+ * on `day` (e.g. a 23:00→01:00 event renders 23:00–24:00 on the start day and
+ * 00:00–01:00 on the next). Pure — safe to call per render, never per frame.
+ */
+declare function layoutDayEvents<T>(events: CalendarEvent<T>[], day: Date): PositionedEvent<T>[];
+//#endregion
+export { Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type CalendarTheme, CalendarThemeProvider, DEFAULT_HOUR_HEIGHT, DefaultEvent, type EventKeyExtractor, type ICalendarEvent, MonthPager, type MonthPagerProps, MonthView, type MonthViewProps, type PartialCalendarTheme, type PositionedEvent, type RenderEvent, type RenderEventArgs, TimeGrid, type TimeGridProps, type WeekStartsOn, defaultTheme, getIsToday, getWeekDays, isSameCalendarDay, isWeekend, layoutDayEvents, mergeTheme, minutesIntoDay, useCalendarTheme };