@lazerlen/legend-calendar 1.0.0

package/src/components/CalendarList.stories.tsx

@@ -0,0 +1,326 @@
+import type { Meta, StoryObj } from "@storybook/react-native";
+import {
+  addDays,
+  addMonths,
+  endOfYear,
+  startOfMonth,
+  startOfYear,
+  subMonths,
+} from "date-fns";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { Button, Text, View } from "react-native";
+
+import type { CalendarListProps, CalendarListRef } from "@/components";
+import { Calendar } from "@/components";
+import { HStack } from "@/components/HStack";
+import { VStack } from "@/components/VStack";
+import { paddingDecorator } from "@/developer/decorators";
+import { loggingHandler } from "@/developer/loggginHandler";
+import { fromDateId, toDateId } from "@/helpers/dates";
+import type { CalendarActiveDateRange } from "@/hooks/useCalendar";
+import { useDateRange } from "@/hooks/useDateRange";
+import { useTheme } from "@/hooks/useTheme";
+
+const today = new Date();
+
+const startOfThisMonth = startOfMonth(today);
+
+const CalendarListMeta: Meta<typeof Calendar.List> = {
+  title: "Calendar.List",
+  component: Calendar.List,
+  argTypes: {},
+  args: {
+    onCalendarDayPress: loggingHandler("onCalendarDayPress"),
+    calendarRowVerticalSpacing: 8,
+    calendarRowHorizontalSpacing: 8,
+    calendarFutureScrollRangeInMonths: 12,
+    calendarPastScrollRangeInMonths: 12,
+
+    calendarFirstDayOfWeek: "sunday",
+    calendarInitialMonthId: toDateId(startOfThisMonth),
+  },
+  decorators: [paddingDecorator],
+};
+
+export default CalendarListMeta;
+
+export const Default: StoryObj<typeof Calendar.List> = {};
+
+export const SpacingDense: StoryObj<typeof Calendar.List> = {
+  args: {
+    calendarRowVerticalSpacing: 0,
+    calendarRowHorizontalSpacing: 4,
+  },
+};
+
+export const WithDateRangeAndDisabledDates: StoryObj<typeof Calendar.List> = {
+  args: {
+    calendarActiveDateRanges: [
+      {
+        startId: "2024-01-15",
+        endId: "2024-01-28",
+      },
+    ],
+    calendarDisabledDateIds: ["2024-01-01", "2024-01-02"],
+    calendarInitialMonthId: "2024-01-01",
+  },
+};
+
+export const WithShortFutureScrollRange: StoryObj<typeof Calendar.List> = {
+  args: {
+    calendarPastScrollRangeInMonths: 1,
+    calendarFutureScrollRangeInMonths: 1,
+    calendarInitialMonthId: "2024-02-01",
+  },
+};
+
+export function SpacingSparse() {
+  const [selectedDate, setSelectedDate] = useState<undefined | string>(
+    undefined
+  );
+
+  const onCalendarDayPress = (dateId: string) => {
+    setSelectedDate(dateId);
+  };
+
+  return (
+    <VStack grow spacing={24}>
+      <Text>Selected date: {selectedDate}</Text>
+
+      <Calendar.List
+        calendarActiveDateRanges={[
+          {
+            startId: selectedDate,
+            endId: selectedDate,
+          },
+        ]}
+        calendarDayHeight={50}
+        calendarInitialMonthId={selectedDate}
+        calendarMonthHeaderHeight={20}
+        calendarRowHorizontalSpacing={16}
+        calendarRowVerticalSpacing={16}
+        calendarSpacing={48}
+        calendarWeekHeaderHeight={32}
+        onCalendarDayPress={onCalendarDayPress}
+      />
+    </VStack>
+  );
+}
+
+export function ImperativeScrolling() {
+  const [currentMonth, setCurrentMonth] = useState(startOfMonth(new Date()));
+
+  const [activeDateId, setActiveDateId] = useState<string | undefined>(
+    toDateId(addDays(currentMonth, 3))
+  );
+
+  const calendarActiveDateRanges = useMemo<CalendarActiveDateRange[]>(() => {
+    if (!activeDateId) return [];
+
+    return [{ startId: activeDateId, endId: activeDateId }];
+  }, [activeDateId]);
+
+  const ref = useRef<CalendarListRef>(null);
+
+  const onCalendarDayPress = useCallback((dateId: string) => {
+    ref.current?.scrollToDate(fromDateId(dateId), true);
+    setActiveDateId(dateId);
+  }, []);
+
+  return (
+    <View style={{ paddingTop: 20, flex: 1 }}>
+      <VStack alignItems="center" grow spacing={20}>
+        <HStack spacing={12}>
+          <Button
+            onPress={() => {
+              const pastMonth = subMonths(currentMonth, 1);
+              setCurrentMonth(pastMonth);
+              ref.current?.scrollToMonth(pastMonth, true);
+            }}
+            title="Past month"
+          />
+          <Text>Current: {toDateId(currentMonth)}</Text>
+          <Button
+            onPress={() => {
+              const nextMonth = addMonths(currentMonth, 1);
+              setCurrentMonth(nextMonth);
+              ref.current?.scrollToMonth(nextMonth, true);
+            }}
+            title="Next month"
+          />
+        </HStack>
+        <Button
+          onPress={() => {
+            const thisMonth = startOfMonth(new Date());
+            setCurrentMonth(thisMonth);
+            ref.current?.scrollToMonth(thisMonth, true);
+          }}
+          title="Today"
+        />
+        <View style={{ flex: 1, width: "100%" }}>
+          <Calendar.List
+            calendarActiveDateRanges={calendarActiveDateRanges}
+            calendarInitialMonthId={toDateId(currentMonth)}
+            onCalendarDayPress={onCalendarDayPress}
+            ref={ref}
+          />
+        </View>
+      </VStack>
+    </View>
+  );
+}
+
+export function MinAndMaxDates() {
+  return (
+    <VStack alignItems="center" grow spacing={20}>
+      <Text>This calendar list is only available for the 2024 period</Text>
+      <View style={{ flex: 1, width: "100%" }}>
+        <Calendar.List
+          calendarInitialMonthId="2024-02-13"
+          calendarMaxDateId="2024-12-31"
+          calendarMinDateId="2024-01-01"
+          onCalendarDayPress={loggingHandler("onCalendarDayPress")}
+        />
+      </View>
+    </VStack>
+  );
+}
+
+export function DateRangePicker() {
+  const calendarListProps = useMemo<Partial<CalendarListProps>>(() => {
+    const today = new Date();
+    return {
+      calendarInitialMonthId: toDateId(today),
+      calendarMinDateId: toDateId(startOfYear(today)),
+      calendarMaxDateId: toDateId(endOfYear(today)),
+    };
+  }, []);
+
+  const calendarDateRangeProps = useDateRange();
+  const { onClearDateRange, dateRange, isDateRangeValid } =
+    calendarDateRangeProps;
+
+  const { colors } = useTheme();
+
+  const textProps = {
+    style: { color: colors.content.primary },
+  };
+
+  return (
+    <VStack alignItems="center" grow spacing={20}>
+      <Text style={{ ...textProps.style, fontWeight: "bold" }}>
+        This shows how to build a date range picker bounded by the current year
+      </Text>
+      <View style={{ flex: 1, width: "100%" }}>
+        <Calendar.List {...calendarListProps} {...calendarDateRangeProps} />
+      </View>
+      <HStack justifyContent="space-between" width="100%">
+        <Button onPress={onClearDateRange} title="Clear range" />
+        <VStack spacing={4}>
+          <Text {...textProps}>Start: {dateRange.startId ?? "?"}</Text>
+          <Text {...textProps}>End: {dateRange.endId ?? "?"}</Text>
+        </VStack>
+        <VStack alignItems="flex-end" spacing={4}>
+          <Text {...textProps}>Is range valid?</Text>
+          <Text {...textProps}>{isDateRangeValid ? "✅" : "❌"}</Text>
+        </VStack>
+      </HStack>
+    </VStack>
+  );
+}
+
+export const DatePicker = () => {
+  const [activeDateId, setActiveDateId] = useState<string | undefined>(
+    toDateId(addDays(startOfThisMonth, 3))
+  );
+
+  const calendarActiveDateRanges = useMemo<CalendarActiveDateRange[]>(() => {
+    if (!activeDateId) return [];
+
+    return [{ startId: activeDateId, endId: activeDateId }];
+  }, [activeDateId]);
+
+  return (
+    <Calendar.List
+      calendarActiveDateRanges={calendarActiveDateRanges}
+      calendarInitialMonthId={toDateId(startOfThisMonth)}
+      onCalendarDayPress={setActiveDateId}
+    />
+  );
+};
+
+export const ScrollingBackwardsWorkaround = () => {
+  return (
+    <VStack alignItems="stretch" grow spacing={12}>
+      <Text>This preloads all past months between Jan 1st 2020 and today</Text>
+
+      <Calendar.List
+        calendarFutureScrollRangeInMonths={1}
+        calendarInitialMonthId="2024-02-01"
+        calendarMaxDateId="2024-05-01"
+        calendarMinDateId="2020-01-01"
+        calendarPastScrollRangeInMonths={50}
+        onCalendarDayPress={loggingHandler("onCalendarDayPress")}
+      />
+    </VStack>
+  );
+};
+
+export const TwoCalendarListsMounted = () => {
+  return (
+    <VStack grow spacing={48}>
+      <CalendarInstanceDemo instanceId="First" startingIndex={3} />
+      <CalendarInstanceDemo instanceId="Second" startingIndex={10} />
+    </VStack>
+  );
+};
+
+function CalendarInstanceDemo({
+  instanceId,
+  startingIndex,
+}: {
+  instanceId: string;
+  startingIndex: number;
+}) {
+  const calendarDateRangeProps = useDateRange();
+  const rerender = useRef(0);
+  rerender.current += 1;
+  return (
+    <VStack grow spacing={8}>
+      <Calendar.List
+        {...calendarDateRangeProps}
+        calendarInstanceId={instanceId}
+      />
+      <Text>
+        {instanceId}: {calendarDateRangeProps.dateRange.startId} -{" "}
+        {calendarDateRangeProps.dateRange.endId} (re-renders: {rerender.current}
+        ⚡)
+      </Text>
+    </VStack>
+  );
+}
+
+export const Demo = () => {
+  const dateRangeOne = useDateRange();
+  const dateRangeTwo = useDateRange();
+  return (
+    <VStack grow spacing={48}>
+      <VStack grow spacing={4}>
+        <Text>First calendar</Text>
+        <Calendar
+          calendarInstanceId="First"
+          calendarMonthId="2024-08-01"
+          {...dateRangeOne}
+        />
+      </VStack>
+      <VStack grow spacing={4}>
+        <Text>Second calendar</Text>
+        <Calendar
+          calendarInstanceId="Second"
+          calendarMonthId="2024-08-01"
+          {...dateRangeTwo}
+        />
+      </VStack>
+    </VStack>
+  );
+};

package/src/components/CalendarList.tsx

@@ -0,0 +1,373 @@
+import {
+  LegendList as LegendListBase,
+  type LegendListProps,
+  type LegendListRef,
+} from "@legendapp/list";
+import { memo, useCallback, useImperativeHandle, useMemo, useRef } from "react";
+import { View } from "react-native";
+
+import type { CalendarProps } from "@/components/Calendar";
+import { Calendar } from "@/components/Calendar";
+import { getWeekOfMonth, startOfMonth, toDateId } from "@/helpers/dates";
+import type { CalendarMonth } from "@/hooks/useCalendarList";
+import { getHeightForMonth, useCalendarList } from "@/hooks/useCalendarList";
+
+// Type assertion to make LegendList compatible with React 19
+const LegendList = LegendListBase as <T>(
+  props: LegendListProps<T> & { ref?: React.Ref<LegendListRef> }
+) => React.ReactElement;
+/**
+ * Represents each `CalendarList` item. It's enhanced with the required
+ * `Calendar` props to simplify building custom `Calendar` components.
+ */
+export type CalendarMonthEnhanced = CalendarMonth & {
+  calendarProps: Omit<CalendarProps, "calendarMonthId">;
+};
+
+const keyExtractor = (month: CalendarMonth) => month.id;
+
+export interface CalendarListProps
+  extends Omit<CalendarProps, "calendarMonthId">,
+    Omit<
+      LegendListProps<CalendarMonthEnhanced>,
+      "renderItem" | "data" | "children"
+    > {
+  /**
+   * How many months to show before the current month. Once the user scrolls
+   * past this range and if they haven't exceeded the `calendarMinDateId`, new
+   * months are prepended in this increment.
+   * @defaultValue 12
+   */
+  calendarPastScrollRangeInMonths?: number;
+  /**
+   * How many months to show after the current month. Once the user scrolls
+   * past this range and if they haven't exceeded the `calendarMaxDateId`, new
+   * months are appended in this increment.
+   * @defaultValue 12
+   */
+  calendarFutureScrollRangeInMonths?: number;
+
+  /**
+   * An additional height to use in the month's height calculation. Useful when
+   * providing a custom `Calendar` component with extra content such as a
+   * footer.
+   */
+  calendarAdditionalHeight?: number;
+
+  /**
+   * The vertical spacing between each `<Calendar />` component.
+   * @defaultValue 20
+   */
+  calendarSpacing?: number;
+
+  /**
+   * The initial month to open the calendar to, as a `YYYY-MM-DD` string.
+   * Defaults to the current month.
+   *
+   * **Tip**: To convert to date ID, use `toDateId(date)`.
+   */
+  calendarInitialMonthId?: string;
+
+  /**
+   * Overwrites the default `Calendar` component.
+   *
+   * **Important**: when providing a custom implementation, make sure to
+   * manually set all the spacing and height props to ensure the list scrolls
+   * to the right offset:
+   * - calendarDayHeight
+   * - calendarMonthHeaderHeight
+   * - calendarWeekHeaderHeight
+   * - calendarAdditionalHeight
+   * - calendarRowVerticalSpacing
+   * - calendarSpacing
+   */
+  renderItem?: LegendListProps<CalendarMonthEnhanced>["renderItem"];
+}
+
+interface ImperativeScrollParams {
+  /**
+   * An additional offset to add to the final scroll position. Useful when
+   * you need to slightly change the final scroll position.
+   */
+  additionalOffset?: number;
+}
+export interface CalendarListRef {
+  scrollToMonth: (
+    date: Date,
+    animated: boolean,
+    params?: ImperativeScrollParams
+  ) => void;
+  scrollToDate: (
+    date: Date,
+    animated: boolean,
+    params?: ImperativeScrollParams
+  ) => void;
+  scrollToOffset: (offset: number, animated: boolean) => void;
+}
+
+export const CalendarList = memo(function CalendarList({
+  ref,
+  ...props
+}: CalendarListProps & { ref?: React.Ref<CalendarListRef> }) {
+  const {
+    // List-related props
+    calendarInitialMonthId,
+    calendarPastScrollRangeInMonths = 12,
+    calendarFutureScrollRangeInMonths = 12,
+    calendarFirstDayOfWeek = "sunday",
+    calendarFormatLocale,
+
+    // Spacings
+    calendarSpacing = 20,
+    calendarRowHorizontalSpacing,
+    calendarRowVerticalSpacing = 8,
+
+    // Heights
+    calendarMonthHeaderHeight = 20,
+    calendarDayHeight = 32,
+    calendarWeekHeaderHeight = calendarDayHeight,
+    calendarAdditionalHeight = 0,
+
+    // Other props
+    calendarColorScheme,
+    theme,
+    onEndReached,
+    onStartReached,
+    ...otherProps
+  } = props;
+
+  const {
+    calendarActiveDateRanges,
+    calendarDisabledDateIds,
+    calendarInstanceId,
+    calendarMaxDateId,
+    calendarMinDateId,
+    getCalendarDayFormat,
+    getCalendarMonthFormat,
+    getCalendarWeekDayFormat,
+    onCalendarDayPress,
+    CalendarPressableComponent,
+    ...flatListProps
+  } = otherProps;
+
+  const calendarProps = useMemo(
+    (): CalendarMonthEnhanced["calendarProps"] => ({
+      calendarActiveDateRanges,
+      calendarColorScheme,
+      calendarDayHeight,
+      calendarDisabledDateIds,
+      calendarFirstDayOfWeek,
+      calendarFormatLocale,
+      calendarInstanceId,
+      calendarMaxDateId,
+      calendarMinDateId,
+      calendarMonthHeaderHeight,
+      calendarRowHorizontalSpacing,
+      calendarRowVerticalSpacing,
+      calendarWeekHeaderHeight,
+      getCalendarDayFormat,
+      getCalendarMonthFormat,
+      getCalendarWeekDayFormat,
+      onCalendarDayPress,
+      theme,
+      CalendarPressableComponent,
+    }),
+    [
+      calendarColorScheme,
+      calendarActiveDateRanges,
+      calendarDayHeight,
+      calendarDisabledDateIds,
+      calendarFirstDayOfWeek,
+      calendarFormatLocale,
+      calendarMaxDateId,
+      calendarMinDateId,
+      calendarMonthHeaderHeight,
+      calendarRowHorizontalSpacing,
+      calendarRowVerticalSpacing,
+      calendarWeekHeaderHeight,
+      getCalendarDayFormat,
+      getCalendarMonthFormat,
+      getCalendarWeekDayFormat,
+      calendarInstanceId,
+      onCalendarDayPress,
+      theme,
+      CalendarPressableComponent,
+    ]
+  );
+
+  const {
+    initialMonthIndex,
+    monthList,
+    appendMonths,
+    prependMonths,
+    addMissingMonths,
+  } = useCalendarList({
+    calendarFirstDayOfWeek,
+    calendarFutureScrollRangeInMonths,
+    calendarPastScrollRangeInMonths,
+    calendarInitialMonthId,
+    calendarMaxDateId,
+    calendarMinDateId,
+  });
+
+  const monthListWithCalendarProps = useMemo(() => {
+    return monthList.map((month) => ({
+      ...month,
+      calendarProps,
+    }));
+  }, [calendarProps, monthList]);
+
+  const handleOnEndReached = useCallback(
+    (info: { distanceFromEnd: number }) => {
+      appendMonths(calendarFutureScrollRangeInMonths);
+      onEndReached?.(info);
+    },
+    [appendMonths, calendarFutureScrollRangeInMonths, onEndReached]
+  );
+
+  const handleOnStartReached = useCallback(
+    (info: { distanceFromStart: number }) => {
+      prependMonths(calendarPastScrollRangeInMonths);
+      onStartReached?.(info);
+    },
+    [prependMonths, calendarPastScrollRangeInMonths, onStartReached]
+  );
+
+  const handleGetFixedItemSize = useCallback(
+    (_index: number, item: CalendarMonth) => {
+      return getHeightForMonth({
+        calendarMonth: item,
+        calendarSpacing,
+        calendarDayHeight,
+        calendarMonthHeaderHeight,
+        calendarRowVerticalSpacing,
+        calendarAdditionalHeight,
+        calendarWeekHeaderHeight,
+      });
+    },
+    [
+      calendarAdditionalHeight,
+      calendarDayHeight,
+      calendarMonthHeaderHeight,
+      calendarRowVerticalSpacing,
+      calendarSpacing,
+      calendarWeekHeaderHeight,
+    ]
+  );
+
+  /**
+   * Returns the offset for the given month (how much the user needs to
+   * scroll to reach the month).
+   */
+  const getScrollOffsetForMonth = useCallback(
+    (date: Date) => {
+      const monthId = toDateId(startOfMonth(date));
+
+      let baseMonthList = monthList;
+      let index = baseMonthList.findIndex((month) => month.id === monthId);
+
+      if (index === -1) {
+        baseMonthList = addMissingMonths(monthId);
+        index = baseMonthList.findIndex((month) => month.id === monthId);
+      }
+
+      return baseMonthList.slice(0, index).reduce((acc, month) => {
+        const currentHeight = getHeightForMonth({
+          calendarMonth: month,
+          calendarSpacing,
+          calendarDayHeight,
+          calendarMonthHeaderHeight,
+          calendarRowVerticalSpacing,
+          calendarWeekHeaderHeight,
+          calendarAdditionalHeight,
+        });
+
+        return acc + currentHeight;
+      }, 0);
+    },
+    [
+      addMissingMonths,
+      calendarAdditionalHeight,
+      calendarDayHeight,
+      calendarMonthHeaderHeight,
+      calendarRowVerticalSpacing,
+      calendarSpacing,
+      calendarWeekHeaderHeight,
+      monthList,
+    ]
+  );
+
+  const legendListRef = useRef<LegendListRef>(null);
+
+  useImperativeHandle(ref, () => ({
+    scrollToMonth(
+      date,
+      animated,
+      { additionalOffset = 0 } = { additionalOffset: 0 }
+    ) {
+      // Wait for the next render cycle to ensure the list has been
+      // updated with the new months.
+      setTimeout(() => {
+        legendListRef.current?.scrollToOffset({
+          offset: getScrollOffsetForMonth(date) + additionalOffset,
+          animated,
+        });
+      }, 0);
+    },
+    scrollToDate(
+      date,
+      animated,
+      { additionalOffset = 0 } = {
+        additionalOffset: 0,
+      }
+    ) {
+      const currentMonthOffset = getScrollOffsetForMonth(date);
+      const weekOfMonthIndex = getWeekOfMonth(date, calendarFirstDayOfWeek);
+      const rowHeight = calendarDayHeight + calendarRowVerticalSpacing;
+
+      let weekOffset = calendarWeekHeaderHeight + rowHeight * weekOfMonthIndex;
+
+      /**
+       * We need to subtract one vertical spacing to avoid cutting off the
+       * desired date. A simple way of understanding why is imagining we
+       * want to scroll exactly to the given date, but leave a little bit of
+       * breathing room (`calendarRowVerticalSpacing`) above it.
+       */
+      weekOffset = weekOffset - calendarRowVerticalSpacing;
+
+      legendListRef.current?.scrollToOffset({
+        offset: currentMonthOffset + weekOffset + additionalOffset,
+        animated,
+      });
+    },
+    scrollToOffset(offset, animated) {
+      legendListRef.current?.scrollToOffset({ offset, animated });
+    },
+  }));
+
+  const calendarContainerStyle = useMemo(() => {
+    return { paddingBottom: calendarSpacing };
+  }, [calendarSpacing]);
+
+  return (
+    <LegendList
+      data={monthListWithCalendarProps}
+      estimatedItemSize={273}
+      getFixedItemSize={handleGetFixedItemSize}
+      initialScrollIndex={initialMonthIndex}
+      keyExtractor={keyExtractor}
+      onEndReached={handleOnEndReached}
+      onStartReached={handleOnStartReached}
+      recycleItems
+      ref={legendListRef}
+      renderItem={({ item }: { item: CalendarMonthEnhanced }) => (
+        <View style={calendarContainerStyle}>
+          <Calendar calendarMonthId={item.id} {...item.calendarProps} />
+        </View>
+      )}
+      showsVerticalScrollIndicator={false}
+      style={{ flex: 1 }}
+      {...flatListProps}
+    />
+  );
+});