### Install @super-calendar/core dependencies

Source: https://super-calendar.afonsojramos.me/guides/headless

Install the core engine and date-fns for date manipulation.

```bash
npm install @super-calendar/core date-fns
```

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

### Install @super-calendar/dom dependencies

Source: https://super-calendar.afonsojramos.me/guides/dom

Commands to install the required packages using npm or pnpm.

```bash
npm install @super-calendar/dom react react-dom @legendapp/list date-fns
```

```bash
pnpm add @super-calendar/dom react react-dom @legendapp/list date-fns
```

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

### Install package and peer dependencies

Source: https://super-calendar.afonsojramos.me/quickstart

Install the required dependencies for the calendar to function in a React Native environment.

```bash
npx expo install @super-calendar/native react-native-reanimated react-native-gesture-handler react-native-worklets @legendapp/list date-fns
```

```bash
pnpm add @super-calendar/native react-native-reanimated react-native-gesture-handler react-native-worklets @legendapp/list date-fns
```

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

### Install web dependencies

Source: https://super-calendar.afonsojramos.me/guides/web

Install the required peer dependencies to enable React Native web support.

```bash
npx expo install react-dom react-native-web @expo/metro-runtime
```

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

### Adding haptics on drag start

Source: https://super-calendar.afonsojramos.me/guides/dragging

Use the onDragStart callback to trigger haptic feedback when an event is initially picked up.

```tsx
import * as Haptics from "expo-haptics";

<Calendar
  /* ... */
  onDragStart={() => {
    void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
  }}
/>;
```

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

### Implementing a basic week grid in Super Calendar

Source: https://super-calendar.afonsojramos.me/migrating-from-calendar-kit

A minimal example showing the controlled component pattern using date state and event handlers.

```tsx
import { useState } from "react";
import { Calendar, type CalendarEvent } from "@super-calendar/native";

export function Schedule({ events }: { events: CalendarEvent[] }) {
  const [date, setDate] = useState(() => new Date());
  return (
    <Calendar
      mode="week"
      date={date}
      onChangeDate={setDate}
      events={events}
      onPressEvent={(event) => console.log(event.title)}
      onDragEvent={(event, start, end) => console.log("moved", event.title, start, end)}
    />
  );
}
```

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

### Configure a basic week view calendar

Source: https://super-calendar.afonsojramos.me/guides/time-grid

Initializes a calendar in week mode, starting the scroll position at 8:00 AM.

```tsx
<Calendar
  mode="week"
  date={date}
  events={events}
  scrollOffsetMinutes={8 * 60} // open scrolled to 8am
  onChangeDate={setDate}
/>
```

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

### Implement a DateRangePicker

Source: https://super-calendar.afonsojramos.me/guides/date-picker

A controlled date range input that manages start and end selection.

```tsx
import { useState } from "react";
import { type DateRange, DateRangePicker } from "@super-calendar/dom";

function Field() {
  const [range, setRange] = useState<DateRange | null>(null);
  return <DateRangePicker value={range} onChange={setRange} weekStartsOn={1} />;
}
```

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

### Reschedule events in month mode

Source: https://super-calendar.afonsojramos.me/guides/dragging

Implement event rescheduling by using the onDragEvent prop to update event start and end times.

```tsx
<Calendar
  mode="month"
  /* ... */
  onDragEvent={(event, start, end) =>
    setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e)))
  }
/>
```

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

### Rejecting a drag event

Source: https://super-calendar.afonsojramos.me/guides/dragging

Return false from onDragEvent to prevent a drop. This example demonstrates using expo-haptics to provide feedback when a drop is rejected due to overlaps.

```tsx
import * as Haptics from "expo-haptics";

onDragEvent={(event, start, end) => {
  if (overlapsAnother(event, start, end)) {
    void Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
    return false;
  }
  setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e)));
}}
```

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

### Basic Month View Implementation

Source: https://super-calendar.afonsojramos.me/guides/month-view

Standard configuration for rendering a month grid with date navigation.

```tsx
<Calendar
  mode="month"
  date={date}
  events={events}
  onChangeDate={setDate}
  onPressDay={(day) => {
    setDate(day);
    setMode("day");
  }}
/>
```

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

### Initialize Calendar Component

Source: https://super-calendar.afonsojramos.me/guides/dom

Basic implementation of the Calendar component using the week mode and event handling.

```tsx
import { Calendar, type CalendarEvent } from "@super-calendar/dom";

const events: CalendarEvent[] = [
  { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) },
];

export function App() {
  return (
    <Calendar
      mode="week"
      date={new Date()}
      events={events}
      weekStartsOn={1}
      height={520}
      onPressEvent={(event) => console.log(event.title)}
    />
  );
}
```

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

### Enable keyboard day navigation in month view

Source: https://super-calendar.afonsojramos.me/guides/dom

Adds roving day focus to a month view, allowing users to select days via keyboard. Requires the keyboardDayNavigation prop and an onPressDay handler.

```tsx
import { Calendar, type CalendarEvent } from "@super-calendar/dom";

const events: CalendarEvent[] = [
  { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) },
];

// Month view where arrow keys also move a roving day focus (Enter opens the day).
<Calendar
  mode="month"
  date={new Date()}
  events={events}
  keyboardDayNavigation
  onPressDay={(day) => console.log("open day", day)}
/>;
```

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

### Render a schedule view with Calendar

Source: https://super-calendar.afonsojramos.me/guides/schedule

Basic implementation of the schedule mode using the Calendar component.

```tsx
<Calendar mode="schedule" date={date} events={events} onChangeDate={setDate} />
```

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

### Create events via drag

Source: https://super-calendar.afonsojramos.me/guides/dragging

Use the onCreateEvent prop to handle event creation by dragging on empty grid space.

```tsx
<Calendar
  /* ... */
  onCreateEvent={(start, end) =>
    setEvents((prev) => [...prev, { id: makeId(), title: "New event", start, end }])
  }
/>
```

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

### Porting Prompt for Coding Agents

Source: https://super-calendar.afonsojramos.me/coming-from-react-big-calendar

A set of instructions to provide to an AI coding agent for automating the migration from react-big-calendar to super-calendar.

```text
You are porting a react-big-calendar app to super-calendar. On the web import
from `@super-calendar/dom`; on React Native import from `@super-calendar/native`
(add Reanimated v4, Gesture Handler, Worklets, @legendapp/list v3, date-fns and
wrap the app in <GestureHandlerRootView>). Rewrite the calendar element rather
than renaming a localizer.

1. Drop the `localizer`. Pass `weekStartsOn` and, for non-English, a date-fns
   `Locale` as `locale`. Ensure event `start`/`end` are Date objects (not the
   accessor strings); fold startAccessor/endAccessor/titleAccessor into the event
   shape { start, end, title, ...yourFields }.
2. Replace `view`/`onView` with `mode`, and `date`/`onNavigate` with `date` +
   `onChangeDate`. Map views: month->"month", week->"week", day->"day",
   agenda->"schedule".
3. Handlers: onSelectEvent -> onPressEvent; onSelectSlot -> onCreateEvent (drag)
   and onPressCell/onPressDay (tap).
4. Drag/resize: remove the withDragAndDrop HOC and onEventDrop/onEventResize; add
   onDragEvent(event, start, end) (return false to reject). Set eventOverlap={false}
   to block overlaps declaratively.
5. Custom rendering: components.event -> a `renderEvent` component;
   components.toolbar -> your own controls or `headerComponent`; eventPropGetter/
   dayPropGetter -> eventCellStyle/calendarCellStyle (and per-slot `classNames`
   on the web renderer).
6. Time-grid bounds min/max -> minHour/maxHour.
7. Recurrence: react-big-calendar has none; if you expanded rules yourself, use
   `expandRecurringEvents(events, rangeStart, rangeEnd)` over the visible range.
8. Note react-big-calendar treats the end date as exclusive; check all-day and
   multi-day spans render as you expect and adjust the end if needed.

Then run the app and verify views, selection, event placement, and drag.
```

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

### Migration prompt for coding agents

Source: https://super-calendar.afonsojramos.me/migrating-from-calendar-kit

A comprehensive prompt designed for AI coding assistants to automate the migration process from @howljs/calendar-kit to @super-calendar/native.

```text
You are migrating a React Native app from `@howljs/calendar-kit` to
`@super-calendar/native`. They overlap on the time-grid views (day/3-day/week),
resources, and drag, but the component shape is different, so rewrite the
calendar layer rather than renaming props. Make the smallest changes that
compile and preserve the current behaviour.

1. Dependencies
   - Remove `@howljs/calendar-kit`.
   - Add `@super-calendar/native` and its peers: `react-native-reanimated` (v4),
     `react-native-gesture-handler`, `react-native-worklets`, `@legendapp/list`
     (v3), and `date-fns`. On Expo use `npx expo install`. Keep
     `<GestureHandlerRootView style={{ flex: 1 }}>` at the app root.

2. Component shape
   - Replace the `CalendarContainer` / `CalendarHeader` / `CalendarBody`
     composition with a single `<Calendar>`.
   - calendar-kit is driven imperatively through a ref (`goToDate`, `goToNextPage`);
     super-calendar is controlled. Hold `date` in state, render
     `<Calendar date={date} mode={mode} onChangeDate={setDate} />`, and change
     `date` / `mode` instead of calling ref methods.
   - Map the view: `numberOfDays={1|3|7}` becomes `mode="day" | "3days" | "week"`.
     There is no `CalendarBody` scroll config; the grid fills its parent, so wrap
     it in a `flex: 1` container.

3. Events
   - Pass the same event array to `events`. super-calendar reads `start`,
     `end`, and `title` (Dates, not ISO strings), plus any of your own fields via the
     generic `CalendarEvent<T>`. Convert ISO strings to `Date`.
   - `onPressEvent` maps directly. `onLongPressEvent` maps directly.
   - Drag-to-edit (`onDragEventEnd`-style handlers) becomes a single
     `onDragEvent={(event, start, end) => ...}`; return `false` to reject a drop.
   - Drag-to-create (`onDragCreateEnd`) becomes `onCreateEvent={(start, end) => ...}`.
   - Tapping empty space maps to `onPressCell`.

4. Resources
   - The resource view moves to the `ResourceTimeline` component (import from
     `@super-calendar/native`). Pass `resources` and read each event's lane via
     `resourceId`. Its drag handler is `onDragEvent(event, start, end, resource)`.

5. Views calendar-kit doesn't have
   - Add `mode="month"` and `mode="schedule"` where useful; they come for free.

6. Theming
   - Move the `theme` object to super-calendar's `theme` prop
     (see the theming guide) and, on web, per-slot `classNames`.

After migrating, run the app and check: the time grid renders, events land in the
right slots, drag/resize/create still fire your handlers, and resources page as
before.
```

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

### Implement dark mode with useColorScheme

Source: https://super-calendar.afonsojramos.me/guides/theming

Use the useColorScheme hook to toggle between the default and dark themes based on the system setting.

```tsx
import { Calendar, darkTheme, defaultTheme } from "@super-calendar/native";
import { useColorScheme } from "react-native";

const scheme = useColorScheme();
<Calendar /* ... */ theme={scheme === "dark" ? darkTheme : defaultTheme} />;
```

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

### Enabling Drag and Selection

Source: https://super-calendar.afonsojramos.me/guides/month-view

Configure drag-to-select and drag-to-move functionality for events and date ranges.

```tsx
<Calendar
  mode="month"
  /* ... */
  selectedRange={range ?? undefined}
  onSelectDrag={selectRange}
  onCreateEvent={createAllDay}
  onDragEvent={moveEvent}
/>
```

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

### Create all-day events in month mode

Source: https://super-calendar.afonsojramos.me/guides/dragging

Enable all-day event creation in month mode by passing the onCreateEvent prop with the allDay flag.

```tsx
<Calendar
  mode="month"
  /* ... */
  onCreateEvent={(start, end) =>
    setEvents((prev) => [...prev, { id: makeId(), title: "New", start, end, allDay: true }])
  }
/>
```

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

### Porting prompt for coding agents

Source: https://super-calendar.afonsojramos.me/coming-from-fullcalendar

Use this prompt to instruct a coding agent on how to migrate FullCalendar components, event handlers, and data structures to the super-calendar API.

```text
You are porting a FullCalendar app to super-calendar. On the web import from
`@super-calendar/dom`; on React Native import from `@super-calendar/native` and
add its peers (Reanimated v4, Gesture Handler, Worklets, @legendapp/list v3,
date-fns) with <GestureHandlerRootView> at the root. Rewrite the calendar rather
than renaming plugins.

1. Replace the <FullCalendar plugins={...} initialView=...> element with a single
   <Calendar mode=... date=... onChangeDate=... events=...>. Map views:
   dayGridMonth -> "month", timeGridWeek -> "week", timeGridDay -> "day",
   listWeek -> "schedule", multiMonthYear -> "year". Resource timeline becomes
   the separate <ResourceTimeline> component.
2. Hold the anchor date in state; replace datesSet/goto API calls with setting
   `date` and reading `onChangeDate` / `onChangeDateRange`.
3. Events: pass an array of { start: Date, end: Date, title, ...your fields }.
   Convert ISO strings to Date. For URL/Google/iCal feeds, fetch them yourself
   (use `parseICalendar` for iCal text). Keep your own event objects for saving.
4. Handlers: eventClick -> onPressEvent; dateClick/select -> onPressCell /
   onPressDay / onCreateEvent; editable -> onDragEvent(event, start, end);
   eventStartEditable / eventDurationEditable / eventOverlap keep their names;
   enforce eventConstraint/businessHours by returning false from onDragEvent.
5. Rendering: eventContent/eventDidMount -> a `renderEvent` component.
6. Recurrence: replace the rrule plugin with `expandRecurringEvents(events,
   rangeStart, rangeEnd)` over the visible range, or set `recurrence` on events.
7. There is no built-in header toolbar; render your own prev/next/title controls
   and drive `date` / `mode`.

Then run the app and verify views, event placement, drag/resize, and recurrence.
```

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

### Implement TimeGrid and MonthList

Source: https://super-calendar.afonsojramos.me/guides/dom

Use TimeGrid and MonthList components with the useDateRange hook. Note that both components require an explicit height prop for virtualization.

```tsx
import { useMemo } from "react";
import { type CalendarEvent, MonthList, TimeGrid, useDateRange } from "@super-calendar/dom";

const events: CalendarEvent[] = [
  { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) },
  {
    title: "Design review",
    start: new Date(2026, 5, 23, 9, 15),
    end: new Date(2026, 5, 23, 10, 30),
  },
];

export function App() {
  const today = useMemo(() => new Date(), []);
  const { range, onPressDate, reset } = useDateRange({ minDate: today });

  return (
    <>
      <TimeGrid date={today} mode="week" weekStartsOn={1} events={events} height={480} />

      <MonthList
        date={today}
        minDate={today}
        weekStartsOn={1}
        selectedRange={range ?? undefined}
        onPressDay={onPressDate}
        height={420}
      />
      <button type="button" onClick={reset}>
        Clear
      </button>
    </>
  );
}
```

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

### Create a custom range picker

Source: https://super-calendar.afonsojramos.me/guides/date-picker

Build a custom picker interface by wrapping MonthList and using the useDateRange hook.

```tsx
import { MonthList, useDateRange } from "@super-calendar/dom";

function CustomRange() {
  const { range, onPressDate } = useDateRange();
  return (
    <MonthList
      weekStartsOn={1}
      selectedRange={range ?? undefined}
      onPressDay={onPressDate}
      height={320}
    />
  );
}
```

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

### Enable keyboard event navigation in time grid

Source: https://super-calendar.afonsojramos.me/guides/dom

Enables arrow-key movement between events in a week view. Requires the keyboardEventNavigation prop.

```tsx
import { Calendar } from "@super-calendar/dom";

// Time grid where arrow keys move a roving focus between events.
<Calendar mode="week" date={new Date()} events={events} keyboardEventNavigation />;
```

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

### <Calendar> Component Props

Source: https://super-calendar.afonsojramos.me/reference/api

The <Calendar> component is the primary entry point for the library. Below are the common props used to configure the calendar's data, date, and display settings.

```APIDOC
## <Calendar> Component Props

### Description
The <Calendar> component is the main entry point for the library. It accepts various props to control event data, anchor dates, and display modes.

### Props
- **events** (CalendarEvent<T>[]) - The list of events to display. The generic T represents your custom data structure.
- **date** (Date) - The controlled anchor date, read in the device's local time.
- **mode** (CalendarMode) - The display mode of the calendar. Options: 'month', 'week', 'day', '3days', 'custom', 'schedule'.
- **numberOfDays** (number) - The number of columns to display when mode is set to 'custom'.
- **weekStartsOn** (0–6) - Defines the start of the week (0 = Sunday, 1 = Monday).
- **weekdayFormat** ('narrow' | 'short' | 'long') - The width of the weekday header (default: 'short').
- **timeZone** (string) - The IANA time zone used to display events.
```

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

### Initialize Agenda Component

Source: https://super-calendar.afonsojramos.me/guides/dom

Implementation of the Agenda component for displaying a scrolling list of events grouped by date.

```tsx
import { Agenda, type CalendarEvent } from "@super-calendar/dom";

const events: CalendarEvent[] = [
  { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) },
  { title: "Lunch", start: new Date(2026, 5, 23, 12, 0), end: new Date(2026, 5, 23, 13, 0) },
];

<Agenda
  events={events}
  height={520}
  onPressEvent={(event) => console.log(event.title)}
  onPressDay={(day) => console.log("header", day)}
/>;
```

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

### Implement Resource Paging

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Use resourcesPerPage and resourcePage to control the number of visible lanes and navigate between pages.

```tsx
const [page, setPage] = useState(0);
const pages = Math.ceil(resources.length / 3);

<ResourceTimeline
  date={date}
  orientation="vertical"
  resources={resources}
  events={events}
  resourcesPerPage={3}
  resourcePage={page}
/>;
// Your controls:
<Button title="Next rooms" onPress={() => setPage((p) => Math.min(p + 1, pages - 1))} />;
```

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

### Calendar Implementation Comparison

Source: https://super-calendar.afonsojramos.me/coming-from-react-big-calendar

Comparison of the component structure between react-big-calendar and the super-calendar web renderer.

```tsx
import { Calendar, dateFnsLocalizer } from "react-big-calendar";

const localizer = dateFnsLocalizer(/* ... */);

<Calendar
  localizer={localizer}
  events={events}
  defaultView="week"
  onSelectEvent={(event) => open(event)}
  onSelectSlot={(slot) => create(slot.start, slot.end)}
  selectable
/>;
```

```tsx
import { useState } from "react";
import { Calendar } from "@super-calendar/dom";

function Schedule({ events }) {
  const [date, setDate] = useState(() => new Date());
  return (
    <Calendar
      mode="week"
      date={date}
      onChangeDate={setDate}
      events={events}
      onPressEvent={(event) => open(event)}
      onCreateEvent={(start, end) => create(start, end)}
    />
  );
}
```

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

### Handle Event Creation in Year View

Source: https://super-calendar.afonsojramos.me/guides/year-view

Configures the calendar to handle all-day event creation via the onCreateEvent callback.

```tsx
<Calendar
  mode="year"
  /* ... */
  onCreateEvent={(start, end) =>
    setEvents((prev) => [...prev, { id: makeId(), title: "Leave", start, end, allDay: true }])
  }
/>
```

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

### Exporting to iCalendar format

Source: https://super-calendar.afonsojramos.me/guides/ical

Convert events to a VCALENDAR string and create a downloadable blob.

```ts
const ics = toICalendar(events);

// Offer it as a download in the browser:
const url = URL.createObjectURL(new Blob([ics], { type: "text/calendar" }));
```

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

### Implement keyboard paging

Source: https://super-calendar.afonsojramos.me/guides/dom

Enables PageUp and PageDown keys for calendar navigation by providing an onChangeDate handler.

```tsx
<Calendar mode="week" date={date} onChangeDate={setDate} events={events} />
```

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

### Render a weekly calendar view

Source: https://super-calendar.afonsojramos.me/guides/views

Displays the calendar in week mode using the Calendar component.

```tsx
<Calendar mode="week" date={date} events={events} onChangeDate={setDate} />
```

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

### Handle empty space interactions in ResourceTimeline

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Use onPressCell and onCreateEvent to capture user interactions on empty slots and create new events associated with specific resources.

```tsx
<ResourceTimeline
  date={date}
  resources={resources}
  events={events}
  onPressCell={(at, resource) => openBookingForm(resource, at)}
  onCreateEvent={(start, end, resource) =>
    setEvents((prev) => [...prev, { title: "New booking", start, end, resourceId: resource.id }])
  }
/>
```

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

### Implement drag-to-select and event creation in year mode

Source: https://super-calendar.afonsojramos.me/guides/dragging

Uses onSelectDrag to track the range during interaction and onCreateEvent to finalize the event creation upon release.

```tsx
<Calendar
  mode="year"
  /* ... */
  selectedRange={range ?? undefined}
  onSelectDrag={selectRange}
  onCreateEvent={(start, end) =>
    setEvents((prev) => [...prev, { id: makeId(), title: "Leave", start, end, allDay: true }])
  }
/>
```

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

### Construct local anchor dates

Source: https://super-calendar.afonsojramos.me/guides/time-zones

Construct anchor dates as local dates to ensure consistent behavior across different time zones.

```ts
new Date(2026, 7, 24); // local Aug 24, anchors the week you expect everywhere
new Date("2026-08-24T00:00:00Z"); // UTC instant, still Aug 23 west of UTC
```

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

### Configure vertical orientation

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Set the orientation prop to vertical to display resources as columns, which is ideal for narrow screens.

```tsx
<ResourceTimeline
  date={date}
  orientation="vertical"
  resources={resources}
  events={events}
  startHour={7}
  endHour={20}
/>
```

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

### Display Props

Source: https://super-calendar.afonsojramos.me/reference/api

Properties used to customize the visual appearance and layout of the calendar grid.

```APIDOC
## Display Props

### Parameters
- **scrollOffsetMinutes** (number) - Initial vertical scroll.
- **hourHeight** (number) - Row height (px per hour).
- **timeslots** (number) - Hour sub-divisions.
- **ampm** (boolean) - 12-hour labels.
- **showNowIndicator** (boolean) - Current-time line (default on).
- **showAllDayEventCell** (boolean) - All-day lane (default on).
- **allDayLabel** (string) - Schedule all-day text ("All day").
- **highlightWeekends** (boolean) - Tint weekend cells/columns (month + time grid, default on).
- **maxVisibleEventCount** (number) - Month: fixed cap on event lanes per week row.
- **showTitle** (boolean) - Month: the built-in "MMMM yyyy" label above the grid (default on).
- **theme** (PartialCalendarTheme) - Color/text/metric overrides.
- **classNames** (Partial<Record<CalendarSlot, string>>) - Per-slot Tailwind classes.
- **styles** (Partial<Record<CalendarSlot, StyleProp>>) - Per-slot style overrides, merged last.
```

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

### Portal overlays to the React root

Source: https://super-calendar.afonsojramos.me/guides/web

Ensure UI library portals are mounted to the React root element instead of document.body to maintain event delegation.

```tsx
const [container, setContainer] = useState<HTMLElement | null>(null);
useEffect(() => setContainer(document.getElementById("root")), []);
// ...
<Menu.Portal container={container}>{/* menu */}</Menu.Portal>;
```

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

### Importing iCalendar functions

Source: https://super-calendar.afonsojramos.me/guides/ical

Import the necessary parsing and conversion functions from the core package.

```ts
import { parseICalendar, toICalendar } from "@super-calendar/core";
// also re-exported from "@super-calendar/dom" and "@super-calendar/native"
```

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

### Selection Props

Source: https://super-calendar.afonsojramos.me/reference/api

Properties used to configure date selection behavior, including range constraints and selection callbacks.

```APIDOC
## Selection Props

### Parameters
- **selectedDates** (Date[]) - Discrete selected days (month + year).
- **selectedRange** (DateRange) - A selected span (month + year).
- **fillCellOnSelection** (boolean) - Month: fill the cell instead of the pill band.
- **minDate** (Date) - Earliest selectable day (inclusive).
- **maxDate** (Date) - Latest selectable day (inclusive).
- **isDateDisabled** ((date) => boolean) - Return true to forbid a specific day.
- **onSelectDrag** ((start, end) => void) - Drag to sweep a range; pair with useDateRange.
```

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

### Render Year View Calendar

Source: https://super-calendar.afonsojramos.me/guides/year-view

Basic implementation of the calendar in year mode with drill-down handlers for days and months.

```tsx
<Calendar
  mode="year"
  date={date}
  events={events}
  onChangeDate={setDate}
  onPressDay={(day) => {
    setDate(day);
    setMode("day");
  }}
  onPressMonth={(month) => {
    setDate(month);
    setMode("month");
  }}
/>
```

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

### Responsive orientation switching

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Dynamically toggle the orientation prop based on viewport width.

```tsx
orientation={width < 600 ? "vertical" : "horizontal"}
```

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

### Wrap app in GestureHandlerRootView

Source: https://super-calendar.afonsojramos.me/quickstart

Ensure the application tree is wrapped in GestureHandlerRootView as required by the gesture handler library.

```tsx
import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function App() {
  return <GestureHandlerRootView style={{ flex: 1 }}>{/* ... */}</GestureHandlerRootView>;
}
```

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

### Implement a custom month grid with useMonthGrid

Source: https://super-calendar.afonsojramos.me/guides/headless

Use the useMonthGrid hook to retrieve grid data and render custom day-cell markup in React Native.

```tsx
import { View, Text, Pressable } from "react-native";
import { useMonthGrid } from "@super-calendar/core";

function MyMonth({ month, range }: { month: Date; range?: DateRange }) {
  const { weeks, weekdays } = useMonthGrid(month, {
    weekStartsOn: 1,
    selectedRange: range,
  });

  return (
    <View>
      <View style={{ flexDirection: "row" }}>
        {weekdays.map((w) => (
          <Text key={w.label} style={{ flex: 1, textAlign: "center" }}>
            {w.label}
          </Text>
        ))}
      </View>
      {weeks.map((week) => (
        <View key={week.id} style={{ flexDirection: "row" }}>
          {week.days.map((day) => (
            <Pressable key={day.id} style={{ flex: 1 }} disabled={day.isDisabled}>
              <Text
                style={{
                  textAlign: "center",
                  opacity: day.isCurrentMonth ? 1 : 0.4,
                  fontWeight: day.isToday ? "700" : "400",
                  color: day.isSelected ? "#fff" : "#000",
                }}
              >
                {day.label}
              </Text>
            </Pressable>
          ))}
        </View>
      ))}
    </View>
  );
}
```

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

### Apply inline styles to MonthView

Source: https://super-calendar.afonsojramos.me/guides/styling

Use the styles prop for one-off tweaks that override default styles and classes.

```tsx
import { MonthView } from "@super-calendar/dom";

<MonthView styles={{ title: { textAlign: "center" }, day: { borderRadius: 8 } }} />;
```

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

### Implement a Range Picker with MonthList

Source: https://super-calendar.afonsojramos.me/guides/month-list

Use the useDateRange hook to manage selection state and pass the resulting range and handlers to the MonthList component.

```tsx
import { MonthList, useDateRange } from "@super-calendar/native";

function RangePicker() {
  const [date, setDate] = useState(new Date());
  const { range, onPressDate, selectRange } = useDateRange({ minDate: new Date() });

  return (
    <MonthList
      date={date}
      weekStartsOn={1}
      selectedRange={range ?? undefined}
      minDate={new Date()}
      onPressDay={onPressDate}
      onSelectDrag={selectRange}
      onChangeVisibleMonth={setDate}
    />
  );
}
```

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

### Apply and Merge DOM Themes

Source: https://super-calendar.afonsojramos.me/guides/dom

Use mergeDomTheme to override default theme values and apply the resulting object to the TimeGrid component.

```tsx
import { darkDomTheme, mergeDomTheme, TimeGrid } from "@super-calendar/dom";

// mergeDomTheme(overrides, base?) — base defaults to defaultDomTheme.
const brand = mergeDomTheme({ selectedBackground: "#7c3aed", cellHeight: 56 });

<TimeGrid date={new Date()} mode="day" theme={brand} height={480} />;
// or pass `theme={darkDomTheme}` for dark mode
```

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

### Implement ResourceTimeline in React

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Basic implementation of the ResourceTimeline component using the @super-calendar/dom package, defining resources and events for a single day.

```tsx
import { type CalendarEvent, ResourceTimeline } from "@super-calendar/dom";

const resources = [
  { id: "room-a", title: "Room A" },
  { id: "room-b", title: "Room B" },
];

const events: CalendarEvent<{ resourceId: string }>[] = [
  {
    resourceId: "room-a",
    title: "Standup",
    start: new Date(2026, 5, 26, 9),
    end: new Date(2026, 5, 26, 10),
  },
  {
    resourceId: "room-b",
    title: "Review",
    start: new Date(2026, 5, 26, 11),
    end: new Date(2026, 5, 26, 12),
  },
];

<ResourceTimeline date={new Date(2026, 5, 26)} resources={resources} events={events} />;
```

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

### Define business hours for grid shading

Source: https://super-calendar.afonsojramos.me/guides/theming

Provide a function to businessHours to return the active time range or null to shade the entire day.

```tsx
<Calendar
  /* ... */
  businessHours={(date) => {
    const weekday = date.getDay();
    if (weekday === 0 || weekday === 6) return null; // weekends closed
    return { start: 9, end: 17 };
  }}
/>
```

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

### Fetch events with useEventSource

Source: https://super-calendar.afonsojramos.me/guides/events

Use this hook to fetch events from a URL and pass them to the Calendar component. The refetchIntervalMs option enables periodic updates.

```tsx
import { useEventSource } from "@super-calendar/core";

const { events, loading, error, refetch } = useEventSource("https://example.com/rooms.ics", {
  refetchIntervalMs: 5 * 60_000,
});

<Calendar mode="week" date={date} events={events} onChangeDate={setDate} />;
```

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

### Implement Drag-to-Select in Year View

Source: https://super-calendar.afonsojramos.me/guides/year-view

Enables range selection by pairing the calendar with the useDateRange hook.

```tsx
const { range, onPressDate, selectRange } = useDateRange();

<Calendar
  mode="year"
  date={date}
  events={events}
  onChangeDate={setDate}
  selectedRange={range ?? undefined}
  onPressDay={onPressDate}
  onSelectDrag={selectRange}
/>;
```

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

### Implement a single DatePicker

Source: https://super-calendar.afonsojramos.me/guides/date-picker

A controlled single date input using the DatePicker component.

```tsx
import { useState } from "react";
import { DatePicker } from "@super-calendar/dom";

function Field() {
  const [value, setValue] = useState<Date | null>(null);
  return <DatePicker value={value} onChange={setValue} weekStartsOn={1} />;
}
```

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

### Configure resource-specific business hours

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Define business hours per resource by passing a function to the businessHours prop, returning null for fully closed lanes.

```tsx
<ResourceTimeline
  date={date}
  resources={resources}
  events={events}
  businessHours={(day, resource) => (resource.id === "vault" ? null : { start: 9, end: 17 })}
/>
```

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

### React Native Resource Timeline Implementation

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

The native implementation supports standard timeline props plus drag-and-drop event handling via onDragEvent.

```tsx
import { ResourceTimeline } from "@super-calendar/native";

<ResourceTimeline
  date={date}
  resources={resources}
  events={events}
  onPressEvent={setSelected}
  onDragEvent={(event, start, end, resource) => {
    setEvents((prev) =>
      prev.map((e) => (e === event ? { ...e, start, end, resourceId: resource.id } : e)),
    );
  }}
/>;
```

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

### Render a custom day count view

Source: https://super-calendar.afonsojramos.me/guides/views

Configures the calendar to display a specific number of days using custom mode.

```tsx
<Calendar mode="custom" numberOfDays={5} date={date} events={events} onChangeDate={setDate} />
```

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

### toICalendar(events, options)

Source: https://super-calendar.afonsojramos.me/guides/ical

Converts an array of event objects into a VCALENDAR string.

```APIDOC
## toICalendar(events, options)

### Description
Produces a complete VCALENDAR string from an array of event objects.

### Parameters
- **events** (Array<CalendarEvent>) - Required - The list of events to export.
- **options** (Object) - Optional - Configuration object containing `prodId` and `now` (for DTSTAMP).
```

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

### Apply Calendar Theme Tokens

Source: https://super-calendar.afonsojramos.me/guides/theming

Pass a theme object to the Calendar component to override default colors and text styles.

```tsx
<Calendar
  // ...
  theme={{
    colors: { todayBackground: "#E5484D", nowIndicator: "#E5484D" },
    text: { dayNumber: { fontSize: 24, fontWeight: "800" } },
  }}
/>
```

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

### Style picker components

Source: https://super-calendar.afonsojramos.me/guides/date-picker

Apply custom classes to picker slots and internal calendar elements using the classNames prop.

```tsx
<DateRangePicker
  value={range}
  onChange={setRange}
  classNames={{
    trigger: "rounded-lg border px-3 py-2",
    dayBadge: "data-[selected]:bg-indigo-600 data-[selected]:text-white",
  }}
/>
```

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

### Define background events

Source: https://super-calendar.afonsojramos.me/guides/events

Set the display property to 'background' to render events as non-interactive shaded bands behind the grid.

```tsx
const events: CalendarEvent[] = [
  { title: "Maintenance", start: at(9), end: at(12), display: "background" },
  { title: "Standup", start: at(9), end: at(10) }, // renders normally, on top
];
```

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

### Apply React Native Container Styles

Source: https://super-calendar.afonsojramos.me/guides/theming

Use the containers map to provide ViewStyle overrides for specific native renderer elements.

```tsx
<Calendar
  theme={{ containers: { agendaRow: { paddingHorizontal: 20 }, allDayLane: { opacity: 0.9 } } }}
/>
```

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

### Restrict move or resize

Source: https://super-calendar.afonsojramos.me/guides/dragging

Use startEditable and durationEditable properties to control whether an event can be moved or resized, respectively.

```tsx
const events = [
  { id: "1", title: "Standup", start, end, durationEditable: false }, // move, don't resize
  { id: "2", title: "Focus", start, end, startEditable: false }, // resize, don't move
];

// Or a grid-wide default (e.g. resize is off everywhere):
<Calendar eventDurationEditable={false} onDragEvent={onDrag} /* ... */ />;
```

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

### Implement multiple day selection

Source: https://super-calendar.afonsojramos.me/guides/selection

Manages an array of selected dates by updating state on each press event.

```tsx
const [picked, setPicked] = useState<Date[]>([]);

<MonthList
  date={date}
  weekStartsOn={1}
  selectedDates={picked}
  onPressDay={(day) => setPicked((prev) => [...prev, day])}
  onChangeVisibleMonth={setDate}
/>;
```

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

### Render custom business hour content

Source: https://super-calendar.afonsojramos.me/guides/time-grid

Use renderBusinessHours to inject custom visual elements into closed time regions. The returned content should be decorative and non-interactive.

```tsx
<Calendar
  mode="week"
  date={date}
  events={events}
  businessHours={() => ({ start: 9, end: 17 })}
  renderBusinessHours={({ start }) => <ClosedBand label={start === 0 ? "Opens 9am" : "Closed"} />}
  onChangeDate={setDate}
  onPressEvent={onPress}
/>
```

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

### Define business hours with gaps

Source: https://super-calendar.afonsojramos.me/guides/time-grid

Use a function returning an array of time windows to define multiple business hour segments, such as including a lunch break.

```tsx
// Open 9-12 and 13-17: the 12-13 lunch hour shades closed too.
businessHours={() => [
  { start: 9, end: 12 },
  { start: 13, end: 17 },
]}
```

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

### Configuring Event Overflow

Source: https://super-calendar.afonsojramos.me/guides/month-view

Control how many event lanes are visible per week row.

```tsx
<Calendar mode="month" /* ... */ />                            // auto-fit (default)
<Calendar mode="month" maxVisibleEventCount={3} /* ... */ />   // fixed cap
```

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

### Apply date constraints and disabled days

Source: https://super-calendar.afonsojramos.me/guides/selection

Uses minDate, maxDate, and isDateDisabled to restrict selectable dates, passing the same constraints to the useDateRange hook.

```tsx
const minDate = useMemo(() => new Date(), []); // no past dates
const { range, onPressDate, selectRange } = useDateRange({ minDate });

<MonthList
  date={date}
  weekStartsOn={1}
  selectedRange={range ?? undefined}
  minDate={minDate}
  isDateDisabled={(d) => d.getDay() === 0} // also block Sundays
  onPressDay={onPressDate}
  onSelectDrag={selectRange}
/>;
```

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

### Parsing iCalendar data

Source: https://super-calendar.afonsojramos.me/guides/ical

Fetch an .ics file and parse its content into an array of events.

```ts
const res = await fetch("/calendar.ics");
const events = parseICalendar(await res.text());

// -> [{ uid, title, start, end, allDay?, description?, location?, recurrence? }]
```

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

### Integrate selection in Calendar component

Source: https://super-calendar.afonsojramos.me/guides/selection

Applies selection props to the Calendar component to allow range selection alongside event displays.

```tsx
const { range, onPressDate, selectRange } = useDateRange();

<Calendar
  mode="month"
  date={date}
  events={events}
  onChangeDate={setDate}
  selectedRange={range ?? undefined}
  onPressDay={onPressDate}
  onSelectDrag={selectRange}
  onPressEvent={openEvent}
/>;
```

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

### MonthList Component Props

Source: https://super-calendar.afonsojramos.me/guides/month-list

The MonthList component accepts various props to configure the date picker's behavior, selection logic, and appearance.

```APIDOC
## MonthList Props

### Props
- **date** (Date) - The month scrolled to on mount.
- **weekStartsOn** (0–6) - First day of the week.
- **events** (CalendarEvent<T>[]) - Optional; omit for an events-free picker.
- **weekRowHeight** (number) - Height of each week row (px). Default 56.
- **monthHeaderHeight** (number) - Title-row height (px). Default 44.
- **renderEvent** (RenderEvent<T>) - Optional; defaults to DefaultEvent.
- **keyExtractor** ((event, index) => string) - Optional; defaults to start-time + index.
- **selectedDates** (Date[]) - Selected days.
- **selectedRange** (DateRange) - Selected span.
- **minDate / maxDate** (Date) - Bound the selectable range.
- **isDateDisabled** ((date) => boolean) - Disable specific days.
- **onSelectDrag** ((start, end) => void) - Drag-to-select; pair with useDateRange().selectRange.
- **showAdjacentMonths** (boolean) - Show dimmed adjacent-month days. Default false.
- **highlightWeekends** (boolean) - Tint weekend day cells. Default true.
- **onPressDay** ((date) => void) - Tap a day cell.
- **onChangeVisibleMonth** ((month) => void) - Fires with the topmost month once it's ~60% visible.
- **renderMonthHeader** ((month) => ReactNode) - Replace the default LLLL yyyy title.
```

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

### Handling Cell and Day Taps

Source: https://super-calendar.afonsojramos.me/guides/month-view

Define interactions for tapping specific cells or days within the month grid.

```tsx
<Calendar
  mode="month"
  /* ... */
  onPressCell={(day) => openNewAppointment(day)} // midnight of the tapped day
  onPressDay={(day) => {
    setDate(day);
    setMode("day");
  }}
/>
```

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

### Handle Event Drag and Drop

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Use onDragEvent to update event timing or resource assignment, returning false to reject drops.

```tsx
import { ResourceTimeline } from "@super-calendar/dom";

<ResourceTimeline
  date={date}
  resources={resources}
  events={events}
  onDragEvent={(event, start, end, resource) => {
    if (event.locked) return false;
    setEvents((prev) =>
      prev.map((e) => (e === event ? { ...e, start, end, resourceId: resource.id } : e)),
    );
  }}
/>;
```

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

### Use Standalone YearView Component

Source: https://super-calendar.afonsojramos.me/guides/year-view

Imports and renders the YearView component independently of the main Calendar container.

```tsx
import { YearView } from "@super-calendar/native";

<YearView date={date} events={events} weekStartsOn={1} onPressDay={jumpTo} />;
```

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

### Render a controlled Calendar

Source: https://super-calendar.afonsojramos.me/quickstart

Implement a controlled Calendar component by managing date and mode state and providing event data.

```tsx
import { useState } from "react";
import { Calendar, type CalendarEvent, type CalendarMode } from "@super-calendar/native";

const events: CalendarEvent[] = [
  { title: "Standup", start: new Date(2026, 5, 23, 9, 0), end: new Date(2026, 5, 23, 9, 30) },
];

export function MyCalendar() {
  const [date, setDate] = useState(() => new Date());
  const [mode, setMode] = useState<CalendarMode>("week");
  return (
    <Calendar
      mode={mode}
      date={date}
      events={events}
      weekStartsOn={1}
      onChangeDate={setDate}
      onPressEvent={(event) => console.log(event.title)}
    />
  );
}
```

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

### Style day cells with Tailwind data variants

Source: https://super-calendar.afonsojramos.me/guides/styling

Use data attributes like data-[today] and data-[selected] within the classNames prop to apply conditional styles to day cells.

```tsx
import { MonthView } from "@super-calendar/dom";

<MonthView
  classNames={{
    day: "data-[today]:bg-blue-600 data-[today]:text-white data-[selected]:ring-2",
  }}
/>;
```

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

### Map events to resources with custom accessor

Source: https://super-calendar.afonsojramos.me/guides/resource-timeline

Use the resourceId prop to define a custom function that extracts the resource identifier from an event object.

```tsx
<ResourceTimeline
  date={date}
  resources={resources}
  events={events}
  resourceId={(event) => event.room}
/>
```

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

### Layout timed events with layoutDayEvents

Source: https://super-calendar.afonsojramos.me/guides/headless

Resolves overlapping events into side-by-side columns for grid displays. Returns PositionedEvent objects containing vertical and horizontal placement data.

```tsx
import { layoutDayEvents } from "@super-calendar/core";

for (const pe of layoutDayEvents(events, day)) {
  // pe.event                              the original event
  // pe.startHours, pe.durationHours       vertical position (hours from midnight)
  // pe.column / pe.columns                left = (column / columns) * 100%, width = 100% / columns
  // pe.continuesBefore / pe.continuesAfter   multi-day clipping flags
}
```

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

### Define a custom event with metadata

Source: https://super-calendar.afonsojramos.me/guides/events

Use the generic CalendarEvent type to attach custom fields to event objects.

```tsx
import type { CalendarEvent } from "@super-calendar/native";

type Meta = { id: string; calendarId: string; color: string };

const events: CalendarEvent<Meta>[] = [
  {
    title: "Standup",
    start: new Date(2026, 5, 23, 9, 0),
    end: new Date(2026, 5, 23, 9, 30),
    id: "1",
    calendarId: "work",
    color: "#1F6FEB",
  },
];
```

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

### Enable event dragging

Source: https://super-calendar.afonsojramos.me/guides/dragging

Pass the onDragEvent handler to the Calendar component to enable moving and resizing events.

```tsx
<Calendar
  /* ... */
  onDragEvent={(event, start, end) =>
    setEvents((prev) => prev.map((e) => (e.id === event.id ? { ...e, start, end } : e)))
  }
/>
```