@super-calendar/native 2.0.0 → 2.1.2

package/src/components/DefaultMonthEvent.tsx

@@ -1,3 +1,4 @@
+import type { ReactElement } from "react";
 import { StyleSheet, Text, TouchableOpacity, View } from "react-native";
 import { useCalendarTheme } from "../theme";
 import type { RenderEventArgs } from "../types";
@@ -26,7 +27,7 @@ export function DefaultMonthEvent<T>({
   cellStyle,
   onPress,
   onLongPress,
-}: RenderEventArgs<T>) {
+}: RenderEventArgs<T>): ReactElement {
   const theme = useCalendarTheme();
   const isAllDayEvent = isAllDay ?? false;
   const timeLabel = eventTimeLabel({

package/src/components/MonthList.tsx

@@ -12,7 +12,7 @@ import {
   type Locale,
   startOfMonth,
 } from "date-fns";
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { memo, type ReactElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   type LayoutChangeEvent,
   type NativeScrollEvent,
@@ -69,6 +69,7 @@ const noop = () => {};
 const defaultKeyExtractor: EventKeyExtractor<unknown> = (event) =>
   `${event.start.toISOString()}|${event.end.toISOString()}|${event.title ?? ""}`;
 
+/** Props for {@link MonthList}, the vertically scrolling list of months. */
 export type MonthListProps<T> = {
   /** The month scrolled to on mount. */
   date: Date;
@@ -155,7 +156,7 @@ function MonthListInner<T>({
   onSelectDrag,
   onChangeVisibleMonth,
   renderMonthHeader,
-}: MonthListProps<T>) {
+}: MonthListProps<T>): ReactElement {
   const theme = useCalendarTheme();
   const listRef = useRef<LegendListRef>(null);
 
@@ -553,6 +554,24 @@ function MonthBlock({
   );
 }
 
+/**
+ * A vertically scrolling, virtualized list of month grids. It doubles as the
+ * date picker: pass `selectedRange`/`selectedDates` and selection handlers to
+ * turn it into a single-date or range picker. Free of Reanimated, so the
+ * `/picker` entry point can ship it without the timetable views.
+ *
+ * @example
+ * ```tsx
+ * import { MonthList } from "react-native-super-calendar/picker";
+ *
+ * <MonthList
+ *   date={new Date()}
+ *   weekStartsOn={0}
+ *   selectedRange={range}
+ *   onPressDay={handlePressDay}
+ * />
+ * ```
+ */
 export const MonthList = memo(MonthListInner) as typeof MonthListInner;
 
 const styles = StyleSheet.create({

package/src/components/MonthPager.tsx

@@ -5,7 +5,7 @@ import {
   type OnViewableItemsChangedInfo,
 } from "@legendapp/list/react-native";
 import { addMonths, differenceInCalendarMonths, format, type Locale, startOfMonth } from "date-fns";
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { memo, type ReactElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   Platform,
   StyleSheet,
@@ -34,6 +34,7 @@ const PAGE_WINDOW = 60;
 // paging commits once per settle rather than mid-swipe.
 const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
 
+/** Props for {@link MonthPager}, the horizontally swipeable month carousel. */
 export type MonthPagerProps<T> = {
   date: Date;
   events: CalendarEvent<T>[];
@@ -90,7 +91,7 @@ function MonthPagerInner<T>({
   activeDate,
   renderHeaderForMonthView,
   renderCustomDateForMonth,
-}: MonthPagerProps<T>) {
+}: MonthPagerProps<T>): ReactElement {
   const theme = useCalendarTheme();
   const { width, height } = useWindowDimensions();
   const listRef = useRef<LegendListRef>(null);
@@ -318,6 +319,24 @@ function MonthPagerInner<T>({
   );
 }
 
+/**
+ * A horizontally swipeable month carousel. Swipe left/right to page between
+ * months; the committed month is reported through `onChangeDate`. It is the
+ * Reanimated-driven month view that `Calendar` uses in month mode.
+ *
+ * @example
+ * ```tsx
+ * import { MonthPager } from "react-native-super-calendar";
+ *
+ * <MonthPager
+ *   date={date}
+ *   events={events}
+ *   weekStartsOn={0}
+ *   onChangeDate={setDate}
+ *   onPressEvent={(e) => console.log(e.title)}
+ * />
+ * ```
+ */
 export const MonthPager = memo(MonthPagerInner) as typeof MonthPagerInner;
 
 type MonthWeekdayHeaderProps = {

package/src/components/MonthView.tsx

@@ -1,5 +1,5 @@
 import { format, type Locale, isSameMonth, startOfDay } from "date-fns";
-import { memo, useMemo, useState } from "react";
+import { memo, type ReactElement, useMemo, useState } from "react";
 import {
   type LayoutChangeEvent,
   Platform,
@@ -42,6 +42,7 @@ const FALLBACK_VISIBLE_COUNT = 3;
 const numericStyle = (value: number | string | undefined, fallback: number) =>
   typeof value === "number" ? value : fallback;
 
+/** Props for {@link MonthView}, the single-month grid. */
 export type MonthViewProps<T> = {
   date: Date;
   events: CalendarEvent<T>[];
@@ -139,7 +140,7 @@ function MonthViewInner<T>({
   renderCustomDateForMonth,
   onDayPointerDown,
   onDayPointerEnter,
-}: MonthViewProps<T>) {
+}: MonthViewProps<T>): ReactElement {
   const theme = useCalendarTheme();
   // Selection comes from context (so cached pages still repaint), but explicit
   // props win for direct/standalone use of MonthView.
@@ -454,6 +455,22 @@ function MonthViewInner<T>({
   );
 }
 
+/**
+ * A single month rendered as a 7-column grid of day cells, each showing its
+ * event chips with a "+N more" overflow. Render it on its own for a static
+ * month, or let `MonthList`/`Calendar` page through months for you.
+ *
+ * @example
+ * ```tsx
+ * import { MonthView, type CalendarEvent } from "react-native-super-calendar";
+ *
+ * <MonthView
+ *   date={new Date()}
+ *   events={events}
+ *   onPressDay={(day) => console.log(day)}
+ * />
+ * ```
+ */
 export const MonthView = memo(MonthViewInner) as typeof MonthViewInner;
 
 const styles = StyleSheet.create({

package/src/components/TimeGrid.tsx

@@ -15,7 +15,7 @@ import {
   startOfDay,
   startOfWeek,
 } from "date-fns";
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { memo, type ReactElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   type GestureResponderEvent,
   Platform,
@@ -90,6 +90,7 @@ const PAGE_WINDOW = 180;
 const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
 
 // Matches the dom renderer's default so both grids start at the same density.
+/** Default height in pixels of one hour row on the time grid. */
 export const DEFAULT_HOUR_HEIGHT = 48;
 const DEFAULT_MIN_HOUR_HEIGHT = 32;
 const DEFAULT_MAX_HOUR_HEIGHT = 160;
@@ -206,23 +207,30 @@ function AnimatedEventBox<T>({
   const moveOffsetX = useSharedValue(0);
   const resizeDelta = useSharedValue(0);
 
+  // Pull the geometry out as primitives so the worklets below close over plain
+  // numbers, not `positioned` itself. Referencing `positioned.*` inside a
+  // worklet captures the whole object, and `positioned.event` holds `Date`s,
+  // which react-native-worklets >=0.10 refuses to copy to the UI thread
+  // ("Cannot copy value of type `Date`").
+  const startHours = positioned.startHours;
+  const durationHours = positioned.durationHours;
+
   // Live pixel height of the box, driven on the UI thread by the shared
   // cellHeight (plus any in-progress resize). Handed to renderEvent so custom
   // renderers can reveal detail progressively as the grid zooms, without
   // re-rendering. Explicit deps so the worklet re-captures the event's geometry.
   const boxHeight = useDerivedValue(
-    () =>
-      Math.max(positioned.durationHours * cellHeight.value + resizeDelta.value, MIN_EVENT_HEIGHT),
-    [positioned.durationHours],
+    () => 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, minHour],
+    [startHours, durationHours, minHour],
   );
 
   // Clear the drag preview once the committed change re-renders this box at its
@@ -730,7 +738,11 @@ function TimetablePageInner<T>({
     [mode, date, weekStartsOn, numberOfDays, isRTL, weekEndsOn],
   );
 
-  const dayWidth = (width - hourColumnWidth) / days.length;
+  // Plain number for worklets to close over: reading `days.length` inside a
+  // gesture worklet would capture the whole `days` array (of `Date`s), which
+  // react-native-worklets >=0.10 refuses to copy to the UI thread.
+  const dayCount = days.length;
+  const dayWidth = (width - hourColumnWidth) / dayCount;
   const dayLeft = (dayIndex: number) => hourColumnWidth + dayIndex * dayWidth;
 
   const dayLayouts = useMemo(() => days.map((day) => layoutDayEvents(events, day)), [days, events]);
@@ -848,7 +860,7 @@ function TimetablePageInner<T>({
     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;
@@ -884,7 +896,7 @@ function TimetablePageInner<T>({
       : pan.activateAfterLongPress(DRAG_ACTIVATE_MS);
   }, [
     createEnabled,
-    days.length,
+    dayCount,
     dayWidth,
     hourColumnWidth,
     heightSource,
@@ -1150,6 +1162,7 @@ function TimetablePageInner<T>({
 
 const TimetablePage = memo(TimetablePageInner) as typeof TimetablePageInner;
 
+/** Props for {@link TimeGrid}, the day/week timetable view. */
 export type TimeGridProps<T> = {
   mode: TimeGridMode;
   /** Day columns to show in `custom` mode. Ignored by day/3days/week. Default 1. */
@@ -1284,7 +1297,7 @@ function TimeGridInner<T>({
   onPressDateHeader,
   onChangeDate,
   renderHeader,
-}: TimeGridProps<T>) {
+}: TimeGridProps<T>): ReactElement {
   // Guard against an inverted/out-of-range window so the grid never collapses.
   const clampedMinHour = Math.max(0, Math.min(minHour, HOURS_PER_DAY - 1));
   const clampedMaxHour = Math.max(clampedMinHour + 1, Math.min(maxHour, HOURS_PER_DAY));
@@ -1706,6 +1719,25 @@ function TimeGridInner<T>({
   );
 }
 
+/**
+ * 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)}
+ * />
+ * ```
+ */
 export const TimeGrid = memo(TimeGridInner) as typeof TimeGridInner;
 
 type DefaultHeaderProps = {

package/src/index.tsx

@@ -1,3 +1,25 @@
+/**
+ * The React Native renderer for super-calendar: gesture-driven, virtualized
+ * month, week, and day views, plus the agenda and date picker. Runs on native
+ * and on the web through react-native-web.
+ *
+ * Built on the headless core, Legend List, Gesture Handler, and Reanimated. For
+ * a picker-only bundle that does not pull in Reanimated, import from
+ * `@super-calendar/native/picker` instead.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar } from "@super-calendar/native";
+ *
+ * export function App() {
+ *   return <Calendar mode="month" />;
+ * }
+ * ```
+ *
+ * @see https://super-calendar.afonsojramos.me
+ *
+ * @module
+ */
 export { Calendar, type CalendarProps } from "./components/Calendar";
 export { Agenda, type AgendaProps } from "./components/Agenda";
 export { MonthView, type MonthViewProps } from "./components/MonthView";

package/src/picker.tsx

@@ -1,7 +1,20 @@
-// Date-picker entry point: the month grid, selection, and the headless grid,
-// with no dependency on the timetable views or Reanimated. Import from
-// "react-native-super-calendar/picker" for a picker-only bundle that doesn't
-// require react-native-reanimated. The main entry re-exports everything.
+/**
+ * The picker-only entry point for `@super-calendar/native`: the month grid,
+ * selection, and the headless grid, with no dependency on the timetable views or
+ * Reanimated.
+ *
+ * Import from `@super-calendar/native/picker` for a lighter bundle that does not
+ * require react-native-reanimated. The main entry re-exports everything here.
+ *
+ * @example
+ * ```tsx
+ * import { MonthView } from "@super-calendar/native/picker";
+ * ```
+ *
+ * @see https://super-calendar.afonsojramos.me
+ *
+ * @module
+ */
 export { MonthView, type MonthViewProps } from "./components/MonthView";
 export { MonthPager, type MonthPagerProps } from "./components/MonthPager";
 export { MonthList, type MonthListProps } from "./components/MonthList";

package/src/theme.ts

@@ -1,5 +1,5 @@
 import { type CalendarColors, darkColors, lightColors } from "@super-calendar/core";
-import { createContext, useContext } from "react";
+import { type Context, createContext, useContext } from "react";
 import type { TextStyle } from "react-native";
 
 /**
@@ -10,6 +10,7 @@ import type { TextStyle } from "react-native";
 export interface CalendarTheme {
   /** The shared colour palette (sourced from `@super-calendar/core`). */
   colors: CalendarColors;
+  /** Text styles for the calendar's labels and the built-in event box. */
   text: {
     /** Large day number in the week/day header. */
     dayNumber: TextStyle;
@@ -33,6 +34,7 @@ export interface CalendarTheme {
   rangeBandHeight: number;
 }
 
+/** The default light theme. Every key the calendar reads falls back to this. */
 export const defaultTheme: CalendarTheme = {
   colors: lightColors,
   text: {
@@ -72,6 +74,11 @@ export function mergeTheme(theme?: PartialCalendarTheme): CalendarTheme {
   };
 }
 
+/**
+ * A theme with every key optional. Pass this to `<Calendar theme={...} />` to
+ * override only the colours, text styles, or metrics you care about; the rest
+ * come from {@link defaultTheme}.
+ */
 export type PartialCalendarTheme = {
   colors?: Partial<CalendarTheme["colors"]>;
   text?: Partial<CalendarTheme["text"]>;
@@ -79,8 +86,14 @@ export type PartialCalendarTheme = {
   rangeBandHeight?: number;
 };
 
-const CalendarThemeContext = createContext<CalendarTheme>(defaultTheme);
+const CalendarThemeContext: Context<CalendarTheme> = createContext<CalendarTheme>(defaultTheme);
 
+/**
+ * Context provider that supplies the active {@link CalendarTheme} to descendants.
+ * `<Calendar>` wraps its subtree in this; use it directly only to theme custom
+ * components rendered outside a `<Calendar>`.
+ */
 export const CalendarThemeProvider = CalendarThemeContext.Provider;
 
-export const useCalendarTheme = () => useContext(CalendarThemeContext);
+/** Read the active {@link CalendarTheme} from context. Useful inside custom renderers. */
+export const useCalendarTheme = (): CalendarTheme => useContext(CalendarThemeContext);

package/src/types.ts

@@ -20,6 +20,11 @@ export type {
 // The React Native render contract lives here, not in core: it references
 // Reanimated (`SharedValue`) and React Native (`ViewStyle`) types, which must
 // not leak into the platform-free core.
+/**
+ * Props passed to a {@link RenderEvent} component for one event. Carries the
+ * event, the current mode, press handlers, and built-in renderer hints such as
+ * `boxHeight`, `continuesBefore`/`continuesAfter`, and `isAllDay`.
+ */
 export type RenderEventArgs<T = unknown> = {
   event: CalendarEvent<T>;
   mode: CalendarMode;