@super-calendar/dom 2.3.1 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-calendar/dom",
-  "version": "2.3.1",
+  "version": "2.4.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.1"
+    "@super-calendar/core": "2.4.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>
   );
 }

package/src/ResourceTimeline.tsx

@@ -42,16 +42,28 @@ export interface Resource {
 /** Props passed to a custom resource-timeline event renderer. */
 export interface ResourceEventArgs<T = unknown> {
   event: CalendarEvent<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}. */
 export 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<T>[];
@@ -61,11 +73,13 @@ export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<Resou
   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;
@@ -90,6 +104,9 @@ export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<Resou
 
 const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
 
+// Hour-gutter width in the vertical orientation, matching the time grid's axis.
+const GUTTER_WIDTH = 56;
+
 type DragState = {
   key: string;
   kind: "move" | "resize";
@@ -100,9 +117,13 @@ type DragState = {
 
 function DefaultBar<T>({
   event,
+  height,
   boxProps,
   theme,
 }: ResourceEventArgs<T> & { boxProps: ResolvedSlot; theme: DomCalendarTheme }) {
+  // Vertical bars gate the time line on their height (short slots show just the
+  // title); horizontal bars keep it always, as before.
+  const showTime = height != null ? height > 34 : true;
   const time = eventTimeLabel({
     mode: "day",
     isAllDay: false,
@@ -139,7 +160,7 @@ function DefaultBar<T>({
       >
         {event.title}
       </div>
-      {time ? <div style={{ opacity: 0.75, fontSize: 11 }}>{time}</div> : null}
+      {time && showTime ? <div style={{ opacity: 0.75, fontSize: 11 }}>{time}</div> : null}
     </div>
   );
 }
@@ -162,12 +183,14 @@ function DefaultBar<T>({
  */
 export function ResourceTimeline<T = unknown>({
   date,
+  orientation = "horizontal",
   resources,
   events,
   resourceId = (event) => (event as { resourceId?: string }).resourceId,
   startHour = 0,
   endHour = 24,
   hourWidth = 80,
+  hourHeight = 48,
   rowHeight = 56,
   labelWidth = 140,
   ampm = false,
@@ -185,6 +208,9 @@ export function ResourceTimeline<T = unknown>({
   const slot = createSlots<ResourceTimelineSlot>({ classNames, styles });
   const Renderer = renderEvent;
   const snapHours = dragStepMinutes / 60;
+  const vertical = orientation === "vertical";
+  // Pixels per hour along whichever axis carries the time.
+  const hourSize = vertical ? hourHeight : hourWidth;
 
   // `drag` drives the visual; `dragRef` is the source of truth the pointer
   // handlers read so they never see a stale closure between events.
@@ -210,13 +236,13 @@ export function ResourceTimeline<T = unknown>({
     } catch {
       // Pointer capture is best-effort.
     }
-    origin.current = { x: e.clientX, startHours, durationHours };
+    origin.current = { x: vertical ? e.clientY : e.clientX, startHours, durationHours };
     applyDrag({ key, kind, startHours, durationHours, moved: false });
   };
   const moveDrag = (e: ReactPointerEvent) => {
     const d = dragRef.current;
     if (!d || !origin.current) return;
-    const dHours = (e.clientX - origin.current.x) / hourWidth;
+    const dHours = ((vertical ? e.clientY : e.clientX) - origin.current.x) / hourSize;
     const snap = (v: number) => Math.round(v / snapHours) * snapHours;
     if (d.kind === "move") {
       const startHours = clamp(
@@ -275,6 +301,186 @@ export function ResourceTimeline<T = unknown>({
     return map;
   }, [resources, events, resourceId, date]);
 
+  if (vertical) {
+    // Time flows down like the time grid: hour gutter on the left, one flexed
+    // column per resource, so narrow screens share the width instead of
+    // scrolling sideways.
+    const trackHeight = (endHour - startHour) * hourHeight;
+    const vGridLines = `repeating-linear-gradient(to bottom, transparent 0, transparent ${hourHeight - 1}px, ${theme.gridLine} ${hourHeight - 1}px, ${theme.gridLine} ${hourHeight}px)`;
+    return (
+      <div
+        className={className}
+        style={{ fontFamily: theme.fontFamily, color: theme.text, overflowY: "auto", ...style }}
+      >
+        {/* Header: corner above the hour gutter + one label per resource column */}
+        <div
+          {...slot("header", {
+            // Sticky so the resource labels stay visible while the hours scroll
+            // (matching the native renderer's fixed header row).
+            base: { display: "flex", position: "sticky", top: 0, zIndex: 2 },
+            themed: { borderBottom: `1px solid ${theme.gridLine}`, background: theme.surface },
+          })}
+        >
+          <div {...slot("corner", { base: { width: GUTTER_WIDTH, flex: "none" } })} />
+          {resources.map((resource) => (
+            <div
+              key={resource.id}
+              {...slot("resourceLabel", {
+                base: {
+                  flex: 1,
+                  minWidth: 0,
+                  padding: "6px 4px",
+                  textAlign: "center",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  whiteSpace: "nowrap",
+                  boxSizing: "border-box",
+                },
+                themed: {
+                  fontSize: 13,
+                  fontWeight: 600,
+                  borderLeft: `1px solid ${theme.gridLine}`,
+                },
+              })}
+            >
+              {resource.title ?? resource.id}
+            </div>
+          ))}
+        </div>
+        <div style={{ display: "flex" }}>
+          <div
+            {...slot("timeAxis", {
+              base: {
+                position: "relative",
+                width: GUTTER_WIDTH,
+                flex: "none",
+                height: trackHeight,
+              },
+            })}
+          >
+            {hours.map((h) => (
+              <div
+                key={h}
+                {...slot("hourTick", {
+                  base: {
+                    position: "absolute",
+                    top: Math.max(0, (h - startHour) * hourHeight - 6),
+                    right: 6,
+                  },
+                  themed: { fontSize: 10, color: theme.textMuted },
+                })}
+              >
+                {formatHour(h, { ampm })}
+              </div>
+            ))}
+          </div>
+          {resources.map((resource) => {
+            const positioned = byResource.get(resource.id) ?? [];
+            return (
+              <div
+                key={resource.id}
+                {...slot("row", {
+                  base: { flex: 1, minWidth: 0 },
+                  themed: { borderLeft: `1px solid ${theme.gridLine}` },
+                })}
+              >
+                <div {...slot("track", { base: { position: "relative", height: trackHeight } })}>
+                  <div
+                    aria-hidden
+                    {...slot("gridLines", {
+                      base: { position: "absolute", inset: 0, pointerEvents: "none" },
+                      themed: { backgroundImage: vGridLines },
+                    })}
+                  />
+                  {positioned.map((pe, idx) => {
+                    const key = `${resource.id}:${idx}`;
+                    const active = drag?.key === key ? drag : null;
+                    const startH = active ? active.startHours : pe.startHours;
+                    const durH = active ? active.durationHours : pe.durationHours;
+                    const top = clamp(startH - startHour, 0, endHour - startHour) * hourHeight;
+                    const bottom =
+                      clamp(startH + durH - startHour, 0, endHour - startHour) * hourHeight;
+                    const height = Math.max(bottom - top, 2);
+                    // Overlapping events share the column as side-by-side sub-lanes.
+                    const lanePct = 100 / pe.columns;
+                    const onPress = () => onPressEvent?.(pe.event);
+                    const args: ResourceEventArgs<T> = {
+                      event: pe.event,
+                      width: 0,
+                      height,
+                      onPress,
+                    };
+                    const draggable = !!onDragEvent;
+                    return (
+                      <button
+                        key={idx}
+                        type="button"
+                        onClick={draggable ? undefined : onPress}
+                        aria-label={pe.event.title}
+                        {...dataState({ "data-dragging": !!active })}
+                        onPointerDown={
+                          draggable
+                            ? (e) => beginDrag(e, key, "move", pe.startHours, pe.durationHours)
+                            : undefined
+                        }
+                        onPointerMove={draggable ? moveDrag : undefined}
+                        onPointerUp={draggable ? (e) => endDrag(e, pe.event, onPress) : undefined}
+                        onPointerCancel={draggable ? cancelDrag : undefined}
+                        {...slot("event", {
+                          base: {
+                            position: "absolute",
+                            top,
+                            height,
+                            left: `${pe.column * lanePct}%`,
+                            width: `${lanePct}%`,
+                            padding: 1,
+                            border: "none",
+                            background: "transparent",
+                            cursor: draggable ? "grab" : "pointer",
+                            touchAction: draggable ? "none" : "auto",
+                            font: "inherit",
+                            textAlign: "left",
+                            boxSizing: "border-box",
+                            zIndex: active ? 3 : 1,
+                            opacity: active ? 0.85 : 1,
+                          },
+                        })}
+                      >
+                        {Renderer ? (
+                          <Renderer {...args} />
+                        ) : (
+                          <DefaultBar {...args} theme={theme} boxProps={slot("eventBox")} />
+                        )}
+                        {draggable ? (
+                          <span
+                            aria-hidden
+                            onPointerDown={(e) => {
+                              e.stopPropagation();
+                              beginDrag(e, key, "resize", pe.startHours, pe.durationHours);
+                            }}
+                            style={{
+                              position: "absolute",
+                              left: 0,
+                              right: 0,
+                              bottom: 0,
+                              height: 8,
+                              cursor: "ns-resize",
+                              touchAction: "none",
+                            }}
+                          />
+                        ) : null}
+                      </button>
+                    );
+                  })}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    );
+  }
+
   const gridLines = `repeating-linear-gradient(to right, transparent 0, transparent ${hourWidth - 1}px, ${theme.gridLine} ${hourWidth - 1}px, ${theme.gridLine} ${hourWidth}px)`;
 
   return (