@super-calendar/dom 2.0.0 → 2.1.2

package/README.md

@@ -0,0 +1,65 @@
+# @super-calendar/dom
+
+[![JSR](https://jsr.io/badges/@super-calendar/dom)](https://jsr.io/@super-calendar/dom) [![JSR score](https://jsr.io/badges/@super-calendar/dom/score)](https://jsr.io/@super-calendar/dom)
+
+The react-dom renderer for [super-calendar](https://github.com/afonsojramos/react-native-super-calendar): a virtualized **month / week / day** calendar and date picker built from real DOM components. No React Native, no react-native-web.
+
+It is built on the headless [`@super-calendar/core`](https://jsr.io/@super-calendar/core) and Legend List's DOM renderer.
+
+## Install
+
+```sh
+# Deno
+deno add jsr:@super-calendar/dom
+
+# npm / pnpm / yarn / bun
+npx jsr add @super-calendar/dom
+pnpm dlx jsr add @super-calendar/dom
+bunx jsr add @super-calendar/dom
+```
+
+Peer dependencies: `@legendapp/list` (>=3), `date-fns` (>=3), `react` (>=19), and `react-dom` (>=19).
+
+## Usage
+
+```tsx
+import { useState } from "react";
+import { Calendar, type CalendarEvent } from "@super-calendar/dom";
+
+type MyEvent = { id: string; color: string };
+
+const events: CalendarEvent<MyEvent>[] = [
+  {
+    id: "1",
+    color: "#1F6FEB",
+    title: "Lecture",
+    start: new Date(2026, 5, 19, 10, 0),
+    end: new Date(2026, 5, 19, 11, 30),
+  },
+];
+
+export function MyCalendar() {
+  const [date, setDate] = useState(new Date());
+
+  return (
+    <Calendar
+      mode="week"
+      date={date}
+      events={events}
+      weekStartsOn={1}
+      onPressDay={setDate}
+      onPressEvent={(event) => console.log(event.id)}
+    />
+  );
+}
+```
+
+For a custom picker, pair the headless hooks (`useDateRange`, `useMonthGrid`) with `MonthList` and `TimeGrid`, all re-exported from this package.
+
+## Documentation
+
+See the [full documentation](https://super-calendar.afonsojramos.me), the [quickstart](https://super-calendar.afonsojramos.me/quickstart), and the [API reference](https://super-calendar.afonsojramos.me/reference/api).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,8 +1,12 @@
 import { Locale } from "date-fns";
-import { CSSProperties, ComponentType, ReactNode } from "react";
+import { CSSProperties, ComponentType, ReactElement, ReactNode } from "react";
 import { BusinessHours, BusinessHours as BusinessHours$1, CalendarColors, CalendarEvent, CalendarEvent as CalendarEvent$1, CalendarMode, CalendarMode as CalendarMode$1, DateRange, DateRange as DateRange$1, DateSelectionConstraints, DateSelectionConstraints as DateSelectionConstraints$1, DaySelectionState, ICalendarEvent, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, TimeGridMode, TimeGridMode as TimeGridMode$1, UseDateRangeOptions, UseMonthGridOptions, WeekStartsOn, WeekStartsOn as WeekStartsOn$1, buildMonthGrid, daySelectionState, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, nextDateRange, useDateRange, useMonthGrid } from "@super-calendar/core";
 
 //#region src/theme.d.ts
+/**
+ * Theme for the react-dom renderer. Combines the shared color palette from
+ * `@super-calendar/core` with the DOM-specific pixel metrics and font stack.
+ */
 type DomCalendarTheme = CalendarColors & {
   /** Row height of a day cell, in px. */cellHeight: number; /** Diameter of the day badge, in px. */
   dayBadgeSize: number;
@@ -14,7 +18,9 @@ type DomCalendarTheme = CalendarColors & {
   rangeBandHeight: number; /** Font stack for the calendar. */
   fontFamily: string;
 };
+/** The default light theme: the core light palette plus the DOM metrics. */
 declare const defaultDomTheme: DomCalendarTheme;
+/** The dark theme: the core dark palette plus the DOM metrics. */
 declare const darkDomTheme: DomCalendarTheme;
 /** Merge a partial override onto a base theme (defaults to {@link defaultDomTheme}). */
 declare function mergeDomTheme(overrides?: Partial<DomCalendarTheme>, base?: DomCalendarTheme): DomCalendarTheme;
@@ -22,32 +28,42 @@ declare function mergeDomTheme(overrides?: Partial<DomCalendarTheme>, base?: Dom
 //#region src/Agenda.d.ts
 /** Props passed to a custom agenda (schedule) event renderer. */
 interface DomAgendaEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
   /** Always "schedule"; lets a renderer shared with other views branch on it. */
   mode: "schedule";
+  /** Whether the event is all-day. */
   isAllDay: boolean;
   /** Render the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this row. */
   onPress: () => void;
 }
+/** A component that renders a single agenda (schedule) event row. */
 type DomAgendaEvent<T = unknown> = ComponentType<DomAgendaEventArgs<T>>;
+/** Props for {@link Agenda}. */
 interface AgendaProps<T = unknown> {
   /** Events to list. The consumer controls which (and therefore the date range). */
   events: CalendarEvent$1<T>[];
+  /** date-fns locale for the day headers and time labels. */
   locale?: Locale;
   /** Render times in 12-hour AM/PM (default false, 24h). */
   ampm?: boolean;
   /** Highlight this date's header instead of the real "today". */
   activeDate?: Date;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
   /** Replace the built-in event row. */
   renderEvent?: DomAgendaEvent<T>;
+  /** Tap an event row. */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
   /** Tap a day's header. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -55,6 +71,11 @@ interface AgendaProps<T = unknown> {
  * elements. Events are sorted by start and grouped under a date header per day;
  * the consumer controls which events (and therefore which dates) are shown. The
  * react-dom counterpart of the React Native `Agenda`.
+ *
+ * @example
+ * ```tsx
+ * <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
+ * ```
  */
 declare function Agenda<T = unknown>({
   events,
@@ -68,15 +89,19 @@ declare function Agenda<T = unknown>({
   onPressDay,
   className,
   style
-}: AgendaProps<T>): import("react").JSX.Element;
+}: AgendaProps<T>): ReactElement;
 //#endregion
 //#region src/MonthView.d.ts
 /** Props passed to a custom month event chip renderer. */
 interface DomMonthEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
+  /** Call to fire the view's `onPressEvent` for this chip. */
   onPress: () => void;
 }
+/** A component that renders a single month-grid event chip. */
 type DomMonthEvent<T = unknown> = ComponentType<DomMonthEventArgs<T>>;
+/** Props for {@link MonthView}. */
 interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1 {
   /** Any day within the month to render. */
   date: Date;
@@ -126,13 +151,22 @@ interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1 {
    * (rendered without `events`) is always navigable regardless of this flag.
    */
   keyboardDayNavigation?: boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 interface MonthViewInternalProps<T = unknown> extends MonthViewProps<T> {
   eventsByDay?: ReadonlyMap<string, CalendarEvent$1<T>[]>;
 }
-/** A single static month grid, rendered with plain DOM elements. */
+/**
+ * A single static month grid, rendered with plain DOM elements.
+ *
+ * @example
+ * ```tsx
+ * <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
+ * ```
+ */
 declare function MonthView<T = unknown>({
   date,
   weekStartsOn,
@@ -158,28 +192,41 @@ declare function MonthView<T = unknown>({
   keyboardDayNavigation,
   className,
   style
-}: MonthViewInternalProps<T>): import("react").JSX.Element;
+}: MonthViewInternalProps<T>): ReactElement;
 //#endregion
 //#region src/TimeGrid.d.ts
 /** Props passed to a custom time-grid event renderer. */
 interface DomRenderEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
+  /** The current view mode. */
   mode: CalendarMode$1;
+  /** Whether the event is all-day. */
   isAllDay: boolean;
+  /** Pixel height of the event box (timed events only). */
   boxHeight?: number;
+  /** The event started before the visible day and continues into it. */
   continuesBefore?: boolean;
+  /** The event continues past the visible day. */
   continuesAfter?: boolean;
   /** Show the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this event. */
   onPress: () => void;
 }
+/** A component that renders a single time-grid event box. */
 type DomRenderEvent<T = unknown> = ComponentType<DomRenderEventArgs<T>>;
+/** Props for {@link TimeGrid}. */
 interface TimeGridProps<T = unknown> {
+  /** Anchor date; the visible columns are derived from it and `mode`. */
   date: Date;
+  /** Events to lay out on the grid. */
   events?: CalendarEvent$1<T>[];
   /** "day" (default), "3days", "week", or "custom" (with `numberOfDays`). */
   mode?: TimeGridMode$1;
+  /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn$1;
   /** Initial pixels per hour (default 48). */
   hourHeight?: number;
@@ -187,7 +234,9 @@ interface TimeGridProps<T = unknown> {
   scrollOffsetMinutes?: number;
   /** Pinch / Ctrl-⌘-scroll to zoom the grid (default true). */
   zoomable?: boolean;
+  /** Lower bound for pixels per hour when zooming. */
   minHourHeight?: number;
+  /** Upper bound for pixels per hour when zooming. */
   maxHourHeight?: number;
   /** Snap dragged events to this many minutes (default 15). */
   dragStepMinutes?: number;
@@ -201,13 +250,19 @@ interface TimeGridProps<T = unknown> {
   showNowIndicator?: boolean;
   /** Show the all-day lane above the grid (default true). */
   showAllDayEventCell?: boolean;
+  /** date-fns locale for the column headers and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Custom event renderer; falls back to the built-in event box. */
   renderEvent?: DomRenderEvent<T>;
-  /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
+  /** Replace the hour-axis label. Receives the hour (0-23) and the `ampm` flag. */
   hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /** Tap an event. */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  /** Tap a day's column header. */
   onPressDateHeader?: (day: Date) => void;
   /** Tap empty grid space; called with the date and time at the press. */
   onPressCell?: (date: Date) => void;
@@ -220,7 +275,9 @@ interface TimeGridProps<T = unknown> {
    * Return `false` to reject the drop (the event snaps back).
    */
   onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -228,6 +285,11 @@ interface TimeGridProps<T = unknown> {
  * positioned with the library's pure `layoutDayEvents`, so overlap columns and
  * multi-day clipping match the React Native renderer. Supports Ctrl/⌘-scroll and
  * two-finger pinch to zoom, and pointer drag to move / resize events.
+ *
+ * @example
+ * ```tsx
+ * <TimeGrid mode="week" date={new Date()} events={events} />
+ * ```
  */
 declare function TimeGrid<T = unknown>({
   date,
@@ -259,9 +321,10 @@ declare function TimeGrid<T = unknown>({
   onDragEvent,
   className,
   style
-}: TimeGridProps<T>): import("react").JSX.Element;
+}: TimeGridProps<T>): ReactElement;
 //#endregion
 //#region src/Calendar.d.ts
+/** Props for {@link Calendar}. */
 interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
   /**
    * The view to render (default "week"). `month` renders a month grid, `schedule`
@@ -276,11 +339,15 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
   weekStartsOn?: WeekStartsOn$1;
   /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** date-fns locale for titles, headers, and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
   /** Tap an event (both layouts). */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
@@ -346,6 +413,11 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
  * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
  * an {@link Agenda}; the time-grid modes render a {@link TimeGrid}. For a
  * scrolling month picker, use {@link MonthList} directly.
+ *
+ * @example
+ * ```tsx
+ * <Calendar mode="week" date={new Date()} events={events} />
+ * ```
  */
 declare function Calendar<T = unknown>({
   mode,
@@ -388,9 +460,10 @@ declare function Calendar<T = unknown>({
   onPressMore,
   renderMonthEvent,
   renderScheduleEvent
-}: CalendarProps<T>): import("react").JSX.Element;
+}: CalendarProps<T>): ReactElement;
 //#endregion
 //#region src/MonthList.d.ts
+/** Props for {@link MonthList}. */
 interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   /** Anchor month; the list spans `pastMonths` before to `futureMonths` after. */
   date: Date;
@@ -398,6 +471,7 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   pastMonths?: number;
   /** Months to render after the anchor (default 12). */
   futureMonths?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn$1;
   /** Events to render as chips in each day cell (calendar layout when provided). */
   events?: CalendarEvent$1<T>[];
@@ -411,11 +485,15 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
   /** Tap the "+N more" overflow row. */
   onPressMore?: (events: CalendarEvent$1<T>[], date: Date) => void;
+  /** Selected span; days between the endpoints get the range band. */
   selectedRange?: DateRange$1;
+  /** Discrete selected days (single / multiple). */
   selectedDates?: Date[];
   /** Fill the whole cell on selection instead of the default rounded pill band. */
   fillCellOnSelection?: boolean;
+  /** date-fns locale for the month titles and weekday labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
@@ -425,8 +503,11 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
    * layout (no `events`) is always navigable regardless.
    */
   keyboardDayNavigation?: boolean;
+  /** Fired when a selectable day is clicked. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -458,6 +539,6 @@ declare function MonthList<T = unknown>({
   onPressDay,
   className,
   style
-}: MonthListProps<T>): import("react").JSX.Element;
+}: MonthListProps<T>): ReactElement;
 //#endregion
 export { Agenda, type AgendaProps, type BusinessHours, Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type DateRange, type DateSelectionConstraints, type DaySelectionState, type DomAgendaEvent, type DomAgendaEventArgs, type DomCalendarTheme, type DomMonthEvent, type DomMonthEventArgs, type DomRenderEvent, type DomRenderEventArgs, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthView, type MonthViewProps, type PositionedEvent, TimeGrid, type TimeGridMode, type TimeGridProps, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, darkDomTheme, daySelectionState, defaultDomTheme, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, mergeDomTheme, nextDateRange, useDateRange, useMonthGrid };

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import { Locale } from "date-fns";
-import { CSSProperties, ComponentType, ReactNode } from "react";
+import { CSSProperties, ComponentType, ReactElement, ReactNode } from "react";
 import { BusinessHours, BusinessHours as BusinessHours$1, CalendarColors, CalendarEvent, CalendarEvent as CalendarEvent$1, CalendarMode, CalendarMode as CalendarMode$1, DateRange, DateRange as DateRange$1, DateSelectionConstraints, DateSelectionConstraints as DateSelectionConstraints$1, DaySelectionState, ICalendarEvent, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, TimeGridMode, TimeGridMode as TimeGridMode$1, UseDateRangeOptions, UseMonthGridOptions, WeekStartsOn, WeekStartsOn as WeekStartsOn$1, buildMonthGrid, daySelectionState, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, nextDateRange, useDateRange, useMonthGrid } from "@super-calendar/core";
 
 //#region src/theme.d.ts
+/**
+ * Theme for the react-dom renderer. Combines the shared color palette from
+ * `@super-calendar/core` with the DOM-specific pixel metrics and font stack.
+ */
 type DomCalendarTheme = CalendarColors & {
   /** Row height of a day cell, in px. */cellHeight: number; /** Diameter of the day badge, in px. */
   dayBadgeSize: number;
@@ -14,7 +18,9 @@ type DomCalendarTheme = CalendarColors & {
   rangeBandHeight: number; /** Font stack for the calendar. */
   fontFamily: string;
 };
+/** The default light theme: the core light palette plus the DOM metrics. */
 declare const defaultDomTheme: DomCalendarTheme;
+/** The dark theme: the core dark palette plus the DOM metrics. */
 declare const darkDomTheme: DomCalendarTheme;
 /** Merge a partial override onto a base theme (defaults to {@link defaultDomTheme}). */
 declare function mergeDomTheme(overrides?: Partial<DomCalendarTheme>, base?: DomCalendarTheme): DomCalendarTheme;
@@ -22,32 +28,42 @@ declare function mergeDomTheme(overrides?: Partial<DomCalendarTheme>, base?: Dom
 //#region src/Agenda.d.ts
 /** Props passed to a custom agenda (schedule) event renderer. */
 interface DomAgendaEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
   /** Always "schedule"; lets a renderer shared with other views branch on it. */
   mode: "schedule";
+  /** Whether the event is all-day. */
   isAllDay: boolean;
   /** Render the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this row. */
   onPress: () => void;
 }
+/** A component that renders a single agenda (schedule) event row. */
 type DomAgendaEvent<T = unknown> = ComponentType<DomAgendaEventArgs<T>>;
+/** Props for {@link Agenda}. */
 interface AgendaProps<T = unknown> {
   /** Events to list. The consumer controls which (and therefore the date range). */
   events: CalendarEvent$1<T>[];
+  /** date-fns locale for the day headers and time labels. */
   locale?: Locale;
   /** Render times in 12-hour AM/PM (default false, 24h). */
   ampm?: boolean;
   /** Highlight this date's header instead of the real "today". */
   activeDate?: Date;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
   /** Replace the built-in event row. */
   renderEvent?: DomAgendaEvent<T>;
+  /** Tap an event row. */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
   /** Tap a day's header. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -55,6 +71,11 @@ interface AgendaProps<T = unknown> {
  * elements. Events are sorted by start and grouped under a date header per day;
  * the consumer controls which events (and therefore which dates) are shown. The
  * react-dom counterpart of the React Native `Agenda`.
+ *
+ * @example
+ * ```tsx
+ * <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
+ * ```
  */
 declare function Agenda<T = unknown>({
   events,
@@ -68,15 +89,19 @@ declare function Agenda<T = unknown>({
   onPressDay,
   className,
   style
-}: AgendaProps<T>): import("react").JSX.Element;
+}: AgendaProps<T>): ReactElement;
 //#endregion
 //#region src/MonthView.d.ts
 /** Props passed to a custom month event chip renderer. */
 interface DomMonthEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
+  /** Call to fire the view's `onPressEvent` for this chip. */
   onPress: () => void;
 }
+/** A component that renders a single month-grid event chip. */
 type DomMonthEvent<T = unknown> = ComponentType<DomMonthEventArgs<T>>;
+/** Props for {@link MonthView}. */
 interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1 {
   /** Any day within the month to render. */
   date: Date;
@@ -126,13 +151,22 @@ interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1 {
    * (rendered without `events`) is always navigable regardless of this flag.
    */
   keyboardDayNavigation?: boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 interface MonthViewInternalProps<T = unknown> extends MonthViewProps<T> {
   eventsByDay?: ReadonlyMap<string, CalendarEvent$1<T>[]>;
 }
-/** A single static month grid, rendered with plain DOM elements. */
+/**
+ * A single static month grid, rendered with plain DOM elements.
+ *
+ * @example
+ * ```tsx
+ * <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
+ * ```
+ */
 declare function MonthView<T = unknown>({
   date,
   weekStartsOn,
@@ -158,28 +192,41 @@ declare function MonthView<T = unknown>({
   keyboardDayNavigation,
   className,
   style
-}: MonthViewInternalProps<T>): import("react").JSX.Element;
+}: MonthViewInternalProps<T>): ReactElement;
 //#endregion
 //#region src/TimeGrid.d.ts
 /** Props passed to a custom time-grid event renderer. */
 interface DomRenderEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent$1<T>;
+  /** The current view mode. */
   mode: CalendarMode$1;
+  /** Whether the event is all-day. */
   isAllDay: boolean;
+  /** Pixel height of the event box (timed events only). */
   boxHeight?: number;
+  /** The event started before the visible day and continues into it. */
   continuesBefore?: boolean;
+  /** The event continues past the visible day. */
   continuesAfter?: boolean;
   /** Show the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this event. */
   onPress: () => void;
 }
+/** A component that renders a single time-grid event box. */
 type DomRenderEvent<T = unknown> = ComponentType<DomRenderEventArgs<T>>;
+/** Props for {@link TimeGrid}. */
 interface TimeGridProps<T = unknown> {
+  /** Anchor date; the visible columns are derived from it and `mode`. */
   date: Date;
+  /** Events to lay out on the grid. */
   events?: CalendarEvent$1<T>[];
   /** "day" (default), "3days", "week", or "custom" (with `numberOfDays`). */
   mode?: TimeGridMode$1;
+  /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn$1;
   /** Initial pixels per hour (default 48). */
   hourHeight?: number;
@@ -187,7 +234,9 @@ interface TimeGridProps<T = unknown> {
   scrollOffsetMinutes?: number;
   /** Pinch / Ctrl-⌘-scroll to zoom the grid (default true). */
   zoomable?: boolean;
+  /** Lower bound for pixels per hour when zooming. */
   minHourHeight?: number;
+  /** Upper bound for pixels per hour when zooming. */
   maxHourHeight?: number;
   /** Snap dragged events to this many minutes (default 15). */
   dragStepMinutes?: number;
@@ -201,13 +250,19 @@ interface TimeGridProps<T = unknown> {
   showNowIndicator?: boolean;
   /** Show the all-day lane above the grid (default true). */
   showAllDayEventCell?: boolean;
+  /** date-fns locale for the column headers and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Custom event renderer; falls back to the built-in event box. */
   renderEvent?: DomRenderEvent<T>;
-  /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
+  /** Replace the hour-axis label. Receives the hour (0-23) and the `ampm` flag. */
   hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /** Tap an event. */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  /** Tap a day's column header. */
   onPressDateHeader?: (day: Date) => void;
   /** Tap empty grid space; called with the date and time at the press. */
   onPressCell?: (date: Date) => void;
@@ -220,7 +275,9 @@ interface TimeGridProps<T = unknown> {
    * Return `false` to reject the drop (the event snaps back).
    */
   onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -228,6 +285,11 @@ interface TimeGridProps<T = unknown> {
  * positioned with the library's pure `layoutDayEvents`, so overlap columns and
  * multi-day clipping match the React Native renderer. Supports Ctrl/⌘-scroll and
  * two-finger pinch to zoom, and pointer drag to move / resize events.
+ *
+ * @example
+ * ```tsx
+ * <TimeGrid mode="week" date={new Date()} events={events} />
+ * ```
  */
 declare function TimeGrid<T = unknown>({
   date,
@@ -259,9 +321,10 @@ declare function TimeGrid<T = unknown>({
   onDragEvent,
   className,
   style
-}: TimeGridProps<T>): import("react").JSX.Element;
+}: TimeGridProps<T>): ReactElement;
 //#endregion
 //#region src/Calendar.d.ts
+/** Props for {@link Calendar}. */
 interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
   /**
    * The view to render (default "week"). `month` renders a month grid, `schedule`
@@ -276,11 +339,15 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
   weekStartsOn?: WeekStartsOn$1;
   /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** date-fns locale for titles, headers, and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
   /** Tap an event (both layouts). */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
@@ -346,6 +413,11 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
  * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
  * an {@link Agenda}; the time-grid modes render a {@link TimeGrid}. For a
  * scrolling month picker, use {@link MonthList} directly.
+ *
+ * @example
+ * ```tsx
+ * <Calendar mode="week" date={new Date()} events={events} />
+ * ```
  */
 declare function Calendar<T = unknown>({
   mode,
@@ -388,9 +460,10 @@ declare function Calendar<T = unknown>({
   onPressMore,
   renderMonthEvent,
   renderScheduleEvent
-}: CalendarProps<T>): import("react").JSX.Element;
+}: CalendarProps<T>): ReactElement;
 //#endregion
 //#region src/MonthList.d.ts
+/** Props for {@link MonthList}. */
 interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   /** Anchor month; the list spans `pastMonths` before to `futureMonths` after. */
   date: Date;
@@ -398,6 +471,7 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   pastMonths?: number;
   /** Months to render after the anchor (default 12). */
   futureMonths?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn$1;
   /** Events to render as chips in each day cell (calendar layout when provided). */
   events?: CalendarEvent$1<T>[];
@@ -411,11 +485,15 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
   /** Tap the "+N more" overflow row. */
   onPressMore?: (events: CalendarEvent$1<T>[], date: Date) => void;
+  /** Selected span; days between the endpoints get the range band. */
   selectedRange?: DateRange$1;
+  /** Discrete selected days (single / multiple). */
   selectedDates?: Date[];
   /** Fill the whole cell on selection instead of the default rounded pill band. */
   fillCellOnSelection?: boolean;
+  /** date-fns locale for the month titles and weekday labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
@@ -425,8 +503,11 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
    * layout (no `events`) is always navigable regardless.
    */
   keyboardDayNavigation?: boolean;
+  /** Fired when a selectable day is clicked. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 /**
@@ -458,6 +539,6 @@ declare function MonthList<T = unknown>({
   onPressDay,
   className,
   style
-}: MonthListProps<T>): import("react").JSX.Element;
+}: MonthListProps<T>): ReactElement;
 //#endregion
 export { Agenda, type AgendaProps, type BusinessHours, Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type DateRange, type DateSelectionConstraints, type DaySelectionState, type DomAgendaEvent, type DomAgendaEventArgs, type DomCalendarTheme, type DomMonthEvent, type DomMonthEventArgs, type DomRenderEvent, type DomRenderEventArgs, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, MonthView, type MonthViewProps, type PositionedEvent, TimeGrid, type TimeGridMode, type TimeGridProps, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, buildMonthGrid, darkDomTheme, daySelectionState, defaultDomTheme, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, mergeDomTheme, nextDateRange, useDateRange, useMonthGrid };

package/dist/index.js

@@ -11,10 +11,12 @@ const METRICS = {
 	rangeBandHeight: 32,
 	fontFamily: "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
 };
+/** The default light theme: the core light palette plus the DOM metrics. */
 const defaultDomTheme = {
 	..._super_calendar_core.lightColors,
 	...METRICS
 };
+/** The dark theme: the core dark palette plus the DOM metrics. */
 const darkDomTheme = {
 	..._super_calendar_core.darkColors,
 	...METRICS
@@ -64,6 +66,11 @@ function DefaultAgendaRow({ event, isAllDay, ampm = false, theme }) {
 * elements. Events are sorted by start and grouped under a date header per day;
 * the consumer controls which events (and therefore which dates) are shown. The
 * react-dom counterpart of the React Native `Agenda`.
+*
+* @example
+* ```tsx
+* <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
+* ```
 */
 function Agenda({ events, locale, ampm = false, activeDate, theme: themeOverrides, height = 480, renderEvent, onPressEvent, onPressDay, className, style }) {
 	const theme = (0, react.useMemo)(() => mergeDomTheme(themeOverrides), [themeOverrides]);
@@ -330,7 +337,14 @@ function moreButtonStyle(theme) {
 		color: theme.textMuted
 	};
 }
-/** A single static month grid, rendered with plain DOM elements. */
+/**
+* A single static month grid, rendered with plain DOM elements.
+*
+* @example
+* ```tsx
+* <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
+* ```
+*/
 function MonthView({ date, weekStartsOn = 0, events, eventsByDay: eventsByDayProp, renderEvent, maxVisibleEventCount = 3, moreLabel = "{moreCount} More", onPressEvent, onPressMore, selectedRange, selectedDates, showAdjacentMonths = true, fillCellOnSelection = false, showTitle = true, showWeekdays = true, locale, theme: themeOverrides, minDate, maxDate, isDateDisabled, onPressDay, keyboardDayNavigation = false, className, style }) {
 	const theme = (0, react.useMemo)(() => mergeDomTheme(themeOverrides), [themeOverrides]);
 	const eventsMode = events !== void 0;
@@ -613,6 +627,11 @@ function DefaultDomEvent({ event, mode, isAllDay, boxHeight, ampm = false, theme
 * positioned with the library's pure `layoutDayEvents`, so overlap columns and
 * multi-day clipping match the React Native renderer. Supports Ctrl/⌘-scroll and
 * two-finger pinch to zoom, and pointer drag to move / resize events.
+*
+* @example
+* ```tsx
+* <TimeGrid mode="week" date={new Date()} events={events} />
+* ```
 */
 function TimeGrid({ date, events = [], mode = "day", numberOfDays = 1, weekStartsOn = 0, hourHeight: initialHourHeight = 48, scrollOffsetMinutes = 480, zoomable = true, minHourHeight = 24, maxHourHeight = 160, dragStepMinutes = 15, ampm = false, timeslots = 1, businessHours, showNowIndicator = true, showAllDayEventCell = true, locale, theme: themeOverrides, height = 600, renderEvent, hourComponent, onPressEvent, onPressDateHeader, onPressCell, onCreateEvent, onDragStart, onDragEvent, className, style }) {
 	const theme = (0, react.useMemo)(() => mergeDomTheme(themeOverrides), [themeOverrides]);
@@ -1148,6 +1167,11 @@ function TimeGrid({ date, events = [], mode = "day", numberOfDays = 1, weekStart
 * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
 * an {@link Agenda}; the time-grid modes render a {@link TimeGrid}. For a
 * scrolling month picker, use {@link MonthList} directly.
+*
+* @example
+* ```tsx
+* <Calendar mode="week" date={new Date()} events={events} />
+* ```
 */
 function Calendar({ mode = "week", date, events, weekStartsOn = 0, numberOfDays, locale, theme, height, className, style, onPressEvent, ampm, hourHeight, scrollOffsetMinutes, timeslots, businessHours, showNowIndicator, showAllDayEventCell, dragStepMinutes, onPressCell, onCreateEvent, onDragStart, onDragEvent, onPressDateHeader, renderTimeEvent, hourComponent, maxVisibleEventCount, moreLabel, showAdjacentMonths, fillCellOnSelection, selectedRange, selectedDates, minDate, maxDate, isDateDisabled, keyboardDayNavigation, onPressDay, onPressMore, renderMonthEvent, renderScheduleEvent }) {
 	if (mode === "schedule") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Agenda, {

package/dist/index.mjs

@@ -10,10 +10,12 @@ const METRICS = {
 	rangeBandHeight: 32,
 	fontFamily: "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"
 };
+/** The default light theme: the core light palette plus the DOM metrics. */
 const defaultDomTheme = {
 	...lightColors,
 	...METRICS
 };
+/** The dark theme: the core dark palette plus the DOM metrics. */
 const darkDomTheme = {
 	...darkColors,
 	...METRICS
@@ -63,6 +65,11 @@ function DefaultAgendaRow({ event, isAllDay, ampm = false, theme }) {
 * elements. Events are sorted by start and grouped under a date header per day;
 * the consumer controls which events (and therefore which dates) are shown. The
 * react-dom counterpart of the React Native `Agenda`.
+*
+* @example
+* ```tsx
+* <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
+* ```
 */
 function Agenda({ events, locale, ampm = false, activeDate, theme: themeOverrides, height = 480, renderEvent, onPressEvent, onPressDay, className, style }) {
 	const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
@@ -329,7 +336,14 @@ function moreButtonStyle(theme) {
 		color: theme.textMuted
 	};
 }
-/** A single static month grid, rendered with plain DOM elements. */
+/**
+* A single static month grid, rendered with plain DOM elements.
+*
+* @example
+* ```tsx
+* <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
+* ```
+*/
 function MonthView({ date, weekStartsOn = 0, events, eventsByDay: eventsByDayProp, renderEvent, maxVisibleEventCount = 3, moreLabel = "{moreCount} More", onPressEvent, onPressMore, selectedRange, selectedDates, showAdjacentMonths = true, fillCellOnSelection = false, showTitle = true, showWeekdays = true, locale, theme: themeOverrides, minDate, maxDate, isDateDisabled, onPressDay, keyboardDayNavigation = false, className, style }) {
 	const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
 	const eventsMode = events !== void 0;
@@ -612,6 +626,11 @@ function DefaultDomEvent({ event, mode, isAllDay, boxHeight, ampm = false, theme
 * positioned with the library's pure `layoutDayEvents`, so overlap columns and
 * multi-day clipping match the React Native renderer. Supports Ctrl/⌘-scroll and
 * two-finger pinch to zoom, and pointer drag to move / resize events.
+*
+* @example
+* ```tsx
+* <TimeGrid mode="week" date={new Date()} events={events} />
+* ```
 */
 function TimeGrid({ date, events = [], mode = "day", numberOfDays = 1, weekStartsOn = 0, hourHeight: initialHourHeight = 48, scrollOffsetMinutes = 480, zoomable = true, minHourHeight = 24, maxHourHeight = 160, dragStepMinutes = 15, ampm = false, timeslots = 1, businessHours, showNowIndicator = true, showAllDayEventCell = true, locale, theme: themeOverrides, height = 600, renderEvent, hourComponent, onPressEvent, onPressDateHeader, onPressCell, onCreateEvent, onDragStart, onDragEvent, className, style }) {
 	const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
@@ -1147,6 +1166,11 @@ function TimeGrid({ date, events = [], mode = "day", numberOfDays = 1, weekStart
 * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
 * an {@link Agenda}; the time-grid modes render a {@link TimeGrid}. For a
 * scrolling month picker, use {@link MonthList} directly.
+*
+* @example
+* ```tsx
+* <Calendar mode="week" date={new Date()} events={events} />
+* ```
 */
 function Calendar({ mode = "week", date, events, weekStartsOn = 0, numberOfDays, locale, theme, height, className, style, onPressEvent, ampm, hourHeight, scrollOffsetMinutes, timeslots, businessHours, showNowIndicator, showAllDayEventCell, dragStepMinutes, onPressCell, onCreateEvent, onDragStart, onDragEvent, onPressDateHeader, renderTimeEvent, hourComponent, maxVisibleEventCount, moreLabel, showAdjacentMonths, fillCellOnSelection, selectedRange, selectedDates, minDate, maxDate, isDateDisabled, keyboardDayNavigation, onPressDay, onPressMore, renderMonthEvent, renderScheduleEvent }) {
 	if (mode === "schedule") return /* @__PURE__ */ jsx(Agenda, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/dom",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "description": "Virtualized month / week / day calendar and date picker for react-dom. No React Native, no react-native-web.",
   "keywords": [
     "calendar",
@@ -11,14 +11,14 @@
     "web",
     "week-view"
   ],
-  "homepage": "https://github.com/afonsojramos/react-native-super-calendar#readme",
+  "homepage": "https://super-calendar.afonsojramos.me",
   "bugs": {
-    "url": "https://github.com/afonsojramos/react-native-super-calendar/issues"
+    "url": "https://github.com/afonsojramos/super-calendar/issues"
   },
   "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/dom"
   },
   "source": "./src/index.ts",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-calendar/core": "2.0.0"
+    "@super-calendar/core": "2.1.2"
   },
   "peerDependencies": {
     "@legendapp/list": ">=3",

package/src/Agenda.tsx

@@ -1,40 +1,50 @@
 import { LegendList } from "@legendapp/list/react";
 import { format, isSameDay, type Locale, startOfDay } from "date-fns";
-import { type ComponentType, type CSSProperties, useMemo } from "react";
+import { type ComponentType, type CSSProperties, type ReactElement, useMemo } from "react";
 import type { CalendarEvent } from "@super-calendar/core";
 import { eventTimeLabel, getIsToday, isAllDayEvent } from "@super-calendar/core";
 import { type DomCalendarTheme, mergeDomTheme } from "./theme";
 
 /** Props passed to a custom agenda (schedule) event renderer. */
 export interface DomAgendaEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent<T>;
   /** Always "schedule"; lets a renderer shared with other views branch on it. */
   mode: "schedule";
+  /** Whether the event is all-day. */
   isAllDay: boolean;
   /** Render the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this row. */
   onPress: () => void;
 }
 
+/** A component that renders a single agenda (schedule) event row. */
 export type DomAgendaEvent<T = unknown> = ComponentType<DomAgendaEventArgs<T>>;
 
+/** Props for {@link Agenda}. */
 export interface AgendaProps<T = unknown> {
   /** Events to list. The consumer controls which (and therefore the date range). */
   events: CalendarEvent<T>[];
+  /** date-fns locale for the day headers and time labels. */
   locale?: Locale;
   /** Render times in 12-hour AM/PM (default false, 24h). */
   ampm?: boolean;
   /** Highlight this date's header instead of the real "today". */
   activeDate?: Date;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
   /** Replace the built-in event row. */
   renderEvent?: DomAgendaEvent<T>;
+  /** Tap an event row. */
   onPressEvent?: (event: CalendarEvent<T>) => void;
   /** Tap a day's header. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 
@@ -79,6 +89,11 @@ function DefaultAgendaRow<T>({
  * elements. Events are sorted by start and grouped under a date header per day;
  * the consumer controls which events (and therefore which dates) are shown. The
  * react-dom counterpart of the React Native `Agenda`.
+ *
+ * @example
+ * ```tsx
+ * <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
+ * ```
  */
 export function Agenda<T = unknown>({
   events,
@@ -92,7 +107,7 @@ export function Agenda<T = unknown>({
   onPressDay,
   className,
   style,
-}: AgendaProps<T>) {
+}: AgendaProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
   const Renderer = renderEvent;
 

package/src/Calendar.tsx

@@ -1,5 +1,5 @@
 import type { Locale } from "date-fns";
-import type { CSSProperties, ReactNode } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
 import type {
   BusinessHours,
   CalendarEvent,
@@ -13,6 +13,7 @@ import { type DomMonthEvent, MonthView } from "./MonthView";
 import { type DomRenderEvent, TimeGrid } from "./TimeGrid";
 import type { DomCalendarTheme } from "./theme";
 
+/** Props for {@link Calendar}. */
 export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
   /**
    * The view to render (default "week"). `month` renders a month grid, `schedule`
@@ -27,11 +28,15 @@ export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
   weekStartsOn?: WeekStartsOn;
   /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** date-fns locale for titles, headers, and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 
   /** Tap an event (both layouts). */
@@ -105,6 +110,11 @@ export interface CalendarProps<T = unknown> extends DateSelectionConstraints {
  * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
  * an {@link Agenda}; the time-grid modes render a {@link TimeGrid}. For a
  * scrolling month picker, use {@link MonthList} directly.
+ *
+ * @example
+ * ```tsx
+ * <Calendar mode="week" date={new Date()} events={events} />
+ * ```
  */
 export function Calendar<T = unknown>({
   mode = "week",
@@ -150,7 +160,7 @@ export function Calendar<T = unknown>({
   renderMonthEvent,
   // schedule
   renderScheduleEvent,
-}: CalendarProps<T>) {
+}: CalendarProps<T>): ReactElement {
   if (mode === "schedule") {
     return (
       <Agenda<T>

package/src/MonthList.tsx

@@ -1,6 +1,6 @@
 import { LegendList } from "@legendapp/list/react";
 import { addMonths, type Locale, startOfMonth } from "date-fns";
-import { type CSSProperties, useMemo } from "react";
+import { type CSSProperties, type ReactElement, useMemo } from "react";
 import {
   buildMonthGrid,
   type CalendarEvent,
@@ -13,6 +13,7 @@ import {
 import { type DomMonthEvent, MonthView } from "./MonthView";
 import { type DomCalendarTheme, mergeDomTheme } from "./theme";
 
+/** Props for {@link MonthList}. */
 export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
   /** Anchor month; the list spans `pastMonths` before to `futureMonths` after. */
   date: Date;
@@ -20,6 +21,7 @@ export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
   pastMonths?: number;
   /** Months to render after the anchor (default 12). */
   futureMonths?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
   /** Events to render as chips in each day cell (calendar layout when provided). */
   events?: CalendarEvent<T>[];
@@ -33,11 +35,15 @@ export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
   onPressEvent?: (event: CalendarEvent<T>) => void;
   /** Tap the "+N more" overflow row. */
   onPressMore?: (events: CalendarEvent<T>[], date: Date) => void;
+  /** Selected span; days between the endpoints get the range band. */
   selectedRange?: DateRange;
+  /** Discrete selected days (single / multiple). */
   selectedDates?: Date[];
   /** Fill the whole cell on selection instead of the default rounded pill band. */
   fillCellOnSelection?: boolean;
+  /** date-fns locale for the month titles and weekday labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px (default 480). */
   height?: number | string;
@@ -47,8 +53,11 @@ export interface MonthListProps<T = unknown> extends DateSelectionConstraints {
    * layout (no `events`) is always navigable regardless.
    */
   keyboardDayNavigation?: boolean;
+  /** Fired when a selectable day is clicked. */
   onPressDay?: (date: Date) => void;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 
@@ -81,7 +90,7 @@ export function MonthList<T = unknown>({
   onPressDay,
   className,
   style,
-}: MonthListProps<T>) {
+}: MonthListProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
 
   const months = useMemo(() => {

package/src/MonthView.tsx

@@ -11,6 +11,7 @@ import {
   type ComponentType,
   type CSSProperties,
   type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
   useEffect,
   useMemo,
   useRef,
@@ -40,12 +41,16 @@ const CELL_PAD = 4;
 
 /** Props passed to a custom month event chip renderer. */
 export interface DomMonthEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent<T>;
+  /** Call to fire the view's `onPressEvent` for this chip. */
   onPress: () => void;
 }
 
+/** A component that renders a single month-grid event chip. */
 export type DomMonthEvent<T = unknown> = ComponentType<DomMonthEventArgs<T>>;
 
+/** Props for {@link MonthView}. */
 export interface MonthViewProps<T = unknown> extends DateSelectionConstraints {
   /** Any day within the month to render. */
   date: Date;
@@ -95,7 +100,9 @@ export interface MonthViewProps<T = unknown> extends DateSelectionConstraints {
    * (rendered without `events`) is always navigable regardless of this flag.
    */
   keyboardDayNavigation?: boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 
@@ -281,7 +288,14 @@ interface MonthViewInternalProps<T = unknown> extends MonthViewProps<T> {
   eventsByDay?: ReadonlyMap<string, CalendarEvent<T>[]>;
 }
 
-/** A single static month grid, rendered with plain DOM elements. */
+/**
+ * A single static month grid, rendered with plain DOM elements.
+ *
+ * @example
+ * ```tsx
+ * <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
+ * ```
+ */
 export function MonthView<T = unknown>({
   date,
   weekStartsOn = 0,
@@ -307,7 +321,7 @@ export function MonthView<T = unknown>({
   keyboardDayNavigation = false,
   className,
   style,
-}: MonthViewInternalProps<T>) {
+}: MonthViewInternalProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
 
   // Calendar layout (date in the corner + event chips) is on whenever `events`

package/src/TimeGrid.tsx

@@ -3,6 +3,7 @@ import {
   type ComponentType,
   type CSSProperties,
   type PointerEvent as ReactPointerEvent,
+  type ReactElement,
   type ReactNode,
   useEffect,
   useMemo,
@@ -36,25 +37,38 @@ const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v
 
 /** Props passed to a custom time-grid event renderer. */
 export interface DomRenderEventArgs<T = unknown> {
+  /** The event to render. */
   event: CalendarEvent<T>;
+  /** The current view mode. */
   mode: CalendarMode;
+  /** Whether the event is all-day. */
   isAllDay: boolean;
+  /** Pixel height of the event box (timed events only). */
   boxHeight?: number;
+  /** The event started before the visible day and continues into it. */
   continuesBefore?: boolean;
+  /** The event continues past the visible day. */
   continuesAfter?: boolean;
   /** Show the time range in 12-hour AM/PM. */
   ampm?: boolean;
+  /** Call to fire the view's `onPressEvent` for this event. */
   onPress: () => void;
 }
 
+/** A component that renders a single time-grid event box. */
 export type DomRenderEvent<T = unknown> = ComponentType<DomRenderEventArgs<T>>;
 
+/** Props for {@link TimeGrid}. */
 export interface TimeGridProps<T = unknown> {
+  /** Anchor date; the visible columns are derived from it and `mode`. */
   date: Date;
+  /** Events to lay out on the grid. */
   events?: CalendarEvent<T>[];
   /** "day" (default), "3days", "week", or "custom" (with `numberOfDays`). */
   mode?: TimeGridMode;
+  /** Column count for `mode="custom"`. */
   numberOfDays?: number;
+  /** First day of the week. Sunday = 0 (default) ... Saturday = 6. */
   weekStartsOn?: WeekStartsOn;
   /** Initial pixels per hour (default 48). */
   hourHeight?: number;
@@ -62,7 +76,9 @@ export interface TimeGridProps<T = unknown> {
   scrollOffsetMinutes?: number;
   /** Pinch / Ctrl-⌘-scroll to zoom the grid (default true). */
   zoomable?: boolean;
+  /** Lower bound for pixels per hour when zooming. */
   minHourHeight?: number;
+  /** Upper bound for pixels per hour when zooming. */
   maxHourHeight?: number;
   /** Snap dragged events to this many minutes (default 15). */
   dragStepMinutes?: number;
@@ -76,13 +92,19 @@ export interface TimeGridProps<T = unknown> {
   showNowIndicator?: boolean;
   /** Show the all-day lane above the grid (default true). */
   showAllDayEventCell?: boolean;
+  /** date-fns locale for the column headers and time labels. */
   locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px. */
   height?: number | string;
+  /** Custom event renderer; falls back to the built-in event box. */
   renderEvent?: DomRenderEvent<T>;
-  /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
+  /** Replace the hour-axis label. Receives the hour (0-23) and the `ampm` flag. */
   hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /** Tap an event. */
   onPressEvent?: (event: CalendarEvent<T>) => void;
+  /** Tap a day's column header. */
   onPressDateHeader?: (day: Date) => void;
   /** Tap empty grid space; called with the date and time at the press. */
   onPressCell?: (date: Date) => void;
@@ -95,7 +117,9 @@ export interface TimeGridProps<T = unknown> {
    * Return `false` to reject the drop (the event snaps back).
    */
   onDragEvent?: (event: CalendarEvent<T>, start: Date, end: Date) => void | boolean;
+  /** Class applied to the root element. */
   className?: string;
+  /** Inline styles applied to the root element. */
   style?: CSSProperties;
 }
 
@@ -190,6 +214,11 @@ function DefaultDomEvent<T>({
  * positioned with the library's pure `layoutDayEvents`, so overlap columns and
  * multi-day clipping match the React Native renderer. Supports Ctrl/⌘-scroll and
  * two-finger pinch to zoom, and pointer drag to move / resize events.
+ *
+ * @example
+ * ```tsx
+ * <TimeGrid mode="week" date={new Date()} events={events} />
+ * ```
  */
 export function TimeGrid<T = unknown>({
   date,
@@ -221,7 +250,7 @@ export function TimeGrid<T = unknown>({
   onDragEvent,
   className,
   style,
-}: TimeGridProps<T>) {
+}: TimeGridProps<T>): ReactElement {
   const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
   const scrollRef = useRef<HTMLDivElement>(null);
   const dfns = locale ? { locale } : undefined;

package/src/index.ts

@@ -1,7 +1,24 @@
-// react-dom entry point: real DOM components (no React Native, no react-native-web).
-// Built on the library's headless core and Legend List's DOM renderer. Pair with
-// the headless hooks (useDateRange, useMonthGrid) re-exported below for selection
-// state and custom layouts.
+/**
+ * The react-dom renderer for super-calendar: real DOM components, no React
+ * Native and no react-native-web.
+ *
+ * Built on the headless core and Legend List's DOM renderer. The headless hooks
+ * (`useDateRange`, `useMonthGrid`) are re-exported below for selection state and
+ * custom layouts.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar } from "@super-calendar/dom";
+ *
+ * export function App() {
+ *   return <Calendar mode="month" />;
+ * }
+ * ```
+ *
+ * @see https://super-calendar.afonsojramos.me
+ *
+ * @module
+ */
 export { Agenda, type AgendaProps, type DomAgendaEvent, type DomAgendaEventArgs } from "./Agenda";
 export { Calendar, type CalendarProps } from "./Calendar";
 export {

package/src/theme.ts

@@ -5,6 +5,10 @@
 // DOM-specific pixel metrics and font stack live here.
 import { type CalendarColors, darkColors, lightColors } from "@super-calendar/core";
 
+/**
+ * Theme for the react-dom renderer. Combines the shared color palette from
+ * `@super-calendar/core` with the DOM-specific pixel metrics and font stack.
+ */
 export type DomCalendarTheme = CalendarColors & {
   /** Row height of a day cell, in px. */
   cellHeight: number;
@@ -25,8 +29,10 @@ const SYSTEM_FONT =
 
 const METRICS = { cellHeight: 48, dayBadgeSize: 34, rangeBandHeight: 32, fontFamily: SYSTEM_FONT };
 
+/** The default light theme: the core light palette plus the DOM metrics. */
 export const defaultDomTheme: DomCalendarTheme = { ...lightColors, ...METRICS };
 
+/** The dark theme: the core dark palette plus the DOM metrics. */
 export const darkDomTheme: DomCalendarTheme = { ...darkColors, ...METRICS };
 
 /** Merge a partial override onto a base theme (defaults to {@link defaultDomTheme}). */