@super-calendar/core 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afonso Jorge Ramos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,542 @@
+import { Locale } from "date-fns";
+
+//#region src/types.d.ts
+type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule";
+/** The time-grid modes (day-column views, excluding month and schedule). */
+type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
+/**
+ * The minimal shape every calendar event must have. Layout (positioning,
+ * overlap resolution, paging) only ever reads `start`/`end`; `title` is used by
+ * the built-in default renderer. Anything else lives in your own type and is
+ * threaded through untouched via the `T` generic.
+ */
+interface ICalendarEvent {
+  start: Date;
+  end: Date;
+  title?: string;
+  /**
+   * Force this event into the all-day lane (above the time grid) instead of the
+   * timed columns. When omitted, an event is treated as all-day only if it spans
+   * whole days (both `start` and `end` land on midnight).
+   */
+  allDay?: boolean;
+  /** Ignore taps/long-presses on this event (the built-in renderer also dims it). */
+  disabled?: boolean;
+  /**
+   * Repeat rule. Pass the event to `expandRecurringEvents(events, start, end)` to
+   * materialise its occurrences within a range; the calendar itself doesn't
+   * expand recurrences.
+   */
+  recurrence?: RecurrenceRule;
+}
+/** How often a recurring event repeats. */
+type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
+/** A simple, RRULE-inspired repeat rule expanded by `expandRecurringEvents`. */
+interface RecurrenceRule {
+  freq: RecurrenceFrequency;
+  /** Repeat every N periods. Default 1. */
+  interval?: number;
+  /** Stop after this many occurrences (including the first). */
+  count?: number;
+  /** Stop on/after this date (inclusive). */
+  until?: Date;
+  /**
+   * For `weekly`: the weekdays to repeat on (0 = Sunday … 6 = Saturday), keeping
+   * the event's time of day. Omit to repeat on the start date's own weekday.
+   */
+  weekdays?: WeekStartsOn[];
+}
+/**
+ * An event carrying arbitrary extra fields `T` alongside the required shape.
+ * `ICalendarEvent` is authoritative: keys it reserves (`start`/`end`/`title`)
+ * cannot be re-typed by `T`.
+ */
+type CalendarEvent<T = unknown> = ICalendarEvent & Omit<T, keyof ICalendarEvent>;
+/** Build a stable key for an event. Defaults to start-time + index. */
+type EventKeyExtractor<T = unknown> = (event: CalendarEvent<T>, index: number) => string;
+/** Sunday = 0 … Saturday = 6, matching `Date.prototype.getDay()`. */
+type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * A day's open hours for `businessHours` shading on the time grid: `{ start, end }`
+ * in hours (fractions allowed, e.g. 9.5), or `null` when the day is closed (fully
+ * shaded). `undefined` from the callback means "no business-hours shading". Shared
+ * by both renderers; pair with `closedHourBands` to get the spans to shade.
+ */
+type BusinessHours = (date: Date) => {
+  start: number;
+  end: number;
+} | null;
+//#endregion
+//#region src/tokens.d.ts
+interface CalendarColors {
+  /** Hour lines, day separators and month-cell borders. */
+  gridLine: string;
+  /** Background tint behind weekend columns/cells. */
+  weekendBackground: string;
+  /** Background tint over hours outside business hours (time grid). */
+  outsideHoursBackground: string;
+  /** Today badge fill. */
+  todayBackground: string;
+  /** Today badge text. */
+  todayText: string;
+  /** Selected day / range-endpoint badge fill. */
+  selectedBackground: string;
+  /** Selected day / range-endpoint badge text. */
+  selectedText: string;
+  /** Band behind a selected range. */
+  rangeBackground: string;
+  /** Hover highlight behind a day (DOM, mouse only). */
+  hoverBackground: string;
+  /** Current-time indicator line (time grid). */
+  nowIndicator: string;
+  /** Primary text (day numbers, weekday labels). */
+  text: string;
+  /** Muted text (hour labels, "+N more"). */
+  textMuted: string;
+  /** Dimmed text for disabled / adjacent-month days. */
+  textDisabled: string;
+  /** Default event chip fill. */
+  eventBackground: string;
+  /** Default event chip text. */
+  eventText: string;
+}
+declare const lightColors: CalendarColors;
+declare const darkColors: CalendarColors;
+//#endregion
+//#region src/presentation.d.ts
+/** Which range-band shape a day shows. */
+type RangeBandKind = "none" | "fill" | "pill-start" | "pill-mid" | "pill-end";
+/** The band shape for a day, given the fill-cell option. */
+declare function rangeBandKind(day: {
+  isInRange: boolean;
+  isRangeStart: boolean;
+  isRangeEnd: boolean;
+}, fillCell: boolean): RangeBandKind;
+/** Whether a band shape rounds its leading / trailing edge (pill ends). */
+declare function bandRounding(kind: RangeBandKind): {
+  start: boolean;
+  end: boolean;
+};
+/** Which filled badge a day shows (today wins over a selection). */
+type DayBadgeKind = "none" | "today" | "selected";
+/**
+ * The filled-badge kind for a day. `isSelected` is true for both range endpoints
+ * and discrete selected days; today always wins when it coincides.
+ */
+declare function dayBadgeKind(day: {
+  isSelected: boolean;
+}, isToday: boolean): DayBadgeKind;
+//#endregion
+//#region src/utils/dateRange.d.ts
+/** A selected span. `end` is `null` while only the first endpoint has been picked. */
+interface DateRange {
+  start: Date;
+  end: Date | null;
+}
+/** Limits applied before a date can be selected. */
+interface DateSelectionConstraints {
+  /** Earliest selectable day (inclusive). */
+  minDate?: Date;
+  /** Latest selectable day (inclusive). */
+  maxDate?: Date;
+  /** Return true to forbid selecting a specific day. */
+  isDateDisabled?: (date: Date) => boolean;
+}
+/** Whether `date` passes the min/max/disabled constraints (compared by calendar day). */
+declare function isDateSelectable(date: Date, constraints?: DateSelectionConstraints): boolean;
+/**
+ * The range after pressing `pressed`, mirroring the familiar date-picker model:
+ * - no range yet, or a complete range exists → start fresh (`{ start: pressed, end: null }`),
+ *   so a third press resets the selection.
+ * - an open range (a start but no end) → close it, auto-swapping when the press
+ *   precedes the start so `start <= end` always holds.
+ *
+ * Returns `current` unchanged when `pressed` isn't selectable.
+ */
+declare function nextDateRange(current: DateRange | null, pressed: Date, constraints?: DateSelectionConstraints): DateRange | null;
+/** True when `date` is one of the range's two endpoints. */
+declare function isRangeEndpoint(date: Date, range: DateRange | null): boolean;
+/** True when `date` falls within a complete range (endpoints included). */
+declare function isWithinDateRange(date: Date, range: DateRange | null): boolean;
+/** The selection/disabled flags for one day. */
+interface DaySelectionState {
+  /** Fails the min/max/disabled constraints. */
+  isDisabled: boolean;
+  /** A `selectedDates` day or a range endpoint (and not disabled). */
+  isSelected: boolean;
+  /** Inside a complete range, endpoints included (and not disabled). */
+  isInRange: boolean;
+  isRangeStart: boolean;
+  isRangeEnd: boolean;
+}
+/**
+ * The canonical per-day selection state, shared by `MonthView` (rendering) and
+ * `buildMonthGrid` (the headless grid) so the built-in views and a custom
+ * calendar can never disagree on what a day's state is.
+ */
+declare function daySelectionState(date: Date, selection: {
+  selectedDates?: Date[];
+  selectedRange?: DateRange | null;
+}, constraints?: DateSelectionConstraints): DaySelectionState;
+/**
+ * Per-day state shared with the month grid via context: the current selection
+ * plus the selectability constraints. Threaded through context (not props) so
+ * cached/virtualized day cells still repaint when any of it changes.
+ */
+interface CalendarSelection extends DateSelectionConstraints {
+  selectedDates?: Date[];
+  selectedRange?: DateRange;
+}
+/**
+ * Provides the active selection to the month grid. Day cells read it via
+ * {@link useCalendarSelection} so they repaint on selection changes even when
+ * the virtualized list has cached (and so won't re-render) their page.
+ */
+declare const CalendarSelectionProvider: import("react").Provider<CalendarSelection>;
+declare const useCalendarSelection: () => CalendarSelection;
+/** Options for {@link useDateRange}. */
+interface UseDateRangeOptions extends DateSelectionConstraints {
+  /** Pre-select a range on mount. */
+  initialRange?: DateRange | null;
+}
+/**
+ * Controlled-ish range selection state for the month view. Returns the current
+ * `range` plus an `onPressDate` handler to wire to `Calendar`'s `onPressDay`, a
+ * `reset`, and the raw `setRange` for full control.
+ *
+ * ```tsx
+ * const { range, onPressDate } = useDateRange({ minDate: new Date() });
+ * <Calendar mode="month" selectedRange={range ?? undefined} onPressDay={onPressDate} … />
+ * ```
+ */
+declare function useDateRange(options?: UseDateRangeOptions): {
+  range: DateRange | null;
+  onPressDate: (date: Date) => void;
+  selectRange: (a: Date, b: Date) => void;
+  reset: () => void;
+  setRange: import("react").Dispatch<import("react").SetStateAction<DateRange | null>>;
+};
+//#endregion
+//#region src/utils/dates.d.ts
+/** The seven dates of the week containing `date`, starting on `weekStartsOn`. */
+declare const getWeekDays: (date: Date, weekStartsOn: WeekStartsOn) => Date[];
+/** How many day columns a time-grid mode shows. `custom` uses `numberOfDays`. */
+declare const viewDayCount: (mode: CalendarMode, numberOfDays?: number) => number;
+/**
+ * Days in the inclusive span from `weekStartsOn` to `weekEndsOn` (1–7),
+ * wrapping when the end precedes the start (e.g. Sat→Wed). Mirrors
+ * react-native-big-calendar's `weekDaysCount`.
+ */
+declare const weekDaysCount: (weekStartsOn: WeekStartsOn, weekEndsOn: WeekStartsOn) => number;
+/**
+ * The day columns to render for a time-grid page. `week` spans the calendar week
+ * (honouring `weekStartsOn`). `custom` with a `weekEndsOn` spans the partial week
+ * from `weekStartsOn` to `weekEndsOn` (anchored to `date`'s week, paging by week);
+ * otherwise every mode shows `viewDayCount` consecutive days starting at `date`.
+ */
+declare const getViewDays: (mode: CalendarMode, date: Date, weekStartsOn: WeekStartsOn, numberOfDays?: number, isRTL?: boolean, weekEndsOn?: WeekStartsOn) => Date[];
+/**
+ * The calendar weeks covering `month`, padded to whole weeks starting on
+ * `weekStartsOn`. `showSixWeeks` always returns six rows (42 days) for a
+ * fixed-height grid; `isRTL` reverses each week's day order.
+ */
+declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, {
+  showSixWeeks,
+  isRTL
+}?: {
+  showSixWeeks?: boolean;
+  isRTL?: boolean;
+}) => Date[][];
+declare const isWeekend: (date: Date) => boolean;
+declare const getIsToday: (date: Date) => boolean;
+declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
+/** Minutes elapsed since midnight (0–1439). */
+declare const minutesIntoDay: (date: Date) => number;
+//#endregion
+//#region src/utils/drag.d.ts
+/**
+ * Minutes to shift an event, snapping a vertical pixel drag to the nearest
+ * `stepMinutes`. Runs on the UI thread inside the drag gesture. Returns 0 for a
+ * degenerate grid (non-positive height/step).
+ */
+declare function snapDeltaMinutes(translationPx: number, cellHeightPx: number, stepMinutes: number): number;
+/** A copy of `date` shifted by `minutes` (may be negative). */
+declare function shiftMinutes(date: Date, minutes: number): Date;
+/**
+ * Resolve a committed drag into the event's new bounds: `start` shifts by
+ * `deltaStartMinutes`, `end` by `deltaEndMinutes` (a move passes the same delta
+ * to both; a resize passes 0 for the start). Returns `null` when the change
+ * would collapse the event below one `snapMinutes` step, so the gesture leaves
+ * the event untouched rather than committing a degenerate duration. Pure, so the
+ * commit path is unit-testable without a running gesture.
+ */
+declare function resolveDraggedBounds(start: Date, end: Date, deltaStartMinutes: number, deltaEndMinutes: number, snapMinutes: number): {
+  start: Date;
+  end: Date;
+} | null;
+/**
+ * The start/end of a new event swept out on `day` by dragging from `startPx` to
+ * `endPx` (vertical pixels from the grid's top, i.e. the `minHour` line). Both
+ * ends snap to `snapMinutes`; the range is ordered (drag up or down) and widened
+ * to at least one step so a stationary press still yields a usable event.
+ * Returns `null` for a degenerate grid (non-positive height/step). Pure, so the
+ * commit path is unit-testable without a running gesture.
+ */
+declare function cellRangeFromDrag(day: Date, startPx: number, endPx: number, cellHeightPx: number, minHour: number, snapMinutes: number): {
+  start: Date;
+  end: Date;
+} | null;
+//#endregion
+//#region src/utils/eventDisplay.d.ts
+/**
+ * Minimum event-box height (px) before the built-in renderer shows the time line
+ * on a narrow multi-column timed grid. Tied to the default theme's font sizes.
+ */
+declare const MIN_BOX_HEIGHT_FOR_TIME = 56;
+/** Hard-clip an overflowing title by default; opt into a trailing ellipsis. */
+declare function titleEllipsizeMode(ellipsizeTitle: boolean): "clip" | "tail";
+/**
+ * Screen-reader label for an event: its title followed by "all day" or its time
+ * range (which the grid otherwise only conveys visually). Empty title is dropped.
+ */
+declare function eventAccessibilityLabel(args: {
+  title?: string;
+  isAllDay: boolean;
+  start: Date;
+  end: Date;
+  ampm: boolean; /** Spoken text for an all-day event. Default "all day". */
+  allDayLabel?: string;
+}): string;
+/**
+ * Month cells and the all-day lane show a single clipped line; timed-grid titles
+ * (`undefined`) wrap to fill the box.
+ */
+declare function titleNumberOfLines(mode: CalendarMode, isAllDay: boolean): number | undefined;
+/**
+ * The secondary line under the title in the built-in renderer, or `null` when
+ * none should show. Timed events get their `start - end` range. An all-day event
+ * gets the literal "All day" in the schedule (which has no all-day lane to
+ * signal it positionally) and nothing on the day/week grid (the lane already
+ * does). Month cells and `showTime={false}` always return `null`.
+ */
+declare function eventTimeLabel(args: {
+  mode: CalendarMode;
+  isAllDay: boolean;
+  start: Date;
+  end: Date;
+  ampm: boolean;
+  showTime: boolean; /** Text for an all-day event in the schedule. Default "All day". */
+  allDayLabel?: string;
+}): string | null;
+/**
+ * The default hour-axis label shared by both renderers' time grids, so the gutter
+ * reads the same on each: 24-hour "HH:00" (e.g. "08:00"), or a compact 12-hour
+ * "h AM/PM" (e.g. "8 AM") when `ampm` is set. Exported so a custom hour renderer
+ * can reuse the same formatting.
+ */
+declare function formatHour(hour: number, opts?: {
+  ampm?: boolean;
+}): string;
+/**
+ * Whether the time line fits in the box. The wide `day` column and contexts with
+ * no live box height (e.g. schedule, where `boxHeightPx` is undefined) always
+ * show it; narrow multi-column modes only once the box is at least
+ * {@link MIN_BOX_HEIGHT_FOR_TIME} tall. Runs on the UI thread inside the event
+ * renderer's animated style.
+ */
+declare function isTimeVisibleAtHeight(boxHeightPx: number | undefined, mode: CalendarMode): boolean;
+/** Layout for the built-in timed-grid event chip at a given box height. */
+type EventChipLayout = {
+  /**
+   * Max whole title lines that fit in the box. `0` means "no clamp" (the box
+   * height is unknown, e.g. the schedule), so the title may wrap freely.
+   */
+  titleMaxLines: number; /** Whether the secondary time line still has room below the title. */
+  showTime: boolean;
+};
+/**
+ * Lay out the built-in timed-grid event chip for a box of `boxHeightPx`: how
+ * many whole title lines fit, and whether the time line still has room below
+ * them. The title is primary, so the title fills the box in whole lines (never a
+ * half-cropped line) and the time only shows once a full line is left over. Pass
+ * `titleLineHeightPx`/`timeLineHeightPx` matching the rendered line heights so
+ * the clamp lands on a line boundary.
+ *
+ * Worklet-safe, so the native renderer can drive the title's max-height on the UI
+ * thread as the grid zooms; the dom renderer calls it with its static box height.
+ * A `boxHeightPx` of `undefined` (the schedule has no live box height) returns
+ * `titleMaxLines: 0` (no clamp) with the unconditional time visibility.
+ */
+declare function eventChipLayout(args: {
+  boxHeightPx: number | undefined;
+  mode: CalendarMode;
+  hasTime: boolean;
+  titleLineHeightPx: number;
+  timeLineHeightPx: number;
+  paddingYPx: number;
+}): EventChipLayout;
+/** How many month-cell chips fit in the available height. */
+type MonthEventCapacity = {
+  /** Count when every event fits, with no overflow label. */full: number; /** Count that leaves room for the "+N more" label. */
+  withMore: number;
+};
+/**
+ * Derive how many event chips fit in a month cell from the measured space.
+ * `chipRowHeightPx` is one chip plus its gap; `moreRowHeightPx` is the overflow
+ * label plus its gap. Both counts are clamped to >= 0.
+ */
+declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx: number, moreRowHeightPx: number): MonthEventCapacity;
+/**
+ * Chips to show for a day: all of them when they fit, otherwise `withMore` (at
+ * least one) so the rest collapse into a "+N more" label.
+ */
+declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
+//#endregion
+//#region src/utils/layout.d.ts
+type PositionedEvent<T> = {
+  event: CalendarEvent<T>; /** Hours from midnight to the event's segment start on this day (fractional). */
+  startHours: number; /** Segment duration in hours on this day (clamped to a small minimum). */
+  durationHours: number; /** Zero-based column index within its overlap cluster. */
+  column: number; /** Total columns in this event's overlap cluster. */
+  columns: number; /** True when the segment is clipped because the event continues before/after this day. */
+  continuesBefore: boolean;
+  continuesAfter: boolean;
+};
+/**
+ * Lay out a single day's events: events that overlap in time are split into
+ * side-by-side columns. Multi-day events are clipped to the portion that falls
+ * on `day` (e.g. a 23:00→01:00 event renders 23:00–24:00 on the start day and
+ * 00:00–01:00 on the next). Pure — safe to call per render, never per frame.
+ */
+declare function layoutDayEvents<T>(events: CalendarEvent<T>[], day: Date): PositionedEvent<T>[];
+/**
+ * Whether an event belongs in the all-day lane. An explicit `allDay` flag wins;
+ * otherwise it's inferred when the event spans whole days (both `start` and
+ * `end` land on midnight, e.g. an iCal-style all-day event). Pure.
+ */
+declare function isAllDayEvent<T>(event: CalendarEvent<T>): boolean;
+/**
+ * The `startOfDay` ISO keys of every calendar day an event touches (inclusive).
+ * An event ending exactly at midnight does not count the following day. Used to
+ * index events by day for the month grid. Pure.
+ */
+declare function eventDayKeys<T>(event: CalendarEvent<T>): string[];
+/**
+ * Index events by the `startOfDay` ISO key of every day they touch (via
+ * {@link eventDayKeys}), so a month grid can look up a day's events with
+ * `startOfDay(date).toISOString()`. Built once and shared across month cells.
+ */
+declare function groupEventsByDay<T>(events: readonly CalendarEvent<T>[]): Map<string, CalendarEvent<T>[]>;
+/**
+ * Order a day's events for the month and list views: all-day events come first
+ * (they head the day regardless of their start time), then timed events by start.
+ * Shared by both renderers so the order is identical. Use as an `Array.sort`
+ * comparator.
+ */
+declare function compareDayEvents<T>(a: CalendarEvent<T>, b: CalendarEvent<T>): number;
+/**
+ * The closed hour-spans of a day to shade on the time grid, given a
+ * `businessHours` callback and the visible `[minHour, maxHour]` window: the spans
+ * before open and after close (clamped to the window), the whole window when the
+ * day is closed (`null`) or the open hours are inverted/empty, or none when the
+ * callback returns `undefined`. Shared by both renderers so shading stays
+ * identical. Co-located with `groupEventsByDay`; both feed the grid layout.
+ */
+declare function closedHourBands(day: Date, businessHours: BusinessHours | undefined, minHour?: number, maxHour?: number): {
+  start: number;
+  end: number;
+}[];
+//#endregion
+//#region src/utils/monthGrid.d.ts
+/** A single day in the grid, with all the state a custom cell needs to render. */
+interface MonthGridDay {
+  date: Date;
+  /** Stable `yyyy-MM-dd` id, handy as a React key. */
+  id: string;
+  /** Day-of-month, e.g. "1". */
+  label: string;
+  isCurrentMonth: boolean;
+  isToday: boolean;
+  isWeekend: boolean;
+  isDisabled: boolean;
+  isSelected: boolean;
+  isRangeStart: boolean;
+  isRangeEnd: boolean;
+  /** Inside a complete range (endpoints included). */
+  isInRange: boolean;
+}
+/** One week row. */
+interface MonthGridWeek {
+  id: string;
+  days: MonthGridDay[];
+}
+/** A weekday header cell (e.g. "Mon"). */
+interface MonthGridWeekday {
+  date: Date;
+  label: string;
+}
+interface MonthGrid {
+  weeks: MonthGridWeek[];
+  weekdays: MonthGridWeekday[];
+}
+interface UseMonthGridOptions extends DateSelectionConstraints {
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn;
+  /** Always return six week rows for a fixed-height grid. Default false. */
+  showSixWeeks?: boolean;
+  /** Reverse each week's day order (right-to-left). Default false. */
+  isRTL?: boolean;
+  /** Selected discrete days (single/multiple). */
+  selectedDates?: Date[];
+  /** Selected span. */
+  selectedRange?: DateRange;
+  /** A date-fns locale for the weekday labels. */
+  locale?: Locale;
+}
+/**
+ * Pure month-grid builder: the weeks and weekday headers for `month`, each day
+ * annotated with selection/disabled/today state. Use this when you need the
+ * data outside React; inside a component prefer {@link useMonthGrid}.
+ */
+declare function buildMonthGrid(month: Date, options?: UseMonthGridOptions): MonthGrid;
+/**
+ * Headless month-grid hook. Returns the weeks and weekday headers for `month`,
+ * each day annotated with selection/disabled/today state, so you can render a
+ * fully custom calendar without reimplementing the date maths.
+ *
+ * ```tsx
+ * const { weeks, weekdays } = useMonthGrid(month, { selectedRange: range });
+ * // map weekdays -> header cells, weeks -> rows, days -> your own <DayCell />
+ * ```
+ */
+declare function useMonthGrid(month: Date, options?: UseMonthGridOptions): MonthGrid;
+//#endregion
+//#region src/utils/recurrence.d.ts
+/**
+ * Materialise recurring events into concrete occurrences overlapping
+ * `[rangeStart, rangeEnd]`. Non-recurring events pass through untouched, so the
+ * result is ready to hand to `<Calendar events={...} />`. Each occurrence keeps
+ * the original event's duration and fields (minus `recurrence`).
+ */
+declare function expandRecurringEvents<T>(events: CalendarEvent<T>[], rangeStart: Date, rangeEnd: Date): CalendarEvent<T>[];
+//#endregion
+//#region src/utils/timezone.d.ts
+/**
+ * Reinterpret an instant as its wall-clock time in `timeZone`, returned as a
+ * device-local `Date` whose fields (hours, minutes, …) read back as that zone's
+ * clock. The calendar lays events out from `getHours()`/`getMinutes()`, so
+ * passing zoned dates makes it render in `timeZone` regardless of the device.
+ *
+ * DST-correct via `Intl` (available on modern React Native Hermes/JSC and the
+ * web). The result is for display/layout only; it no longer points at the
+ * original UTC instant, so don't round-trip it back to a real time.
+ */
+declare function toZonedTime(date: Date, timeZone: string): Date;
+/**
+ * Map every event's `start`/`end` through {@link toZonedTime} so the calendar
+ * displays them in `timeZone`. Other fields are preserved. Memoize the result
+ * (e.g. with `useMemo`) since it allocates new dates.
+ */
+declare function eventsInTimeZone<T>(events: CalendarEvent<T>[], timeZone: string): CalendarEvent<T>[];
+//#endregion
+export { BusinessHours, CalendarColors, CalendarEvent, CalendarMode, CalendarSelection, CalendarSelectionProvider, DateRange, DateSelectionConstraints, DayBadgeKind, DaySelectionState, EventChipLayout, EventKeyExtractor, ICalendarEvent, MIN_BOX_HEIGHT_FOR_TIME, MonthEventCapacity, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RangeBandKind, RecurrenceFrequency, RecurrenceRule, TimeGridMode, UseDateRangeOptions, UseMonthGridOptions, WeekStartsOn, bandRounding, buildMonthGrid, buildMonthWeeks, cellRangeFromDrag, closedHourBands, compareDayEvents, darkColors, dayBadgeKind, daySelectionState, eventAccessibilityLabel, eventChipLayout, eventDayKeys, eventTimeLabel, eventsInTimeZone, expandRecurringEvents, formatHour, getIsToday, getViewDays, getWeekDays, groupEventsByDay, isAllDayEvent, isDateSelectable, isRangeEndpoint, isSameCalendarDay, isTimeVisibleAtHeight, isWeekend, isWithinDateRange, layoutDayEvents, lightColors, minutesIntoDay, monthEventCapacity, monthVisibleCount, nextDateRange, rangeBandKind, resolveDraggedBounds, shiftMinutes, snapDeltaMinutes, titleEllipsizeMode, titleNumberOfLines, toZonedTime, useCalendarSelection, useDateRange, useMonthGrid, viewDayCount, weekDaysCount };