@lazerlen/legend-calendar 1.4.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazerlen/legend-calendar",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "private": false,
   "description": "A better calendar for React Native.",
   "repository": {
@@ -28,7 +28,7 @@
     "@babel/preset-typescript": "^7.28.5",
     "@lazerlen/eslint-config": "*",
     "@lazerlen/tsconfig": "*",
-    "@legendapp/list": "^3.0.0-beta.39",
+    "@legendapp/list": "^3.0.0",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/bun": "^1.3.2",
     "@types/react": "~19.1.10",
@@ -42,8 +42,8 @@
     "typescript": "~5.9.2"
   },
   "peerDependencies": {
-    "@legendapp/list": ">=3.0.0-beta.39",
+    "@legendapp/list": ">=3.0.0",
     "react": "*",
     "react-native": "*"
   }
-}
+}

package/src/components/Calendar.tsx

@@ -1,4 +1,4 @@
-import { memo, useEffect } from "react";
+import { useEffect } from "react";
 import type { ColorSchemeName, PressableProps } from "react-native";
 
 import type {
@@ -13,6 +13,7 @@ import type { CalendarItemEmptyProps } from "@/components/CalendarItemEmpty";
 import { CalendarItemEmpty } from "@/components/CalendarItemEmpty";
 import type { CalendarItemWeekNameProps } from "@/components/CalendarItemWeekName";
 import { CalendarItemWeekName } from "@/components/CalendarItemWeekName";
+import { useCalendarListConfig } from "@/components/CalendarListConfigContext";
 import type { CalendarRowMonthProps } from "@/components/CalendarRowMonth";
 import { CalendarRowMonth } from "@/components/CalendarRowMonth";
 import type { CalendarRowWeekProps } from "@/components/CalendarRowWeek";
@@ -105,7 +106,7 @@ export interface CalendarProps extends UseCalendarParams {
   CalendarPressableComponent?: PressableLike;
 }
 
-const BaseCalendar = memo(function BaseCalendar(props: CalendarProps) {
+const BaseCalendar = function BaseCalendar(props: CalendarProps) {
   const {
     calendarInstanceId,
     calendarRowVerticalSpacing = 8,
@@ -185,16 +186,23 @@ const BaseCalendar = memo(function BaseCalendar(props: CalendarProps) {
       ))}
     </VStack>
   );
-});
+};
+
+export const Calendar = function Calendar(props: CalendarProps) {
+  const listConfig = useCalendarListConfig();
+
+  // When inside CalendarList, merge context values as defaults.
+  // Direct props always take precedence over context.
+  const resolvedProps = listConfig ? { ...listConfig, ...props } : props;
 
-export const Calendar = memo(function Calendar(props: CalendarProps) {
   const {
     calendarInstanceId,
     calendarActiveDateRanges,
     calendarMonthId,
     calendarColorScheme,
     ...otherProps
-  } = props;
+  } = resolvedProps;
+
   useEffect(() => {
     // When used inside CalendarList, calendarActiveDateRanges is undefined
     // because CalendarList writes directly to the store. Skip to avoid
@@ -204,16 +212,6 @@ export const Calendar = memo(function Calendar(props: CalendarProps) {
       calendarInstanceId ?? "legend-calendar-default-instance",
       calendarActiveDateRanges
     );
-    /**
-     * While `calendarMonthId` is not used by the effect, we still need it in
-     * the dependency array since [LegendList uses recycling
-     * internally](https://legendapp.com/open-source/list/).
-     *
-     * This means `Calendar` can re-render with different props instead of
-     * getting re-mounted. Without it, we would see staled/invalid data, as
-     * reported by
-     * [#11](https://github.com/MarceloPrado/flash-calendar/issues/11).
-     */
   }, [calendarActiveDateRanges, calendarInstanceId, calendarMonthId]);
 
   return (
@@ -225,4 +223,4 @@ export const Calendar = memo(function Calendar(props: CalendarProps) {
       />
     </CalendarThemeProvider>
   );
-});
+};

package/src/components/CalendarItemDay.tsx

@@ -1,5 +1,4 @@
 import type { ReactNode } from "react";
-import { memo } from "react";
 import type { TextStyle, ViewStyle } from "react-native";
 import { Pressable, StyleSheet, View } from "react-native";
 
@@ -161,7 +160,7 @@ export interface CalendarItemDayProps {
  * `CalendarItemDayWithContainer`, since it also includes the spacing between
  * each day.
  */
-export const CalendarItemDay = memo(function CalendarItemDay({
+export const CalendarItemDay = function CalendarItemDay({
   onPress,
   children,
   theme,
@@ -295,7 +294,7 @@ export const CalendarItemDay = memo(function CalendarItemDay({
       }}
     </CalendarPressableComponent>
   );
-});
+};
 
 interface CalendarItemDayContainerTheme {
   /** An empty view that acts as a spacer between each day. The spacing is
@@ -331,7 +330,7 @@ export interface CalendarItemDayContainerProps {
   metadata?: CalendarDayMetadata;
 }
 
-export const CalendarItemDayContainer = memo(function CalendarItemDayContainer({
+export const CalendarItemDayContainer = function CalendarItemDayContainer({
   children,
   isStartOfWeek,
   shouldShowActiveDayFiller,
@@ -389,7 +388,7 @@ export const CalendarItemDayContainer = memo(function CalendarItemDayContainer({
       {children}
     </View>
   );
-});
+};
 
 export interface CalendarItemDayWithContainerProps
   extends Omit<CalendarItemDayProps, "height">,
@@ -409,7 +408,7 @@ export interface CalendarItemDayWithContainerProps
   calendarInstanceId?: string;
 }
 
-export const CalendarItemDayWithContainer = memo(
+export const CalendarItemDayWithContainer =
   function CalendarItemDayWithContainer({
     children,
     metadata: baseMetadata,
@@ -447,5 +446,4 @@ export const CalendarItemDayWithContainer = memo(
         </CalendarItemDay>
       </CalendarItemDayContainer>
     );
-  }
-);
+  };

package/src/components/CalendarItemEmpty.tsx

@@ -1,4 +1,3 @@
-import { memo } from "react";
 import type { ViewStyle } from "react-native";
 import { StyleSheet, View } from "react-native";
 
@@ -18,11 +17,11 @@ export interface CalendarItemEmptyProps {
   };
 }
 
-export const CalendarItemEmpty = memo(function CalendarItemEmpty(
+export const CalendarItemEmpty = function CalendarItemEmpty(
   props: CalendarItemEmptyProps
 ) {
   const { height, theme } = props;
   const containerStyles = [{ ...styles.container, height }, theme?.container];
 
   return <View style={containerStyles} />;
-});
+};

package/src/components/CalendarItemWeekName.tsx

@@ -1,5 +1,4 @@
 import type { ReactNode } from "react";
-import { memo } from "react";
 import type { TextStyle, ViewStyle } from "react-native";
 import { StyleSheet, View } from "react-native";
 
@@ -35,7 +34,7 @@ export interface CalendarItemWeekNameProps {
   textProps?: Omit<CalendarTextProps, "children">;
 }
 
-export const CalendarItemWeekName = memo(function CalendarItemWeekName({
+export const CalendarItemWeekName = function CalendarItemWeekName({
   children,
   height,
   theme,
@@ -57,4 +56,4 @@ export const CalendarItemWeekName = memo(function CalendarItemWeekName({
       </Text>
     </View>
   );
-});
+};

package/src/components/CalendarList.tsx

@@ -3,11 +3,18 @@ import {
   type LegendListProps,
   type LegendListRef,
 } from "@legendapp/list/react-native";
-import { useEffect, useImperativeHandle, useRef } from "react";
+import {
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { StyleSheet, View } from "react-native";
 
 import type { CalendarProps } from "@/components/Calendar";
 import { Calendar } from "@/components/Calendar";
+import { CalendarListConfigProvider } from "@/components/CalendarListConfigContext";
 import {
   fromDateId,
   getWeekOfMonth,
@@ -27,11 +34,78 @@ const LegendList = LegendListBase as <T>(
  * `Calendar` props to simplify building custom `Calendar` components.
  */
 export type CalendarMonthEnhanced = CalendarMonth & {
+  /**
+   * The calendar configuration props for this item. Available when using a
+   * custom `renderItem` for backwards compatibility.
+   *
+   * @deprecated Prefer reading calendar config from context via
+   * `useCalendarListConfig()` instead of spreading `item.calendarProps`.
+   * This avoids creating a new data array each render and lets LegendList
+   * skip unnecessary item re-renders.
+   *
+   * **Before (slower):**
+   * ```tsx
+   * renderItem={({ item }) => (
+   *   <MyCalendar calendarMonthId={item.id} {...item.calendarProps} />
+   * )}
+   * ```
+   *
+   * **After (faster):**
+   * ```tsx
+   * // Inside your custom calendar component:
+   * const listConfig = useCalendarListConfig();
+   * // Merge: { ...listConfig, ...props }
+   * ```
+   */
   calendarProps: Omit<CalendarProps, "calendarMonthId">;
 };
 
 const keyExtractor = (month: CalendarMonth) => month.id;
 
+function buildCalendarConfig(
+  calendarColorScheme: CalendarMonthEnhanced["calendarProps"]["calendarColorScheme"],
+  calendarDayHeight: number,
+  calendarDisabledDateIds: CalendarMonthEnhanced["calendarProps"]["calendarDisabledDateIds"],
+  calendarFirstDayOfWeek: CalendarMonthEnhanced["calendarProps"]["calendarFirstDayOfWeek"],
+  calendarFormatLocale: CalendarMonthEnhanced["calendarProps"]["calendarFormatLocale"],
+  calendarInstanceId: CalendarMonthEnhanced["calendarProps"]["calendarInstanceId"],
+  calendarMaxDateId: CalendarMonthEnhanced["calendarProps"]["calendarMaxDateId"],
+  calendarMinDateId: CalendarMonthEnhanced["calendarProps"]["calendarMinDateId"],
+  calendarMonthHeaderHeight: number,
+  calendarRowHorizontalSpacing: CalendarMonthEnhanced["calendarProps"]["calendarRowHorizontalSpacing"],
+  calendarRowVerticalSpacing: number,
+  calendarWeekHeaderHeightProp: CalendarMonthEnhanced["calendarProps"]["calendarWeekHeaderHeight"],
+  getCalendarDayFormat: CalendarMonthEnhanced["calendarProps"]["getCalendarDayFormat"],
+  getCalendarMonthFormat: CalendarMonthEnhanced["calendarProps"]["getCalendarMonthFormat"],
+  getCalendarWeekDayFormat: CalendarMonthEnhanced["calendarProps"]["getCalendarWeekDayFormat"],
+  onCalendarDayPress: CalendarMonthEnhanced["calendarProps"]["onCalendarDayPress"],
+  theme: CalendarMonthEnhanced["calendarProps"]["theme"],
+  CalendarPressableComponent: CalendarMonthEnhanced["calendarProps"]["CalendarPressableComponent"]
+): CalendarMonthEnhanced["calendarProps"] {
+  const calendarWeekHeaderHeight =
+    calendarWeekHeaderHeightProp ?? calendarDayHeight;
+  return {
+    calendarColorScheme,
+    calendarDayHeight,
+    calendarDisabledDateIds,
+    calendarFirstDayOfWeek,
+    calendarFormatLocale,
+    calendarInstanceId,
+    calendarMaxDateId,
+    calendarMinDateId,
+    calendarMonthHeaderHeight,
+    calendarRowHorizontalSpacing,
+    calendarRowVerticalSpacing,
+    calendarWeekHeaderHeight,
+    getCalendarDayFormat,
+    getCalendarMonthFormat,
+    getCalendarWeekDayFormat,
+    onCalendarDayPress,
+    theme,
+    CalendarPressableComponent,
+  };
+}
+
 export interface CalendarListProps
   extends Omit<CalendarProps, "calendarMonthId">,
     Omit<
@@ -100,6 +174,12 @@ export interface CalendarListProps
    * - calendarAdditionalHeight
    * - calendarRowVerticalSpacing
    * - calendarSpacing
+   *
+   * **Performance tip**: Using `item.calendarProps` is provided for
+   * backwards compatibility but creates a new data array each render.
+   * For better performance, have your custom component call
+   * `useCalendarListConfig()` to read the shared config from context
+   * and only use `item.id` as `calendarMonthId`.
    */
   renderItem?: LegendListProps<CalendarMonthEnhanced>["renderItem"];
 }
@@ -125,39 +205,37 @@ export interface CalendarListRef {
   scrollToOffset: (offset: number, animated: boolean) => void;
 }
 
-export function CalendarList({
-  ref,
-  ...props
-}: CalendarListProps & { ref?: React.Ref<CalendarListRef> }) {
+type CalendarListInnerProps = CalendarListProps & {
+  ref?: React.Ref<CalendarListRef>;
+} & {
+  flatListProps: Omit<
+    LegendListProps<CalendarMonthEnhanced>,
+    "renderItem" | "data" | "children"
+  >;
+};
+
+export function CalendarList(
+  props: CalendarListProps & { ref?: React.Ref<CalendarListRef> }
+) {
   const {
-    // List-related props
+    ref,
     calendarInitialMonthId,
-    calendarInitialScrollToActiveRange = true,
-    calendarPastScrollRangeInMonths = 12,
-    calendarFutureScrollRangeInMonths = 12,
-    calendarFirstDayOfWeek = "sunday",
+    calendarInitialScrollToActiveRange,
+    calendarPastScrollRangeInMonths,
+    calendarFutureScrollRangeInMonths,
+    calendarFirstDayOfWeek,
     calendarFormatLocale,
-
-    // Spacings
-    calendarSpacing = 20,
+    calendarSpacing,
     calendarRowHorizontalSpacing,
-    calendarRowVerticalSpacing = 8,
-
-    // Heights
-    calendarMonthHeaderHeight = 20,
-    calendarDayHeight = 32,
-    calendarWeekHeaderHeight = calendarDayHeight,
-    calendarAdditionalHeight = 0,
-
-    // Other props
+    calendarRowVerticalSpacing,
+    calendarMonthHeaderHeight,
+    calendarDayHeight,
+    calendarWeekHeaderHeight,
+    calendarAdditionalHeight,
     calendarColorScheme,
     theme,
     onEndReached,
     onStartReached,
-    ...otherProps
-  } = props;
-
-  const {
     calendarActiveDateRanges,
     calendarDisabledDateIds,
     calendarInstanceId,
@@ -168,9 +246,82 @@ export function CalendarList({
     getCalendarWeekDayFormat,
     onCalendarDayPress,
     CalendarPressableComponent,
+    renderItem,
     ...flatListProps
-  } = otherProps;
+  } = props;
+  return (
+    <CalendarListInner
+      CalendarPressableComponent={CalendarPressableComponent}
+      calendarActiveDateRanges={calendarActiveDateRanges}
+      calendarAdditionalHeight={calendarAdditionalHeight}
+      calendarColorScheme={calendarColorScheme}
+      calendarDayHeight={calendarDayHeight}
+      calendarDisabledDateIds={calendarDisabledDateIds}
+      calendarFirstDayOfWeek={calendarFirstDayOfWeek}
+      calendarFormatLocale={calendarFormatLocale}
+      calendarFutureScrollRangeInMonths={calendarFutureScrollRangeInMonths}
+      calendarInitialMonthId={calendarInitialMonthId}
+      calendarInitialScrollToActiveRange={calendarInitialScrollToActiveRange}
+      calendarInstanceId={calendarInstanceId}
+      calendarMaxDateId={calendarMaxDateId}
+      calendarMinDateId={calendarMinDateId}
+      calendarMonthHeaderHeight={calendarMonthHeaderHeight}
+      calendarPastScrollRangeInMonths={calendarPastScrollRangeInMonths}
+      calendarRowHorizontalSpacing={calendarRowHorizontalSpacing}
+      calendarRowVerticalSpacing={calendarRowVerticalSpacing}
+      calendarSpacing={calendarSpacing}
+      calendarWeekHeaderHeight={calendarWeekHeaderHeight}
+      flatListProps={flatListProps}
+      getCalendarDayFormat={getCalendarDayFormat}
+      getCalendarMonthFormat={getCalendarMonthFormat}
+      getCalendarWeekDayFormat={getCalendarWeekDayFormat}
+      onCalendarDayPress={onCalendarDayPress}
+      onEndReached={onEndReached}
+      onStartReached={onStartReached}
+      ref={ref}
+      renderItem={renderItem}
+      theme={theme}
+    />
+  );
+}
 
+function CalendarListInner({
+  ref,
+  // List-related props
+  calendarInitialMonthId,
+  calendarInitialScrollToActiveRange = true,
+  calendarPastScrollRangeInMonths = 12,
+  calendarFutureScrollRangeInMonths = 12,
+  calendarFirstDayOfWeek = "sunday",
+  calendarFormatLocale,
+  // Spacings
+  calendarSpacing = 20,
+  calendarRowHorizontalSpacing,
+  calendarRowVerticalSpacing = 8,
+  // Heights
+  calendarMonthHeaderHeight = 20,
+  calendarDayHeight = 32,
+  calendarWeekHeaderHeight: calendarWeekHeaderHeightProp,
+  calendarAdditionalHeight = 0,
+  // Other props
+  calendarColorScheme,
+  theme,
+  onEndReached,
+  onStartReached,
+  // Calendar config props
+  calendarActiveDateRanges,
+  calendarDisabledDateIds,
+  calendarInstanceId,
+  calendarMaxDateId,
+  calendarMinDateId,
+  getCalendarDayFormat,
+  getCalendarMonthFormat,
+  getCalendarWeekDayFormat,
+  onCalendarDayPress,
+  CalendarPressableComponent,
+  renderItem: customRenderItem,
+  flatListProps,
+}: CalendarListInnerProps) {
   // Write directly to store to bypass the entire render cascade.
   // This means calendarProps stays stable and monthListWithCalendarProps
   // doesn't recompute on every date tap.
@@ -181,27 +332,57 @@ export function CalendarList({
     );
   }, [calendarActiveDateRanges, calendarInstanceId]);
 
-  const calendarProps: CalendarMonthEnhanced["calendarProps"] = {
-    // calendarActiveDateRanges intentionally omitted - written to store above
-    calendarColorScheme,
-    calendarDayHeight,
-    calendarDisabledDateIds,
-    calendarFirstDayOfWeek,
-    calendarFormatLocale,
-    calendarInstanceId,
-    calendarMaxDateId,
-    calendarMinDateId,
-    calendarMonthHeaderHeight,
-    calendarRowHorizontalSpacing,
-    calendarRowVerticalSpacing,
-    calendarWeekHeaderHeight,
-    getCalendarDayFormat,
-    getCalendarMonthFormat,
-    getCalendarWeekDayFormat,
-    onCalendarDayPress,
-    theme,
-    CalendarPressableComponent,
-  };
+  // calendarActiveDateRanges intentionally omitted - written to store above.
+  // useMemo is required here: the React Compiler cannot cache the result of
+  // buildCalendarConfig because all its arguments flow through `tN === undefined
+  // ? default : tN` conditional expressions (the compiler's own pattern for
+  // defaulted props), which block cache slot generation.
+  const calendarProps = useMemo(
+    () =>
+      buildCalendarConfig(
+        calendarColorScheme,
+        calendarDayHeight,
+        calendarDisabledDateIds,
+        calendarFirstDayOfWeek,
+        calendarFormatLocale,
+        calendarInstanceId,
+        calendarMaxDateId,
+        calendarMinDateId,
+        calendarMonthHeaderHeight,
+        calendarRowHorizontalSpacing,
+        calendarRowVerticalSpacing,
+        calendarWeekHeaderHeightProp,
+        getCalendarDayFormat,
+        getCalendarMonthFormat,
+        getCalendarWeekDayFormat,
+        onCalendarDayPress,
+        theme,
+        CalendarPressableComponent
+      ),
+    [
+      calendarColorScheme,
+      calendarDayHeight,
+      calendarDisabledDateIds,
+      calendarFirstDayOfWeek,
+      calendarFormatLocale,
+      calendarInstanceId,
+      calendarMaxDateId,
+      calendarMinDateId,
+      calendarMonthHeaderHeight,
+      calendarRowHorizontalSpacing,
+      calendarRowVerticalSpacing,
+      calendarWeekHeaderHeightProp,
+      getCalendarDayFormat,
+      getCalendarMonthFormat,
+      getCalendarWeekDayFormat,
+      onCalendarDayPress,
+      theme,
+      CalendarPressableComponent,
+    ]
+  );
+
+  const calendarWeekHeaderHeight =
+    calendarWeekHeaderHeightProp ?? calendarDayHeight;
 
   const {
     initialMonthIndex,
@@ -218,29 +399,33 @@ export function CalendarList({
     calendarMinDateId,
   });
 
-  // Compute the scroll index based on active date range if enabled
-  let computedInitialScrollIndex = initialMonthIndex;
-  if (calendarInitialScrollToActiveRange && calendarActiveDateRanges) {
-    const firstRange = calendarActiveDateRanges[0];
-    if (firstRange?.startId) {
-      // Convert the startId to the first day of that month
-      const startDate = fromDateId(firstRange.startId);
-      const monthId = toDateId(startOfMonth(startDate));
-
-      // Find the index of this month in the monthList
-      const monthIndex = monthList.findIndex((month) => month.id === monthId);
-
-      // Use this index if found, otherwise fall back to initialMonthIndex
-      if (monthIndex !== -1) {
-        computedInitialScrollIndex = monthIndex;
+  // Frozen after mount — initialScrollIndex must not change after first render
+  // or LegendList re-renders its entire inner tree on every update.
+  // useState initializer runs exactly once on mount.
+  const [computedInitialScrollIndex] = useState(() => {
+    if (calendarInitialScrollToActiveRange && calendarActiveDateRanges) {
+      const firstRange = calendarActiveDateRanges[0];
+      if (firstRange?.startId) {
+        const startDate = fromDateId(firstRange.startId);
+        const monthId = toDateId(startOfMonth(startDate));
+        const monthIndex = monthList.findIndex((month) => month.id === monthId);
+        if (monthIndex !== -1) {
+          return monthIndex;
+        }
       }
     }
-  }
+    return initialMonthIndex;
+  });
 
-  const monthListWithCalendarProps = monthList.map((month) => ({
-    ...month,
-    calendarProps,
-  }));
+  // Only build the enhanced list when user provides a custom renderItem
+  // (backwards-compat path). Otherwise use plain monthList so the data
+  // identity stays stable and LegendList can skip item re-renders.
+  const listData = customRenderItem
+    ? monthList.map((month) => ({
+        ...month,
+        calendarProps,
+      }))
+    : (monthList as unknown as CalendarMonthEnhanced[]);
 
   const handleOnEndReached = (info: { distanceFromEnd: number }) => {
     appendMonths(calendarFutureScrollRangeInMonths);
@@ -331,7 +516,7 @@ export function CalendarList({
 
   const calendarContainerStyle = { paddingBottom: calendarSpacing };
 
-  const getFixedItemSize = (item: CalendarMonthEnhanced) => {
+  const getFixedItemSize = (item: CalendarMonth | CalendarMonthEnhanced) => {
     return getHeightForMonth({
       calendarMonth: item,
       calendarSpacing,
@@ -343,35 +528,37 @@ export function CalendarList({
     });
   };
 
+  // onCalendarDayPress is provided via CalendarListConfigContext at runtime,
+  // so we only need to pass calendarMonthId here.
   const handleRenderItem = ({ item }: { item: CalendarMonthEnhanced }) => (
     <View style={calendarContainerStyle}>
-      <Calendar calendarMonthId={item.id} {...item.calendarProps} />
+      <Calendar
+        calendarMonthId={item.id}
+        onCalendarDayPress={onCalendarDayPress}
+      />
     </View>
   );
 
-  // Uncertain why but passing this as a no op resolved blanking issues after adding
-  // getFixedItemSize + recycleItems
-  const handleViewableItemsChanged = () => {};
-
   return (
-    <LegendList
-      data={monthListWithCalendarProps}
-      drawDistance={560}
-      estimatedItemSize={273}
-      getFixedItemSize={getFixedItemSize}
-      initialScrollIndex={computedInitialScrollIndex}
-      keyExtractor={keyExtractor}
-      maintainVisibleContentPosition
-      onEndReached={handleOnEndReached}
-      onStartReached={handleOnStartReached}
-      onViewableItemsChanged={handleViewableItemsChanged}
-      recycleItems
-      ref={legendListRef}
-      renderItem={handleRenderItem}
-      showsVerticalScrollIndicator={false}
-      style={styles.container}
-      {...flatListProps}
-    />
+    <CalendarListConfigProvider value={calendarProps}>
+      <LegendList
+        data={listData}
+        drawDistance={560}
+        estimatedItemSize={273}
+        getFixedItemSize={getFixedItemSize}
+        initialScrollIndex={computedInitialScrollIndex}
+        keyExtractor={keyExtractor}
+        maintainVisibleContentPosition
+        onEndReached={handleOnEndReached}
+        onStartReached={handleOnStartReached}
+        recycleItems
+        ref={legendListRef}
+        renderItem={customRenderItem ?? handleRenderItem}
+        showsVerticalScrollIndicator={false}
+        style={styles.container}
+        {...flatListProps}
+      />
+    </CalendarListConfigProvider>
   );
 }
 

package/src/components/CalendarListConfigContext.tsx

@@ -0,0 +1,29 @@
+import { createContext, useContext } from "react";
+
+import type { CalendarProps } from "@/components/Calendar";
+
+/**
+ * The calendar configuration props shared across all items in a
+ * `CalendarList`. When `Calendar` is rendered inside `CalendarList`, it reads
+ * these values from context instead of receiving them through the list item's
+ * data, which keeps the `data` array identity stable and allows LegendList to
+ * skip unnecessary re-renders.
+ *
+ * When `Calendar` is used standalone (outside a list), the context is `null`
+ * and all props are passed directly.
+ */
+export type CalendarListConfig = Omit<CalendarProps, "calendarMonthId">;
+
+const CalendarListConfigContext = createContext<CalendarListConfig | null>(
+  null
+);
+
+export const CalendarListConfigProvider = CalendarListConfigContext.Provider;
+
+/**
+ * Returns the shared calendar configuration from the nearest
+ * `CalendarListConfigProvider`, or `null` when used outside a `CalendarList`.
+ */
+export const useCalendarListConfig = (): CalendarListConfig | null => {
+  return useContext(CalendarListConfigContext);
+};