@lazerlen/legend-calendar 1.0.0

package/src/components/Calendar.tsx

@@ -0,0 +1,224 @@
+import { memo, useEffect } from "react";
+import type { ColorSchemeName, PressableProps } from "react-native";
+
+import type {
+  CalendarItemDayContainerProps,
+  CalendarItemDayProps,
+} from "@/components/CalendarItemDay";
+import {
+  CalendarItemDayContainer,
+  CalendarItemDayWithContainer,
+} from "@/components/CalendarItemDay";
+import type { CalendarItemEmptyProps } from "@/components/CalendarItemEmpty";
+import { CalendarItemEmpty } from "@/components/CalendarItemEmpty";
+import type { CalendarItemWeekNameProps } from "@/components/CalendarItemWeekName";
+import { CalendarItemWeekName } from "@/components/CalendarItemWeekName";
+import type { CalendarRowMonthProps } from "@/components/CalendarRowMonth";
+import { CalendarRowMonth } from "@/components/CalendarRowMonth";
+import type { CalendarRowWeekProps } from "@/components/CalendarRowWeek";
+import { CalendarRowWeek } from "@/components/CalendarRowWeek";
+import { CalendarThemeProvider } from "@/components/CalendarThemeProvider";
+import { VStack } from "@/components/VStack";
+import { uppercaseFirstLetter } from "@/helpers/strings";
+import type { BaseTheme } from "@/helpers/tokens";
+import type { UseCalendarParams } from "@/hooks/useCalendar";
+import { useCalendar } from "@/hooks/useCalendar";
+import { activeDateRangesEmitter } from "@/hooks/useOptimizedDayMetadata";
+
+export type PressableLike = React.ComponentType<
+  Pick<PressableProps, "children" | "style" | "disabled"> & {
+    onPress: () => void;
+  }
+>;
+
+export interface CalendarTheme {
+  rowMonth?: CalendarRowMonthProps["theme"];
+  rowWeek?: CalendarRowWeekProps["theme"];
+  itemWeekName?: CalendarItemWeekNameProps["theme"];
+  itemEmpty?: CalendarItemEmptyProps["theme"];
+  itemDayContainer?: CalendarItemDayContainerProps["theme"];
+  /**
+   * The theme for the day. `base` is applied before any state, allowing you to
+   * set a base value once and use it for all states.
+   */
+  itemDay?: CalendarItemDayProps["theme"];
+}
+
+export type CalendarOnDayPress = (dateId: string) => void;
+
+export interface CalendarProps extends UseCalendarParams {
+  /**
+   * A unique identifier for this calendar instance. This is useful if you
+   * need to render more than one calendar at once. This allows Legend Calendar
+   * to scope its state to the given instance.
+   *
+   * No need to get fancy with `uuid` or anything like that - a simple static
+   * string is enough.
+   *
+   * If not provided, Legend Calendar will use a default value which will hoist
+   * the state in a global scope.
+   */
+  calendarInstanceId?: string;
+  /**
+   * The spacing between each calendar row (the month header, the week days row,
+   * and the weeks row)
+   * @defaultValue 8
+   */
+  calendarRowVerticalSpacing?: number;
+  /**
+   * The spacing between each day in the weeks row.
+   * @defaultValue 8
+   */
+  calendarRowHorizontalSpacing?: number;
+  /**
+   * The height of each day cell.
+   * @defaultValue 32
+   */
+  calendarDayHeight?: number;
+  /**
+   * The height of the week day's header.
+   * @defaultValue calendarDayHeight
+   */
+  calendarWeekHeaderHeight?: number;
+  /**
+   * The height of the month header.
+   * @defaultValue 20
+   */
+  calendarMonthHeaderHeight?: number;
+  /**
+   * When set, Legend Calendar will use this color scheme instead of the system's
+   * value (`light|dark`). This is useful if your app doesn't support dark-mode,
+   * for example.
+   *
+   * We don't advise using this prop - ideally, your app should reflect the
+   * user's preferences.
+   * @defaultValue undefined
+   */
+  calendarColorScheme?: ColorSchemeName;
+  /**
+   * The callback to be called when a day is pressed.
+   */
+  onCalendarDayPress: CalendarOnDayPress;
+  /** Theme to customize the calendar component. */
+  theme?: CalendarTheme;
+  /** Optional component to replace the default <Pressable> component. */
+  CalendarPressableComponent?: PressableLike;
+}
+
+const BaseCalendar = memo(function BaseCalendar(props: CalendarProps) {
+  const {
+    calendarInstanceId,
+    calendarRowVerticalSpacing = 8,
+    calendarRowHorizontalSpacing = 8,
+    calendarDayHeight = 32,
+    calendarMonthHeaderHeight = 20,
+    calendarWeekHeaderHeight = calendarDayHeight,
+    onCalendarDayPress,
+    theme,
+    CalendarPressableComponent,
+    ...buildCalendarParams
+  } = props;
+
+  const { calendarRowMonth, weeksList, weekDaysList } =
+    useCalendar(buildCalendarParams);
+
+  return (
+    <VStack
+      alignItems="center"
+      spacing={calendarRowVerticalSpacing as keyof BaseTheme["spacing"]}
+    >
+      <CalendarRowMonth
+        height={calendarMonthHeaderHeight}
+        theme={theme?.rowMonth}
+      >
+        {uppercaseFirstLetter(calendarRowMonth)}
+      </CalendarRowMonth>
+      <CalendarRowWeek spacing={8} theme={theme?.rowWeek}>
+        {weekDaysList.map((weekDay, i) => (
+          <CalendarItemWeekName
+            height={calendarWeekHeaderHeight}
+            key={i}
+            theme={theme?.itemWeekName}
+          >
+            {weekDay}
+          </CalendarItemWeekName>
+        ))}
+      </CalendarRowWeek>
+      {weeksList.map((week, index) => (
+        <CalendarRowWeek key={index}>
+          {week.map((dayProps) => {
+            if (dayProps.isDifferentMonth) {
+              return (
+                <CalendarItemDayContainer
+                  dayHeight={calendarDayHeight}
+                  daySpacing={calendarRowHorizontalSpacing}
+                  isStartOfWeek={dayProps.isStartOfWeek}
+                  key={dayProps.id}
+                  metadata={dayProps}
+                  theme={theme?.itemDayContainer}
+                >
+                  <CalendarItemEmpty
+                    height={calendarDayHeight}
+                    theme={theme?.itemEmpty}
+                  />
+                </CalendarItemDayContainer>
+              );
+            }
+
+            return (
+              <CalendarItemDayWithContainer
+                CalendarPressableComponent={CalendarPressableComponent}
+                calendarInstanceId={calendarInstanceId}
+                containerTheme={theme?.itemDayContainer}
+                dayHeight={calendarDayHeight}
+                daySpacing={calendarRowHorizontalSpacing}
+                key={dayProps.id}
+                metadata={dayProps}
+                onPress={onCalendarDayPress}
+                theme={theme?.itemDay}
+              >
+                {dayProps.displayLabel}
+              </CalendarItemDayWithContainer>
+            );
+          })}
+        </CalendarRowWeek>
+      ))}
+    </VStack>
+  );
+});
+
+export const Calendar = memo(function Calendar(props: CalendarProps) {
+  const {
+    calendarInstanceId,
+    calendarActiveDateRanges,
+    calendarMonthId,
+    calendarColorScheme,
+    ...otherProps
+  } = props;
+  useEffect(() => {
+    activeDateRangesEmitter.emit("onSetActiveDateRanges", {
+      instanceId: calendarInstanceId,
+      ranges: 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 (
+    <CalendarThemeProvider colorScheme={calendarColorScheme}>
+      <BaseCalendar
+        {...otherProps}
+        calendarInstanceId={calendarInstanceId}
+        calendarMonthId={calendarMonthId}
+      />
+    </CalendarThemeProvider>
+  );
+});

package/src/components/CalendarItemDay.tsx

@@ -0,0 +1,385 @@
+import type { ReactNode } from "react";
+import { useCallback, useMemo } from "react";
+import type { TextProps, TextStyle, ViewStyle } from "react-native";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+
+import type { BaseTheme } from "@/helpers/tokens";
+import type { CalendarDayMetadata } from "@/hooks/useCalendar";
+import { useOptimizedDayMetadata } from "@/hooks/useOptimizedDayMetadata";
+import { useTheme } from "@/hooks/useTheme";
+
+import type { PressableLike } from "./Calendar";
+
+// react-native-web/overrides.ts
+declare module "react-native" {
+  interface PressableStateCallbackType {
+    hovered?: boolean;
+    focused?: boolean;
+  }
+}
+
+const styles = StyleSheet.create({
+  baseContainer: {
+    padding: 6,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 16,
+    flex: 1,
+  },
+  baseContent: {
+    textAlign: "center",
+  },
+});
+
+export type DayState = "idle" | "active" | "today" | "disabled";
+
+interface DayTheme {
+  container: Omit<ViewStyle, "borderRadius">;
+  content: TextStyle;
+}
+type CalendarItemDayTheme = Record<
+  DayState,
+  (params: {
+    isStartOfRange: boolean;
+    isEndOfRange: boolean;
+    isPressed: boolean;
+    isHovered?: boolean;
+    isFocused?: boolean;
+  }) => DayTheme
+>;
+
+const buildBaseStyles = (theme: BaseTheme): CalendarItemDayTheme => {
+  const baseContent = {
+    ...styles.baseContent,
+    color: theme.colors.content.primary,
+  };
+
+  return {
+    active: ({ isPressed, isHovered, isStartOfRange, isEndOfRange }) => {
+      const baseStyles: DayTheme & { container: ViewStyle } =
+        isPressed || isHovered
+          ? {
+              container: {
+                ...styles.baseContainer,
+                backgroundColor: theme.colors.background.tertiary,
+              },
+              content: {
+                ...baseContent,
+                color: theme.colors.content.primary,
+              },
+            }
+          : {
+              container: {
+                ...styles.baseContainer,
+                backgroundColor: theme.colors.background.inverse.primary,
+              },
+              content: {
+                ...baseContent,
+                color: theme.colors.content.inverse.primary,
+              },
+            };
+
+      baseStyles.container.borderRadius = 0;
+      if (isStartOfRange) {
+        baseStyles.container.borderTopLeftRadius = 16;
+        baseStyles.container.borderBottomLeftRadius = 16;
+      }
+      if (isEndOfRange) {
+        baseStyles.container.borderTopRightRadius = 16;
+        baseStyles.container.borderBottomRightRadius = 16;
+      }
+      if (!isStartOfRange && !isEndOfRange) {
+        baseStyles.container.borderRadius = 0;
+      }
+      return baseStyles;
+    },
+    disabled: () => ({
+      container: styles.baseContainer,
+      content: {
+        ...baseContent,
+        color: theme.colors.content.disabled,
+      },
+    }),
+    idle: ({ isPressed, isHovered }) => {
+      return isPressed || isHovered
+        ? {
+            container: {
+              ...styles.baseContainer,
+              backgroundColor: theme.colors.background.tertiary,
+            },
+            content: {
+              ...baseContent,
+              color: theme.colors.content.primary,
+            },
+          }
+        : {
+            container: styles.baseContainer,
+            content: baseContent,
+          };
+    },
+    today: ({ isPressed, isHovered }) => {
+      return isPressed || isHovered
+        ? {
+            container: {
+              ...styles.baseContainer,
+              backgroundColor: theme.colors.background.tertiaryPressed,
+            },
+            content: baseContent,
+          }
+        : {
+            container: {
+              ...styles.baseContainer,
+              borderColor: theme.colors.borders.default,
+              borderStyle: "solid",
+              borderWidth: 1,
+            },
+            content: baseContent,
+          };
+    },
+  };
+};
+
+export interface CalendarItemDayProps {
+  children: ReactNode;
+  onPress: (id: string) => void;
+  metadata: CalendarDayMetadata;
+  theme?: Partial<
+    Record<
+      DayState | "base",
+      (
+        params: CalendarDayMetadata & {
+          isPressed: boolean;
+          isHovered?: boolean;
+          isFocused?: boolean;
+        }
+      ) => Partial<DayTheme>
+    >
+  >;
+  /** The cell's height */
+  height: number;
+  /** Optional TextProps to spread to the <Text> component. */
+  textProps?: Omit<TextProps, "children" | "onPress">;
+  /** Optional component to replace the default <Pressable> component. */
+  CalendarPressableComponent?: PressableLike;
+}
+
+/**
+ * The base calendar item day component. This component is responsible for
+ * rendering each day cell, along with its event handlers.
+ *
+ * This is not meant to be used directly. Instead, use the
+ * `CalendarItemDayWithContainer`, since it also includes the spacing between
+ * each day.
+ */
+export const CalendarItemDay = ({
+  onPress,
+  children,
+  theme,
+  height,
+  metadata,
+  textProps,
+  CalendarPressableComponent = Pressable as PressableLike,
+}: CalendarItemDayProps) => {
+  const baseTheme = useTheme();
+  const baseStyles = useMemo(() => {
+    return buildBaseStyles(baseTheme);
+  }, [baseTheme]);
+
+  const handlePress = useCallback(() => {
+    onPress(metadata.id);
+  }, [metadata.id, onPress]);
+
+  return (
+    <CalendarPressableComponent
+      disabled={metadata.state === "disabled"}
+      onPress={handlePress}
+      style={({
+        pressed: isPressed,
+        hovered: isHovered,
+        focused: isFocused,
+      }) => {
+        const params = {
+          isPressed,
+          isHovered,
+          isFocused,
+          isEndOfRange: metadata.isEndOfRange ?? false,
+          isStartOfRange: metadata.isStartOfRange ?? false,
+        };
+        const { container } = baseStyles[metadata.state](params);
+        return {
+          ...container,
+          height,
+          ...theme?.base?.({ ...metadata, isPressed }).container,
+          ...theme?.[metadata.state]?.({ ...metadata, isPressed }).container,
+        };
+      }}
+    >
+      {({ pressed: isPressed, hovered: isHovered, focused: isFocused }) => {
+        const params = {
+          isPressed,
+          isHovered,
+          isFocused,
+          isEndOfRange: metadata.isEndOfRange ?? false,
+          isStartOfRange: metadata.isStartOfRange ?? false,
+        };
+        const { content } = baseStyles[metadata.state](params);
+        return (
+          <Text
+            {...textProps}
+            style={{
+              ...content,
+              ...(textProps?.style ?? ({} as object)),
+              ...theme?.base?.({ ...metadata, isPressed, isHovered, isFocused })
+                .content,
+              ...theme?.[metadata.state]?.({
+                ...metadata,
+                isPressed,
+                isHovered,
+                isFocused,
+              }).content,
+            }}
+          >
+            {children}
+          </Text>
+        );
+      }}
+    </CalendarPressableComponent>
+  );
+};
+
+interface CalendarItemDayContainerTheme {
+  /** An empty view that acts as a spacer between each day. The spacing is
+   * controlled by the `daySpacing` prop. */
+  spacer?: ViewStyle;
+  /** An absolute positioned filler to join the active days together in a single
+   * complete range. */
+  activeDayFiller?: ViewStyle | ((params: CalendarDayMetadata) => ViewStyle);
+}
+
+export interface CalendarItemDayContainerProps {
+  children: ReactNode;
+  isStartOfWeek: boolean;
+  /**
+   * If true, the active day filler/extension will be shown. The filler is used
+   * as a visual effect to join the active days together in a complete range.
+   */
+  shouldShowActiveDayFiller?: boolean;
+  theme?: CalendarItemDayContainerTheme;
+  /**
+   * The spacing between each day
+   */
+  daySpacing: number;
+  /** The day's height */
+  dayHeight: number;
+  /** The metadata for the day, extracted from the calendar's state. */
+  metadata?: CalendarDayMetadata;
+}
+
+export const CalendarItemDayContainer = ({
+  children,
+  isStartOfWeek,
+  shouldShowActiveDayFiller,
+  theme,
+  daySpacing,
+  dayHeight,
+  metadata,
+}: CalendarItemDayContainerProps) => {
+  const baseTheme = useTheme();
+  const spacerStyles = useMemo<ViewStyle>(() => {
+    return {
+      position: "relative",
+      marginLeft: isStartOfWeek ? 0 : daySpacing,
+      flex: 1,
+      height: dayHeight,
+      ...theme?.spacer,
+    };
+  }, [dayHeight, daySpacing, isStartOfWeek, theme?.spacer]);
+
+  const activeDayFiller = useMemo<ViewStyle | null>(() => {
+    if (!shouldShowActiveDayFiller) {
+      return null;
+    }
+
+    return {
+      position: "absolute",
+      top: 0,
+      bottom: 0,
+      right: -(daySpacing + 1), // +1 to cover the 1px gap
+      width: daySpacing + 2, // +2 to cover the 1px gap (distributes evenly on both sides)
+      backgroundColor: baseTheme.colors.background.inverse.primary,
+      ...(typeof theme?.activeDayFiller === "function" && !!metadata
+        ? theme.activeDayFiller(metadata)
+        : theme?.activeDayFiller),
+    };
+  }, [
+    baseTheme.colors.background.inverse.primary,
+    daySpacing,
+    metadata,
+    shouldShowActiveDayFiller,
+    theme,
+  ]);
+
+  return (
+    <View style={spacerStyles}>
+      {children}
+      {activeDayFiller ? <View style={activeDayFiller} /> : null}
+    </View>
+  );
+};
+
+export interface CalendarItemDayWithContainerProps
+  extends Omit<CalendarItemDayProps, "height">,
+    Pick<CalendarItemDayContainerProps, "daySpacing" | "dayHeight"> {
+  containerTheme?: CalendarItemDayContainerTheme;
+  /**
+   * A unique identifier for this calendar instance. This is useful if you
+   * need to render more than one calendar at once. This allows Legend Calendar
+   * to scope its state to the given instance.
+   *
+   * No need to get fancy with `uuid` or anything like that - a simple static
+   * string is enough.
+   *
+   * If not provided, Legend Calendar will use a default value which will hoist
+   * the state in a global scope.
+   */
+  calendarInstanceId?: string;
+}
+
+export const CalendarItemDayWithContainer = ({
+  children,
+  metadata: baseMetadata,
+  onPress,
+  theme,
+  dayHeight,
+  daySpacing,
+  containerTheme,
+  calendarInstanceId,
+  CalendarPressableComponent,
+}: CalendarItemDayWithContainerProps) => {
+  const metadata = useOptimizedDayMetadata(baseMetadata, calendarInstanceId);
+
+  return (
+    <CalendarItemDayContainer
+      dayHeight={dayHeight}
+      daySpacing={daySpacing}
+      isStartOfWeek={metadata.isStartOfWeek}
+      metadata={metadata}
+      shouldShowActiveDayFiller={
+        metadata.isRangeValid && !metadata.isEndOfWeek
+          ? !metadata.isEndOfRange
+          : false
+      }
+      theme={containerTheme}
+    >
+      <CalendarItemDay
+        CalendarPressableComponent={CalendarPressableComponent}
+        height={dayHeight}
+        metadata={metadata}
+        onPress={onPress}
+        theme={theme}
+      >
+        {children}
+      </CalendarItemDay>
+    </CalendarItemDayContainer>
+  );
+};

package/src/components/CalendarItemEmpty.tsx

@@ -0,0 +1,30 @@
+import { memo, useMemo } from "react";
+import type { ViewStyle } from "react-native";
+import { View, StyleSheet } from "react-native";
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 6,
+    flex: 1,
+  },
+});
+
+export interface CalendarItemEmptyProps {
+  /** The height of the cell. Should be the same as `CalendarItemDay`. */
+  height: number;
+  /** The theme of the empty cell, useful for customizing the component. */
+  theme?: {
+    container?: ViewStyle;
+  };
+}
+
+export const CalendarItemEmpty = memo(function CalendarItemEmpty(
+  props: CalendarItemEmptyProps
+) {
+  const { height, theme } = props;
+  const containerStyles = useMemo(() => {
+    return [{ ...styles.container, height }, theme?.container];
+  }, [height, theme?.container]);
+
+  return <View style={containerStyles} />;
+});

package/src/components/CalendarItemWeekName.tsx

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+import type { TextProps, TextStyle, ViewStyle } from "react-native";
+import { StyleSheet, Text, View } from "react-native";
+
+import { lightTheme } from "@/helpers/tokens";
+import { useTheme } from "@/hooks/useTheme";
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: "center",
+    flex: 1,
+    justifyContent: "center",
+    padding: lightTheme.spacing[6],
+  },
+  content: {},
+});
+
+interface CalendarItemWeekNameTheme {
+  container?: ViewStyle;
+  content?: TextStyle;
+}
+
+export interface CalendarItemWeekNameProps {
+  children: ReactNode;
+  /**
+   * The height of the week name, needed to correctly measure the calendar's
+   */
+  height: number;
+  /** The theme of the week name, useful for customizing the component. */
+  theme?: CalendarItemWeekNameTheme;
+  /** Optional TextProps to spread to the <Text> component. */
+  textProps?: Omit<TextProps, "children">;
+}
+
+export const CalendarItemWeekName = ({
+  children,
+  height,
+  theme,
+  textProps,
+}: CalendarItemWeekNameProps) => {
+  const { colors } = useTheme();
+  const { containerStyles, contentStyles } = useMemo(() => {
+    const containerStyles = [styles.container, { height }, theme?.container];
+    const contentStyles = [
+      styles.content,
+      { color: colors.content.primary },
+      textProps?.style,
+      theme?.content,
+    ];
+    return { containerStyles, contentStyles };
+  }, [
+    colors.content.primary,
+    height,
+    theme?.container,
+    theme?.content,
+    textProps?.style,
+  ]);
+
+  return (
+    <View style={containerStyles}>
+      <Text {...textProps} style={contentStyles}>
+        {children}
+      </Text>
+    </View>
+  );
+};