@super-calendar/dom 2.3.1 → 2.4.0

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 import { Locale } from "date-fns";
 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, EventAccessibilityLabelContext, EventAccessibilityLabeler, EventAccessibilityLabeler as EventAccessibilityLabeler$1, ICalEvent, ICalendarEvent, MonthGrid, MonthGridDay, MonthGridWeek, MonthGridWeekday, PositionedEvent, RecurrenceFrequency, RecurrenceRule, TimeGridMode, TimeGridMode as TimeGridMode$1, ToICalendarOptions, UseDateRangeOptions, UseMonthGridOptions, WeekStartsOn, WeekStartsOn as WeekStartsOn$1, WeekdayFormat, WeekdayFormat as WeekdayFormat$1, buildMonthGrid, daySelectionState, expandRecurringEvents, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, nextDateRange, parseICalendar, toICalendar, useDateRange, useMonthGrid, weekdayFormatToken } from "@super-calendar/core";
-
 //#region src/slots.d.ts
 /**
  * Per-slot styling overrides. Give a slot a Tailwind/CSS class and/or an inline
@@ -37,14 +36,17 @@ interface ResolvedSlot {
  * `@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. */
+  /** 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. */
+  rangeBandHeight: number;
+  /** Font stack for the calendar. */
   fontFamily: string;
 };
 /** The default light theme: the core light palette plus the DOM metrics. */
@@ -117,22 +119,7 @@ interface AgendaProps<T = unknown> extends SlotStyleProps<AgendaSlot> {
  * <Agenda events={events} onPressEvent={(e) => console.log(e.title)} />
  * ```
  */
-declare function Agenda<T = unknown>({
-  events,
-  locale,
-  ampm,
-  activeDate,
-  theme: themeOverrides,
-  height,
-  renderEvent,
-  eventAccessibilityLabel,
-  onPressEvent,
-  onPressDay,
-  className,
-  style,
-  classNames,
-  styles
-}: AgendaProps<T>): ReactElement;
+declare function Agenda<T = unknown>({ events, locale, ampm, activeDate, theme: themeOverrides, height, renderEvent, eventAccessibilityLabel, onPressEvent, onPressDay, className, style, classNames, styles }: AgendaProps<T>): ReactElement;
 //#endregion
 //#region src/MonthView.d.ts
 /**
@@ -231,44 +218,14 @@ interface MonthViewInternalProps<T = unknown> extends MonthViewProps<T> {
  * <MonthView date={new Date()} events={events} onPressDay={(d) => setDate(d)} />
  * ```
  */
-declare function MonthView<T = unknown>({
-  date,
-  weekStartsOn,
-  weekdayFormat,
-  events,
-  eventsByDay: eventsByDayProp,
-  renderEvent,
-  eventAccessibilityLabel,
-  maxVisibleEventCount,
-  moreLabel,
-  onPressEvent,
-  onPressMore,
-  selectedRange,
-  selectedDates,
-  showAdjacentMonths,
-  fillCellOnSelection,
-  showTitle,
-  showWeekdays,
-  locale,
-  theme: themeOverrides,
-  minDate,
-  maxDate,
-  isDateDisabled,
-  onPressDay,
-  onCreateEvent,
-  keyboardDayNavigation,
-  className,
-  style,
-  classNames,
-  styles
-}: MonthViewInternalProps<T>): ReactElement;
+declare function MonthView<T = unknown>({ date, weekStartsOn, weekdayFormat, events, eventsByDay: eventsByDayProp, renderEvent, eventAccessibilityLabel, maxVisibleEventCount, moreLabel, onPressEvent, onPressMore, selectedRange, selectedDates, showAdjacentMonths, fillCellOnSelection, showTitle, showWeekdays, locale, theme: themeOverrides, minDate, maxDate, isDateDisabled, onPressDay, onCreateEvent, keyboardDayNavigation, className, style, classNames, styles }: MonthViewInternalProps<T>): ReactElement;
 //#endregion
 //#region src/TimeGrid.d.ts
 /**
  * Styleable parts of {@link TimeGrid}. Pass a class or inline style per slot via
  * the `classNames` / `styles` props.
  */
-type TimeGridSlot = "header" | "columnHeader" | "columnHeaderWeekday" | "columnHeaderDate" | "allDayLane" | "allDayLabel" | "allDayColumn" | "allDayEvent" | "hourGutter" | "hourLabel" | "dayColumn" | "gridLines" | "businessHours" | "event" | "eventBox" | "nowIndicator" | "createGhost";
+type TimeGridSlot = "header" | "weekNumber" | "columnHeader" | "columnHeaderWeekday" | "columnHeaderDate" | "allDayLane" | "allDayLabel" | "allDayColumn" | "allDayEvent" | "hourGutter" | "hourLabel" | "dayColumn" | "gridLines" | "businessHours" | "event" | "eventBox" | "nowIndicator" | "createGhost";
 /** Props passed to a custom time-grid event renderer. */
 interface DomRenderEventArgs<T = unknown> {
   /** The event to render. */
@@ -320,6 +277,16 @@ interface TimeGridProps<T = unknown> extends SlotStyleProps<TimeGridSlot> {
   ampm?: boolean;
   /** Sub-divisions per hour for the grid lines, e.g. 2 for half-hour (default 1). */
   timeslots?: number;
+  /** First hour shown (0–23). Default 0. */
+  minHour?: number;
+  /** Last hour shown, exclusive (1–24). Default 24. */
+  maxHour?: number;
+  /** Hide the left hour-axis column (lines stay, labels/gutter go). Default false. */
+  hideHours?: boolean;
+  /** Show the ISO week number in the header gutter. Default false. */
+  showWeekNumber?: boolean;
+  /** Prefix for the week number, e.g. "W" → "W28". Default "W". */
+  weekNumberPrefix?: string;
   /** 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). */
@@ -343,6 +310,14 @@ interface TimeGridProps<T = unknown> extends SlotStyleProps<TimeGridSlot> {
   eventAccessibilityLabel?: EventAccessibilityLabeler$1<T>;
   /** Replace the hour-axis label. Receives the hour (0-23) and the `ampm` flag. */
   hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /**
+   * Add arrow-key navigation between events. Up/Down move between a day's events by
+   * time, Left/Right jump to the nearest event in the adjacent day, Home/End go to
+   * the day's first/last event; Enter/Space activate. Additive: every event stays
+   * individually tabbable (so screen-reader users keep full access), so this is a
+   * convenience for sighted keyboard users. Default false.
+   */
+  keyboardEventNavigation?: boolean;
   /** Tap an event. */
   onPressEvent?: (event: CalendarEvent$1<T>) => void;
   /** Tap a day's column header. */
@@ -374,41 +349,7 @@ interface TimeGridProps<T = unknown> extends SlotStyleProps<TimeGridSlot> {
  * <TimeGrid mode="week" date={new Date()} events={events} />
  * ```
  */
-declare function TimeGrid<T = unknown>({
-  date,
-  events,
-  mode,
-  numberOfDays,
-  weekStartsOn,
-  weekdayFormat,
-  hourHeight: initialHourHeight,
-  scrollOffsetMinutes,
-  zoomable,
-  minHourHeight,
-  maxHourHeight,
-  dragStepMinutes,
-  ampm,
-  timeslots,
-  businessHours,
-  showNowIndicator,
-  showAllDayEventCell,
-  locale,
-  theme: themeOverrides,
-  height,
-  renderEvent,
-  eventAccessibilityLabel,
-  hourComponent,
-  onPressEvent,
-  onPressDateHeader,
-  onPressCell,
-  onCreateEvent,
-  onDragStart,
-  onDragEvent,
-  className,
-  style,
-  classNames,
-  styles
-}: TimeGridProps<T>): ReactElement;
+declare function TimeGrid<T = unknown>({ date, events, mode, numberOfDays, weekStartsOn, weekdayFormat, hourHeight: initialHourHeight, scrollOffsetMinutes, zoomable, minHourHeight, maxHourHeight, dragStepMinutes, ampm, timeslots, minHour, maxHour, hideHours, showWeekNumber, weekNumberPrefix, keyboardEventNavigation, businessHours, showNowIndicator, showAllDayEventCell, locale, theme: themeOverrides, height, renderEvent, eventAccessibilityLabel, hourComponent, onPressEvent, onPressDateHeader, onPressCell, onCreateEvent, onDragStart, onDragEvent, className, style, classNames, styles }: TimeGridProps<T>): ReactElement;
 //#endregion
 //#region src/Calendar.d.ts
 /**
@@ -426,6 +367,13 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
   mode?: "month" | "schedule" | TimeGridMode$1;
   /** Controlled anchor date. Change it (e.g. from your own header) to navigate. */
   date: Date;
+  /**
+   * Fires with the next/previous period's date when the user pages the focused
+   * calendar with **PageDown** / **PageUp** (a month in `month`, a week in
+   * `schedule`, else the view's day span). It's controlled, so update `date` in
+   * response. Omit it to leave paging to your own controls.
+   */
+  onChangeDate?: (date: Date) => void;
   /** Your events. */
   events?: CalendarEvent$1<T>[];
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
@@ -434,6 +382,12 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
   numberOfDays?: number;
   /** date-fns locale for titles, headers, and time labels. */
   locale?: Locale;
+  /**
+   * Display events in this IANA time zone (e.g. `"America/New_York"`), DST-correct
+   * and independent of the device zone. Display-only: it shifts the wall-clock the
+   * grid lays out from, it doesn't change your `Date`s. Uses `eventsInTimeZone`.
+   */
+  timeZone?: string;
   /** Theme overrides; falls back to the default light theme. */
   theme?: Partial<DomCalendarTheme>;
   /** Height of the scroll viewport, in px. */
@@ -458,6 +412,16 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
   scrollOffsetMinutes?: number;
   /** Sub-divisions per hour for the grid lines. */
   timeslots?: number;
+  /** First hour shown (0–23). Default 0. */
+  minHour?: number;
+  /** Last hour shown, exclusive (1–24). Default 24. */
+  maxHour?: number;
+  /** Hide the left hour-axis column (lines stay, labels/gutter go). Default false. */
+  hideHours?: boolean;
+  /** Show the ISO week number in the header gutter. Default false. */
+  showWeekNumber?: boolean;
+  /** Prefix for the week number, e.g. "W" → "W28". Default "W". */
+  weekNumberPrefix?: string;
   /** Shade the hours outside business hours. */
   businessHours?: BusinessHours$1;
   /** Show the current-time indicator (default true). */
@@ -480,6 +444,11 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
   renderTimeEvent?: DomRenderEvent<T>;
   /** Replace the hour-axis label. Receives the hour (0–23) and the `ampm` flag. */
   hourComponent?: (hour: number, ampm: boolean) => ReactNode;
+  /**
+   * Add arrow-key navigation between time-grid events (a convenience for sighted
+   * keyboard users; every event stays individually tabbable). Time-grid modes only.
+   */
+  keyboardEventNavigation?: boolean;
   /** Max chips per day before a "+N more" row. */
   maxVisibleEventCount?: number;
   /** Overflow row template; `{moreCount}` is replaced. */
@@ -520,52 +489,7 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
  * <Calendar mode="week" date={new Date()} events={events} />
  * ```
  */
-declare function Calendar<T = unknown>({
-  mode,
-  date,
-  events,
-  weekStartsOn,
-  numberOfDays,
-  locale,
-  theme,
-  height,
-  className,
-  style,
-  onPressEvent,
-  eventAccessibilityLabel,
-  ampm,
-  hourHeight,
-  scrollOffsetMinutes,
-  timeslots,
-  businessHours,
-  showNowIndicator,
-  showAllDayEventCell,
-  dragStepMinutes,
-  onPressCell,
-  onCreateEvent,
-  onDragStart,
-  onDragEvent,
-  onPressDateHeader,
-  renderTimeEvent,
-  hourComponent,
-  maxVisibleEventCount,
-  moreLabel,
-  showAdjacentMonths,
-  weekdayFormat,
-  fillCellOnSelection,
-  selectedRange,
-  selectedDates,
-  minDate,
-  maxDate,
-  isDateDisabled,
-  keyboardDayNavigation,
-  onPressDay,
-  onPressMore,
-  renderMonthEvent,
-  renderScheduleEvent,
-  classNames,
-  styles
-}: CalendarProps<T>): ReactElement;
+declare function Calendar<T = unknown>({ mode, date, events, onChangeDate, weekStartsOn, numberOfDays, locale, timeZone, theme, height, className, style, onPressEvent, eventAccessibilityLabel, ampm, hourHeight, scrollOffsetMinutes, timeslots, minHour, maxHour, hideHours, showWeekNumber, weekNumberPrefix, businessHours, showNowIndicator, showAllDayEventCell, dragStepMinutes, onPressCell, onCreateEvent, onDragStart, onDragEvent, onPressDateHeader, renderTimeEvent, hourComponent, keyboardEventNavigation, maxVisibleEventCount, moreLabel, showAdjacentMonths, weekdayFormat, fillCellOnSelection, selectedRange, selectedDates, minDate, maxDate, isDateDisabled, keyboardDayNavigation, onPressDay, onPressMore, renderMonthEvent, renderScheduleEvent, classNames, styles }: CalendarProps<T>): ReactElement;
 //#endregion
 //#region src/MonthList.d.ts
 /**
@@ -634,35 +558,7 @@ interface MonthListProps<T = unknown> extends DateSelectionConstraints$1, SlotSt
  * 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,
-  weekdayFormat,
-  weekStartsOn,
-  events,
-  renderEvent,
-  eventAccessibilityLabel,
-  maxVisibleEventCount,
-  moreLabel,
-  onPressEvent,
-  onPressMore,
-  selectedRange,
-  selectedDates,
-  fillCellOnSelection,
-  locale,
-  theme: themeOverrides,
-  height,
-  minDate,
-  maxDate,
-  isDateDisabled,
-  keyboardDayNavigation,
-  onPressDay,
-  className,
-  style,
-  classNames,
-  styles
-}: MonthListProps<T>): ReactElement;
+declare function MonthList<T = unknown>({ date, pastMonths, futureMonths, weekdayFormat, weekStartsOn, events, renderEvent, eventAccessibilityLabel, maxVisibleEventCount, moreLabel, onPressEvent, onPressMore, selectedRange, selectedDates, fillCellOnSelection, locale, theme: themeOverrides, height, minDate, maxDate, isDateDisabled, keyboardDayNavigation, onPressDay, className, style, classNames, styles }: MonthListProps<T>): ReactElement;
 //#endregion
 //#region src/DateRangePicker.d.ts
 /** Styleable chrome of the pickers (the calendar's own slots forward through too). */
@@ -703,23 +599,7 @@ interface DatePickerProps extends PickerBaseProps {
  * <DatePicker value={value} onChange={setValue} />
  * ```
  */
-declare function DatePicker({
-  value,
-  onChange,
-  formatLabel,
-  weekStartsOn,
-  height,
-  placeholder,
-  disabled,
-  theme: themeOverrides,
-  className,
-  style,
-  classNames,
-  styles,
-  minDate,
-  maxDate,
-  isDateDisabled
-}: DatePickerProps): ReactElement;
+declare function DatePicker({ value, onChange, formatLabel, weekStartsOn, height, placeholder, disabled, theme: themeOverrides, className, style, classNames, styles, minDate, maxDate, isDateDisabled }: DatePickerProps): ReactElement;
 /** Props for {@link DateRangePicker}. */
 interface DateRangePickerProps extends PickerBaseProps {
   /** The selected range, or `null`. `end` is `null` while only the start is picked. */
@@ -740,23 +620,7 @@ interface DateRangePickerProps extends PickerBaseProps {
  * <DateRangePicker value={range} onChange={setRange} />
  * ```
  */
-declare function DateRangePicker({
-  value,
-  onChange,
-  formatLabel,
-  weekStartsOn,
-  height,
-  placeholder,
-  disabled,
-  theme: themeOverrides,
-  className,
-  style,
-  classNames,
-  styles,
-  minDate,
-  maxDate,
-  isDateDisabled
-}: DateRangePickerProps): ReactElement;
+declare function DateRangePicker({ value, onChange, formatLabel, weekStartsOn, height, placeholder, disabled, theme: themeOverrides, className, style, classNames, styles, minDate, maxDate, isDateDisabled }: DateRangePickerProps): ReactElement;
 //#endregion
 //#region src/ResourceTimeline.d.ts
 /**
@@ -774,15 +638,27 @@ interface Resource {
 /** Props passed to a custom resource-timeline event renderer. */
 interface ResourceEventArgs<T = unknown> {
   event: CalendarEvent$1<T>;
-  /** Pixel width of the event bar. */
+  /**
+   * Pixel width of the event bar. In the vertical orientation the columns flex
+   * to the container, so this is 0 there; size against `height` instead.
+   */
   width: number;
+  /** Pixel height of the event bar; set in the vertical orientation. */
+  height?: number;
   onPress: () => void;
 }
 /** Props for {@link ResourceTimeline}. */
 interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<ResourceTimelineSlot> {
-  /** The day to lay out along the horizontal axis. */
+  /** The day to lay out along the time axis. */
   date: Date;
-  /** The rows, top to bottom. */
+  /**
+   * Lay the day out along the horizontal axis with resources as rows (the
+   * default), or down the vertical axis with resources as columns, like the
+   * time grid. Vertical reads better on narrow screens: the columns share the
+   * width instead of the axis scrolling sideways.
+   */
+  orientation?: "horizontal" | "vertical";
+  /** The resource lanes: rows when horizontal, columns when vertical. */
   resources: Resource[];
   /** Events; each is placed in the row named by `resourceId(event)`. */
   events: CalendarEvent$1<T>[];
@@ -792,11 +668,13 @@ interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<ResourceTime
   startHour?: number;
   /** Last hour shown, exclusive (default 24). */
   endHour?: number;
-  /** Pixels per hour along the axis (default 80). */
+  /** Pixels per hour along the horizontal axis (default 80). Horizontal only. */
   hourWidth?: number;
-  /** Height of each resource row in px (default 56). */
+  /** Pixels per hour down the vertical axis (default 48). Vertical only. */
+  hourHeight?: number;
+  /** Height of each resource row in px (default 56). Horizontal only. */
   rowHeight?: number;
-  /** Width of the left resource-label column in px (default 140). */
+  /** Width of the left resource-label column in px (default 140). Horizontal only. */
   labelWidth?: number;
   /** 12-hour AM/PM axis labels (default false). */
   ampm?: boolean;
@@ -834,26 +712,6 @@ interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<ResourceTime
  * />
  * ```
  */
-declare function ResourceTimeline<T = unknown>({
-  date,
-  resources,
-  events,
-  resourceId,
-  startHour,
-  endHour,
-  hourWidth,
-  rowHeight,
-  labelWidth,
-  ampm,
-  theme: themeOverrides,
-  renderEvent,
-  onPressEvent,
-  onDragEvent,
-  dragStepMinutes,
-  className,
-  style,
-  classNames,
-  styles
-}: ResourceTimelineProps<T>): ReactElement;
+declare function ResourceTimeline<T = unknown>({ date, orientation, resources, events, resourceId, startHour, endHour, hourWidth, hourHeight, rowHeight, labelWidth, ampm, theme: themeOverrides, renderEvent, onPressEvent, onDragEvent, dragStepMinutes, className, style, classNames, styles }: ResourceTimelineProps<T>): ReactElement;
 //#endregion
 export { Agenda, type AgendaProps, type AgendaSlot, type BusinessHours, Calendar, type CalendarEvent, type CalendarMode, type CalendarProps, type CalendarSlot, DatePicker, type DatePickerProps, type DatePickerSlot, type DateRange, DateRangePicker, type DateRangePickerProps, type DateSelectionConstraints, type DaySelectionState, type DomAgendaEvent, type DomAgendaEventArgs, type DomCalendarTheme, type DomMonthEvent, type DomMonthEventArgs, type DomRenderEvent, type DomRenderEventArgs, type EventAccessibilityLabelContext, type EventAccessibilityLabeler, type ICalEvent, type ICalendarEvent, type MonthGrid, type MonthGridDay, type MonthGridWeek, type MonthGridWeekday, MonthList, type MonthListProps, type MonthListSlot, MonthView, type MonthViewProps, type MonthViewSlot, type PositionedEvent, type RecurrenceFrequency, type RecurrenceRule, type ResolvedSlot, type Resource, type ResourceEventArgs, ResourceTimeline, type ResourceTimelineProps, type ResourceTimelineSlot, type SlotDefault, type SlotStyleProps, TimeGrid, type TimeGridMode, type TimeGridProps, type TimeGridSlot, type ToICalendarOptions, type UseDateRangeOptions, type UseMonthGridOptions, type WeekStartsOn, type WeekdayFormat, buildMonthGrid, darkDomTheme, daySelectionState, defaultDomTheme, expandRecurringEvents, getViewDays, isAllDayEvent, isDateSelectable, isRangeEndpoint, isWithinDateRange, layoutDayEvents, mergeDomTheme, nextDateRange, parseICalendar, toICalendar, useDateRange, useMonthGrid, weekdayFormatToken };