@super-calendar/dom 2.0.0

package/LICENSE

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

package/dist/index.d.mts

@@ -0,0 +1,463 @@
+import { Locale } from "date-fns";
+import { CSSProperties, ComponentType, 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
+type DomCalendarTheme = CalendarColors & {
+  /** Row height of a day cell, in px. */cellHeight: number; /** Diameter of the day badge, in px. */
+  dayBadgeSize: number;
+  /**
+   * Height of the selection band strip, in px (the default pill look). The pill's
+   * corner radius is half this. Ignored when `fillCellOnSelection` is set, where
+   * the band fills the whole cell instead.
+   */
+  rangeBandHeight: number; /** Font stack for the calendar. */
+  fontFamily: string;
+};
+declare const defaultDomTheme: DomCalendarTheme;
+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;
+//#endregion
+//#region src/Agenda.d.ts
+/** Props passed to a custom agenda (schedule) event renderer. */
+interface DomAgendaEventArgs<T = unknown> {
+  event: CalendarEvent$1<T>;
+  /** Always "schedule"; lets a renderer shared with other views branch on it. */
+  mode: "schedule";
+  isAllDay: boolean;
+  /** Render the time range in 12-hour AM/PM. */
+  ampm?: boolean;
+  onPress: () => void;
+}
+type DomAgendaEvent<T = unknown> = ComponentType<DomAgendaEventArgs<T>>;
+interface AgendaProps<T = unknown> {
+  /** Events to list. The consumer controls which (and therefore the date range). */
+  events: CalendarEvent$1<T>[];
+  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?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px (default 480). */
+  height?: number | string;
+  /** Replace the built-in event row. */
+  renderEvent?: DomAgendaEvent<T>;
+  onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  /** Tap a day's header. */
+  onPressDay?: (date: Date) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+/**
+ * A vertical, day-grouped list of events: the schedule view, with plain DOM
+ * 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`.
+ */
+declare function Agenda<T = unknown>({
+  events,
+  locale,
+  ampm,
+  activeDate,
+  theme: themeOverrides,
+  height,
+  renderEvent,
+  onPressEvent,
+  onPressDay,
+  className,
+  style
+}: AgendaProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/MonthView.d.ts
+/** Props passed to a custom month event chip renderer. */
+interface DomMonthEventArgs<T = unknown> {
+  event: CalendarEvent$1<T>;
+  onPress: () => void;
+}
+type DomMonthEvent<T = unknown> = ComponentType<DomMonthEventArgs<T>>;
+interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1 {
+  /** Any day within the month to render. */
+  date: Date;
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn$1;
+  /**
+   * Events to render as chips in each day cell. Passing this (even `[]`) switches
+   * the grid to the calendar layout (date in the corner, chips below); omit it for
+   * the compact date-picker look.
+   */
+  events?: CalendarEvent$1<T>[];
+  /** Custom chip renderer; falls back to the built-in titled chip. */
+  renderEvent?: DomMonthEvent<T>;
+  /** Max chips shown per day before a "+N more" row (default 3). */
+  maxVisibleEventCount?: number;
+  /** Template for the overflow row; `{moreCount}` is replaced (default "{moreCount} More"). */
+  moreLabel?: string;
+  /** Tap an event chip. */
+  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[];
+  /** Render days from the neighbouring months in the leading/trailing cells (default true). */
+  showAdjacentMonths?: boolean;
+  /**
+   * Fill the whole cell with the range background instead of the default
+   * centered rounded "pill" strip. Default false.
+   */
+  fillCellOnSelection?: boolean;
+  /** Render the "Month yyyy" title above the grid (default true). */
+  showTitle?: boolean;
+  /** Render the weekday header row (default true). */
+  showWeekdays?: boolean;
+  /** date-fns locale for the title and weekday labels. */
+  locale?: Locale;
+  /** Theme overrides; falls back to the default light theme. */
+  theme?: Partial<DomCalendarTheme>;
+  /** Fired when a selectable day is clicked. */
+  onPressDay?: (date: Date) => void;
+  /**
+   * When events are shown, also make the day cells keyboard-navigable: a single
+   * roving tab stop, arrow keys move the focus, Enter opens the day (`onPressDay`).
+   * Default false, so keyboard focus moves through events only. The date picker
+   * (rendered without `events`) is always navigable regardless of this flag.
+   */
+  keyboardDayNavigation?: boolean;
+  className?: string;
+  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. */
+declare function MonthView<T = unknown>({
+  date,
+  weekStartsOn,
+  events,
+  eventsByDay: eventsByDayProp,
+  renderEvent,
+  maxVisibleEventCount,
+  moreLabel,
+  onPressEvent,
+  onPressMore,
+  selectedRange,
+  selectedDates,
+  showAdjacentMonths,
+  fillCellOnSelection,
+  showTitle,
+  showWeekdays,
+  locale,
+  theme: themeOverrides,
+  minDate,
+  maxDate,
+  isDateDisabled,
+  onPressDay,
+  keyboardDayNavigation,
+  className,
+  style
+}: MonthViewInternalProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/TimeGrid.d.ts
+/** Props passed to a custom time-grid event renderer. */
+interface DomRenderEventArgs<T = unknown> {
+  event: CalendarEvent$1<T>;
+  mode: CalendarMode$1;
+  isAllDay: boolean;
+  boxHeight?: number;
+  continuesBefore?: boolean;
+  continuesAfter?: boolean;
+  /** Show the time range in 12-hour AM/PM. */
+  ampm?: boolean;
+  onPress: () => void;
+}
+type DomRenderEvent<T = unknown> = ComponentType<DomRenderEventArgs<T>>;
+interface TimeGridProps<T = unknown> {
+  date: Date;
+  events?: CalendarEvent$1<T>[];
+  /** "day" (default), "3days", "week", or "custom" (with `numberOfDays`). */
+  mode?: TimeGridMode$1;
+  numberOfDays?: number;
+  weekStartsOn?: WeekStartsOn$1;
+  /** Initial pixels per hour (default 48). */
+  hourHeight?: number;
+  /** Initial scroll position, in minutes from midnight (default 8:00). */
+  scrollOffsetMinutes?: number;
+  /** Pinch / Ctrl-⌘-scroll to zoom the grid (default true). */
+  zoomable?: boolean;
+  minHourHeight?: number;
+  maxHourHeight?: number;
+  /** Snap dragged events to this many minutes (default 15). */
+  dragStepMinutes?: number;
+  /** Render event time ranges in 12-hour AM/PM (default false, 24h). */
+  ampm?: boolean;
+  /** Sub-divisions per hour for the grid lines, e.g. 2 for half-hour (default 1). */
+  timeslots?: number;
+  /** Shade the hours outside business hours; `null` shades the whole day. */
+  businessHours?: BusinessHours$1;
+  /** Show the current-time indicator on today's column (default true). */
+  showNowIndicator?: boolean;
+  /** Show the all-day lane above the grid (default true). */
+  showAllDayEventCell?: boolean;
+  locale?: Locale;
+  theme?: Partial<DomCalendarTheme>;
+  height?: number | string;
+  renderEvent?: DomRenderEvent<T>;
+  /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
+  hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  onPressDateHeader?: (day: Date) => void;
+  /** Tap empty grid space; called with the date and time at the press. */
+  onPressCell?: (date: Date) => void;
+  /** Drag empty grid space to create; called with the swept start/end. */
+  onCreateEvent?: (start: Date, end: Date) => void;
+  /** Fires when an event drag begins (e.g. to trigger haptics). */
+  onDragStart?: (event: CalendarEvent$1<T>) => void;
+  /**
+   * Enables drag-to-move and resize; called with the proposed new start/end.
+   * Return `false` to reject the drop (the event snaps back).
+   */
+  onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+/**
+ * A day / week / N-day time grid rendered with plain DOM elements. Events are
+ * 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.
+ */
+declare function TimeGrid<T = unknown>({
+  date,
+  events,
+  mode,
+  numberOfDays,
+  weekStartsOn,
+  hourHeight: initialHourHeight,
+  scrollOffsetMinutes,
+  zoomable,
+  minHourHeight,
+  maxHourHeight,
+  dragStepMinutes,
+  ampm,
+  timeslots,
+  businessHours,
+  showNowIndicator,
+  showAllDayEventCell,
+  locale,
+  theme: themeOverrides,
+  height,
+  renderEvent,
+  hourComponent,
+  onPressEvent,
+  onPressDateHeader,
+  onPressCell,
+  onCreateEvent,
+  onDragStart,
+  onDragEvent,
+  className,
+  style
+}: TimeGridProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/Calendar.d.ts
+interface CalendarProps<T = unknown> extends DateSelectionConstraints$1 {
+  /**
+   * The view to render (default "week"). `month` renders a month grid, `schedule`
+   * a day-grouped agenda list, and the others a time grid.
+   */
+  mode?: "month" | "schedule" | TimeGridMode$1;
+  /** Controlled anchor date. Change it (e.g. from your own header) to navigate. */
+  date: Date;
+  /** Your events. */
+  events?: CalendarEvent$1<T>[];
+  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
+  weekStartsOn?: WeekStartsOn$1;
+  /** Column count for `mode="custom"`. */
+  numberOfDays?: number;
+  locale?: Locale;
+  theme?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px. */
+  height?: number | string;
+  className?: string;
+  style?: CSSProperties;
+  /** Tap an event (both layouts). */
+  onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  /** 12-hour AM/PM time labels (default false). */
+  ampm?: boolean;
+  /** Initial pixels per hour. */
+  hourHeight?: number;
+  /** Initial scroll position, in minutes from midnight. */
+  scrollOffsetMinutes?: number;
+  /** Sub-divisions per hour for the grid lines. */
+  timeslots?: number;
+  /** Shade the hours outside business hours. */
+  businessHours?: BusinessHours$1;
+  /** Show the current-time indicator (default true). */
+  showNowIndicator?: boolean;
+  /** Show the all-day lane (default true). */
+  showAllDayEventCell?: boolean;
+  /** Snap dragged/created events to this many minutes. */
+  dragStepMinutes?: number;
+  /** Tap empty grid space. */
+  onPressCell?: (date: Date) => void;
+  /** Drag empty grid space to create. */
+  onCreateEvent?: (start: Date, end: Date) => void;
+  /** Fires when an event drag begins. */
+  onDragStart?: (event: CalendarEvent$1<T>) => void;
+  /** Enables drag-to-move/resize; return `false` to reject the drop. */
+  onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
+  /** Tap a day's column header. */
+  onPressDateHeader?: (day: Date) => void;
+  /** Custom time-grid event renderer. */
+  renderTimeEvent?: DomRenderEvent<T>;
+  /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
+  hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /** Max chips per day before a "+N more" row. */
+  maxVisibleEventCount?: number;
+  /** Overflow row template; `{moreCount}` is replaced. */
+  moreLabel?: string;
+  /** Render neighbouring months' days in the leading/trailing cells (default true). */
+  showAdjacentMonths?: boolean;
+  /** Fill the cell with the range background instead of the pill band. */
+  fillCellOnSelection?: boolean;
+  /** Selected span. */
+  selectedRange?: DateRange$1;
+  /** Discrete selected days. */
+  selectedDates?: Date[];
+  /**
+   * In month mode, make day cells keyboard-navigable (one roving tab stop, arrow
+   * keys, Enter to open the day). Default false: keyboard focus moves through
+   * events only. Has no effect on the time-grid modes.
+   */
+  keyboardDayNavigation?: boolean;
+  /** Tap a day cell. */
+  onPressDay?: (date: Date) => void;
+  /** Tap the "+N more" overflow row. */
+  onPressMore?: (events: CalendarEvent$1<T>[], date: Date) => void;
+  /** Custom month chip renderer. */
+  renderMonthEvent?: DomMonthEvent<T>;
+  /** Custom agenda row renderer (`mode="schedule"`). */
+  renderScheduleEvent?: DomAgendaEvent<T>;
+}
+/**
+ * Batteries-included entry point for the react-dom renderer: it picks the right
+ * 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.
+ */
+declare function Calendar<T = unknown>({
+  mode,
+  date,
+  events,
+  weekStartsOn,
+  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
+}: CalendarProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/MonthList.d.ts
+interface MonthListProps<T = unknown> extends DateSelectionConstraints$1 {
+  /** Anchor month; the list spans `pastMonths` before to `futureMonths` after. */
+  date: Date;
+  /** Months to render before the anchor (default 1). */
+  pastMonths?: number;
+  /** Months to render after the anchor (default 12). */
+  futureMonths?: number;
+  weekStartsOn?: WeekStartsOn$1;
+  /** Events to render as chips in each day cell (calendar layout when provided). */
+  events?: CalendarEvent$1<T>[];
+  /** Custom chip renderer; falls back to the built-in titled chip. */
+  renderEvent?: DomMonthEvent<T>;
+  /** Max chips shown per day before a "+N more" row (default 3). */
+  maxVisibleEventCount?: number;
+  /** Template for the overflow row; `{moreCount}` is replaced. */
+  moreLabel?: string;
+  /** Tap an event chip. */
+  onPressEvent?: (event: CalendarEvent$1<T>) => void;
+  /** Tap the "+N more" overflow row. */
+  onPressMore?: (events: CalendarEvent$1<T>[], date: Date) => void;
+  selectedRange?: DateRange$1;
+  selectedDates?: Date[];
+  /** Fill the whole cell on selection instead of the default rounded pill band. */
+  fillCellOnSelection?: boolean;
+  locale?: Locale;
+  theme?: Partial<DomCalendarTheme>;
+  /** Height of the scroll viewport, in px (default 480). */
+  height?: number | string;
+  /**
+   * When events are shown, make each month's day cells keyboard-navigable (roving
+   * tab stop, arrow keys, Enter to open the day). Default false. The picker
+   * layout (no `events`) is always navigable regardless.
+   */
+  keyboardDayNavigation?: boolean;
+  onPressDay?: (date: Date) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+/**
+ * A vertically scrolling, virtualized list of months: the date picker. Built on
+ * Legend List's DOM renderer and the library's headless grid logic. Selection is
+ * controlled, pass `selectedRange` (or `selectedDates`) and handle `onPressDay`.
+ */
+declare function MonthList<T = unknown>({
+  date,
+  pastMonths,
+  futureMonths,
+  weekStartsOn,
+  events,
+  renderEvent,
+  maxVisibleEventCount,
+  moreLabel,
+  onPressEvent,
+  onPressMore,
+  selectedRange,
+  selectedDates,
+  fillCellOnSelection,
+  locale,
+  theme: themeOverrides,
+  height,
+  minDate,
+  maxDate,
+  isDateDisabled,
+  keyboardDayNavigation,
+  onPressDay,
+  className,
+  style
+}: MonthListProps<T>): import("react").JSX.Element;
+//#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 };