### Develop or Run Example App with Bun

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

Use this command to start the development server or run the example application.

```bash
bun dev
```

--------------------------------

### Start Local Development Server

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/README.md

Starts a local development server for live preview. Changes are reflected without restarting.

```bash
$ yarn start
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

Run this command at the root of the project to install all necessary dependencies using Bun.

```bash
bun install
```

--------------------------------

### Install Dependencies

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/README.md

Installs project dependencies using Yarn.

```bash
$ yarn
```

--------------------------------

### Install Flash Calendar and FlashList

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Install the package and its required peer dependency using npm or yarn.

```bash
npm add @marceloterreiro/flash-calendar @shopify/flash-list
# or
yarn add @marceloterreiro/flash-calendar @shopify/flash-list
```

--------------------------------

### Build Project with Bun

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

Execute this command to build the project, which is required after a fresh installation.

```bash
bun run build
```

--------------------------------

### Install Flash Calendar

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/index.mdx

Add the Flash Calendar package to your project using npm or yarn. Ensure peer dependencies are also installed.

```bash
npm add @marceloterreiro/flash-calendar
```

--------------------------------

### Programmatic Scrolling with Calendar List Ref

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/tips-and-tricks.mdx

Control calendar scrolling imperatively using a ref. This example demonstrates scrolling to a specific month and handling day presses by scrolling to the selected date.

```typescript
import { addMonths, subMonths, startOfMonth } from "date-fns";
import type { CalendarListRef } from "@marceloterreiro/flash-calendar";
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useRef, useState, useCallback } from "react";
import { Button, Text, View } from "react-native";

export function ImperativeScrolling() {
  const [currentMonth, setCurrentMonth] = useState(startOfMonth(new Date()));
  const ref = useRef<CalendarListRef>(null);

  const onCalendarDayPress = useCallback((dateId: string) => {
    ref.current?.scrollToDate(fromDateId(dateId), true);
  }, []);

  return (
    <View style={{ paddingTop: 20, flex: 1 }}>
      <View style={{ flexDirection: "row", gap: 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"
        />
      </View>
      <View style={{ flex: 1, width: "100%" }}>
        <Calendar.List
          calendarInitialMonthId={toDateId(currentMonth)}
          onCalendarDayPress={onCalendarDayPress}
          ref={ref}
        />
      </View>
    </View>
  );
}
```

--------------------------------

### Optimized Calendar.List with Memoized Handler

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/troubleshooting.mdx

This example shows the corrected implementation using `useCallback` for the `onCalendarDayPress` handler and the updater function pattern for state. This prevents unnecessary re-renders of `BaseCalendar` components, improving performance.

```tsx
import type { CalendarOnDayPress } from "@marceloterreiro/flash-calendar";
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { addMonths } from "date-fns";
import { useCallback, useState } from "react";
import { Text } from "react-native";

const todayId = toDateId(new Date());
const maxDateId = toDateId(addMonths(new Date(), 12));

export const SlowExampleAddressed = () => {
  const [dateIds, setDateIds] = useState<string[]>([]);
  const dateRanges = dateIds.map((dateId) => ({
    startId: dateId,
    endId: dateId,
  }));

  // highlight-start
  // This is the fix: memoized onCalendarDayPress and updater function pattern
  // It keeps `BaseCalendar` props stable, allowing each month to skip re-renders
  const handleCalendarDayPress = useCallback<CalendarOnDayPress>((dateId) => {
    setDateIds((dateIds) => {
      if (dateIds.includes(dateId)) {
        return dateIds.filter((id) => id !== dateId);
      } else {
        return [...dateIds, dateId];
      }
    });
  }, []);
  // highlight-end

  return (
    <Calendar.VStack alignItems="stretch" grow spacing={12}>
      <Text>✅ This is safe to copy, perf issues addressed</Text>

      <Calendar.List
        calendarActiveDateRanges={dateRanges}
        calendarInitialMonthId={todayId}
        calendarMaxDateId={maxDateId}
        calendarMinDateId={todayId}
        onCalendarDayPress={handleCalendarDayPress}
      />
    </Calendar.VStack>
  );
};

```

--------------------------------

### Slow Calendar.List with Date Ranges

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/troubleshooting.mdx

This example demonstrates a common performance issue where `Calendar.List` re-renders excessively due to unmemoized state updates. Avoid using this code directly; it's for illustrating the problem.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { addMonths } from "date-fns";
import { Text } from "react-native";

const todayId = toDateId(new Date());
const maxDateId = toDateId(addMonths(new Date(), 12));

export const SlowExample = () => {
  const [dateIds, setDateIds] = useState<string[]>([]);
  const dateRanges = dateIds.map((dateId) => ({
    startId: dateId,
    endId: dateId,
  }));

  return (
    <Calendar.VStack alignItems="stretch" grow spacing={12}>
      <Text>⚠️ Don't copy-paste this example, it has performance issues</Text>

      <Calendar.List
        calendarActiveDateRanges={dateRanges}
        calendarInitialMonthId={todayId}
        calendarMaxDateId={maxDateId}
        calendarMinDateId={todayId}
        onCalendarDayPress={(dateId) => {
          if (dateIds.includes(dateId)) {
            setDateIds(dateIds.filter((id) => id !== dateId));
          } else {
            setDateIds([...dateIds, dateId]);
          }
        }}
      />
    </Calendar.VStack>
  );
};

```

--------------------------------

### Safe Date ID Conversion

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/tips-and-tricks.mdx

Avoid unexpected results due to timezones by using `toDateId` for converting dates to string IDs. The example shows the recommended approach over `toISOString().slice(0, 10)`.

```typescript
const endOfJanuaryId = toDateId("2024-01-31");
const endOfJanuary = fromDateId(endOfJanuaryId); // Date object
```

--------------------------------

### Run Documentation Website with Bun

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

Command to serve the documentation website locally.

```bash
bun docs
```

--------------------------------

### Build Static Website

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/README.md

Generates static website content into the 'build' directory for hosting.

```bash
$ yarn build
```

--------------------------------

### Override Text Props for Calendar Day

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/customization.mdx

Control nested Text components within a Calendar.Item.Day by overriding `textProps`. This example disables font scaling for accessibility.

```tsx
import {
  Calendar,
  useOptimizedDayMetadata,
} from "@marceloterreiro/flash-calendar";
import { Text } from "react-native";
import type { CalendarItemDayWithContainerProps } from "@/components/CalendarItemDay";

import { useRenderCount } from "./useRenderCount";

export const PerfTestCalendarItemDayWithContainer = ({
  children,
  metadata: baseMetadata,
  onPress,
  theme,
  dayHeight,
  daySpacing,
  containerTheme,
}: CalendarItemDayWithContainerProps) => {
  const metadata = useOptimizedDayMetadata(baseMetadata);
  const renderCounter = useRenderCount();

  return (
    <Calendar.Item.Day.Container
      dayHeight={dayHeight}
      daySpacing={daySpacing}
      isStartOfWeek={metadata.isStartOfWeek}
      shouldShowActiveDayFiller={
        metadata.isRangeValid && !metadata.isEndOfWeek
          ? !metadata.isEndOfRange
          : false
      }
      theme={containerTheme}
    >
      <Calendar.Item.Day
        textProps={{ allowFontScaling: false }}
        height={dayHeight}
        metadata={metadata}
        onPress={onPress}
        theme={theme}
      >
        {children}
        <Text
          style={{
            fontSize: 8,
            fontStyle: "italic",
            textAlign: "center",
            color: metadata.state === "active" ? "white" : "black",
          }}
        >
          {"\n"}render: {renderCounter}x
        </Text>
      </Calendar.Item.Day>
    </Calendar.Item.Day.Container>
  );
};

```

--------------------------------

### Date Range Picker with useDateRange Hook

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Implements a date range picker using the `useDateRange` hook. This hook manages the `calendarActiveDateRanges` and `onCalendarDayPress` logic for selecting a start and end date.

```tsx
import { Calendar, useDateRange } from "@marceloterreiro/flash-calendar";

export const CalendarListDateRange = () => {
  const {
    calendarActiveDateRanges,
    onCalendarDayPress,
    // Also available for your convenience:
    // dateRange, // { startId?: string, endId?: string }
    // isDateRangeValid, // boolean
    // onClearDateRange, // () => void
  } = useDateRange();
  return (
    <Calendar.List
      calendarActiveDateRanges={calendarActiveDateRanges}
      onCalendarDayPress={onCalendarDayPress}
    />
  );
};
```

--------------------------------

### Deploy Website (SSH)

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/README.md

Deploys the website using SSH. Assumes SSH is configured for Git operations.

```bash
$ USE_SSH=true yarn deploy
```

--------------------------------

### Deploy Website (No SSH)

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/README.md

Deploys the website without SSH. Requires specifying the GitHub username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

To improve developer experience, run tests in watch mode for continuous feedback. Ensure your changes are unit-tested.

```bash
bun test --watch
```

--------------------------------

### Build Raw Calendar Data with `buildCalendar`

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Use `buildCalendar` to obtain the raw data structure for a month, including weeks, month label, and weekday headers. This is useful for building completely custom calendar UIs. Ensure correct date formatting and locale are provided.

```tsx
import { buildCalendar, toDateId, fromDateId } from "@marceloterreiro/flash-calendar";

const data = buildCalendar({
  calendarMonthId: "2024-07-01",
  calendarFirstDayOfWeek: "monday",
  calendarFormatLocale: "en-US",
  calendarActiveDateRanges: [{ startId: "2024-07-10", endId: "2024-07-15" }],
  calendarDisabledDateIds: ["2024-07-04"],
  calendarMinDateId: "2024-07-01",
  calendarMaxDateId: "2024-07-31",
});

console.log(data.calendarRowMonth); // "July 2024"
console.log(data.weekDaysList);     // ["M", "T", "W", "T", "F", "S", "S"]

// Each day in weeksList[row][col] is a CalendarDayMetadata object:
const day = data.weeksList[1][2];
console.log(day.id);            // "2024-07-09"
console.log(day.state);         // "idle" | "active" | "today" | "disabled"
console.log(day.isStartOfRange); // true if it's the range start
console.log(day.isWeekend);     // true for Saturday/Sunday
console.log(day.isDifferentMonth); // true for overflow days from prev/next month
```

--------------------------------

### useCalendar / buildCalendar

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

These functions provide the raw data structure for a single month, including the grid of weeks, formatted month label, and weekday header labels. They are useful for creating completely custom calendar UIs.

```APIDOC
## `buildCalendar(params)` — Low-level calendar data

Returns the raw data structure for a single month: the grid of weeks (`weeksList`), the formatted month label (`calendarRowMonth`), and the weekday header labels (`weekDaysList`). Use this when you need to build a completely custom calendar UI without the default components.

### Parameters

- `calendarMonthId` (string) - Required - The identifier for the month (e.g., "YYYY-MM-DD").
- `calendarFirstDayOfWeek` (string) - Optional - Sets the first day of the week (e.g., "monday", "sunday").
- `calendarFormatLocale` (string) - Optional - The locale for formatting dates (e.g., "en-US").
- `calendarActiveDateRanges` (Array<object>) - Optional - An array of objects defining active date ranges, each with `startId` and `endId`.
- `calendarDisabledDateIds` (Array<string>) - Optional - An array of date identifiers to disable.
- `calendarMinDateId` (string) - Optional - The minimum date identifier for the calendar.
- `calendarMaxDateId` (string) - Optional - The maximum date identifier for the calendar.

### Returns

An object containing:
- `weeksList` (Array<Array<CalendarDayMetadata>>): A 2D array representing the weeks and days.
- `calendarRowMonth` (string): The formatted month label.
- `weekDaysList` (Array<string>): An array of weekday header labels.

### Example

```tsx
import { buildCalendar } from "@marceloterreiro/flash-calendar";

const data = buildCalendar({
  calendarMonthId: "2024-07-01",
  calendarFirstDayOfWeek: "monday",
  calendarFormatLocale: "en-US",
  calendarActiveDateRanges: [{ startId: "2024-07-10", endId: "2024-07-15" }],
  calendarDisabledDateIds: ["2024-07-04"],
  calendarMinDateId: "2024-07-01",
  calendarMaxDateId: "2024-07-31",
});

console.log(data.calendarRowMonth); // "July 2024"
console.log(data.weekDaysList);     // ["M", "T", "W", "T", "F", "S", "S"]

const day = data.weeksList[1][2];
console.log(day.id);            // "2024-07-09"
console.log(day.state);         // "idle" | "active" | "today" | "disabled"
console.log(day.isStartOfRange); // true if it's the range start
console.log(day.isWeekend);     // true for Saturday/Sunday
console.log(day.isDifferentMonth); // true for overflow days from prev/next month
```
```

--------------------------------

### Run Specific File Tests in Watch Mode

Source: https://github.com/marceloprado/flash-calendar/blob/main/README.md

Run tests in watch mode for a specific file. This is useful for focused testing during development.

```bash
bun test --watch {filename}
```

--------------------------------

### Calendar.List

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Renders an infinite or bounded scrollable list of months backed by FlashList. It accepts all `<Calendar>` props plus list-specific ones and exposes an imperative ref for programmatic scrolling.

```APIDOC
## `<Calendar.List>` — Infinite-scroll calendar list

Renders an infinite (or bounded) scrollable list of months backed by FlashList. Accepts all `<Calendar>` props plus list-specific ones. Exposes an imperative ref for programmatic scrolling.

### Props

- `calendarInitialMonthId` (string): The ID of the month to initially scroll to.
- `calendarPastScrollRangeInMonths` (number): The number of months to load in the past.
- `calendarFutureScrollRangeInMonths` (number): The number of months to load in the future.
- `calendarSpacing` (number): The vertical gap between months.
- `calendarActiveDateRanges` (Array<[string, string]>): An array of date ranges to highlight.
- `onCalendarDayPress` (function): Callback function when a day is pressed.
- `calendarMinDateId` (string, optional): The minimum scrollable date ID.
- `calendarMaxDateId` (string, optional): The maximum scrollable date ID.

### Example Usage

```tsx
import { Calendar, toDateId, useDateRange } from "@marceloterreiro/flash-calendar";
import { useRef } from "react";
import { Button, View } from "react-native";
import type { CalendarListRef } from "@marceloterreiro/flash-calendar";

const today = toDateId(new Date());

export function InfiniteCalendarList() {
  const ref = useRef<CalendarListRef>(null);
  const { calendarActiveDateRanges, onCalendarDayPress } = useDateRange();

  return (
    <View style={{ flex: 1 }}>
      <Button
        title="Scroll to today"
        onPress={() => ref.current?.scrollToDate(new Date(), true)}
      />
      <Calendar.List
        ref={ref}
        calendarInitialMonthId={today}
        calendarPastScrollRangeInMonths={12}
        calendarFutureScrollRangeInMonths={12}
        calendarSpacing={20}
        calendarActiveDateRanges={calendarActiveDateRanges}
        onCalendarDayPress={onCalendarDayPress}
        calendarMinDateId="2023-01-01"
        calendarMaxDateId="2026-12-31"
      />
    </View>
  );
}
```
```

--------------------------------

### Basic Calendar Usage

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Renders a minimal Calendar component. Use `calendarActiveDateRanges` to highlight selected dates and `onCalendarDayPress` to update the state.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useState } from "react";
import { Text, View } from "react-native";

const today = toDateId(new Date());

export function BasicCalendar() {
  const [selectedDate, setSelectedDate] = useState(today);
  return (
    <View>
      <Text>Selected date: {selectedDate}</Text>
      <Calendar
        calendarActiveDateRanges={[
          {
            startId: selectedDate,
            endId: selectedDate,
          },
        ]}
        calendarMonthId={today}
        onCalendarDayPress={setSelectedDate}
      />
    </View>
  );
}
```

--------------------------------

### Basic Calendar List Usage

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Renders a minimal `Calendar.List` component. Similar to `Calendar`, it uses `calendarActiveDateRanges` for highlighting and `onCalendarDayPress` for state updates.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useState } from "react";
import { Text, View } from "react-native";

const today = toDateId(new Date());

export function BasicCalendarList() {
  const [selectedDate, setSelectedDate] = useState(today);

  return (
    <View style={{ flex: 1 }}>
      <Text>Selected date: {selectedDate}</Text>
      <Calendar.List
        calendarActiveDateRanges={[
          {
            startId: selectedDate,
            endId: selectedDate,
          },
        ]}
        calendarInitialMonthId={today}
        onCalendarDayPress={setSelectedDate}
      />
    </View>
  );
}
```

--------------------------------

### Custom Calendar Styling with `theme` Prop

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

The `theme` prop allows extensive customization of the calendar's visual appearance by providing a `CalendarTheme` object. This object maps to different parts of the calendar's anatomy, with `itemDay` accepting callbacks for dynamic styling based on interaction state and day metadata.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import type { CalendarTheme } from "@marceloterreiro/flash-calendar";
import { memo } from "react";

const accent = "#585ABF";

const linearTheme: CalendarTheme = {
  rowMonth: { 
    content: { textAlign: "left", color: "rgba(255,255,255,0.5)", fontWeight: "700" },
  },
  rowWeek: {
    container: {
      borderBottomWidth: 1,
      borderBottomColor: "rgba(255,255,255,0.1)",
      borderStyle: "solid",
    },
  },
  itemWeekName: { content: { color: "rgba(255,255,255,0.5)" } },
  itemDayContainer: {
    activeDayFiller: { backgroundColor: accent },
  },
  itemDay: {
    // "base" applies to every state before per-state overrides
    idle: ({ isPressed, isWeekend }) => ({
      container: {
        backgroundColor: isPressed ? accent : "transparent",
        borderRadius: 4,
      },
      content: {
        color: isWeekend && !isPressed ? "rgba(255,255,255,0.5)" : "#fff",
      },
    }),
    today: ({ isPressed }) => ({
      container: {
        borderColor: "rgba(255,255,255,0.5)",
        borderRadius: isPressed ? 4 : 30,
        backgroundColor: isPressed ? accent : "transparent",
      },
      content: { color: isPressed ? "#fff" : "rgba(255,255,255,0.5)" },
    }),
    active: ({ isStartOfRange, isEndOfRange }) => ({
      container: {
        backgroundColor: accent,
        borderTopLeftRadius:     isStartOfRange ? 4 : 0,
        borderBottomLeftRadius:  isStartOfRange ? 4 : 0,
        borderTopRightRadius:    isEndOfRange   ? 4 : 0,
        borderBottomRightRadius: isEndOfRange   ? 4 : 0,
      },
      content: { color: "#fff" },
    }),
  },
};

export const LinearCalendar = memo(() => (
  <Calendar
    calendarMonthId={toDateId(new Date())}
    calendarDayHeight={30}
    calendarRowHorizontalSpacing={16}
    calendarRowVerticalSpacing={16}
    onCalendarDayPress={(dateId) => console.log(dateId)}
    theme={linearTheme}
  />
));

```

--------------------------------

### theme prop

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Allows for extensive visual customization of the calendar components by overriding styles using the `CalendarTheme` object. It supports callbacks for dynamic styling based on interaction states and day metadata.

```APIDOC
## `theme` prop — Styling via `CalendarTheme`

Override any visual aspect of the calendar without replacing components. Each key maps to a part of the anatomy; `itemDay` keys accept a callback that receives live interaction state (`isPressed`, `isHovered`, `isFocused`) plus the full `CalendarDayMetadata`.

### `CalendarTheme` Object Structure

The `CalendarTheme` object accepts styles for various calendar parts, including:

- `rowMonth`: Styles for the month header row.
- `rowWeek`: Styles for the weekday header row.
- `itemWeekName`: Styles for individual weekday names.
- `itemDayContainer`: Styles for the container of a day cell.
- `itemDay`: Styles for the day cell itself, with specific states like `idle`, `today`, `active`, `disabled`, etc.

Each style property can be a direct style object or a callback function that receives interaction state and metadata for dynamic styling.

### Example

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import type { CalendarTheme } from "@marceloterreiro/flash-calendar";
import { memo } from "react";

const accent = "#585ABF";

const linearTheme: CalendarTheme = {
  rowMonth: {
    content: { textAlign: "left", color: "rgba(255,255,255,0.5)", fontWeight: "700" },
  },
  rowWeek: {
    container: {
      borderBottomWidth: 1,
      borderBottomColor: "rgba(255,255,255,0.1)",
      borderStyle: "solid",
    },
  },
  itemWeekName: { content: { color: "rgba(255,255,255,0.5)" } },
  itemDayContainer: {
    activeDayFiller: { backgroundColor: accent },
  },
  itemDay: {
    // "base" applies to every state before per-state overrides
    idle: ({ isPressed, isWeekend }) => ({
      container: {
        backgroundColor: isPressed ? accent : "transparent",
        borderRadius: 4,
      },
      content: {
        color: isWeekend && !isPressed ? "rgba(255,255,255,0.5)" : "#fff",
      },
    }),
    today: ({ isPressed }) => ({
      container: {
        borderColor: "rgba(255,255,255,0.5)",
        borderRadius: isPressed ? 4 : 30,
        backgroundColor: isPressed ? accent : "transparent",
      },
      content: { color: isPressed ? "#fff" : "rgba(255,255,255,0.5)" },
    }),
    active: ({ isStartOfRange, isEndOfRange }) => ({
      container: {
        backgroundColor: accent,
        borderTopLeftRadius:     isStartOfRange ? 4 : 0,
        borderBottomLeftRadius:  isStartOfRange ? 4 : 0,
        borderTopRightRadius:    isEndOfRange   ? 4 : 0,
        borderBottomRightRadius: isEndOfRange   ? 4 : 0,
      },
      content: { color: "#fff" },
    }),
  },
};

export const LinearCalendar = memo(() => (
  <Calendar
    calendarMonthId={toDateId(new Date())}
    calendarDayHeight={30}
    calendarRowHorizontalSpacing={16}
    calendarRowVerticalSpacing={16}
    onCalendarDayPress={(dateId) => console.log(dateId)}
    theme={linearTheme}
  />
));
```
```

--------------------------------

### Calendar with Brazilian Locale

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Configures the `Calendar` component to display dates and months in Brazilian Portuguese using the `calendarFormatLocale` prop.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useState } from "react";

const today = toDateId(new Date());

export function BrazilianCalendar() {
  const [selectedDate, setSelectedDate] = useState(today);
  return (
    <Calendar
      calendarActiveDateRanges={[
        {
          startId: selectedDate ?? undefined,
          endId: selectedDate ?? undefined,
        },
      ]}
      calendarMonthId={today}
      // highlight-next-line
      calendarFormatLocale="pt-BR"
      onCalendarDayPress={setSelectedDate}
    />
  );
}
```

--------------------------------

### CalendarListRef

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

The ref forwarded to `<Calendar.List>` exposes methods for imperative scrolling.

```APIDOC
## `CalendarListRef` — Imperative scrolling

The ref forwarded to `<Calendar.List>` exposes three scroll methods.

### Methods

- `scrollToMonth(date: Date, animated?: boolean)`: Scrolls the list so that the month containing the specified date is at the top.
- `scrollToDate(date: Date, animated?: boolean, options?: { additionalOffset?: number })`: Scrolls the list so that the specific date's row is visible.
- `scrollToOffset(offset: number, animated?: boolean)`: Scrolls the list to a raw pixel offset.

### Example Usage

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useRef } from "react";
import { Button, View } from "react-native";
import type { CalendarListRef } from "@marceloterreiro/flash-calendar";

export function ImperativeScrollDemo() {
  const ref = useRef<CalendarListRef>(null);

  return (
    <View style={{ flex: 1 }}>
      <Button
        title="Go to July 2025"
        onPress={() => ref.current?.scrollToMonth(new Date(2025, 6, 1), true)}
      />
      <Button
        title="Go to exact date"
        onPress={() =>
          ref.current?.scrollToDate(new Date(2025, 6, 15), true, {
            additionalOffset: -20, // nudge 20px above the row
          })
        }
      />
      <Button
        title="Scroll to top"
        onPress={() => ref.current?.scrollToOffset(0, true)}
      />
      <Calendar.List
        ref={ref}
        onCalendarDayPress={(dateId) => console.log(dateId)}
      />
    </View>
  );
}
```
```

--------------------------------

### Infinite Scroll Calendar List

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Renders a scrollable list of months using FlashList. Configure scroll ranges, spacing, and date restrictions. Accepts all Calendar props.

```tsx
import { Calendar, toDateId, useDateRange } from "@marceloterreiro/flash-calendar";
import { useRef } from "react";
import { Button, View } from "react-native";
import type { CalendarListRef } from "@marceloterreiro/flash-calendar";

const today = toDateId(new Date());

export function InfiniteCalendarList() {
  const ref = useRef<CalendarListRef>(null);
  const { calendarActiveDateRanges, onCalendarDayPress } = useDateRange();

  return (
    <View style={{ flex: 1 }}>
      <Button
        title="Scroll to today"
        onPress={() => ref.current?.scrollToDate(new Date(), true)}
      />
      <Calendar.List
        ref={ref}
        // Start scrolled to a specific month
        calendarInitialMonthId={today}
        // Load 12 months in each direction, extending on demand
        calendarPastScrollRangeInMonths={12}
        calendarFutureScrollRangeInMonths={12}
        // Vertical gap between months
        calendarSpacing={20}
        calendarActiveDateRanges={calendarActiveDateRanges}
        onCalendarDayPress={onCalendarDayPress}
        // Optional: restrict scrollable range
        calendarMinDateId="2023-01-01"
        calendarMaxDateId="2026-12-31"
      />
    </View>
  );
}
```

--------------------------------

### Localize Calendar with Custom Date Formatters

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Customize date formatting using libraries like date-fns. Ensure stable references for formatters outside the component to prevent re-renders.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { format } from "date-fns/fp";
import { subMonths } from "date-fns";

// Stable references defined outside the component to avoid re-renders
const formatDay   = format("dd");
const formatMonth = format("MMMM yyyy");
const formatWeek  = format("E");

export function LocalizedCalendar() {
  return (
    <Calendar
      calendarMonthId={toDateId(subMonths(new Date(), 1))}
      // Use a different locale for built-in Intl formatting
      calendarFormatLocale="pt-BR"
      // Or supply fully custom formatters (any date library works)
      getCalendarDayFormat={formatDay}
      getCalendarMonthFormat={formatMonth}
      getCalendarWeekDayFormat={formatWeek}
      onCalendarDayPress={(id) => console.log(id)}
    />
  );
}
```

--------------------------------

### Calendar Scrolling Backwards Workaround

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/limitations.mdx

Provides a workaround for the backward scrolling limitation by preloading past months using `calendarPastScrollRangeInMonths` and `calendarMinDateId`. This approach can impact performance due to increased memory usage but allows for infinite scrolling backwards.

```tsx
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>
  );
};

```

--------------------------------

### Custom Date Formatting with Date-Fns

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Use `getCalendarDayFormat`, `getCalendarMonthFormat`, and `getCalendarWeekDayFormat` props for full control over date display. Ensure formatting functions are stable (defined outside the component or memoized with `useCallback`) to maintain referential equality.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { subMonths } from "date-fns";
import { format } from "date-fns/fp";

const threeMonthsAgo = subMonths(new Date(), 3);

export const CalendarCustomFormatting = () => {
  return (
    <Calendar
      calendarMonthId={toDateId(threeMonthsAgo)}
      // highlight-start
      getCalendarDayFormat={format("dd")}
      getCalendarMonthFormat={format("MMMM yyyy (LL/yyyy)")}
      getCalendarWeekDayFormat={format("E")}
      // highlight-end
      onCalendarDayPress={(dateId) => {
        console.log(`Clicked on ${dateId}`);
      }}
    />
  );
};

```

```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");

```

```tsx
<Calendar
  calendarMonthId={today}
  getCalendarWeekDayFormat={(date) =>
    // prettier-ignore
    format(date, "EEEEEE")
  }
/>

```

--------------------------------

### Render Two Calendars on the Same Screen

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Use the `calendarInstanceId` prop to render multiple independent calendars on the same screen. This is applicable to both `Calendar` and `Calendar.List` components.

```tsx
import { Calendar, useDateRange } from "@marceloterreiro/flash-calendar";

export const TwoCalendarsMounted = () => {
  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>
  );
};

```

--------------------------------

### Calculate Precise Month Height for Custom Calendar Lists

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Use `getHeightForMonth` when implementing custom `renderItem` for `<Calendar.List>` to ensure correct scroll offset calculations by FlashList. This requires providing detailed calendar spacing and dimension configurations.

```tsx
import {
  Calendar,
  getHeightForMonth,
  useCalendarList,
  toDateId,
} from "@marceloterreiro/flash-calendar";
import { FlashList } from "@shopify/flash-list";
import { View } from "react-native";

const DAY_HEIGHT = 36;
const MONTH_HEADER = 24;
const WEEK_HEADER = DAY_HEIGHT;
const ROW_SPACING = 8;
const SPACING = 20;
const ADDITIONAL = 0;

export function CustomCalendarList() {
  const { monthList, appendMonths } = useCalendarList({
    calendarFirstDayOfWeek: "sunday",
    calendarFutureScrollRangeInMonths: 12,
    calendarPastScrollRangeInMonths: 12,
    calendarInitialMonthId: toDateId(new Date()),
  });

  return (
    <FlashList
      data={monthList}
      keyExtractor={(m) => m.id}
      estimatedItemSize={getHeightForMonth({
        calendarMonth: monthList[0],
        calendarDayHeight: DAY_HEIGHT,
        calendarMonthHeaderHeight: MONTH_HEADER,
        calendarWeekHeaderHeight: WEEK_HEADER,
        calendarRowVerticalSpacing: ROW_SPACING,
        calendarSpacing: SPACING,
        calendarAdditionalHeight: ADDITIONAL,
      })}
      onEndReached={() => appendMonths(12)}
      renderItem={({ item: month }) => (
        <View style={{ paddingBottom: SPACING }}>
          <Calendar
            calendarMonthId={month.id}
            calendarDayHeight={DAY_HEIGHT}
            calendarMonthHeaderHeight={MONTH_HEADER}
            calendarWeekHeaderHeight={WEEK_HEADER}
            calendarRowVerticalSpacing={ROW_SPACING}
            onCalendarDayPress={(id) => console.log(id)}
          />
        </View>
      )}
    />
  );
}
```

--------------------------------

### Customizing Calendar Spacing and Size

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/usage.mdx

Adjust the visual spacing and dimensions of calendar elements using props like `calendarDayHeight`, `calendarMonthHeaderHeight`, `calendarRowHorizontalSpacing`, `calendarRowVerticalSpacing`, and `calendarSpacing`.

```tsx
import { Calendar } from "@marceloterreiro/flash-calendar";
import { View } from "react-native";

export const CalendarListCompact = () => {
  return (
    <View style={{ width: 300, flex: 1 }}>
      <Calendar.List
        calendarDayHeight={28}
        calendarMonthHeaderHeight={20}
        calendarRowHorizontalSpacing={0}
        calendarRowVerticalSpacing={4}
        calendarSpacing={10}
        onCalendarDayPress={(dateId) => console.log(`Pressed ${dateId}`)}
      />
    </View>
  );
};

```

--------------------------------

### useDateRange()

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

A convenience hook that manages the two-tap date-range selection pattern. It returns helpers ready to spread directly onto `<Calendar>` or `<Calendar.List>`.

```APIDOC
## `useDateRange()` — Date-range picker state

A convenience hook that manages the two-tap date-range selection pattern. First tap sets `startId`; second tap sets `endId` (or swaps if the new date is earlier than the start). Returns helpers ready to spread directly onto `<Calendar>` or `<Calendar.List>`.

### Return Value

- `calendarActiveDateRanges` (Array<[string, string]>): Pass directly to `Calendar` or `Calendar.List` to highlight the selected range.
- `onCalendarDayPress` (function): Pass directly to `Calendar` or `Calendar.List` to handle day presses for range selection.
- `dateRange` ({ startId?: string; endId?: string }): An object containing the selected start and end date IDs.
- `isDateRangeValid` (boolean): `true` when both `startId` and `endId` are set.
- `onClearDateRange` (function): Resets the date range selection.

### Options

- `startId` (string, optional): Pre-populates the start date of the range.
- `endId` (string, optional): Pre-populates the end date of the range.

### Example Usage

```tsx
import { Calendar, useDateRange } from "@marceloterreiro/flash-calendar";
import { Button, Text, View } from "react-native";

export function DateRangePicker() {
  const {
    calendarActiveDateRanges,
    onCalendarDayPress,
    dateRange,
    isDateRangeValid,
    onClearDateRange,
  } = useDateRange({
    startId: "2024-07-01",
    endId:   "2024-07-07",
  });

  return (
    <View style={{ flex: 1 }}>
      <Text>
        {isDateRangeValid
          ? `${dateRange.startId} → ${dateRange.endId}`
          : "Tap a start date"}
      </Text>
      <Button title="Clear" onPress={onClearDateRange} />
      <Calendar.List
        calendarActiveDateRanges={calendarActiveDateRanges}
        onCalendarDayPress={onCalendarDayPress}
      />
    </View>
  );
}
```
```

--------------------------------

### Apply Border Radius to Calendar Item Day

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/tips-and-tricks.mdx

To set a border radius on `Calendar.Item.Day`, specify the radius for all four corners within the `itemDay` configuration.

```typescript
itemDay: {
  base: () => ({
    container: {
      borderTopRightRadius: 10,
      borderBottomRightRadius: 10,
      borderTopLeftRadius: 10,
      borderBottomLeftRadius: 10,
    },
  }),
}
```

--------------------------------

### Force Light Mode in Calendar

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/tips-and-tricks.mdx

Use the `calendarColorScheme` prop to override the system's theme and enforce a light mode. This is an escape hatch for apps that do not yet support dynamic themes.

```tsx
export const LightModeOnly = () => {
  const { calendarActiveDateRanges, onCalendarDayPress } = useDateRange({
    startId: "2024-02-04",
    endId: "2024-02-09",
  });

  return (
    <Calendar
      calendarActiveDateRanges={calendarActiveDateRanges}
      calendarColorScheme="light"
      calendarMonthId={toDateId(startOfThisMonth)}
      onCalendarDayPress={onCalendarDayPress}
    />
  );
};
```

--------------------------------

### Calendar Scrolling Backwards Limitation

Source: https://github.com/marceloprado/flash-calendar/blob/main/apps/docs/docs/fundamentals/limitations.mdx

Demonstrates the limitation where the calendar does not scroll past the initial month when scrolling backwards. This is due to the current implementation relying on `onEndReached` for appending months and lacking a `onStartReached` equivalent for prepending.

```tsx
export const ScrollingBackwardsLimitation = () => {
  return (
    <VStack alignItems="stretch" grow spacing={12}>
      <Text>Notice how it doesn't scroll past January</Text>

      <Calendar.List
        calendarFutureScrollRangeInMonths={1}
        calendarInitialMonthId="2024-02-01"
        calendarMaxDateId="2024-05-01"
        calendarPastScrollRangeInMonths={1}
        onCalendarDayPress={loggingHandler("onCalendarDayPress")}
      />
    </VStack>
  );
};

```

--------------------------------

### Basic Single-Month Calendar Component

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Renders a single calendar month. This is a controlled component where you manage the selected date range and handle day presses.

```tsx
import { Calendar, toDateId } from "@marceloterreiro/flash-calendar";
import { useState } from "react";
import { Text, View } from "react-native";

const today = toDateId(new Date());

export function BasicCalendar() {
  const [selectedDate, setSelectedDate] = useState(today);

  return (
    <View style={{ padding: 16 }}>
      <Text>Selected: {selectedDate}</Text>
      <Calendar
        // Required: which month to display (any YYYY-MM-DD within the month)
        calendarMonthId={today}
        // Highlight the selected date as a single-day range
        calendarActiveDateRanges={[{ startId: selectedDate, endId: selectedDate }]}
        onCalendarDayPress={setSelectedDate}
        // Optional constraints
        calendarMinDateId="2024-01-01"
        calendarMaxDateId="2025-12-31"
        // Optional disabled dates
        calendarDisabledDateIds={["2024-07-04", "2024-12-25"]}
        // Optional layout tuning
        calendarDayHeight={36}
        calendarRowVerticalSpacing={8}
        calendarRowHorizontalSpacing={8}
        calendarMonthHeaderHeight={24}
        // Week starts on Monday
        calendarFirstDayOfWeek="monday"
        // Force light/dark mode regardless of system setting
        calendarColorScheme="light"
      />
    </View>
  );
}
```

--------------------------------

### Manage Multiple Calendars with `calendarInstanceId`

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Assign a unique `calendarInstanceId` to each `<Calendar>` or `<Calendar.List>` instance when rendering multiple calendars simultaneously to prevent state leakage.

```tsx
import { Calendar, useDateRange } from "@marceloterreiro/flash-calendar";
import { View } from "react-native";

export function TwoCalendars() {
  const rangeA = useDateRange();
  const rangeB = useDateRange();

  return (
    <View style={{ gap: 32 }}>
      <Calendar
        calendarInstanceId="calendar-a"
        calendarMonthId="2024-08-01"
        calendarActiveDateRanges={rangeA.calendarActiveDateRanges}
        onCalendarDayPress={rangeA.onCalendarDayPress}
      />
      <Calendar
        calendarInstanceId="calendar-b"
        calendarMonthId="2024-09-01"
        calendarActiveDateRanges={rangeB.calendarActiveDateRanges}
        onCalendarDayPress={rangeB.onCalendarDayPress}
      />
    </View>
  );
}
```

--------------------------------

### toDateId / fromDateId

Source: https://context7.com/marceloprado/flash-calendar/llms.txt

Timezone-safe helpers to convert between Date objects and 'YYYY-MM-DD' string format. Use these to avoid date shifts caused by UTC conversion.

```APIDOC
## `toDateId(date)` / `fromDateId(dateId)`

Timezone-safe helpers that convert between `Date` objects and the `YYYY-MM-DD` string format ("date ID") used as the primary key throughout the library. Always use these instead of `.toISOString()` to avoid off-by-one date shifts caused by UTC conversion.

```tsx
import { toDateId, fromDateId } from "@marceloterreiro/flash-calendar";

// Date → "YYYY-MM-DD"
const today = toDateId(new Date());           // e.g. "2024-07-15"
const specific = toDateId(new Date(2024, 2, 14)); // "2024-03-14"

// "YYYY-MM-DD" → Date (local timezone, no UTC shift)
const date = fromDateId("2024-07-15");
console.log(date.getFullYear()); // 2024
console.log(date.getMonth());   // 6  (July, 0-indexed)
console.log(date.getDate());    // 15
```
```