@super-calendar/dom 2.3.2 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/dom",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "description": "Virtualized month / week / day calendar and date picker for react-dom. No React Native, no react-native-web.",
   "keywords": [
     "calendar",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@super-calendar/core": "2.3.2"
+    "@super-calendar/core": "2.5.0"
   },
   "peerDependencies": {
     "@legendapp/list": ">=3",

package/src/Calendar.tsx

@@ -1,14 +1,33 @@
-import type { Locale } from "date-fns";
-import type { CSSProperties, ReactElement, ReactNode } from "react";
-import type {
-  BusinessHours,
-  CalendarEvent,
-  DateRange,
-  DateSelectionConstraints,
-  EventAccessibilityLabeler,
-  TimeGridMode,
-  WeekdayFormat,
-  WeekStartsOn,
+import {
+  addDays,
+  addMonths,
+  endOfDay,
+  endOfMonth,
+  endOfWeek,
+  type Locale,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+} from "date-fns";
+import {
+  type CSSProperties,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+  useMemo,
+} from "react";
+import {
+  type BusinessHours,
+  type CalendarEvent,
+  type DateRange,
+  type DateSelectionConstraints,
+  type EventAccessibilityLabeler,
+  eventsInTimeZone,
+  expandRecurringEvents,
+  getViewDays,
+  type TimeGridMode,
+  type WeekdayFormat,
+  type WeekStartsOn,
 } from "@super-calendar/core";
 import { Agenda, type AgendaSlot, type DomAgendaEvent } from "./Agenda";
 import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
@@ -33,6 +52,13 @@ export interface CalendarProps<T = unknown>
   mode?: "month" | "schedule" | TimeGridMode;
   /** 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<T>[];
   /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
@@ -41,6 +67,12 @@ export interface CalendarProps<T = unknown>
   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. */
@@ -68,6 +100,16 @@ export interface CalendarProps<T = unknown>
   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;
   /** Show the current-time indicator (default true). */
@@ -90,6 +132,11 @@ export interface CalendarProps<T = unknown>
   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;
 
   // --- Month mode ---
   /** Max chips per day before a "+N more" row. */
@@ -124,6 +171,48 @@ export interface CalendarProps<T = unknown>
   renderScheduleEvent?: DomAgendaEvent<T>;
 }
 
+// Stable empty array so a missing `events` prop doesn't churn `displayEvents`
+// identity (and bust child memoization) on every re-render.
+const EMPTY_EVENTS: CalendarEvent<never>[] = [];
+
+// Recurrence is expanded over the range a mode renders: the month grid for
+// `month`, the day columns for the time-grid modes, and a forward window for the
+// `schedule` agenda (which has no bounded viewport of its own).
+function expansionRange(
+  mode: "month" | "schedule" | TimeGridMode,
+  date: Date,
+  weekStartsOn: WeekStartsOn,
+  numberOfDays: number | undefined,
+): [Date, Date] {
+  if (mode === "month") {
+    return [
+      startOfWeek(startOfMonth(date), { weekStartsOn }),
+      endOfWeek(endOfMonth(date), { weekStartsOn }),
+    ];
+  }
+  if (mode === "schedule") {
+    // The agenda lists forward from the anchor date; three months is a sensible
+    // default look-ahead. Pre-expand for a different window.
+    return [startOfDay(date), endOfDay(addMonths(date, 3))];
+  }
+  const days = getViewDays(mode, date, weekStartsOn, numberOfDays ?? 1);
+  return [startOfDay(days[0]), endOfDay(days[days.length - 1])];
+}
+
+// The date one page away in `direction` (+1 next, −1 previous): a month for
+// `month`, a week for `schedule`, else the view's day span.
+function pageStep(
+  mode: "month" | "schedule" | TimeGridMode,
+  date: Date,
+  direction: number,
+  weekStartsOn: WeekStartsOn,
+  numberOfDays: number | undefined,
+): Date {
+  if (mode === "month") return addMonths(date, direction);
+  if (mode === "schedule") return addDays(date, direction * 7);
+  return addDays(date, direction * getViewDays(mode, date, weekStartsOn, numberOfDays ?? 1).length);
+}
+
 /**
  * Batteries-included entry point for the react-dom renderer: it picks the right
  * view for `mode`. `month` renders a single {@link MonthView}; `schedule` renders
@@ -139,9 +228,11 @@ export function Calendar<T = unknown>({
   mode = "week",
   date,
   events,
+  onChangeDate,
   weekStartsOn = 0,
   numberOfDays,
   locale,
+  timeZone,
   theme,
   height,
   className,
@@ -153,6 +244,11 @@ export function Calendar<T = unknown>({
   hourHeight,
   scrollOffsetMinutes,
   timeslots,
+  minHour,
+  maxHour,
+  hideHours,
+  showWeekNumber,
+  weekNumberPrefix,
   businessHours,
   showNowIndicator,
   showAllDayEventCell,
@@ -164,6 +260,7 @@ export function Calendar<T = unknown>({
   onPressDateHeader,
   renderTimeEvent,
   hourComponent,
+  keyboardEventNavigation,
   // month
   maxVisibleEventCount,
   moreLabel,
@@ -185,10 +282,41 @@ export function Calendar<T = unknown>({
   classNames,
   styles,
 }: CalendarProps<T>): ReactElement {
+  // Materialise recurring events over the range this mode renders, then apply the
+  // display zone. Non-recurring and already-expanded events pass through
+  // untouched, so identity is preserved for the common (no-recurrence) case.
+  const displayEvents = useMemo(() => {
+    let out: CalendarEvent<T>[] = events ?? EMPTY_EVENTS;
+    if (out.some((e) => e.recurrence)) {
+      let [start, end] = expansionRange(mode, date, weekStartsOn, numberOfDays);
+      // A display zone shifts each occurrence's wall-clock by up to ~a day, which
+      // can move an edge occurrence into a visible column; widen so it's generated.
+      if (timeZone) {
+        start = addDays(start, -1);
+        end = addDays(end, 1);
+      }
+      out = expandRecurringEvents(out, start, end);
+    }
+    if (timeZone) out = eventsInTimeZone(out, timeZone);
+    return out;
+    // `date.getTime()`: recompute on the instant, not a re-created Date identity.
+  }, [events, mode, date.getTime(), weekStartsOn, numberOfDays, timeZone]);
+
+  // PageDown / PageUp page the calendar when the consumer opts in with
+  // `onChangeDate`; keydowns bubble up from the focused grid to this handler.
+  const handlePageKeys = (e: ReactKeyboardEvent) => {
+    if (!onChangeDate) return;
+    if (e.key === "PageDown") onChangeDate(pageStep(mode, date, 1, weekStartsOn, numberOfDays));
+    else if (e.key === "PageUp") onChangeDate(pageStep(mode, date, -1, weekStartsOn, numberOfDays));
+    else return;
+    e.preventDefault();
+  };
+
+  let view: ReactElement;
   if (mode === "schedule") {
-    return (
+    view = (
       <Agenda<T>
-        events={events ?? []}
+        events={displayEvents}
         locale={locale}
         ampm={ampm}
         theme={theme}
@@ -204,13 +332,11 @@ export function Calendar<T = unknown>({
         onPressDay={onPressDay}
       />
     );
-  }
-
-  if (mode === "month") {
-    return (
+  } else if (mode === "month") {
+    view = (
       <MonthView<T>
         date={date}
-        events={events ?? []}
+        events={displayEvents}
         weekStartsOn={weekStartsOn}
         weekdayFormat={weekdayFormat}
         locale={locale}
@@ -237,40 +363,56 @@ export function Calendar<T = unknown>({
         eventAccessibilityLabel={eventAccessibilityLabel}
       />
     );
+  } else {
+    view = (
+      <TimeGrid<T>
+        date={date}
+        mode={mode}
+        events={displayEvents}
+        weekStartsOn={weekStartsOn}
+        weekdayFormat={weekdayFormat}
+        numberOfDays={numberOfDays}
+        locale={locale}
+        theme={theme}
+        height={height}
+        className={className}
+        style={style}
+        classNames={classNames}
+        styles={styles}
+        ampm={ampm}
+        hourHeight={hourHeight}
+        scrollOffsetMinutes={scrollOffsetMinutes}
+        timeslots={timeslots}
+        minHour={minHour}
+        maxHour={maxHour}
+        hideHours={hideHours}
+        showWeekNumber={showWeekNumber}
+        weekNumberPrefix={weekNumberPrefix}
+        businessHours={businessHours}
+        showNowIndicator={showNowIndicator}
+        showAllDayEventCell={showAllDayEventCell}
+        dragStepMinutes={dragStepMinutes}
+        onPressEvent={onPressEvent}
+        onPressCell={onPressCell}
+        onCreateEvent={onCreateEvent}
+        onDragStart={onDragStart}
+        onDragEvent={onDragEvent}
+        onPressDateHeader={onPressDateHeader}
+        renderEvent={renderTimeEvent}
+        eventAccessibilityLabel={eventAccessibilityLabel}
+        hourComponent={hourComponent}
+        keyboardEventNavigation={keyboardEventNavigation}
+      />
+    );
   }
 
+  // `display: contents` adds no layout box, so the view renders exactly as before
+  // while keydowns from the focused grid still bubble to the paging handler (a
+  // no-op when `onChangeDate` is unset). Rendered unconditionally so toggling the
+  // handler never remounts the view subtree.
   return (
-    <TimeGrid<T>
-      date={date}
-      mode={mode}
-      events={events}
-      weekStartsOn={weekStartsOn}
-      weekdayFormat={weekdayFormat}
-      numberOfDays={numberOfDays}
-      locale={locale}
-      theme={theme}
-      height={height}
-      className={className}
-      style={style}
-      classNames={classNames}
-      styles={styles}
-      ampm={ampm}
-      hourHeight={hourHeight}
-      scrollOffsetMinutes={scrollOffsetMinutes}
-      timeslots={timeslots}
-      businessHours={businessHours}
-      showNowIndicator={showNowIndicator}
-      showAllDayEventCell={showAllDayEventCell}
-      dragStepMinutes={dragStepMinutes}
-      onPressEvent={onPressEvent}
-      onPressCell={onPressCell}
-      onCreateEvent={onCreateEvent}
-      onDragStart={onDragStart}
-      onDragEvent={onDragEvent}
-      onPressDateHeader={onPressDateHeader}
-      renderEvent={renderTimeEvent}
-      eventAccessibilityLabel={eventAccessibilityLabel}
-      hourComponent={hourComponent}
-    />
+    <div style={{ display: "contents" }} onKeyDown={handlePageKeys}>
+      {view}
+    </div>
   );
 }