Clarify referential equality

.changeset/smart-pans-sleep.md

@@ -0,0 +1,2 @@
+---
+---

apps/docs/docs/fundamentals/usage.mdx

@@ -3,6 +3,7 @@ sidebar_position: 2
 ---
 
 import Image from "@theme/IdealImage";
+import Admonition from "@theme/Admonition";
 import { HStack } from "@site/src/components/HStack";
 import basicCalendar from "./assets/basic-calendar.png";
 import basicCalendarList from "./assets/basic-calendar-list.png";
@@ -225,6 +226,52 @@ export const CalendarCustomFormatting = () => {
 
 </HStack>
 
+#### Note on referential equality
+
+Due to Flash Calendar's architecture, it's important to make your date
+formatting functions stable. You should move them outside the component
+scope (preferred) or memoize them with `useCallback`. Refer to [Issue
+69](https://github.com/MarceloPrado/flash-calendar/issues/69) for more.
+
+<HStack spacing={12}>
+  <Admonition type="tip" title="DO">
+    Make the formatting functions stable.
+
+    ```tsx
+    const today = toDateId(new Date());
+
+    const Example = () => {
+      return (
+        <View style={{ flex: 1 }}>
+          <Calendar
+            calendarMonthId={today}
+            getCalendarWeekDayFormat={formatWeekDay}
+          />
+        </View>
+      );
+    };
+
+    const formatWeekDay = (date: Date) =>
+      format(date, "EEEEEE");
+    ```
+
+  </Admonition>
+  <Admonition type="danger" title="DON'T">
+    Break referential equality by inlining the formatting functions.
+
+    ```tsx
+    <Calendar
+      calendarMonthId={today}
+      getCalendarWeekDayFormat={(date) =>
+        // prettier-ignore
+        format(date, "EEEEEE")
+      }
+    />
+    ```
+
+  </Admonition>
+</HStack>
+
 ## Min, max and disabled dates
 
 You can limit the range of selectable dates by using the `calendarMinDateId` and

apps/example/src/components/GithubIssues/CalendarGithubIssues.stories.tsx

@@ -0,0 +1,54 @@
+import {
+  Calendar,
+  toDateId,
+  useDateRange,
+} from "@marceloterreiro/flash-calendar";
+import type { Meta } from "@storybook/react";
+import { addDays, format } from "date-fns";
+import { useEffect, useState } from "react";
+import { View } from "react-native";
+
+const CalendarMeta: Meta<typeof Calendar> = {
+  title: "Calendar/Github Issues",
+  decorators: [],
+};
+
+export default CalendarMeta;
+
+const today = toDateId(new Date());
+const todayPlusFive = toDateId(addDays(new Date(), 5));
+
+// See more: https://github.com/MarceloPrado/flash-calendar/issues/69
+export const Issue69 = () => {
+  // This state is simplified for the example. In my case it would come from a context.
+  const [start, setStart] = useState<string | undefined>(today);
+  const [end, setEnd] = useState<string | undefined>(todayPlusFive);
+
+  const { onCalendarDayPress, isDateRangeValid, calendarActiveDateRanges } =
+    useDateRange({ startId: start, endId: end }); // I am setting the default range here because I want the data from my context to be pre-selected here
+
+  useEffect(() => {
+    // Every time the selected range changed I want to update my context (in this example the state)
+    if (isDateRangeValid && calendarActiveDateRanges.length > 0) {
+      const range = calendarActiveDateRanges[0];
+      setStart(range.startId);
+      setEnd(range?.endId);
+    }
+  }, [calendarActiveDateRanges, isDateRangeValid]);
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Calendar
+        calendarActiveDateRanges={calendarActiveDateRanges}
+        calendarColorScheme="light"
+        calendarFirstDayOfWeek="monday"
+        calendarMonthId={today}
+        getCalendarWeekDayFormat={formatWeekDay}
+        // getCalendarWeekDayFormat={(date) => format(date, "EEEEEE")}
+        onCalendarDayPress={onCalendarDayPress}
+      />
+    </View>
+  );
+};
+
+const formatWeekDay = (date: Date) => format(date, "EEEEEE");