@lazerlen/legend-calendar 1.0.0

package/src/hooks/useOptimizedDayMetadata.test.ts

@@ -0,0 +1,582 @@
+import { renderHook, act } from "@testing-library/react-hooks";
+import { describe, it, expect } from "bun:test";
+
+import type { CalendarDayMetadata } from "@/hooks/useCalendar";
+import { fromDateId } from "@/helpers/dates";
+import {
+  activeDateRangesEmitter,
+  useOptimizedDayMetadata,
+} from "@/hooks/useOptimizedDayMetadata";
+
+describe("useOptimizedDayMetadata", () => {
+  it("return the base metadata as the initial value", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-16"),
+      displayLabel: "16",
+      id: "2024-02-16",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    const { result } = renderHook(() => useOptimizedDayMetadata(baseMetadata));
+
+    expect(result.current).toEqual(baseMetadata);
+    expect(result.all).toHaveLength(1);
+  });
+
+  it("if the base changes, the returned value should match it.", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-16"),
+      displayLabel: "16",
+      id: "2024-02-16",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    const { result, rerender } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+
+    expect(result.current).toEqual(baseMetadata);
+    rerender({
+      ...baseMetadata,
+      isDisabled: true,
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      isDisabled: true,
+    });
+    // `useEffect` is called after the hook renders with the new baseMetadata.
+    // Hence, the length of the `result.all` array is 3.
+    expect(result.all).toHaveLength(3);
+  });
+
+  it("endOfRange: returns the updated metadata once an event is emitted", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-16"),
+      displayLabel: "16",
+      id: "2024-02-16",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    // Initial state
+    const { result } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+    expect(result.current).toEqual(baseMetadata);
+
+    // Emit event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result.all).toHaveLength(2);
+  });
+
+  it("startOfRange: returns the updated metadata once an event is emitted", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-01"),
+      displayLabel: "01",
+      id: "2024-02-01",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    // Initial state
+    const { result } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+    expect(result.current).toEqual(baseMetadata);
+
+    // Emit event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result.all).toHaveLength(2);
+  });
+
+  it("startOfRange|endOfRange: returns the updated metadata once an event is emitted", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-01"),
+      displayLabel: "01",
+      id: "2024-02-01",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    // Initial state
+    const { result } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+    expect(result.current).toEqual(baseMetadata);
+
+    // Emit event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-01",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result.all).toHaveLength(2);
+  });
+
+  it("doesn't re-render if the active dates don't overlap", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-18"),
+      displayLabel: "18",
+      id: "2024-02-18",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    // Initial state
+    const { result } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+    expect(result.current).toEqual(baseMetadata);
+
+    // Emit event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-17",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual(baseMetadata);
+    expect(result.all).toHaveLength(1);
+
+    // Emit another event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-19",
+            endId: "2024-02-23",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual(baseMetadata);
+    expect(result.all).toHaveLength(1);
+
+    // Emit an incomplete range
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: undefined,
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual(baseMetadata);
+    expect(result.all).toHaveLength(1);
+
+    // Check if the metadata is updated when the range is complete
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-20",
+          },
+        ],
+      });
+    });
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isRangeValid: true,
+    });
+    expect(result.all).toHaveLength(2);
+  });
+
+  it("resets the state once a new range is selected", () => {
+    const baseMetadata: CalendarDayMetadata = {
+      date: fromDateId("2024-02-01"),
+      displayLabel: "01",
+      id: "2024-02-01",
+      isDifferentMonth: false,
+      isDisabled: false,
+      isEndOfMonth: false,
+      isEndOfRange: false,
+      isEndOfWeek: false,
+      isRangeValid: false,
+      isStartOfMonth: false,
+      isStartOfRange: false,
+      isStartOfWeek: false,
+      isToday: false,
+      isWeekend: false,
+      state: "idle",
+    };
+
+    // Initial state
+    const { result } = renderHook(
+      (initial) => useOptimizedDayMetadata(initial),
+      {
+        initialProps: baseMetadata,
+      }
+    );
+    expect(result.current).toEqual(baseMetadata);
+
+    // Emit event
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-01",
+            endId: "2024-02-01",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result.all).toHaveLength(2);
+
+    // Emit another range
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-03",
+            endId: "2024-02-03",
+          },
+        ],
+      });
+    });
+
+    // Back to the initial state
+    expect(result.current).toEqual(baseMetadata);
+    expect(result.all).toHaveLength(3);
+  });
+});
+
+describe("useOptimizedDayMetadata with calendarInstanceId", () => {
+  const getBaseMetadata = (date: string): CalendarDayMetadata => ({
+    date: fromDateId(date),
+    displayLabel: date.split("-")[2],
+    id: date,
+    isDifferentMonth: false,
+    isDisabled: false,
+    isEndOfMonth: false,
+    isEndOfRange: false,
+    isEndOfWeek: false,
+    isRangeValid: false,
+    isStartOfMonth: false,
+    isStartOfRange: false,
+    isStartOfWeek: false,
+    isToday: false,
+    isWeekend: false,
+    state: "idle",
+  });
+
+  it("uses the default instance ID when not provided", () => {
+    const baseMetadata = getBaseMetadata("2024-02-16");
+    const { result } = renderHook(() => useOptimizedDayMetadata(baseMetadata));
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        ranges: [
+          {
+            startId: "2024-02-16",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+  });
+
+  it("responds to events for the correct instance ID", () => {
+    const instanceId = "test-calendar-1";
+    const baseMetadata = getBaseMetadata("2024-02-16");
+    const { result } = renderHook(() =>
+      useOptimizedDayMetadata(baseMetadata, instanceId)
+    );
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId,
+        ranges: [
+          {
+            startId: "2024-02-16",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+  });
+
+  it("ignores events for different instance IDs", () => {
+    const instanceId = "test-calendar-2";
+    const baseMetadata = getBaseMetadata("2024-02-16");
+    const { result } = renderHook(() =>
+      useOptimizedDayMetadata(baseMetadata, instanceId)
+    );
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId: "different-calendar",
+        ranges: [
+          {
+            startId: "2024-02-16",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    // The metadata should not change
+    expect(result.current).toEqual(baseMetadata);
+  });
+
+  it("handles multiple instances correctly", () => {
+    const instanceId1 = "test-calendar-3";
+    const instanceId2 = "test-calendar-4";
+
+    const baseMetadata1 = getBaseMetadata("2024-02-16");
+    const baseMetadata2 = getBaseMetadata("2024-02-16");
+
+    const { result: result1 } = renderHook(() =>
+      useOptimizedDayMetadata(baseMetadata1, instanceId1)
+    );
+    const { result: result2 } = renderHook(() =>
+      useOptimizedDayMetadata(baseMetadata2, instanceId2)
+    );
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId: instanceId1,
+        ranges: [
+          {
+            startId: "2024-02-16",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result1.current).toEqual({
+      ...baseMetadata1,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result2.current).toEqual(baseMetadata2);
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId: instanceId2,
+        ranges: [
+          {
+            startId: "2024-02-15",
+            endId: "2024-02-17",
+          },
+        ],
+      });
+    });
+
+    expect(result1.current).toEqual({
+      ...baseMetadata1,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+    expect(result2.current).toEqual({
+      ...baseMetadata2,
+      state: "active",
+      isRangeValid: true,
+    });
+  });
+
+  it("resets state for the correct instance when a new range is selected", () => {
+    const instanceId = "test-calendar-5";
+    const baseMetadata = getBaseMetadata("2024-02-16");
+    const { result } = renderHook(() =>
+      useOptimizedDayMetadata(baseMetadata, instanceId)
+    );
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId,
+        ranges: [
+          {
+            startId: "2024-02-16",
+            endId: "2024-02-16",
+          },
+        ],
+      });
+    });
+
+    expect(result.current).toEqual({
+      ...baseMetadata,
+      state: "active",
+      isStartOfRange: true,
+      isEndOfRange: true,
+      isRangeValid: true,
+    });
+
+    act(() => {
+      activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+        instanceId,
+        ranges: [
+          {
+            startId: "2024-02-18",
+            endId: "2024-02-20",
+          },
+        ],
+      });
+    });
+
+    // Should reset to base state
+    expect(result.current).toEqual(baseMetadata);
+  });
+});

package/src/hooks/useOptimizedDayMetadata.ts

@@ -0,0 +1,93 @@
+import mitt from "mitt";
+import { useEffect, useState } from "react";
+
+import {
+  getStateFields,
+  type CalendarActiveDateRange,
+  type CalendarDayMetadata,
+} from "@/hooks/useCalendar";
+
+interface OnSetActiveDateRangesPayload {
+  instanceId?: string;
+  ranges: CalendarActiveDateRange[];
+}
+
+/**
+ * An event emitter for the active date ranges. This notifies the calendar items
+ * when their state changes, allowing just the affected items to re-render.
+ *
+ * While this is an implementation detail focused on improving performance, it's
+ * exported in case you need to build your own calendar. Check the source code
+ * for a reference implementation.
+ */
+export const activeDateRangesEmitter = mitt<{
+  onSetActiveDateRanges: OnSetActiveDateRangesPayload;
+}>();
+
+/**
+ * The default calendar instance ID. This is used when no instance ID is provided.
+ */
+const DEFAULT_CALENDAR_INSTANCE_ID = "legend-calendar-default-instance";
+
+/**
+ * Returns an optimized metadata for a particular day. This hook listens to the
+ * `activeDateRanges` emitter, enabling only the affected calendar items to
+ * re-render.
+ *
+ * While this is an implementation detail focused on improving performance, it's
+ * exported in case you need to build your own calendar. Check the source code
+ * for a reference implementation.
+ */
+export const useOptimizedDayMetadata = (
+  baseMetadata: CalendarDayMetadata,
+  calendarInstanceId?: string
+) => {
+  const [metadata, setMetadata] = useState(baseMetadata);
+
+  const safeCalendarInstanceId =
+    calendarInstanceId ?? DEFAULT_CALENDAR_INSTANCE_ID;
+
+  // Ensure the metadata is updated when the base changes.
+  useEffect(() => {
+    setMetadata(baseMetadata);
+  }, [baseMetadata]);
+
+  useEffect(() => {
+    const handler = (payload: OnSetActiveDateRangesPayload) => {
+      const { ranges, instanceId = DEFAULT_CALENDAR_INSTANCE_ID } = payload;
+      if (instanceId !== safeCalendarInstanceId) {
+        // This event is not for this instance, ignore it.
+        return;
+      }
+
+      // We're only interested in the active date ranges, no need to worry about
+      // disabled states. These are already covered by the base metadata.
+      const { isStartOfRange, isEndOfRange, isRangeValid, state } =
+        getStateFields({
+          id: metadata.id,
+          calendarActiveDateRanges: ranges,
+        });
+
+      if (state === "active") {
+        setMetadata((prev) => ({
+          ...prev,
+          isStartOfRange,
+          isEndOfRange,
+          isRangeValid,
+          state,
+        }));
+      } else {
+        // Resets the state when it's no longer active.
+        setMetadata(baseMetadata);
+      }
+    };
+
+    activeDateRangesEmitter.on("onSetActiveDateRanges", handler);
+
+    return () => {
+      activeDateRangesEmitter.off("onSetActiveDateRanges", handler);
+    };
+  }, [baseMetadata, safeCalendarInstanceId, metadata]);
+
+  return metadata;
+};

package/src/hooks/useTheme.ts

@@ -0,0 +1,14 @@
+import { useColorScheme } from "react-native";
+
+import type { BaseTheme } from "@/helpers/tokens";
+import { darkTheme, lightTheme } from "@/helpers/tokens";
+import { useCalendarTheme } from "@/components/CalendarThemeProvider";
+
+export const useTheme = (): BaseTheme => {
+  const appearance = useColorScheme();
+  const { colorScheme } = useCalendarTheme();
+
+  const theme = colorScheme ?? appearance;
+
+  return theme === "dark" ? darkTheme : lightTheme;
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from "./components";
+export { toDateId, fromDateId } from "./helpers/dates";
+
+export {
+  type UseCalendarParams,
+  type CalendarDayMetadata,
+  type CalendarActiveDateRange,
+  useCalendar,
+  buildCalendar,
+} from "./hooks/useCalendar";
+
+export {
+  type CalendarMonth,
+  type UseCalendarListParams,
+  getHeightForMonth,
+  useCalendarList,
+} from "./hooks/useCalendarList";
+
+export {
+  useOptimizedDayMetadata,
+  activeDateRangesEmitter,
+} from "./hooks/useOptimizedDayMetadata";
+
+export { useDateRange } from "./hooks/useDateRange";