### Install Calendar-Kit and FlashList

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Install the calendar-kit package along with Shopify's FlashList for efficient rendering. This is the initial setup step for using the library.

```bash
npm install @fowusu/calendar-kit @shopify/flash-list
```

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

### Basic Single-Month Calendar Setup

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Set up a simple single-month calendar component. This example shows how to manage a selected date.

```typescript
import React, { useState } from "react"
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit"

const App = () => {
  const [selectedDate, setSelectedDate] = useState<string>()

  return (
    <Calendar
      date={toLocaleDateString(new Date())}
      markedDates={selectedDate ? [selectedDate] : []}
      onDayPress={setSelectedDate}
    />
  )
}

export default App
```

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

### Install Calendar Kit

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Install the library using npm or yarn. Ensure you also install the peer dependencies.

```bash
npm install @fowusu/calendar-kit
# or
yarn add @fowusu/calendar-kit
```

```bash
npm install @shopify/flash-list react react-native
```

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

### Minimal Calendar Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Demonstrates the basic setup for using the Calendar component, including state management for day selection and date formatting.

```typescript
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit"
import { useState } from "react"

export default function App() {
  const [selected, setSelected] = useState<string>()

  return (
    <Calendar
      date={toLocaleDateString(new Date())}
      markedDates={selected ? [selected] : []}
      onDayPress={setSelected}
    />
  )
}
```

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

### Localization Example: Weekday Name Formatting

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Demonstrates retrieving an array of localized weekday names for a given locale and format. This example shows how to get long weekday names for German.

```javascript
// Weekday names
getLocaleWeekDayNames("de-DE", "long")
// ["Sonntag", "Montag", "Dienstag", ...]
```

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

### Start Calendar Kit Project

Source: https://github.com/f0wu5u/calendar-kit/blob/main/example/README.md

Run this command to start the main Calendar Kit project.

```bash
yarn start
```

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

### Install Dependencies

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using Yarn.

```bash
yarn install
```

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

### Install Calendar Kit

Source: https://github.com/f0wu5u/calendar-kit/blob/main/README.md

Install the calendar-kit package using npm, yarn, or expo.

```bash
npm install @fowusu/calendar-kit
```

```bash
yarn add @fowusu/calendar-kit
```

```bash
yarn expo add @fowusu/calendar-kit
```

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

### Install Flash List

Source: https://github.com/f0wu5u/calendar-kit/blob/main/README.md

Install the required @shopify/flash-list dependency for faster list rendering.

```bash
yarn add @shopify/flash-list
```

```bash
yarn expo add @shopify/flash-list
```

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

### Start Calendar Kit for React Native Web

Source: https://github.com/f0wu5u/calendar-kit/blob/main/example/README.md

Use this command to start the Calendar Kit project specifically for React Native web.

```bash
yarn web
```

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

### Localization Example: Month Name Formatting

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Shows how to format month names according to a specific locale using the `formatMonthName` function. This example demonstrates formatting for French.

```javascript
// Month names
formatMonthName(new Date(2024, 5), "fr-FR") // "juin 2024"
```

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

### Custom Day State Logic with Booking Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Implement custom state logic for days using 'customStateCreator'. This example defines a 'BookingState' interface and a creator function to determine booking status, availability, and price.

```typescript
import { StateInputParams, DayState } from "@fowusu/calendar-kit"

interface BookingState {
  isBooked: boolean
  hasAvailability: boolean
  price: number
}

const createBookingState = (
  params: StateInputParams,
  defaultState: DayState
): BookingState => ({
  isBooked: params.markedDates.includes(params.dateString),
  hasAvailability: Math.random() > 0.3,
  price: Math.floor(Math.random() * 300 + 50),
})

const BookingDay: React.FC<InnerDayProps<BookingState>> = ({ day, state, hasAvailability, price }) => (
  <View>
    <Text>{day.getDate()}</Text>
    {hasAvailability && <Text style={{ fontSize: 10, color: "green" }}>${price}</Text>}
  </View>
)

// Usage:
<Calendar
  date="2024-06-15"
  DayComponent={BookingDay}
  customStateCreator={createBookingState}
/>
```

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

### Clone Repository

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine to start making changes.

```bash
git clone https://github.com/your-username/your-repo-name.git
```

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

### Localization Example (Spanish with Custom Weekdays)

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Shows how to set the locale to Spanish (`es-ES`) and provide custom short weekday names.

```typescript
// Spanish with custom weekday names
<Calendar
  date="2024-06-15"
  locale="es-ES"
  weekdaysShort={["Do", "Lu", "Ma", "Mi", "Ju", "Vi", "Sa"]}
/>
```

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

### Single Month Picker Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

A simple example of a single-month calendar picker. It displays the current date and allows users to select a single day.

```typescript
<Calendar
  date={toLocaleDateString(new Date())}
  onDayPress={(date) => setSelectedDate(date)}
/>
```

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

### Horizontal Week Scroller Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

An example demonstrating a horizontal week scroller. It utilizes a ref to scroll to the current day and displays day names.

```typescript
import React, { useRef } from "react"
import { CalendarList, toLocaleDateString, CalendarListRef } from "@fowusu/calendar-kit"
import { Button, View } from "react-native"

const WeekScroller = () => {
  const ref = useRef<CalendarListRef>(null)
  const today = toLocaleDateString(new Date())

  return (
    <View>
      <Button
        onPress={() => ref.current?.scrollToDate(today, true)}
        title="Today"
      />
      <CalendarList
        ref={ref}
        currentDate={today}
        viewAs="week"
        horizontal
        showDayNames
        onDayPress={(date) => console.log("Selected:", date)}
      />
    </View>
  )
}
```

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

### Scroll Tracking Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

An example demonstrating how to track scroll events to determine the currently visible month. It uses the onScroll callback to update a state variable.

```typescript
const TrackingCalendar = () => {
  const [visibleMonth, setVisibleMonth] = useState<string>()

  return (
    <CalendarList
      currentDate={toLocaleDateString(new Date())}
      onScroll={(visibleDates) => {
        if (Array.isArray(visibleDates) && visibleDates.length > 0) {
          setVisibleMonth(visibleDates[0])
        }
      }}
      onActiveMonthChange={setVisibleMonth}
    />
  )
}
```

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

### Get Start and End of Week

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Calculates the start and end of the week for a given date, allowing specification of which day the week starts on (e.g., Sunday or Monday).

```typescript
function startOfWeek(date: Date, { weekStartsOn: DayIndex }): Date
function endOfWeek(date: Date, { weekStartsOn: DayIndex }): Date
```

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

### Localization Example (French)

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Demonstrates setting the locale to French (`fr-FR`) and using the `long` format for weekdays.

```typescript
// French calendar
<Calendar
  date="2024-06-15"
  locale="fr-FR"
  weekdaysFormat="long"
/>
```

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

### Get Start of Month Date Object

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Returns a Date object representing the first day of the month at midnight for a given Date.

```typescript
const first = startOfMonth(new Date("2024-06-15"))
// Date: 2024-06-01T00:00:00Z
```

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

### Basic Vertical Month List Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

A basic example of a vertical month list. It configures the calendar to show past and future months and handles day presses to update selected dates.

```typescript
import React, { useState } from "react"
import { CalendarList, toLocaleDateString } from "@fowusu/calendar-kit"

const MonthListCalendar = () => {
  const [selected, setSelected] = useState<string[]>([])
  const today = toLocaleDateString(new Date())

  return (
    <CalendarList
      currentDate={today}
      pastMonthsCount={3}
      futureMonthsCount={6}
      markedDates={selected}
      onDayPress={(date) => setSelected([date])}
      onActiveMonthChange={(month) => console.log("Active month:", month)}
    />
  )
}
```

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

### Conventional Commits Examples

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for different types of changes.

```bash
feat(component): add new calendar date picker
```

```bash
fix(api): resolve date parsing issue
```

```bash
docs(readme): update contributing guidelines
```

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

### Basic Calendar Usage

Source: https://github.com/f0wu5u/calendar-kit/blob/main/README.md

A basic example demonstrating how to use the Calendar component to display dates and handle day presses.

```typescript jsx
import React, { useCallback, useState } from "react";
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit";

const today = new Date();

const todayDateString = toLocaleDateString(today);

const CalendarComponent = () => {
  const [selectedDay, setSelectedDay] = useState<string>();

  const onDayPress = useCallback((dateString) => {
    setSelectedDay(dateString);
  }, []);

  return (
    <Calendar
      date={todayDateString}
      markedDates={[selectedDay]}
      onDayPress={onDayPress}
    />
  );
};

```

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

### Get Start of Month String

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Converts a date string to represent the first day of its month by replacing the day part with '01'.

```typescript
startOfMonthForDateString("2024-06-15") // "2024-06-01"
```

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

### Localization Configuration

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Shows how to configure the calendar for different locales and weekday formats. This example sets the locale to French and uses the 'long' format for weekdays.

```typescript
<Calendar date="2024-06-15" locale="fr-FR" weekdaysFormat="long" />
```

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

### Calendar List Usage

Source: https://github.com/f0wu5u/calendar-kit/blob/main/README.md

An example demonstrating the CalendarList component for displaying multiple months and handling day presses.

```typescript jsx
import React, { useCallback, useState } from "react";
import {CalendarList, toLocaleDateString} from "@fowusu/calendar-kit";

const today = new Date();
const todayDateString = toLocaleDateString(today);

const CalendarListComponent = () => {
    const [selectedDay, setSelectedDay] = useState<string>();
    
    const onDayPress = useCallback((dateString) => {
        setSelectedDay(dateString);
    }, []);

  return (
    <CalendarList
      currentDate={todayDateString}
      markedDates={[selectedDay]}
      futureMonthsCount={12}
      pastMonthsCount={0}
      onDayPress={onDayPress}
    />
  );
};

```

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

### Date Range Selection with Constraints

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

This example shows how to implement date range selection (check-in/check-out) with minimum and maximum date constraints. It dynamically marks the selected range.

```typescript
import React, { useState } from "react"
import { CalendarList, getDatesInRange, toLocaleDateString } from "@fowusu/calendar-kit"

const CheckInCheckOut = () => {
  const [checkIn, setCheckIn] = useState<string>()
  const [checkOut, setCheckOut] = useState<string>()
  
  const minDate = toLocaleDateString(new Date())
  const futureDate = new Date()
  futureDate.setMonth(futureDate.getMonth() + 3)
  const maxDate = toLocaleDateString(futureDate)

  const handleDayPress = (date: string) => {
    if (!checkIn) {
      setCheckIn(date)
    } else if (!checkOut && date > checkIn) {
      setCheckOut(date)
    } else {
      setCheckIn(date)
      setCheckOut(undefined)
    }
  }

  const markedDates = checkIn && checkOut
    ? getDatesInRange(checkIn, checkOut)
    : checkIn ? [checkIn] : []

  return (
    <CalendarList
      currentDate={minDate}
      minDate={minDate}
      maxDate={maxDate}
      pastMonthsCount={0}
      futureMonthsCount={3}
      markedDates={markedDates}
      onDayPress={handleDayPress}
    />
  )
}
```

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

### Configure Week View

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Customize the week view with options like 'firstDayOfWeek', 'showDayNames', and 'viewAs="week"'. This example sets Monday as the first day and enables day names.

```typescript
<Calendar
  date="2024-06-15"
  viewAs="week"
  firstDayOfWeek={1}
  showDayNames
  contentContainerStyle={{
    width: "100%",
    scrollSnapAlign: "center",
  }}
/>
```

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

### Calendar Localization Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/Calendar.md

Configure the calendar to display dates and weekdays in a specific locale, such as French. Ensure the `locale` prop is set to the desired IETF language tag.

```typescript
const LocalizedCalendar = () => (
  <Calendar
    date="2024-06-15"
    locale="fr-FR"
    weekdaysFormat="long"
  />
)
```

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

### Scrollable Month List Setup

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Implement a scrollable calendar list component. This allows users to navigate through multiple months and select a date.

```typescript
import React, { useState } from "react"
import { CalendarList, toLocaleDateString } from "@fowusu/calendar-kit"

const App = () => {
  const [selectedDate, setSelectedDate] = useState<string>()

  return (
    <CalendarList
      currentDate={toLocaleDateString(new Date())}
      pastMonthsCount={6}
      futureMonthsCount={6}
      markedDates={selectedDate ? [selectedDate] : []}
      onDayPress={setSelectedDate}
    />
  )
}

export default App
```

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

### Create Month Date Range

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Generates an array of month date strings for a range relative to a start date. Specify the start month, and the number of past and future months to include.

```typescript
import { createRange } from "@fowusu/calendar-kit/dist/utils/date"

const months = createRange({
  startMonth: "2024-06-01",
  pastMonthsCount: 2,
  futureMonthsCount: 2,
})
// ["2024-04-01", "2024-05-01", "2024-06-01", "2024-07-01", "2024-08-01"]
```

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

### Date Range Picker Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Illustrates how to select a range of dates for check-in and check-out using the CalendarList component. It requires a helper function `getDatesInRange` to generate the marked dates.

```typescript
const markedDates = getDatesInRange(checkIn, checkOut)
<CalendarList markedDates={markedDates} onDayPress={handleDayPress} />
```

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

### Date Normalization Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Use `toLocaleDateString()` and `dateStringToDate()` for consistent date handling across timezones. Avoid `toISOString().split('T')[0]` as it can lead to timezone shifts.

```typescript
// Good
const str = toLocaleDateString(date)
const date2 = dateStringToDate(str)

// Bad (timezone may shift)
const str = date.toISOString().split("T")[0]
```

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

### DayIndex

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/types.md

Represents the day of the week as a numeric index (0 = Sunday, 1 = Monday, etc.). Used to configure which day the week starts on.

```APIDOC
## Type: DayIndex

### Description
Represents the day of the week as a numeric index (0 = Sunday, 1 = Monday, etc.). Used to configure which day the week starts on.

### Type Definition
```typescript
type DayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6
```

### Usage
Used in: `Calendar`, `CalendarList`, date utility functions like `startOfWeek`, `endOfWeek`
```

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

### createRange

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Generates an array of month date strings for a range relative to a start date. It allows specifying past and future months to include.

```APIDOC
## createRange

### Description
Generates an array of month date strings for a range relative to a start date. It allows specifying past and future months to include.

### Signature
```typescript
function createRange({
  startMonth?: string,
  pastMonthsCount?: number,
  futureMonthsCount?: number
}): string[];
```

### Parameters
#### Object Parameters
- **startMonth** (string) - Optional - Start month in `YYYY-MM-DD` format. Defaults to Today.
- **pastMonthsCount** (number) - Optional - Months to include before start. Defaults to `0`.
- **futureMonthsCount** (number) - Optional - Months to include after start. Defaults to `12`.

### Returns
Array of month strings (e.g., `["2024-01-01", "2024-02-01", ...]`)

### Example
```typescript
import { createRange } from "@fowusu/calendar-kit/dist/utils/date"

const months = createRange({
  startMonth: "2024-06-01",
  pastMonthsCount: 2,
  futureMonthsCount: 2,
})
// ["2024-04-01", "2024-05-01", "2024-06-01", "2024-07-01", "2024-08-01"]
```
```

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

### Override Weekday Short Names

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Provide custom short names for weekdays. This example sets English abbreviations for each day of the week.

```typescript
<Calendar
  date="2024-06-15"
  weekdaysShort={["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]}
/>
```

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

### Scrollable Month List Example

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Renders a scrollable list of months using the `CalendarList` component. It configures the number of past and future months to display and logs the selected day.

```typescript
<CalendarList
  currentDate={toLocaleDateString(new Date())}
  pastMonthsCount={6}
  futureMonthsCount={6}
  onDayPress={(date) => console.log(date)}
/>
```

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

### Custom Day Component Implementation

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Create a custom day component to override the default rendering of calendar days. This example shows how to display available slots as a badge.

```typescript
import { InnerDayProps } from "@fowusu/calendar-kit"
import { View, Text, StyleSheet } from "react-native"

interface CustomDayProps {
  availableSlots?: number
}

const CustomDay: React.FC<InnerDayProps<CustomDayProps>> = ({
  day,
  state,
  isSelected,
  isToday,
  availableSlots = 5,
}) => {
  const backgroundColor = isSelected
    ? "#2196F3"
    : isToday
    ? "#E3F2FD"
    : state === "inactive"
    ? "#F5F5F5"
    : "white"

  const textColor = state === "inactive" ? "#BDBDBD" : isSelected ? "white" : "black"

  return (
    <View style={[styles.container, { backgroundColor }]}>
      <Text style={[styles.dayText, { color: textColor }]}>{day.getDate()}</Text>
      {state === "active" && availableSlots < 3 && (
        <Text style={styles.badge}>{availableSlots}</Text>
      )}
    </View>
  )
}

const styles = StyleSheet.create({
  container: {
    padding: 8,
    alignItems: "center",
    borderRadius: 4,
  },
  dayText: {
    fontWeight: "600",
  },
  badge: {
    fontSize: 10,
    color: "#FF9800",
    marginTop: 2,
  },
})
```

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

### Programmatic Scrolling with CalendarListRef

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

Example of using the CalendarListRef to programmatically scroll to a specific date. Ensure the ref is correctly attached to the CalendarList component.

```typescript
const calendarRef = useRef<CalendarListRef>(null)

return (
  <>
    <CalendarList ref={calendarRef} ... />
    <Button
      onPress={() => calendarRef.current?.scrollToDate("2024-12-25", true)}
      title="Jump to Christmas"
    />
  </>
)
```

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

### Custom Day Component Implementation

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/internal-components.md

Example of a custom day component using InnerDayProps. It demonstrates conditional styling based on state, selection, and today's date, and utilizes React.memo for performance.

```typescript
import React from "react"
import { InnerDayProps, dateStringToDate } from "@fowusu/calendar-kit"

const MyDay = React.memo(({ day, state, isSelected, isToday }: InnerDayProps<{}>) => (
  <View
    style={{
      opacity: state === "inactive" ? 0.5 : 1,
      backgroundColor: isSelected ? "blue" : isToday ? "lightblue" : "white",
    }}
  >
    <Text>{day.getDate()}</Text>
  </View>
))
```

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

### Custom Weekday Names

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Customize the displayed weekday names using the 'weekdaysShort' prop. This example sets short, single-letter abbreviations for Spanish weekdays.

```typescript
<Calendar
  date="2024-06-15"
  locale="es-ES"
  weekdaysFormat="long"
  weekdaysShort={["D", "L", "M", "X", "J", "V", "S"]}
/>
```

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

### Week View Scrolling Setup

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

For the week view to scroll correctly, the parent container must have a defined height. This ensures the `Calendar` component has a bounded area to scroll within.

```typescript
<View style={{ height: 200 }}>
  <Calendar viewAs="week" />
</View>
```

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

### Create Weeks of Month

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Generates an array of week date strings for a specific month. Each element in the returned array is another array of 7 date strings representing a week. Optionally specify the day the week starts on.

```typescript
const weeks = createWeeksOfMonth(new Date(2024, 5, 15), 1) // 0-indexed months
// [
//   ["2024-06-03", "2024-06-04", ..., "2024-06-09"],
//   ["2024-06-10", "2024-06-11", ..., "2024-06-16"],
//   ...
// ]
```

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

### Generate Date Range Strings

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Returns an array of date strings in YYYY-MM-DD format for every day between a start and end date (inclusive). Useful for highlighting date ranges or iterating over a period. Throws errors for invalid date strings or an invalid date range.

```typescript
import { getDatesInRange } from "@fowusu/calendar-kit"

const dates = getDatesInRange("2024-06-10", "2024-06-15")
// ["2024-06-10", "2024-06-11", "2024-06-12", "2024-06-13", "2024-06-14", "2024-06-15"]

// Use case: highlight a date range
const [checkIn, checkOut] = ["2024-06-10", "2024-06-15"]
const markedDates = getDatesInRange(checkIn, checkOut)
```

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

### Handle 'Invalid date range' Error

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/errors.md

Demonstrates catching the 'Invalid date range' error when the start date is after the end date. This example uses a try-catch block to manage invalid range inputs.

```typescript
import { getDatesInRange } from "@fowusu/calendar-kit"

try {
  // Start is after end
  getDatesInRange("2024-06-20", "2024-06-10")
} catch (e) {
  console.error(e.message) // "Invalid date range"
}
```

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

### Safely Get Days in Range

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/errors.md

A utility function to safely retrieve days within a specified date range, returning an empty array if an 'Invalid start or end date' error occurs. This ensures robust handling of date range operations.

```typescript
function safeGetDaysInRange(startDate: Date, endDate: Date): Date[] {
  try {
    return eachDayOfInterval({ start: startDate, end: endDate })
  } catch (e) {
    console.error("Invalid date range provided")
    return []
  }
}
```

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

### Package.json Entry Points

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/exports.md

Defines the main, module, and types entry points for the calendar-kit package in package.json.

```json
{
  "main": "dist/index.js",
  "module": "dist/index.mjs",
  "types": "dist/index.d.ts"
}
```

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

### Run Tests

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Execute the project's test suite to ensure your changes do not introduce regressions.

```bash
yarn test
```

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

### Handle 'Invalid start or end date' Error

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/errors.md

Shows how to catch and handle the 'Invalid start or end date' error when using interval functions with invalid Date objects. A try-catch block is used to manage potential errors.

```typescript
import { eachDayOfInterval } from "@fowusu/calendar-kit"

try {
  eachDayOfInterval({
    start: new Date("invalid"),
    end: new Date("2024-06-15"),
  })
} catch (e) {
  console.error(e.message) // "Invalid start or end date"
}
```

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

### Import Internal Date Utilities

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Demonstrates how to directly import internal date utility functions like `addMonths` and `createRange` from the library's utility directory. These are stable but not part of the public API.

```typescript
// Direct imports
import { addMonths, createRange } from "@fowusu/calendar-kit/dist/utils/date"
```

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

### getWeeksInMonth

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Counts the total number of weeks within a given month, with an option to specify the start of the week.

```APIDOC
## getWeeksInMonth

### Description
Counts the number of weeks in a month.

### Signature
```typescript
function getWeeksInMonth(month: string, startOfWeek?: DayIndex): number;
```

### Parameters
- **month** (string) - The month string in `YYYY-MM-DD` format.
- **startOfWeek** (DayIndex) - Optional - Specifies the starting day of the week.

### Returns
The number of weeks in the specified month.
```

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

### Basic Import Pattern

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/exports.md

Importing core components and date utilities for basic usage of the calendar-kit package.

```typescript
import {
  Calendar,
  CalendarList,
  toLocaleDateString,
  dateStringToDate,
} from "@fowusu/calendar-kit"
```

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

### isSameWeek

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Checks if two Date objects fall within the same calendar week, with an option to specify the starting day of the week.

```APIDOC
## isSameWeek

### Description
Checks if two dates fall in the same week.

### Signature
```typescript
function isSameWeek(
  date: Date,
  dateToCompare: Date,
  { weekStartsOn?: DayIndex }
): boolean;
```

### Parameters
- **date** (Date) - The first date.
- **dateToCompare** (Date) - The second date to compare.
- **weekStartsOn** (DayIndex) - Optional - Specifies the starting day of the week.

### Returns
`true` if both dates fall within the same week, `false` otherwise.
```

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

### Date Range Selection (Check-in/Check-out)

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Illustrates how to implement a date range selection feature using `CalendarList`, `minDate`, and `getDatesInRange` to mark the selected check-in and check-out dates.

```typescript
const [checkIn, setCheckIn] = useState<string>()
const [checkOut, setCheckOut] = useState<string>()

const markedDates = checkIn && checkOut
  ? getDatesInRange(checkIn, checkOut)
  : checkIn ? [checkIn] : []

<CalendarList
  minDate={toLocaleDateString(new Date())}
  markedDates={markedDates}
  onDayPress={(date) => {
    if (!checkIn) setCheckIn(date)
    else if (date > checkIn) setCheckOut(date)
  }}
/>
```

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

### Basic Calendar Component Usage

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Demonstrates how to render a basic calendar component and handle day selection. It initializes the calendar to the current date and updates a state variable when a day is pressed.

```typescript
import React, { useState } from "react"
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit"

export default function App() {
  const [selected, setSelected] = useState<string>()

  return (
    <Calendar
      date={toLocaleDateString(new Date())}
      markedDates={selected ? [selected] : []}
      onDayPress={setSelected}
    />
  )
}
```

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

### Get End of Month Date Object

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Returns a Date object representing the last day of the month at 23:59:59 for a given Date.

```typescript
const last = endOfMonth(new Date("2024-06-15"))
// Date: 2024-06-30T23:59:59Z
```

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

### Import Pattern with Types

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/exports.md

Importing components, types, and date utilities for usage requiring type definitions from the calendar-kit package.

```typescript
import {
  Calendar,
  CalendarList,
  DayIndex,
  DayState,
  InnerDayProps,
  CalendarListRef,
  toLocaleDateString,
} from "@fowusu/calendar-kit"
```

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

### Main Entry Point Exports

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/exports.md

Exports from the main entry point of the calendar-kit package, including components, hooks, and utility functions.

```typescript
// Main entry point
export * from "./components"
export { useRenderCount } from "./hooks/useRenderCount"
export * from "./types"
export {
  dateStringToDate,
  getDatesInRange,
  toLocaleDateString,
} from "./utils/date"
export { getDayState } from "./utils/getDayState"
```

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

### Date String Conversion Utilities

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Shows how to use `toLocaleDateString` to convert a Date object to an ISO 8601-like string and `dateStringToDate` to parse such strings back into Date objects.

```typescript
import { toLocaleDateString, dateStringToDate } from "@fowusu/calendar-kit"

// Convert Date → string
const str = toLocaleDateString(new Date()) // "2024-06-15"

// Convert string → Date
const date = dateStringToDate("2024-06-15") // Date at noon UTC
```

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

### Custom Styling with DayComponent

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Shows how to customize the appearance of individual days by providing a custom `DayComponent` and applying container styles.

```typescript
const CustomDay = ({ day, state, isSelected }) => (
  <View
    style={{
      backgroundColor: isSelected ? "#2196F3" : "white",
      opacity: state === "inactive" ? 0.5 : 1,
    }}
  >
    <Text>{day.getDate()}</Text>
  </View>
)

<Calendar
  DayComponent={CustomDay}
  contentContainerStyle={{ padding: 16, backgroundColor: "#f5f5f5" }}
/>
```

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

### DayIndex Type Definition

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/types.md

Defines the numeric index for days of the week, where 0 represents Sunday. This type is used to specify the starting day of the week.

```typescript
type DayIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6
```

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

### Date Formatting Utilities

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Shows how to convert JavaScript Date objects to ISO 8601 strings and vice-versa using utility functions. These are essential for managing dates within the calendar components.

```typescript
import { toLocaleDateString, dateStringToDate } from "@fowusu/calendar-kit"

// JavaScript Date → string
const dateString = toLocaleDateString(new Date()) // "2024-06-15"

// string → JavaScript Date
const date = dateStringToDate("2024-06-15")       // Date at noon UTC
```

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

### CalendarListRef Methods

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/CalendarList.md

This section details the methods available through the CalendarList ref, allowing for programmatic control of the calendar.

```APIDOC
## CalendarListRef Methods

Use the ref to programmatically scroll the calendar.

### Methods

- **scrollToDate** (dateString: string, animated?: boolean) => void
  - Scrolls the calendar to the specified date.
  - `dateString`: The target date to scroll to. Format: `YYYY-MM-DD`.
  - `animated`: If true, the scroll animation is enabled. Defaults to false.
```

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

### Compare Dates: Same Week

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Determines if two Date objects fall within the same calendar week. An optional configuration object can specify the starting day of the week.

```typescript
function isSameWeek(
  date: Date,
  dateToCompare: Date,
  { weekStartsOn?: DayIndex }
): boolean
```

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

### Basic Month View Calendar

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/Calendar.md

Renders a basic month view calendar. It uses local state to manage the selected date and highlights it. The calendar is initialized to the current date.

```typescript
import React, { useState } from "react"
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit"

const MyCalendar = () => {
  const [selected, setSelected] = useState<string>()
  const today = toLocaleDateString(new Date())

  return (
    <Calendar
      date={today}
      markedDates={selected ? [selected] : []}
      onDayPress={setSelected}
    />
  )
}
```

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

### VIEWABILITY_CONFIG for FlashList/FlatList

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/internal-components.md

Configuration object for FlashList/FlatList to determine item viewability. It specifies minimum time visible and the percentage of the item that must be visible to be considered viewable.

```typescript
const VIEWABILITY_CONFIG = {
  minimumViewTime: 250,
  itemVisiblePercentThreshold: 25,
}
```

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

### Stage and Commit Changes

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Stage all modified files and commit them with a descriptive message following Conventional Commits style.

```bash
git add .
git commit -m "Your detailed description of the change."
```

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

### Custom Day Component Styling

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/README.md

Demonstrates how to apply custom styling to the calendar by providing a `CustomDay` component and overriding `contentContainerStyle`. This allows for extensive visual customization.

```typescript
<Calendar
  DayComponent={CustomDay}
  contentContainerStyle={{ backgroundColor: "#f5f5f5", padding: 16 }}
/>
```

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

### Get Locale Weekday Names

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Retrieves an array of weekday names for a specified locale. You can choose the format for the names: 'long', 'short', or 'narrow'. The default format is 'short'.

```typescript
getLocaleWeekDayNames("en-US", "short")
// ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]

getLocaleWeekDayNames("fr-FR", "long")
// ["dimanche", "lundi", "mardi", "mercredi", "jeudi", "vendredi", "samedi"]
```

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

### createWeeksOfMonth, createWeeksInRange

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/date-utilities.md

Generate arrays of week date strings for a month or date range. Each element is an array of 7 date strings representing a week.

```APIDOC
## createWeeksOfMonth, createWeeksInRange

### Description
Generate arrays of week date strings for a month or date range. Each element is an array of 7 date strings representing a week.

### Signatures
```typescript
function createWeeksOfMonth(date: Date, weekStartsOn?: DayIndex): string[][]
function createWeeksInRange(startDate: Date, endDate: Date, weekStartsOn?: DayIndex): string[][]
```

### Parameters
#### `createWeeksOfMonth`
- **date** (Date) - The date to generate weeks for.
- **weekStartsOn** (DayIndex) - Optional - Specifies the starting day of the week.

#### `createWeeksInRange`
- **startDate** (Date) - The start date of the range.
- **endDate** (Date) - The end date of the range.
- **weekStartsOn** (DayIndex) - Optional - Specifies the starting day of the week.

### Returns
Array of arrays, where each inner array contains 7 date strings representing a week.

### Example
```typescript
const weeks = createWeeksOfMonth(new Date(2024, 5, 15), 1) // 0-indexed months
// [
//   ["2024-06-03", "2024-06-04", ..., "2024-06-09"],
//   ["2024-06-10", "2024-06-11", ..., "2024-06-16"],
//   ...
// ]
```
```

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

### Web Support: Conditional Horizontal Scrolling

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Adapt 'CalendarList' behavior for web platforms. This example disables horizontal scrolling and sets the calendar width to '100%' when running on the web.

```typescript
import { Platform } from "react-native"

const isWeb = Platform.OS === "web"

<CalendarList
  horizontal={isWeb ? false : true}
  calendarWidth={isWeb ? "100%" : undefined}
/>
```

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

### Date Range Picker (Check-in/Check-out)

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Configure a calendar for selecting a date range, such as for check-in and check-out dates. The `getDatesInRange` utility is used to mark the selected range.

```typescript
import React, { useState } from "react"
import { CalendarList, getDatesInRange, toLocaleDateString } from "@fowusu/calendar-kit"

const CheckInCheckOut = () => {
  const [checkIn, setCheckIn] = useState<string>()
  const [checkOut, setCheckOut] = useState<string>()

  const handleDayPress = (date: string) => {
    if (!checkIn) {
      setCheckIn(date)
      setCheckOut(undefined)
    } else if (!checkOut) {
      if (date > checkIn) {
        setCheckOut(date)
      } else {
        setCheckIn(date)
      }
    } else {
      setCheckIn(date)
      setCheckOut(undefined)
    }
  }

  const markedDates = 
    checkIn && checkOut ? getDatesInRange(checkIn, checkOut) : checkIn ? [checkIn] : []

  return (
    <CalendarList
      currentDate={toLocaleDateString(new Date())}
      minDate={toLocaleDateString(new Date())}
      markedDates={markedDates}
      onDayPress={handleDayPress}
    />
  )
}
```

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

### Get Day State

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/utility-functions.md

Computes the visual and interaction state of a single calendar day. Use this to determine if a day is active, inactive, selected, or today based on various constraints.

```typescript
function getDayState(params: StateInputParams): DayState
```

```typescript
{ state: "active" | "inactive"      // interactive state
  isVisible: boolean                 // whether to render the day
  isSelected?: boolean               // whether in markedDates
  isToday: boolean                   // whether equals today
}
```

```typescript
import { getDayState, toLocaleDateString } from "@fowusu/calendar-kit"

const today = toLocaleDateString(new Date())
const tomorrow = toLocaleDateString(new Date(Date.now() + 86400000))

const state = getDayState({
  dateString: tomorrow,
  month: new Date(),
  markedDates: [],
  minDate: today,
  maxDate: undefined,
  showExtraDays: true,
})

console.log(state)
// { state: "active", isVisible: true, isSelected: false, isToday: false }
```

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

### Push Changes to Fork

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Push your committed changes to your forked repository on GitHub.

```bash
git push origin your-branch-name
```

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

### Week View Calendar with Date Constraints

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/Calendar.md

Renders a week view calendar with specific date constraints. It sets the minimum selectable date to today and the maximum to the first day of the next month. A callback logs the selected date to the console.

```typescript
import React from "react"
import { Calendar, toLocaleDateString } from "@fowusu/calendar-kit"

const BookingCalendar = () => {
  const today = new Date()
  const nextMonth = new Date(today.getFullYear(), today.getMonth() + 1, 1)
  
  return (
    <Calendar
      date={toLocaleDateString(today)}
      viewAs="week"
      minDate={toLocaleDateString(today)}
      maxDate={toLocaleDateString(nextMonth)}
      onDayPress={(date) => console.log("Selected:", date)}
    />
  )
}
```

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

### Change Calendar Locale

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/configuration.md

Set the calendar's locale using the 'locale' prop with a BCP 47 language tag. This example shows how to set the locale to French, German, and Arabic.

```typescript
// French
<Calendar date="2024-06-15" locale="fr-FR" />

// German
<Calendar date="2024-06-15" locale="de-DE" />

// Arabic (RTL automatically handled)
<Calendar date="2024-06-15" locale="ar-SA" />
```

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

### Create New Branch

Source: https://github.com/f0wu5u/calendar-kit/blob/main/CONTRIBUTING.md

Create a new branch for your contribution to keep your changes isolated.

```bash
git checkout -b your-branch-name
```

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

### Custom Day Component in React Native

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/api-reference/Calendar.md

Render custom UI for each day in the calendar, including conditional elements like booking indicators. This example uses `InnerDayProps` to access day details and custom state.

```typescript
import React from "react"
import { Calendar, toLocaleDateString, InnerDayProps } from "@fowusu/calendar-kit"
import { View, Text } from "react-native"

interface CustomDayProps {
  isBooked?: boolean
}

const CustomDay: React.FC<InnerDayProps<CustomDayProps>> = ({
  day,
  state,
  isToday,
  isBooked,
}) => (
  <View style={{ opacity: state === "inactive" ? 0.5 : 1 }}>
    <Text style={{ fontWeight: isToday ? "bold" : "normal" }}>
      {day.getDate()}
    </Text>
    {isBooked && <Text style={{ fontSize: 8 }}>●</Text>}
  </View>
)

const MyCalendar = () => {
  return (
    <Calendar
      date={toLocaleDateString(new Date())}
      DayComponent={CustomDay}
      customStateCreator={(params, defaultState) => ({
        isBooked: params.markedDates.includes(params.dateString),
      })}
    />
  )
}
```

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

### Calendar Props

Source: https://github.com/f0wu5u/calendar-kit/blob/main/API_REFERENCE.md

Configuration options for the Calendar component.

```APIDOC
## Calendar Props

### `viewAs`

- **Type**: <small>`<'week', 'month'>?`</small>
- **Description**: Toggle calendar view between weeks list or full month.
- **Default**: `month`

### `WeekAnimatedTransitionComponent`

- **Type**: <small>`React.ComponentType<{ React.PropsWithChildren }>?`</small>
- **Description**: Custom component to wrap weekly calendar view useful when you need to animate entry and exit transitions of weekly calendar component during toggle of `viewAs`.
- **Default**: `React.Fragment`

### `weekContainerStyle`

- **Type**: <small>`ViewStyle?`</small>
- **Description**: `ViewStyle` for each week `row` on the calendar.
- **Default**: `undefined`

### `WeekDayNameComponent`

- **Type**: <small>`React.ComponentType<{ weekDays: string[] }>`</small>
- **Description**: Custom component to render calendar's week day names.
- **Default**: `undefined`

### `weekdaysFormat`

- **Type**: <small>`<'long', 'short', 'narrow'>`</small>
- **Description**: Format option for week day names.
  - `short = ['Mon', 'Tue', ..., 'Sun']`
  - `long = ['Monday', 'Tuesday', ..., 'Sunday']`
  - `narrow = ['M', 'T', ..., 'S']`
- **Default**: `undefined`

### `weekdaysShort`

- **Type**: <small>`string[]?`</small>
- **Description**: Custom names for week days.
  - **Caution**: This overrides the default localized week day names.
- **Default**: `undefined`

### `weeksContainerStyle`

- **Type**: <small>`ViewStyle?`</small>
- **Description**: `ViewStyle` for parent view component of all week `rows` on the calendar. Useful when you need to apply styling to all weeks in the calendar.
- **Default**: `undefined`
```

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

### Date Normalization to UTC Noon

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Illustrates how date strings are normalized to UTC noon to prevent timezone-related rendering issues. This ensures consistent date handling across different environments.

```javascript
const date = dateStringToDate("2024-06-15")
console.log(date.toISOString()) // "2024-06-15T12:00:00.000Z"
```

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

### Safely Compute Date Range

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/errors.md

A utility function that safely computes a date range, handling both invalid date formats and cases where the start date is after the end date. It returns an empty array upon encountering errors.

```typescript
function safeGetDateRange(
  checkIn: string,
  checkOut: string
): string[] {
  if (checkIn > checkOut) {
    console.error("Check-out date must be after check-in date")
    return []
  }

  try {
    return getDatesInRange(checkIn, checkOut)
  } catch (e) {
    console.error("Failed to compute date range")
    return []
  }
}
```

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

### Weekdays Format Options

Source: https://github.com/f0wu5u/calendar-kit/blob/main/API_REFERENCE.md

Defines the format for displaying week day names. Options include 'long', 'short', and 'narrow'.

```javascript
short = ['Mon', 'Tue', ..., 'Sun']
```

```javascript
long = ['Monday', 'Tuesday', ..., 'Sunday']
```

```javascript
narrow = ['M', 'T', ..., 'S']
```

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

### Core API Exports

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/overview.md

Lists the main components, types, date utilities, state computation functions, and hooks exported by the Calendar-Kit package.

```typescript
import { Calendar } from "./components"
export { CalendarList } from "./components"

export type { DayIndex, DayState, InnerDayProps, StateInputParams, CalendarListRef }

export { toLocaleDateString, dateStringToDate, getDatesInRange }

export { getDayState }

export { useRenderCount }
```

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

### Advanced Import Pattern for Date Utilities

Source: https://github.com/f0wu5u/calendar-kit/blob/main/_autodocs/exports.md

Importing specific date utility functions directly from the utils/date module for advanced usage.

```typescript
import {
  createWeeksOfMonth,
  formatMonthName,
  startOfMonth,
} from "@fowusu/calendar-kit/dist/utils/date"
```