@super-calendar/native 2.0.0 → 2.1.2

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, _ as TimeGridMode, a as MonthPagerProps, b as CalendarThemeProvider, c as BusinessHours, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, m as RecurrenceRule, n as MonthList, o as MonthView, p as RecurrenceFrequency, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-CpRoOloh.mjs";
+import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, _ as TimeGridMode, a as MonthPagerProps, b as CalendarThemeProvider, c as BusinessHours, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, m as RecurrenceRule, n as MonthList, o as MonthView, p as RecurrenceFrequency, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-D2s0x2Bn.mjs";
 import { Locale } from "date-fns";
-import { ComponentType } from "react";
+import { ComponentType, ReactElement } from "react";
 import { SharedValue, useSharedValue } from "react-native-reanimated";
 import { DateRange, DateSelectionConstraints, DaySelectionState, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, UseDateRangeOptions, UseMonthGridOptions, buildMonthGrid, buildMonthWeeks, daySelectionState, eventsInTimeZone, expandRecurringEvents, getIsToday, getViewDays, getWeekDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, layoutDayEvents, minutesIntoDay, nextDateRange, toZonedTime, useDateRange, useMonthGrid } from "@super-calendar/core";
 import { StyleProp, ViewStyle } from "react-native";
 
 //#region src/components/TimeGrid.d.ts
+/** Default height in pixels of one hour row on the time grid. */
 declare const DEFAULT_HOUR_HEIGHT = 48;
 /**
  * Called when an event is dragged (moved or resized) to new start/end times.
@@ -22,6 +23,7 @@ type EventDragHandler<T> = (event: CalendarEvent<T>, start: Date, end: Date) =>
 type EventDragStartHandler<T> = (event: CalendarEvent<T>) => void;
 /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
 type HourRenderer = (hour: number, ampm: boolean) => React.ReactNode;
+/** Props for {@link TimeGrid}, the day/week timetable view. */
 type TimeGridProps<T> = {
   mode: TimeGridMode; /** Day columns to show in `custom` mode. Ignored by day/3days/week. Default 1. */
   numberOfDays?: number;
@@ -132,10 +134,30 @@ declare function TimeGridInner<T>({
   onPressDateHeader,
   onChangeDate,
   renderHeader
-}: TimeGridProps<T>): import("react").JSX.Element;
+}: TimeGridProps<T>): ReactElement;
+/**
+ * The timetable view used in day, 3days, week, and custom modes: an
+ * hour-by-hour grid with positioned event boxes, an all-day lane, pinch-to-zoom
+ * density, and optional drag-to-move/resize/create. Pages horizontally between
+ * date ranges, reporting the committed range through `onChangeDate`.
+ *
+ * @example
+ * ```tsx
+ * import { TimeGrid } from "react-native-super-calendar";
+ *
+ * <TimeGrid
+ *   mode="week"
+ *   date={date}
+ *   events={events}
+ *   onChangeDate={setDate}
+ *   onPressEvent={(e) => console.log(e.title)}
+ * />
+ * ```
+ */
 declare const TimeGrid: typeof TimeGridInner;
 //#endregion
 //#region src/components/Calendar.d.ts
+/** Props for the {@link Calendar} component. */
 type CalendarProps<T> = {
   events: CalendarEvent<T>[];
   mode: CalendarMode;
@@ -263,6 +285,32 @@ type CalendarProps<T> = {
   renderCustomDateForMonth?: (date: Date) => React.ReactNode; /** Drawn between rows of the `schedule` (agenda) list. */
   itemSeparatorComponent?: React.ComponentType<unknown> | null;
 };
+/**
+ * The top-level calendar. Switches between month, week, day, 3days, custom, and
+ * schedule modes, and is gesture-driven and virtualized. It is a controlled
+ * component: pass `date` and `mode` and update them from `onChangeDate`.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar, type CalendarEvent } from "react-native-super-calendar";
+ *
+ * function MyCalendar() {
+ *   const [date, setDate] = useState(new Date());
+ *   const events: CalendarEvent[] = [
+ *     { title: "Standup", start: new Date(), end: new Date() },
+ *   ];
+ *   return (
+ *     <Calendar
+ *       mode="week"
+ *       date={date}
+ *       events={events}
+ *       onChangeDate={setDate}
+ *       onPressEvent={(e) => console.log(e.title)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 declare function Calendar<T>({
   events,
   mode,
@@ -329,9 +377,10 @@ declare function Calendar<T>({
   renderHeaderForMonthView,
   renderCustomDateForMonth,
   itemSeparatorComponent
-}: CalendarProps<T>): import("react").JSX.Element;
+}: CalendarProps<T>): ReactElement;
 //#endregion
 //#region src/components/Agenda.d.ts
+/** Props for {@link Agenda}, the day-grouped list view of events. */
 type AgendaProps<T> = {
   events: CalendarEvent<T>[];
   locale?: Locale;
@@ -358,7 +407,7 @@ declare function Agenda<T>({
   onPressDay,
   activeDate,
   itemSeparatorComponent
-}: AgendaProps<T>): import("react").JSX.Element;
+}: AgendaProps<T>): ReactElement;
 //#endregion
 //#region src/components/DefaultEvent.d.ts
 /**
@@ -381,6 +430,6 @@ declare function DefaultEvent<T>({
   cellStyle,
   onPress,
   onLongPress
-}: RenderEventArgs<T>): import("react").JSX.Element;
+}: RenderEventArgs<T>): ReactElement;
 //#endregion
 export { Agenda, type AgendaProps, type BusinessHours, Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type CalendarTheme, CalendarThemeProvider, DEFAULT_HOUR_HEIGHT, type DateRange, type DateSelectionConstraints, type DaySelectionState, DefaultEvent, DefaultMonthEvent, type EventDragHandler, type EventDragStartHandler, type EventKeyExtractor, type HourRenderer, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthPager, type MonthPagerProps, MonthView, type MonthViewProps, type PartialCalendarTheme, type PositionedEvent, type RecurrenceFrequency, type RecurrenceRule, type RenderEvent, type RenderEventArgs, TimeGrid, type TimeGridMode, type TimeGridProps, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, buildMonthWeeks, darkTheme, daySelectionState, defaultTheme, eventsInTimeZone, expandRecurringEvents, getIsToday, getViewDays, getWeekDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, layoutDayEvents, mergeTheme, minutesIntoDay, nextDateRange, toZonedTime, useCalendarTheme, useDateRange, useMonthGrid };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, _ as TimeGridMode, a as MonthPagerProps, b as CalendarThemeProvider, c as BusinessHours, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, m as RecurrenceRule, n as MonthList, o as MonthView, p as RecurrenceFrequency, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-86XCNCge.js";
+import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, _ as TimeGridMode, a as MonthPagerProps, b as CalendarThemeProvider, c as BusinessHours, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, m as RecurrenceRule, n as MonthList, o as MonthView, p as RecurrenceFrequency, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-DaTEIcRs.js";
 import { Locale } from "date-fns";
+import { ComponentType, ReactElement } from "react";
 import { StyleProp, ViewStyle } from "react-native";
 import { SharedValue, useSharedValue } from "react-native-reanimated";
 import { DateRange, DateSelectionConstraints, DaySelectionState, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, UseDateRangeOptions, UseMonthGridOptions, buildMonthGrid, buildMonthWeeks, daySelectionState, eventsInTimeZone, expandRecurringEvents, getIsToday, getViewDays, getWeekDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, layoutDayEvents, minutesIntoDay, nextDateRange, toZonedTime, useDateRange, useMonthGrid } from "@super-calendar/core";
-import { ComponentType } from "react";
 
 //#region src/components/TimeGrid.d.ts
+/** Default height in pixels of one hour row on the time grid. */
 declare const DEFAULT_HOUR_HEIGHT = 48;
 /**
  * Called when an event is dragged (moved or resized) to new start/end times.
@@ -22,6 +23,7 @@ type EventDragHandler<T> = (event: CalendarEvent<T>, start: Date, end: Date) =>
 type EventDragStartHandler<T> = (event: CalendarEvent<T>) => void;
 /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
 type HourRenderer = (hour: number, ampm: boolean) => React.ReactNode;
+/** Props for {@link TimeGrid}, the day/week timetable view. */
 type TimeGridProps<T> = {
   mode: TimeGridMode; /** Day columns to show in `custom` mode. Ignored by day/3days/week. Default 1. */
   numberOfDays?: number;
@@ -132,10 +134,30 @@ declare function TimeGridInner<T>({
   onPressDateHeader,
   onChangeDate,
   renderHeader
-}: TimeGridProps<T>): import("react").JSX.Element;
+}: TimeGridProps<T>): ReactElement;
+/**
+ * The timetable view used in day, 3days, week, and custom modes: an
+ * hour-by-hour grid with positioned event boxes, an all-day lane, pinch-to-zoom
+ * density, and optional drag-to-move/resize/create. Pages horizontally between
+ * date ranges, reporting the committed range through `onChangeDate`.
+ *
+ * @example
+ * ```tsx
+ * import { TimeGrid } from "react-native-super-calendar";
+ *
+ * <TimeGrid
+ *   mode="week"
+ *   date={date}
+ *   events={events}
+ *   onChangeDate={setDate}
+ *   onPressEvent={(e) => console.log(e.title)}
+ * />
+ * ```
+ */
 declare const TimeGrid: typeof TimeGridInner;
 //#endregion
 //#region src/components/Calendar.d.ts
+/** Props for the {@link Calendar} component. */
 type CalendarProps<T> = {
   events: CalendarEvent<T>[];
   mode: CalendarMode;
@@ -263,6 +285,32 @@ type CalendarProps<T> = {
   renderCustomDateForMonth?: (date: Date) => React.ReactNode; /** Drawn between rows of the `schedule` (agenda) list. */
   itemSeparatorComponent?: React.ComponentType<unknown> | null;
 };
+/**
+ * The top-level calendar. Switches between month, week, day, 3days, custom, and
+ * schedule modes, and is gesture-driven and virtualized. It is a controlled
+ * component: pass `date` and `mode` and update them from `onChangeDate`.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar, type CalendarEvent } from "react-native-super-calendar";
+ *
+ * function MyCalendar() {
+ *   const [date, setDate] = useState(new Date());
+ *   const events: CalendarEvent[] = [
+ *     { title: "Standup", start: new Date(), end: new Date() },
+ *   ];
+ *   return (
+ *     <Calendar
+ *       mode="week"
+ *       date={date}
+ *       events={events}
+ *       onChangeDate={setDate}
+ *       onPressEvent={(e) => console.log(e.title)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 declare function Calendar<T>({
   events,
   mode,
@@ -329,9 +377,10 @@ declare function Calendar<T>({
   renderHeaderForMonthView,
   renderCustomDateForMonth,
   itemSeparatorComponent
-}: CalendarProps<T>): import("react").JSX.Element;
+}: CalendarProps<T>): ReactElement;
 //#endregion
 //#region src/components/Agenda.d.ts
+/** Props for {@link Agenda}, the day-grouped list view of events. */
 type AgendaProps<T> = {
   events: CalendarEvent<T>[];
   locale?: Locale;
@@ -358,7 +407,7 @@ declare function Agenda<T>({
   onPressDay,
   activeDate,
   itemSeparatorComponent
-}: AgendaProps<T>): import("react").JSX.Element;
+}: AgendaProps<T>): ReactElement;
 //#endregion
 //#region src/components/DefaultEvent.d.ts
 /**
@@ -381,6 +430,6 @@ declare function DefaultEvent<T>({
   cellStyle,
   onPress,
   onLongPress
-}: RenderEventArgs<T>): import("react").JSX.Element;
+}: RenderEventArgs<T>): ReactElement;
 //#endregion
 export { Agenda, type AgendaProps, type BusinessHours, Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type CalendarTheme, CalendarThemeProvider, DEFAULT_HOUR_HEIGHT, type DateRange, type DateSelectionConstraints, type DaySelectionState, DefaultEvent, DefaultMonthEvent, type EventDragHandler, type EventDragStartHandler, type EventKeyExtractor, type HourRenderer, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthPager, type MonthPagerProps, MonthView, type MonthViewProps, type PartialCalendarTheme, type PositionedEvent, type RecurrenceFrequency, type RecurrenceRule, type RenderEvent, type RenderEventArgs, TimeGrid, type TimeGridMode, type TimeGridProps, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, buildMonthWeeks, darkTheme, daySelectionState, defaultTheme, eventsInTimeZone, expandRecurringEvents, getIsToday, getViewDays, getWeekDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, layoutDayEvents, mergeTheme, minutesIntoDay, nextDateRange, toZonedTime, useCalendarTheme, useDateRange, useMonthGrid };

package/dist/index.js

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_MonthList = require("./MonthList-BCfN-UGz.js");
+const require_MonthList = require("./MonthList-oXiArmbu.js");
 let date_fns = require("date-fns");
 let react = require("react");
 let react_native_reanimated = require("react-native-reanimated");
@@ -368,6 +368,7 @@ const HOURS_PER_DAY = 24;
 const MINUTES_PER_DAY = MINUTES_PER_HOUR * HOURS_PER_DAY;
 const PAGE_WINDOW = 180;
 const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
+/** Default height in pixels of one hour row on the time grid. */
 const DEFAULT_HOUR_HEIGHT = 48;
 const DEFAULT_MIN_HOUR_HEIGHT = 32;
 const DEFAULT_MAX_HOUR_HEIGHT = 160;
@@ -399,14 +400,16 @@ function AnimatedEventBox({ positioned, cellHeight, minHour, left, width, dayWid
 	const moveOffset = (0, react_native_reanimated.useSharedValue)(0);
 	const moveOffsetX = (0, react_native_reanimated.useSharedValue)(0);
 	const resizeDelta = (0, react_native_reanimated.useSharedValue)(0);
-	const boxHeight = (0, react_native_reanimated.useDerivedValue)(() => Math.max(positioned.durationHours * cellHeight.value + resizeDelta.value, MIN_EVENT_HEIGHT), [positioned.durationHours]);
+	const startHours = positioned.startHours;
+	const durationHours = positioned.durationHours;
+	const boxHeight = (0, react_native_reanimated.useDerivedValue)(() => Math.max(durationHours * cellHeight.value + resizeDelta.value, MIN_EVENT_HEIGHT), [durationHours]);
 	const boxStyle = (0, react_native_reanimated.useAnimatedStyle)(() => ({
-		top: (positioned.startHours - minHour) * cellHeight.value + moveOffset.value,
+		top: (startHours - minHour) * cellHeight.value + moveOffset.value,
 		height: boxHeight.value,
 		transform: [{ translateX: moveOffsetX.value }]
 	}), [
-		positioned.startHours,
-		positioned.durationHours,
+		startHours,
+		durationHours,
 		minHour
 	]);
 	(0, react.useEffect)(() => {
@@ -663,7 +666,8 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 		isRTL,
 		weekEndsOn
 	]);
-	const dayWidth = (width - hourColumnWidth) / days.length;
+	const dayCount = days.length;
+	const dayWidth = (width - hourColumnWidth) / dayCount;
 	const dayLeft = (dayIndex) => hourColumnWidth + dayIndex * dayWidth;
 	const dayLayouts = (0, react.useMemo)(() => days.map((day) => (0, _super_calendar_core.layoutDayEvents)(events, day)), [days, events]);
 	const cellDateFromTouch = (event) => {
@@ -749,7 +753,7 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 	]);
 	const createGesture = (0, react.useMemo)(() => {
 		const pan = react_native_gesture_handler.Gesture.Pan().enabled(createEnabled).onStart((event) => {
-			const idx = days.length === 1 ? 0 : Math.floor(event.x / dayWidth);
+			const idx = dayCount === 1 ? 0 : Math.floor(event.x / dayWidth);
 			createDayIndex.value = idx;
 			createStartY.value = event.y;
 			createLeft.value = hourColumnWidth + idx * dayWidth;
@@ -775,7 +779,7 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 		return isWeb ? pan.activeOffsetY([-8, DRAG_ACTIVATE_PX]) : pan.activateAfterLongPress(DRAG_ACTIVATE_MS);
 	}, [
 		createEnabled,
-		days.length,
+		dayCount,
 		dayWidth,
 		hourColumnWidth,
 		heightSource,
@@ -1268,6 +1272,25 @@ function TimeGridInner({ mode, numberOfDays = 1, weekEndsOn, date, events, cellH
 		]
 	});
 }
+/**
+* The timetable view used in day, 3days, week, and custom modes: an
+* hour-by-hour grid with positioned event boxes, an all-day lane, pinch-to-zoom
+* density, and optional drag-to-move/resize/create. Pages horizontally between
+* date ranges, reporting the committed range through `onChangeDate`.
+*
+* @example
+* ```tsx
+* import { TimeGrid } from "react-native-super-calendar";
+*
+* <TimeGrid
+*   mode="week"
+*   date={date}
+*   events={events}
+*   onChangeDate={setDate}
+*   onPressEvent={(e) => console.log(e.title)}
+* />
+* ```
+*/
 const TimeGrid = (0, react.memo)(TimeGridInner);
 const DefaultHeader = ({ days, mode, width, hourColumnWidth, showWeekNumber, weekNumberPrefix = "W", locale, activeDate, onPressDateHeader }) => {
 	const theme = require_MonthList.useCalendarTheme();
@@ -1431,6 +1454,32 @@ function visibleRange(mode, date, weekStartsOn, numberOfDays, weekEndsOn) {
 	const days = (0, _super_calendar_core.getViewDays)(mode, date, weekStartsOn, numberOfDays, false, weekEndsOn);
 	return [(0, date_fns.startOfDay)(days[0]), (0, date_fns.endOfDay)(days[days.length - 1])];
 }
+/**
+* The top-level calendar. Switches between month, week, day, 3days, custom, and
+* schedule modes, and is gesture-driven and virtualized. It is a controlled
+* component: pass `date` and `mode` and update them from `onChangeDate`.
+*
+* @example
+* ```tsx
+* import { Calendar, type CalendarEvent } from "react-native-super-calendar";
+*
+* function MyCalendar() {
+*   const [date, setDate] = useState(new Date());
+*   const events: CalendarEvent[] = [
+*     { title: "Standup", start: new Date(), end: new Date() },
+*   ];
+*   return (
+*     <Calendar
+*       mode="week"
+*       date={date}
+*       events={events}
+*       onChangeDate={setDate}
+*       onPressEvent={(e) => console.log(e.title)}
+*     />
+*   );
+* }
+* ```
+*/
 function Calendar({ events, mode, date, onChangeDate, onChangeDateRange, onPressEvent, onLongPressEvent, onDragEvent, onDragStart, dragStepMinutes, showDragHandle, onPressDay, onLongPressDay, onPressMore, onPressCell, resetPageOnPressCell, onLongPressCell, onCreateEvent, onPressDateHeader, maxVisibleEventCount, sortedMonthView, moreLabel, showAdjacentMonths, disableMonthEventCellPress, weekStartsOn = 0, numberOfDays, weekEndsOn, renderEvent = DefaultEvent, eventCellStyle, calendarCellStyle, businessHours, keyExtractor = defaultKeyExtractor, theme, cellHeight: cellHeightProp, hourHeight = 48, minHourHeight, maxHourHeight, hourColumnWidth, hideHours, timeslots, showAllDayEventCell, showWeekNumber, weekNumberPrefix, hourComponent, showSixWeeks, swipeEnabled, showVerticalScrollIndicator, verticalScrollEnabled, headerComponent, minHour, maxHour, ampm, showTime, ellipsizeTitle, allDayLabel, scrollOffsetMinutes, showNowIndicator, locale, activeDate, isRTL, freeSwipe, renderTimeGridHeader, renderHeaderForMonthView, renderCustomDateForMonth, itemSeparatorComponent }) {
 	const mergedTheme = (0, react.useMemo)(() => require_MonthList.mergeTheme(theme), [theme]);
 	const internalCellHeight = (0, react_native_reanimated.useSharedValue)(hourHeight);

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as useWebPagerKeys, c as defaultTheme, i as MonthView, l as mergeTheme, n as DefaultMonthEvent, o as CalendarThemeProvider, r as MonthPager, s as darkTheme, t as MonthList, u as useCalendarTheme } from "./MonthList-CyrEJ_U6.mjs";
+import { a as useWebPagerKeys, c as defaultTheme, i as MonthView, l as mergeTheme, n as DefaultMonthEvent, o as CalendarThemeProvider, r as MonthPager, s as darkTheme, t as MonthList, u as useCalendarTheme } from "./MonthList-DXvjxiyu.mjs";
 import { addDays, differenceInCalendarDays, endOfDay, endOfMonth, endOfWeek, format, getHours, getISOWeek, getMinutes, isSameDay, startOfDay, startOfMonth, startOfWeek } from "date-fns";
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import Animated, { runOnJS, scrollTo, useAnimatedReaction, useAnimatedRef, useAnimatedScrollHandler, useAnimatedStyle, useDerivedValue, useSharedValue } from "react-native-reanimated";
@@ -344,6 +344,7 @@ const HOURS_PER_DAY = 24;
 const MINUTES_PER_DAY = MINUTES_PER_HOUR * HOURS_PER_DAY;
 const PAGE_WINDOW = 180;
 const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
+/** Default height in pixels of one hour row on the time grid. */
 const DEFAULT_HOUR_HEIGHT = 48;
 const DEFAULT_MIN_HOUR_HEIGHT = 32;
 const DEFAULT_MAX_HOUR_HEIGHT = 160;
@@ -375,14 +376,16 @@ function AnimatedEventBox({ positioned, cellHeight, minHour, left, width, dayWid
 	const moveOffset = useSharedValue(0);
 	const moveOffsetX = useSharedValue(0);
 	const resizeDelta = useSharedValue(0);
-	const boxHeight = useDerivedValue(() => Math.max(positioned.durationHours * cellHeight.value + resizeDelta.value, MIN_EVENT_HEIGHT), [positioned.durationHours]);
+	const startHours = positioned.startHours;
+	const durationHours = positioned.durationHours;
+	const boxHeight = useDerivedValue(() => Math.max(durationHours * cellHeight.value + resizeDelta.value, MIN_EVENT_HEIGHT), [durationHours]);
 	const boxStyle = useAnimatedStyle(() => ({
-		top: (positioned.startHours - minHour) * cellHeight.value + moveOffset.value,
+		top: (startHours - minHour) * cellHeight.value + moveOffset.value,
 		height: boxHeight.value,
 		transform: [{ translateX: moveOffsetX.value }]
 	}), [
-		positioned.startHours,
-		positioned.durationHours,
+		startHours,
+		durationHours,
 		minHour
 	]);
 	useEffect(() => {
@@ -639,7 +642,8 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 		isRTL,
 		weekEndsOn
 	]);
-	const dayWidth = (width - hourColumnWidth) / days.length;
+	const dayCount = days.length;
+	const dayWidth = (width - hourColumnWidth) / dayCount;
 	const dayLeft = (dayIndex) => hourColumnWidth + dayIndex * dayWidth;
 	const dayLayouts = useMemo(() => days.map((day) => layoutDayEvents$1(events, day)), [days, events]);
 	const cellDateFromTouch = (event) => {
@@ -725,7 +729,7 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 	]);
 	const createGesture = useMemo(() => {
 		const pan = Gesture.Pan().enabled(createEnabled).onStart((event) => {
-			const idx = days.length === 1 ? 0 : Math.floor(event.x / dayWidth);
+			const idx = dayCount === 1 ? 0 : Math.floor(event.x / dayWidth);
 			createDayIndex.value = idx;
 			createStartY.value = event.y;
 			createLeft.value = hourColumnWidth + idx * dayWidth;
@@ -751,7 +755,7 @@ function TimetablePageInner({ mode, numberOfDays, date, events, cellHeight, hour
 		return isWeb ? pan.activeOffsetY([-8, DRAG_ACTIVATE_PX]) : pan.activateAfterLongPress(DRAG_ACTIVATE_MS);
 	}, [
 		createEnabled,
-		days.length,
+		dayCount,
 		dayWidth,
 		hourColumnWidth,
 		heightSource,
@@ -1244,6 +1248,25 @@ function TimeGridInner({ mode, numberOfDays = 1, weekEndsOn, date, events, cellH
 		]
 	});
 }
+/**
+* The timetable view used in day, 3days, week, and custom modes: an
+* hour-by-hour grid with positioned event boxes, an all-day lane, pinch-to-zoom
+* density, and optional drag-to-move/resize/create. Pages horizontally between
+* date ranges, reporting the committed range through `onChangeDate`.
+*
+* @example
+* ```tsx
+* import { TimeGrid } from "react-native-super-calendar";
+*
+* <TimeGrid
+*   mode="week"
+*   date={date}
+*   events={events}
+*   onChangeDate={setDate}
+*   onPressEvent={(e) => console.log(e.title)}
+* />
+* ```
+*/
 const TimeGrid = memo(TimeGridInner);
 const DefaultHeader = ({ days, mode, width, hourColumnWidth, showWeekNumber, weekNumberPrefix = "W", locale, activeDate, onPressDateHeader }) => {
 	const theme = useCalendarTheme();
@@ -1407,6 +1430,32 @@ function visibleRange(mode, date, weekStartsOn, numberOfDays, weekEndsOn) {
 	const days = getViewDays$1(mode, date, weekStartsOn, numberOfDays, false, weekEndsOn);
 	return [startOfDay(days[0]), endOfDay(days[days.length - 1])];
 }
+/**
+* The top-level calendar. Switches between month, week, day, 3days, custom, and
+* schedule modes, and is gesture-driven and virtualized. It is a controlled
+* component: pass `date` and `mode` and update them from `onChangeDate`.
+*
+* @example
+* ```tsx
+* import { Calendar, type CalendarEvent } from "react-native-super-calendar";
+*
+* function MyCalendar() {
+*   const [date, setDate] = useState(new Date());
+*   const events: CalendarEvent[] = [
+*     { title: "Standup", start: new Date(), end: new Date() },
+*   ];
+*   return (
+*     <Calendar
+*       mode="week"
+*       date={date}
+*       events={events}
+*       onChangeDate={setDate}
+*       onPressEvent={(e) => console.log(e.title)}
+*     />
+*   );
+* }
+* ```
+*/
 function Calendar({ events, mode, date, onChangeDate, onChangeDateRange, onPressEvent, onLongPressEvent, onDragEvent, onDragStart, dragStepMinutes, showDragHandle, onPressDay, onLongPressDay, onPressMore, onPressCell, resetPageOnPressCell, onLongPressCell, onCreateEvent, onPressDateHeader, maxVisibleEventCount, sortedMonthView, moreLabel, showAdjacentMonths, disableMonthEventCellPress, weekStartsOn = 0, numberOfDays, weekEndsOn, renderEvent = DefaultEvent, eventCellStyle, calendarCellStyle, businessHours, keyExtractor = defaultKeyExtractor, theme, cellHeight: cellHeightProp, hourHeight = 48, minHourHeight, maxHourHeight, hourColumnWidth, hideHours, timeslots, showAllDayEventCell, showWeekNumber, weekNumberPrefix, hourComponent, showSixWeeks, swipeEnabled, showVerticalScrollIndicator, verticalScrollEnabled, headerComponent, minHour, maxHour, ampm, showTime, ellipsizeTitle, allDayLabel, scrollOffsetMinutes, showNowIndicator, locale, activeDate, isRTL, freeSwipe, renderTimeGridHeader, renderHeaderForMonthView, renderCustomDateForMonth, itemSeparatorComponent }) {
 	const mergedTheme = useMemo(() => mergeTheme(theme), [theme]);
 	const internalCellHeight = useSharedValue(hourHeight);

package/dist/picker.d.mts

@@ -1,3 +1,3 @@
-import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, a as MonthPagerProps, b as CalendarThemeProvider, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, n as MonthList, o as MonthView, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-CpRoOloh.mjs";
+import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, a as MonthPagerProps, b as CalendarThemeProvider, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, n as MonthList, o as MonthView, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-D2s0x2Bn.mjs";
 import { DateRange, DateSelectionConstraints, DaySelectionState, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, UseDateRangeOptions, UseMonthGridOptions, buildMonthGrid, buildMonthWeeks, daySelectionState, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, minutesIntoDay, nextDateRange, useDateRange, useMonthGrid } from "@super-calendar/core";
 export { type CalendarEvent, type CalendarMode, type CalendarTheme, CalendarThemeProvider, type DateRange, type DateSelectionConstraints, type DaySelectionState, DefaultMonthEvent, type EventKeyExtractor, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthPager, type MonthPagerProps, MonthView, type MonthViewProps, type PartialCalendarTheme, type RenderEvent, type RenderEventArgs, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, buildMonthWeeks, darkTheme, daySelectionState, defaultTheme, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, mergeTheme, minutesIntoDay, nextDateRange, useCalendarTheme, useDateRange, useMonthGrid };

package/dist/picker.d.ts

@@ -1,3 +1,3 @@
-import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, a as MonthPagerProps, b as CalendarThemeProvider, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, n as MonthList, o as MonthView, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-86XCNCge.js";
+import { C as defaultTheme, S as darkTheme, T as useCalendarTheme, a as MonthPagerProps, b as CalendarThemeProvider, d as EventKeyExtractor, f as ICalendarEvent, g as RenderEventArgs, h as RenderEvent, i as MonthPager, l as CalendarEvent, n as MonthList, o as MonthView, r as MonthListProps, s as MonthViewProps, t as DefaultMonthEvent, u as CalendarMode, v as WeekStartsOn, w as mergeTheme, x as PartialCalendarTheme, y as CalendarTheme } from "./DefaultMonthEvent-DaTEIcRs.js";
 import { DateRange, DateSelectionConstraints, DaySelectionState, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, UseDateRangeOptions, UseMonthGridOptions, buildMonthGrid, buildMonthWeeks, daySelectionState, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, minutesIntoDay, nextDateRange, useDateRange, useMonthGrid } from "@super-calendar/core";
 export { type CalendarEvent, type CalendarMode, type CalendarTheme, CalendarThemeProvider, type DateRange, type DateSelectionConstraints, type DaySelectionState, DefaultMonthEvent, type EventKeyExtractor, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthPager, type MonthPagerProps, MonthView, type MonthViewProps, type PartialCalendarTheme, type RenderEvent, type RenderEventArgs, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, buildMonthWeeks, darkTheme, daySelectionState, defaultTheme, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, mergeTheme, minutesIntoDay, nextDateRange, useCalendarTheme, useDateRange, useMonthGrid };

package/dist/picker.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_MonthList = require("./MonthList-BCfN-UGz.js");
+const require_MonthList = require("./MonthList-oXiArmbu.js");
 let _super_calendar_core = require("@super-calendar/core");
 exports.CalendarThemeProvider = require_MonthList.CalendarThemeProvider;
 exports.DefaultMonthEvent = require_MonthList.DefaultMonthEvent;

package/dist/picker.mjs

@@ -1,3 +1,3 @@
-import { c as defaultTheme, i as MonthView, l as mergeTheme, n as DefaultMonthEvent, o as CalendarThemeProvider, r as MonthPager, s as darkTheme, t as MonthList, u as useCalendarTheme } from "./MonthList-CyrEJ_U6.mjs";
+import { c as defaultTheme, i as MonthView, l as mergeTheme, n as DefaultMonthEvent, o as CalendarThemeProvider, r as MonthPager, s as darkTheme, t as MonthList, u as useCalendarTheme } from "./MonthList-DXvjxiyu.mjs";
 import { buildMonthGrid, buildMonthWeeks, daySelectionState, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, minutesIntoDay, nextDateRange, useDateRange, useMonthGrid } from "@super-calendar/core";
 export { CalendarThemeProvider, DefaultMonthEvent, MonthList, MonthPager, MonthView, buildMonthGrid, buildMonthWeeks, darkTheme, daySelectionState, defaultTheme, getIsToday, getWeekDays, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isWeekend, isWithinDateRange, mergeTheme, minutesIntoDay, nextDateRange, useCalendarTheme, useDateRange, useMonthGrid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/native",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "description": "Gesture-driven, virtualized month / week / day calendar and date picker for React Native (and web via react-native-web).",
   "keywords": [
     "agenda",
@@ -14,14 +14,14 @@
     "timetable",
     "week-view"
   ],
-  "homepage": "https://github.com/afonsojramos/react-native-super-calendar#readme",
+  "homepage": "https://super-calendar.afonsojramos.me",
   "bugs": {
-    "url": "https://github.com/afonsojramos/react-native-super-calendar/issues"
+    "url": "https://github.com/afonsojramos/super-calendar/issues"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/afonsojramos/react-native-super-calendar.git",
+    "url": "git+https://github.com/afonsojramos/super-calendar.git",
     "directory": "packages/native"
   },
   "source": "./src/index.tsx",
@@ -64,7 +64,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-calendar/core": "2.0.0"
+    "@super-calendar/core": "2.1.2"
   },
   "peerDependencies": {
     "@legendapp/list": ">=3",

package/src/components/Agenda.tsx

@@ -1,12 +1,13 @@
 import { LegendList, type LegendListRenderItemProps } from "@legendapp/list/react-native";
 import { format, isSameDay, type Locale, startOfDay } from "date-fns";
-import { type ComponentType, useCallback, useMemo } from "react";
+import { type ComponentType, type ReactElement, useCallback, useMemo } from "react";
 import { StyleSheet, Text, View } from "react-native";
 import { useCalendarTheme } from "../theme";
 import type { CalendarEvent, EventKeyExtractor, RenderEvent } from "../types";
 import { getIsToday } from "@super-calendar/core";
 import { isAllDayEvent } from "@super-calendar/core";
 
+/** Props for {@link Agenda}, the day-grouped list view of events. */
 export type AgendaProps<T> = {
   events: CalendarEvent<T>[];
   locale?: Locale;
@@ -40,7 +41,7 @@ export function Agenda<T>({
   onPressDay,
   activeDate,
   itemSeparatorComponent,
-}: AgendaProps<T>) {
+}: AgendaProps<T>): ReactElement {
   const theme = useCalendarTheme();
   const RenderEventComponent = renderEvent;
 

package/src/components/Calendar.tsx

@@ -7,7 +7,7 @@ import {
   startOfMonth,
   startOfWeek,
 } from "date-fns";
-import { useCallback, useMemo } from "react";
+import { type ReactElement, useCallback, useMemo } from "react";
 import type { StyleProp, ViewStyle } from "react-native";
 import { useSharedValue } from "react-native-reanimated";
 import { CalendarThemeProvider, mergeTheme, type PartialCalendarTheme } from "../theme";
@@ -32,6 +32,7 @@ import {
   TimeGrid,
 } from "./TimeGrid";
 
+/** Props for the {@link Calendar} component. */
 export type CalendarProps<T> = {
   events: CalendarEvent<T>[];
   mode: CalendarMode;
@@ -231,6 +232,32 @@ function visibleRange(
   return [startOfDay(days[0]), endOfDay(days[days.length - 1])];
 }
 
+/**
+ * The top-level calendar. Switches between month, week, day, 3days, custom, and
+ * schedule modes, and is gesture-driven and virtualized. It is a controlled
+ * component: pass `date` and `mode` and update them from `onChangeDate`.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar, type CalendarEvent } from "react-native-super-calendar";
+ *
+ * function MyCalendar() {
+ *   const [date, setDate] = useState(new Date());
+ *   const events: CalendarEvent[] = [
+ *     { title: "Standup", start: new Date(), end: new Date() },
+ *   ];
+ *   return (
+ *     <Calendar
+ *       mode="week"
+ *       date={date}
+ *       events={events}
+ *       onChangeDate={setDate}
+ *       onPressEvent={(e) => console.log(e.title)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function Calendar<T>({
   events,
   mode,
@@ -297,7 +324,7 @@ export function Calendar<T>({
   renderHeaderForMonthView,
   renderCustomDateForMonth,
   itemSeparatorComponent,
-}: CalendarProps<T>) {
+}: CalendarProps<T>): ReactElement {
   const mergedTheme = useMemo(() => mergeTheme(theme), [theme]);
   const internalCellHeight = useSharedValue(hourHeight);
   const cellHeight = cellHeightProp ?? internalCellHeight;

package/src/components/DefaultEvent.tsx

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react";
 import { StyleSheet, Text, TouchableOpacity } from "react-native";
 import Animated, { useAnimatedStyle, useDerivedValue } from "react-native-reanimated";
 import { useCalendarTheme } from "../theme";
@@ -40,7 +41,7 @@ export function DefaultEvent<T>({
   cellStyle,
   onPress,
   onLongPress,
-}: RenderEventArgs<T>) {
+}: RenderEventArgs<T>): ReactElement {
   const theme = useCalendarTheme();
   const isAllDayEvent = isAllDay ?? false;
   const timeLabel = eventTimeLabel({