@lazerlen/legend-calendar 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazerlen/legend-calendar",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "private": false,
   "description": "A better calendar for React Native.",
   "repository": {

package/src/components/CalendarItemDay.tsx

@@ -304,6 +304,12 @@ interface CalendarItemDayContainerTheme {
   /** An absolute positioned filler to join the active days together in a single
    * complete range. */
   activeDayFiller?: ViewStyle | ((params: CalendarDayMetadata) => ViewStyle);
+  /** An absolutely-positioned background view rendered inside the spacer,
+   * behind the day button. Useful for rendering a range band that doesn't
+   * extend behind the circular edge days. */
+  activeDayRangeBackground?:
+    | ViewStyle
+    | ((params: CalendarDayMetadata) => ViewStyle | undefined);
 }
 
 export interface CalendarItemDayContainerProps {
@@ -361,8 +367,24 @@ export const CalendarItemDayContainer = memo(function CalendarItemDayContainer({
           : theme?.activeDayFiller),
       };
 
+  const rangeBackgroundTheme =
+    typeof theme?.activeDayRangeBackground === "function" && metadata
+      ? theme.activeDayRangeBackground(metadata)
+      : theme?.activeDayRangeBackground;
+  const rangeBackground: ViewStyle | null = rangeBackgroundTheme
+    ? {
+        position: "absolute",
+        top: 0,
+        bottom: 0,
+        left: 0,
+        right: 0,
+        ...rangeBackgroundTheme,
+      }
+    : null;
+
   return (
     <View style={spacerStyles}>
+      {rangeBackground ? <View style={rangeBackground} /> : null}
       {activeDayFiller ? <View style={activeDayFiller} /> : null}
       {children}
     </View>

package/src/components/CalendarList.stories.tsx

@@ -249,6 +249,57 @@ export const DatePicker = () => {
   );
 };
 
+export function AutoScrollToActiveRange() {
+  const futureDate = addMonths(today, 6);
+  const futureDateEnd = addMonths(futureDate, 1);
+
+  return (
+    <VStack grow spacing={20}>
+      <Text>
+        This calendar has a date range 6 months in the future. It automatically
+        scrolls to show the active range on mount.
+      </Text>
+      <View style={{ flex: 1, width: "100%" }}>
+        <Calendar.List
+          calendarActiveDateRanges={[
+            {
+              startId: toDateId(futureDate),
+              endId: toDateId(futureDateEnd),
+            },
+          ]}
+          onCalendarDayPress={loggingHandler("onCalendarDayPress")}
+        />
+      </View>
+    </VStack>
+  );
+}
+
+export function AutoScrollDisabled() {
+  const futureDate = addMonths(today, 6);
+  const futureDateEnd = addMonths(futureDate, 1);
+
+  return (
+    <VStack grow spacing={20}>
+      <Text>
+        This calendar has auto-scroll disabled. It opens at the current month
+        even though the active range is 6 months in the future.
+      </Text>
+      <View style={{ flex: 1, width: "100%" }}>
+        <Calendar.List
+          calendarActiveDateRanges={[
+            {
+              startId: toDateId(futureDate),
+              endId: toDateId(futureDateEnd),
+            },
+          ]}
+          calendarInitialScrollToActiveRange={false}
+          onCalendarDayPress={loggingHandler("onCalendarDayPress")}
+        />
+      </View>
+    </VStack>
+  );
+}
+
 export const TwoCalendarListsMounted = () => {
   return (
     <VStack grow spacing={48}>

package/src/components/CalendarList.tsx

@@ -8,7 +8,12 @@ import { StyleSheet, View } from "react-native";
 
 import type { CalendarProps } from "@/components/Calendar";
 import { Calendar } from "@/components/Calendar";
-import { getWeekOfMonth, startOfMonth, toDateId } from "@/helpers/dates";
+import {
+  fromDateId,
+  getWeekOfMonth,
+  startOfMonth,
+  toDateId,
+} from "@/helpers/dates";
 import type { CalendarMonth } from "@/hooks/useCalendarList";
 import { getHeightForMonth, useCalendarList } from "@/hooks/useCalendarList";
 import { activeDateRangesStore } from "@/hooks/useOptimizedDayMetadata";
@@ -69,6 +74,20 @@ export interface CalendarListProps
    */
   calendarInitialMonthId?: string;
 
+  /**
+   * When enabled, automatically scrolls to the month containing the start date
+   * of the first active range on mount. Only applies when
+   * `calendarActiveDateRanges` has at least one range with a `startId`.
+   *
+   * Takes precedence over `calendarInitialMonthId` when enabled and a valid
+   * range exists.
+   *
+   * Uses `initialScrollIndex` internally, so scrolling only happens on mount.
+   *
+   * @defaultValue true
+   */
+  calendarInitialScrollToActiveRange?: boolean;
+
   /**
    * Overwrites the default `Calendar` component.
    *
@@ -113,6 +132,7 @@ export function CalendarList({
   const {
     // List-related props
     calendarInitialMonthId,
+    calendarInitialScrollToActiveRange = true,
     calendarPastScrollRangeInMonths = 12,
     calendarFutureScrollRangeInMonths = 12,
     calendarFirstDayOfWeek = "sunday",
@@ -198,6 +218,25 @@ 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;
+      }
+    }
+  }
+
   const monthListWithCalendarProps = monthList.map((month) => ({
     ...month,
     calendarProps,
@@ -320,7 +359,7 @@ export function CalendarList({
       drawDistance={560}
       estimatedItemSize={273}
       getFixedItemSize={getFixedItemSize}
-      initialScrollIndex={initialMonthIndex}
+      initialScrollIndex={computedInitialScrollIndex}
       keyExtractor={keyExtractor}
       maintainVisibleContentPosition
       onEndReached={handleOnEndReached}