@super-calendar/core 2.0.0 → 2.1.3

package/README.md

@@ -0,0 +1,56 @@
+# @super-calendar/core
+
+[![JSR](https://jsr.io/badges/@super-calendar/core)](https://jsr.io/@super-calendar/core) [![JSR score](https://jsr.io/badges/@super-calendar/core/score)](https://jsr.io/@super-calendar/core)
+
+The render-agnostic core of [super-calendar](https://github.com/afonsojramos/react-native-super-calendar): date math, the selection model, event layout, the month-grid builder, the headless hooks, and the neutral theme tokens.
+
+It imports nothing from React Native, react-dom, Reanimated, Gesture Handler, or Legend List, so it bundles into any renderer. Use it to drive your own UI, or pair it with [`@super-calendar/dom`](https://jsr.io/@super-calendar/dom) (react-dom) or [`@super-calendar/native`](https://jsr.io/@super-calendar/native) (React Native).
+
+## Install
+
+```sh
+# Deno
+deno add jsr:@super-calendar/core
+
+# npm / pnpm / yarn / bun
+npx jsr add @super-calendar/core
+pnpm dlx jsr add @super-calendar/core
+bunx jsr add @super-calendar/core
+```
+
+Peer dependencies: `date-fns` (>=3) and `react` (>=19).
+
+## Usage
+
+Build a fully custom month grid from the headless `useMonthGrid` hook. It returns the weeks, the weekday headers, and per-day state for you to render however you like.
+
+```tsx
+import { useMonthGrid } from "@super-calendar/core";
+
+function MyGrid({ month }: { month: Date }) {
+  const { weeks, weekdays } = useMonthGrid(month, { weekStartsOn: 1 });
+
+  return weeks.map((week) =>
+    week.days.map((day) => (
+      // day carries isToday / isSelected / isInRange / isDisabled / isCurrentMonth
+      <DayCell key={day.date.toISOString()} day={day} />
+    )),
+  );
+}
+```
+
+Manage single, multiple, or range selection with `useDateRange`:
+
+```ts
+import { useDateRange } from "@super-calendar/core";
+
+const range = useDateRange({ mode: "range" });
+```
+
+## Documentation
+
+See the [full documentation](https://super-calendar.afonsojramos.me) and the [API reference](https://super-calendar.afonsojramos.me/reference/api).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 import { Locale } from "date-fns";
+import { Dispatch, SetStateAction } from "react";
 
 //#region src/types.d.ts
+/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
 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">;
@@ -11,8 +13,11 @@ type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
  * threaded through untouched via the `T` generic.
  */
 interface ICalendarEvent {
+  /** When the event begins. */
   start: Date;
+  /** When the event ends. */
   end: Date;
+  /** Display label, shown by the built-in default renderer. */
   title?: string;
   /**
    * Force this event into the all-day lane (above the time grid) instead of the
@@ -33,6 +38,7 @@ interface ICalendarEvent {
 type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
 /** A simple, RRULE-inspired repeat rule expanded by `expandRecurringEvents`. */
 interface RecurrenceRule {
+  /** How often the event repeats. */
   freq: RecurrenceFrequency;
   /** Repeat every N periods. Default 1. */
   interval?: number;
@@ -68,6 +74,7 @@ type BusinessHours = (date: Date) => {
 } | null;
 //#endregion
 //#region src/tokens.d.ts
+/** The shared colour palette both renderers derive their themes from. */
 interface CalendarColors {
   /** Hour lines, day separators and month-cell borders. */
   gridLine: string;
@@ -100,7 +107,9 @@ interface CalendarColors {
   /** Default event chip text. */
   eventText: string;
 }
+/** The default light-theme colour palette. */
 declare const lightColors: CalendarColors;
+/** The default dark-theme colour palette. */
 declare const darkColors: CalendarColors;
 //#endregion
 //#region src/presentation.d.ts
@@ -130,7 +139,9 @@ declare function dayBadgeKind(day: {
 //#region src/utils/dateRange.d.ts
 /** A selected span. `end` is `null` while only the first endpoint has been picked. */
 interface DateRange {
+  /** The first endpoint. */
   start: Date;
+  /** The second endpoint, or `null` while only the first has been picked. */
   end: Date | null;
 }
 /** Limits applied before a date can be selected. */
@@ -166,7 +177,9 @@ interface DaySelectionState {
   isSelected: boolean;
   /** Inside a complete range, endpoints included (and not disabled). */
   isInRange: boolean;
+  /** The range's start endpoint (and not disabled). */
   isRangeStart: boolean;
+  /** The range's end endpoint (and not disabled). */
   isRangeEnd: boolean;
 }
 /**
@@ -184,7 +197,9 @@ declare function daySelectionState(date: Date, selection: {
  * cached/virtualized day cells still repaint when any of it changes.
  */
 interface CalendarSelection extends DateSelectionConstraints {
+  /** Selected discrete days (single or multiple). */
   selectedDates?: Date[];
+  /** Selected span. */
   selectedRange?: DateRange;
 }
 /**
@@ -193,12 +208,26 @@ interface CalendarSelection extends DateSelectionConstraints {
  * the virtualized list has cached (and so won't re-render) their page.
  */
 declare const CalendarSelectionProvider: import("react").Provider<CalendarSelection>;
+/** Reads the active selection provided by {@link CalendarSelectionProvider}. */
 declare const useCalendarSelection: () => CalendarSelection;
 /** Options for {@link useDateRange}. */
 interface UseDateRangeOptions extends DateSelectionConstraints {
   /** Pre-select a range on mount. */
   initialRange?: DateRange | null;
 }
+/** The state and handlers returned by {@link useDateRange}. */
+interface UseDateRangeResult {
+  /** The current selection; `null` until the first endpoint is picked. */
+  range: DateRange | null;
+  /** Wire to `onPressDay`: advances the range (start, then end, then restarts). */
+  onPressDate: (date: Date) => void;
+  /** Set both endpoints at once (ordered); ignored if either isn't selectable. */
+  selectRange: (a: Date, b: Date) => void;
+  /** Clear the selection. */
+  reset: () => void;
+  /** The raw state setter, for full control. */
+  setRange: Dispatch<SetStateAction<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
@@ -209,13 +238,7 @@ interface UseDateRangeOptions extends DateSelectionConstraints {
  * <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>>;
-};
+declare function useDateRange(options?: UseDateRangeOptions): UseDateRangeResult;
 //#endregion
 //#region src/utils/dates.d.ts
 /** The seven dates of the week containing `date`, starting on `weekStartsOn`. */
@@ -247,8 +270,11 @@ declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, {
   showSixWeeks?: boolean;
   isRTL?: boolean;
 }) => Date[][];
+/** True when `date` is a Saturday or Sunday. */
 declare const isWeekend: (date: Date) => boolean;
+/** True when `date` falls on the current calendar day. */
 declare const getIsToday: (date: Date) => boolean;
+/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
 declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
 /** Minutes elapsed since midnight (0–1439). */
 declare const minutesIntoDay: (date: Date) => number;
@@ -393,8 +419,9 @@ declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx:
 declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
 //#endregion
 //#region src/utils/layout.d.ts
+/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
 type PositionedEvent<T> = {
-  event: CalendarEvent<T>; /** Hours from midnight to the event's segment start on this day (fractional). */
+  /** The source event for this segment. */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. */
@@ -450,35 +477,51 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
 //#region src/utils/monthGrid.d.ts
 /** A single day in the grid, with all the state a custom cell needs to render. */
 interface MonthGridDay {
+  /** The day this cell represents. */
   date: Date;
   /** Stable `yyyy-MM-dd` id, handy as a React key. */
   id: string;
   /** Day-of-month, e.g. "1". */
   label: string;
+  /** False for days bleeding in from the previous or next month. */
   isCurrentMonth: boolean;
+  /** The day is today. */
   isToday: boolean;
+  /** The day is a Saturday or Sunday. */
   isWeekend: boolean;
+  /** The day fails the min/max/disabled constraints. */
   isDisabled: boolean;
+  /** The day is a `selectedDates` day or a range endpoint (and not disabled). */
   isSelected: boolean;
+  /** The day is the range's start endpoint. */
   isRangeStart: boolean;
+  /** The day is the range's end endpoint. */
   isRangeEnd: boolean;
   /** Inside a complete range (endpoints included). */
   isInRange: boolean;
 }
 /** One week row. */
 interface MonthGridWeek {
+  /** Stable id for the week row, handy as a React key. */
   id: string;
+  /** The seven days of the row, in display order. */
   days: MonthGridDay[];
 }
 /** A weekday header cell (e.g. "Mon"). */
 interface MonthGridWeekday {
+  /** A representative date for the column, used to derive the label. */
   date: Date;
+  /** The short weekday name (e.g. "Mon"), localised via `locale`. */
   label: string;
 }
+/** The full grid for one month: the week rows and the weekday header cells. */
 interface MonthGrid {
+  /** The week rows, padded to whole weeks. */
   weeks: MonthGridWeek[];
+  /** The weekday header cells, in display order. */
   weekdays: MonthGridWeekday[];
 }
+/** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
@@ -539,4 +582,4 @@ declare function toZonedTime(date: Date, timeZone: string): Date;
  */
 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 };
+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, UseDateRangeResult, 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 };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+import { Dispatch, SetStateAction } from "react";
 import { Locale } from "date-fns";
 
 //#region src/types.d.ts
+/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
 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">;
@@ -11,8 +13,11 @@ type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
  * threaded through untouched via the `T` generic.
  */
 interface ICalendarEvent {
+  /** When the event begins. */
   start: Date;
+  /** When the event ends. */
   end: Date;
+  /** Display label, shown by the built-in default renderer. */
   title?: string;
   /**
    * Force this event into the all-day lane (above the time grid) instead of the
@@ -33,6 +38,7 @@ interface ICalendarEvent {
 type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
 /** A simple, RRULE-inspired repeat rule expanded by `expandRecurringEvents`. */
 interface RecurrenceRule {
+  /** How often the event repeats. */
   freq: RecurrenceFrequency;
   /** Repeat every N periods. Default 1. */
   interval?: number;
@@ -68,6 +74,7 @@ type BusinessHours = (date: Date) => {
 } | null;
 //#endregion
 //#region src/tokens.d.ts
+/** The shared colour palette both renderers derive their themes from. */
 interface CalendarColors {
   /** Hour lines, day separators and month-cell borders. */
   gridLine: string;
@@ -100,7 +107,9 @@ interface CalendarColors {
   /** Default event chip text. */
   eventText: string;
 }
+/** The default light-theme colour palette. */
 declare const lightColors: CalendarColors;
+/** The default dark-theme colour palette. */
 declare const darkColors: CalendarColors;
 //#endregion
 //#region src/presentation.d.ts
@@ -130,7 +139,9 @@ declare function dayBadgeKind(day: {
 //#region src/utils/dateRange.d.ts
 /** A selected span. `end` is `null` while only the first endpoint has been picked. */
 interface DateRange {
+  /** The first endpoint. */
   start: Date;
+  /** The second endpoint, or `null` while only the first has been picked. */
   end: Date | null;
 }
 /** Limits applied before a date can be selected. */
@@ -166,7 +177,9 @@ interface DaySelectionState {
   isSelected: boolean;
   /** Inside a complete range, endpoints included (and not disabled). */
   isInRange: boolean;
+  /** The range's start endpoint (and not disabled). */
   isRangeStart: boolean;
+  /** The range's end endpoint (and not disabled). */
   isRangeEnd: boolean;
 }
 /**
@@ -184,7 +197,9 @@ declare function daySelectionState(date: Date, selection: {
  * cached/virtualized day cells still repaint when any of it changes.
  */
 interface CalendarSelection extends DateSelectionConstraints {
+  /** Selected discrete days (single or multiple). */
   selectedDates?: Date[];
+  /** Selected span. */
   selectedRange?: DateRange;
 }
 /**
@@ -193,12 +208,26 @@ interface CalendarSelection extends DateSelectionConstraints {
  * the virtualized list has cached (and so won't re-render) their page.
  */
 declare const CalendarSelectionProvider: import("react").Provider<CalendarSelection>;
+/** Reads the active selection provided by {@link CalendarSelectionProvider}. */
 declare const useCalendarSelection: () => CalendarSelection;
 /** Options for {@link useDateRange}. */
 interface UseDateRangeOptions extends DateSelectionConstraints {
   /** Pre-select a range on mount. */
   initialRange?: DateRange | null;
 }
+/** The state and handlers returned by {@link useDateRange}. */
+interface UseDateRangeResult {
+  /** The current selection; `null` until the first endpoint is picked. */
+  range: DateRange | null;
+  /** Wire to `onPressDay`: advances the range (start, then end, then restarts). */
+  onPressDate: (date: Date) => void;
+  /** Set both endpoints at once (ordered); ignored if either isn't selectable. */
+  selectRange: (a: Date, b: Date) => void;
+  /** Clear the selection. */
+  reset: () => void;
+  /** The raw state setter, for full control. */
+  setRange: Dispatch<SetStateAction<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
@@ -209,13 +238,7 @@ interface UseDateRangeOptions extends DateSelectionConstraints {
  * <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>>;
-};
+declare function useDateRange(options?: UseDateRangeOptions): UseDateRangeResult;
 //#endregion
 //#region src/utils/dates.d.ts
 /** The seven dates of the week containing `date`, starting on `weekStartsOn`. */
@@ -247,8 +270,11 @@ declare const buildMonthWeeks: (month: Date, weekStartsOn: WeekStartsOn, {
   showSixWeeks?: boolean;
   isRTL?: boolean;
 }) => Date[][];
+/** True when `date` is a Saturday or Sunday. */
 declare const isWeekend: (date: Date) => boolean;
+/** True when `date` falls on the current calendar day. */
 declare const getIsToday: (date: Date) => boolean;
+/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
 declare const isSameCalendarDay: (a: Date, b: Date) => boolean;
 /** Minutes elapsed since midnight (0–1439). */
 declare const minutesIntoDay: (date: Date) => number;
@@ -393,8 +419,9 @@ declare function monthEventCapacity(availableHeightPx: number, chipRowHeightPx:
 declare function monthVisibleCount(total: number, capacity: MonthEventCapacity): number;
 //#endregion
 //#region src/utils/layout.d.ts
+/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
 type PositionedEvent<T> = {
-  event: CalendarEvent<T>; /** Hours from midnight to the event's segment start on this day (fractional). */
+  /** The source event for this segment. */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. */
@@ -450,35 +477,51 @@ declare function closedHourBands(day: Date, businessHours: BusinessHours | undef
 //#region src/utils/monthGrid.d.ts
 /** A single day in the grid, with all the state a custom cell needs to render. */
 interface MonthGridDay {
+  /** The day this cell represents. */
   date: Date;
   /** Stable `yyyy-MM-dd` id, handy as a React key. */
   id: string;
   /** Day-of-month, e.g. "1". */
   label: string;
+  /** False for days bleeding in from the previous or next month. */
   isCurrentMonth: boolean;
+  /** The day is today. */
   isToday: boolean;
+  /** The day is a Saturday or Sunday. */
   isWeekend: boolean;
+  /** The day fails the min/max/disabled constraints. */
   isDisabled: boolean;
+  /** The day is a `selectedDates` day or a range endpoint (and not disabled). */
   isSelected: boolean;
+  /** The day is the range's start endpoint. */
   isRangeStart: boolean;
+  /** The day is the range's end endpoint. */
   isRangeEnd: boolean;
   /** Inside a complete range (endpoints included). */
   isInRange: boolean;
 }
 /** One week row. */
 interface MonthGridWeek {
+  /** Stable id for the week row, handy as a React key. */
   id: string;
+  /** The seven days of the row, in display order. */
   days: MonthGridDay[];
 }
 /** A weekday header cell (e.g. "Mon"). */
 interface MonthGridWeekday {
+  /** A representative date for the column, used to derive the label. */
   date: Date;
+  /** The short weekday name (e.g. "Mon"), localised via `locale`. */
   label: string;
 }
+/** The full grid for one month: the week rows and the weekday header cells. */
 interface MonthGrid {
+  /** The week rows, padded to whole weeks. */
   weeks: MonthGridWeek[];
+  /** The weekday header cells, in display order. */
   weekdays: MonthGridWeekday[];
 }
+/** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
@@ -539,4 +582,4 @@ declare function toZonedTime(date: Date, timeZone: string): Date;
  */
 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 };
+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, UseDateRangeResult, 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 };

package/dist/index.js

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let date_fns = require("date-fns");
 let react = require("react");
 //#region src/tokens.ts
+/** The default light-theme colour palette. */
 const lightColors = {
 	gridLine: "#E2E4E9",
 	weekendBackground: "#F6F7F9",
@@ -19,6 +20,7 @@ const lightColors = {
 	eventBackground: "#DCE7FF",
 	eventText: "#1A1B1E"
 };
+/** The default dark-theme colour palette. */
 const darkColors = {
 	gridLine: "#2A2E37",
 	weekendBackground: "#15171C",
@@ -130,11 +132,14 @@ const buildMonthWeeks = (month, weekStartsOn, { showSixWeeks = false, isRTL = fa
 	}
 	return weeks;
 };
+/** True when `date` is a Saturday or Sunday. */
 const isWeekend = (date) => {
 	const day = date.getDay();
 	return day === 0 || day === 6;
 };
+/** True when `date` falls on the current calendar day. */
 const getIsToday = (date) => (0, date_fns.isToday)(date);
+/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
 const isSameCalendarDay = (a, b) => (0, date_fns.isSameDay)(a, b);
 /** Minutes elapsed since midnight (0–1439). */
 const minutesIntoDay = (date) => (0, date_fns.getHours)(date) * 60 + (0, date_fns.getMinutes)(date);
@@ -210,6 +215,7 @@ const CalendarSelectionContext = (0, react.createContext)({});
 * the virtualized list has cached (and so won't re-render) their page.
 */
 const CalendarSelectionProvider = CalendarSelectionContext.Provider;
+/** Reads the active selection provided by {@link CalendarSelectionProvider}. */
 const useCalendarSelection = () => (0, react.useContext)(CalendarSelectionContext);
 /**
 * Controlled-ish range selection state for the month view. Returns the current

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { addDays, addMonths, addWeeks, addYears, differenceInMinutes, eachDayOfInterval, endOfMonth, endOfWeek, format, getHours, getMinutes, isAfter, isBefore, isSameDay, isSameMonth, isToday, max, min, startOfDay, startOfMonth, startOfWeek } from "date-fns";
 import { createContext, useCallback, useContext, useMemo, useState } from "react";
 //#region src/tokens.ts
+/** The default light-theme colour palette. */
 const lightColors = {
 	gridLine: "#E2E4E9",
 	weekendBackground: "#F6F7F9",
@@ -18,6 +19,7 @@ const lightColors = {
 	eventBackground: "#DCE7FF",
 	eventText: "#1A1B1E"
 };
+/** The default dark-theme colour palette. */
 const darkColors = {
 	gridLine: "#2A2E37",
 	weekendBackground: "#15171C",
@@ -129,11 +131,14 @@ const buildMonthWeeks = (month, weekStartsOn, { showSixWeeks = false, isRTL = fa
 	}
 	return weeks;
 };
+/** True when `date` is a Saturday or Sunday. */
 const isWeekend = (date) => {
 	const day = date.getDay();
 	return day === 0 || day === 6;
 };
+/** True when `date` falls on the current calendar day. */
 const getIsToday = (date) => isToday(date);
+/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
 const isSameCalendarDay = (a, b) => isSameDay(a, b);
 /** Minutes elapsed since midnight (0–1439). */
 const minutesIntoDay = (date) => getHours(date) * 60 + getMinutes(date);
@@ -209,6 +214,7 @@ const CalendarSelectionContext = createContext({});
 * the virtualized list has cached (and so won't re-render) their page.
 */
 const CalendarSelectionProvider = CalendarSelectionContext.Provider;
+/** Reads the active selection provided by {@link CalendarSelectionProvider}. */
 const useCalendarSelection = () => useContext(CalendarSelectionContext);
 /**
 * Controlled-ish range selection state for the month view. Returns the current

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/core",
-  "version": "2.0.0",
+  "version": "2.1.3",
   "description": "Render-agnostic core for super-calendar: date math, selection model, event layout, the month-grid builder, headless hooks, and neutral theme tokens. No renderer.",
   "keywords": [
     "calendar",
@@ -9,10 +9,11 @@
     "headless",
     "react"
   ],
+  "homepage": "https://super-calendar.afonsojramos.me",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/afonsojramos/react-native-super-calendar.git",
+    "url": "git+https://github.com/afonsojramos/super-calendar.git",
     "directory": "packages/core"
   },
   "source": "./src/index.ts",

package/src/index.ts

@@ -1,7 +1,21 @@
-// @super-calendar/core: the render-agnostic core. Date math, the selection
-// model, event layout, the month-grid builder, the headless hooks, and the
-// neutral theme tokens. Imports nothing from React Native, react-dom, Reanimated,
-// Gesture Handler, or Legend List, so it bundles into any renderer.
+/**
+ * The render-agnostic core of super-calendar. Date math, the selection model,
+ * event layout, the month-grid builder, the headless hooks, and the neutral
+ * theme tokens.
+ *
+ * Imports nothing from React Native, react-dom, Reanimated, Gesture Handler, or
+ * Legend List, so it bundles into any renderer. Pair it with `@super-calendar/dom`
+ * or `@super-calendar/native`, or drive your own UI from the headless hooks.
+ *
+ * @example
+ * ```ts
+ * import { useMonthGrid, buildMonthWeeks } from "@super-calendar/core";
+ * ```
+ *
+ * @see https://super-calendar.afonsojramos.me
+ *
+ * @module
+ */
 export * from "./types";
 export * from "./tokens";
 export * from "./presentation";

package/src/tokens.ts

@@ -3,6 +3,7 @@
 // platform types. Renderer-specific metrics (cell / badge / band sizes) stay in
 // each renderer's theme, since they legitimately differ between the two.
 
+/** The shared colour palette both renderers derive their themes from. */
 export interface CalendarColors {
   /** Hour lines, day separators and month-cell borders. */
   gridLine: string;
@@ -36,6 +37,7 @@ export interface CalendarColors {
   eventText: string;
 }
 
+/** The default light-theme colour palette. */
 export const lightColors: CalendarColors = {
   gridLine: "#E2E4E9",
   weekendBackground: "#F6F7F9",
@@ -54,6 +56,7 @@ export const lightColors: CalendarColors = {
   eventText: "#1A1B1E",
 };
 
+/** The default dark-theme colour palette. */
 export const darkColors: CalendarColors = {
   gridLine: "#2A2E37",
   weekendBackground: "#15171C",

package/src/types.ts

@@ -1,3 +1,4 @@
+/** The view the calendar renders: a day-column grid (`day`, `3days`, `week`, `custom`), the `month` grid, or the `schedule` list. */
 export type CalendarMode = "day" | "3days" | "week" | "custom" | "month" | "schedule";
 
 /** The time-grid modes (day-column views, excluding month and schedule). */
@@ -10,8 +11,11 @@ export type TimeGridMode = Exclude<CalendarMode, "month" | "schedule">;
  * threaded through untouched via the `T` generic.
  */
 export interface ICalendarEvent {
+  /** When the event begins. */
   start: Date;
+  /** When the event ends. */
   end: Date;
+  /** Display label, shown by the built-in default renderer. */
   title?: string;
   /**
    * Force this event into the all-day lane (above the time grid) instead of the
@@ -34,6 +38,7 @@ export type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
 
 /** A simple, RRULE-inspired repeat rule expanded by `expandRecurringEvents`. */
 export interface RecurrenceRule {
+  /** How often the event repeats. */
   freq: RecurrenceFrequency;
   /** Repeat every N periods. Default 1. */
   interval?: number;

package/src/utils/dateRange.ts

@@ -1,10 +1,21 @@
 import { isAfter, isBefore, startOfDay } from "date-fns";
-import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import {
+  type Context,
+  createContext,
+  type Dispatch,
+  type SetStateAction,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
 import { isSameCalendarDay } from "./dates";
 
 /** A selected span. `end` is `null` while only the first endpoint has been picked. */
 export interface DateRange {
+  /** The first endpoint. */
   start: Date;
+  /** The second endpoint, or `null` while only the first has been picked. */
   end: Date | null;
 }
 
@@ -72,7 +83,9 @@ export interface DaySelectionState {
   isSelected: boolean;
   /** Inside a complete range, endpoints included (and not disabled). */
   isInRange: boolean;
+  /** The range's start endpoint (and not disabled). */
   isRangeStart: boolean;
+  /** The range's end endpoint (and not disabled). */
   isRangeEnd: boolean;
 }
 
@@ -106,11 +119,13 @@ export function daySelectionState(
  * cached/virtualized day cells still repaint when any of it changes.
  */
 export interface CalendarSelection extends DateSelectionConstraints {
+  /** Selected discrete days (single or multiple). */
   selectedDates?: Date[];
+  /** Selected span. */
   selectedRange?: DateRange;
 }
 
-const CalendarSelectionContext = createContext<CalendarSelection>({});
+const CalendarSelectionContext: Context<CalendarSelection> = createContext<CalendarSelection>({});
 
 /**
  * Provides the active selection to the month grid. Day cells read it via
@@ -119,7 +134,8 @@ const CalendarSelectionContext = createContext<CalendarSelection>({});
  */
 export const CalendarSelectionProvider = CalendarSelectionContext.Provider;
 
-export const useCalendarSelection = () => useContext(CalendarSelectionContext);
+/** Reads the active selection provided by {@link CalendarSelectionProvider}. */
+export const useCalendarSelection = (): CalendarSelection => useContext(CalendarSelectionContext);
 
 /** Options for {@link useDateRange}. */
 export interface UseDateRangeOptions extends DateSelectionConstraints {
@@ -127,6 +143,20 @@ export interface UseDateRangeOptions extends DateSelectionConstraints {
   initialRange?: DateRange | null;
 }
 
+/** The state and handlers returned by {@link useDateRange}. */
+export interface UseDateRangeResult {
+  /** The current selection; `null` until the first endpoint is picked. */
+  range: DateRange | null;
+  /** Wire to `onPressDay`: advances the range (start, then end, then restarts). */
+  onPressDate: (date: Date) => void;
+  /** Set both endpoints at once (ordered); ignored if either isn't selectable. */
+  selectRange: (a: Date, b: Date) => void;
+  /** Clear the selection. */
+  reset: () => void;
+  /** The raw state setter, for full control. */
+  setRange: Dispatch<SetStateAction<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
@@ -137,7 +167,7 @@ export interface UseDateRangeOptions extends DateSelectionConstraints {
  * <Calendar mode="month" selectedRange={range ?? undefined} onPressDay={onPressDate} … />
  * ```
  */
-export function useDateRange(options: UseDateRangeOptions = {}) {
+export function useDateRange(options: UseDateRangeOptions = {}): UseDateRangeResult {
   const { initialRange = null, minDate, maxDate, isDateDisabled } = options;
   const [range, setRange] = useState<DateRange | null>(initialRange);
   const constraints = useMemo<DateSelectionConstraints>(

package/src/utils/dates.ts

@@ -105,13 +105,16 @@ export const buildMonthWeeks = (
   return weeks;
 };
 
+/** True when `date` is a Saturday or Sunday. */
 export const isWeekend = (date: Date): boolean => {
   const day = date.getDay();
   return day === 0 || day === 6;
 };
 
+/** True when `date` falls on the current calendar day. */
 export const getIsToday = (date: Date): boolean => isToday(date);
 
+/** True when `a` and `b` are the same calendar day (ignoring the time of day). */
 export const isSameCalendarDay = (a: Date, b: Date): boolean => isSameDay(a, b);
 
 /** Minutes elapsed since midnight (0–1439). */

package/src/utils/layout.ts

@@ -6,7 +6,9 @@ const MINUTES_PER_HOUR = 60;
 // span still occupies a sliver rather than collapsing to nothing.
 const MIN_DURATION_HOURS = 0.25;
 
+/** An event placed on a single day's time grid by {@link layoutDayEvents}, with its vertical span and overlap column. */
 export type PositionedEvent<T> = {
+  /** The source event for this segment. */
   event: CalendarEvent<T>;
   /** Hours from midnight to the event's segment start on this day (fractional). */
   startHours: number;

package/src/utils/monthGrid.ts

@@ -6,17 +6,25 @@ import { buildMonthWeeks, getIsToday, isWeekend } from "./dates";
 
 /** A single day in the grid, with all the state a custom cell needs to render. */
 export interface MonthGridDay {
+  /** The day this cell represents. */
   date: Date;
   /** Stable `yyyy-MM-dd` id, handy as a React key. */
   id: string;
   /** Day-of-month, e.g. "1". */
   label: string;
+  /** False for days bleeding in from the previous or next month. */
   isCurrentMonth: boolean;
+  /** The day is today. */
   isToday: boolean;
+  /** The day is a Saturday or Sunday. */
   isWeekend: boolean;
+  /** The day fails the min/max/disabled constraints. */
   isDisabled: boolean;
+  /** The day is a `selectedDates` day or a range endpoint (and not disabled). */
   isSelected: boolean;
+  /** The day is the range's start endpoint. */
   isRangeStart: boolean;
+  /** The day is the range's end endpoint. */
   isRangeEnd: boolean;
   /** Inside a complete range (endpoints included). */
   isInRange: boolean;
@@ -24,21 +32,29 @@ export interface MonthGridDay {
 
 /** One week row. */
 export interface MonthGridWeek {
+  /** Stable id for the week row, handy as a React key. */
   id: string;
+  /** The seven days of the row, in display order. */
   days: MonthGridDay[];
 }
 
 /** A weekday header cell (e.g. "Mon"). */
 export interface MonthGridWeekday {
+  /** A representative date for the column, used to derive the label. */
   date: Date;
+  /** The short weekday name (e.g. "Mon"), localised via `locale`. */
   label: string;
 }
 
+/** The full grid for one month: the week rows and the weekday header cells. */
 export interface MonthGrid {
+  /** The week rows, padded to whole weeks. */
   weeks: MonthGridWeek[];
+  /** The weekday header cells, in display order. */
   weekdays: MonthGridWeekday[];
 }
 
+/** Options for {@link buildMonthGrid} and {@link useMonthGrid}. */
 export interface UseMonthGridOptions extends DateSelectionConstraints {
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
   weekStartsOn?: WeekStartsOn;