@super-calendar/dom 2.16.0 → 2.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@super-calendar/dom",
3
- "version": "2.16.0",
3
+ "version": "2.18.0",
4
4
  "description": "Virtualized month / week / day calendar and date picker for react-dom. No React Native, no react-native-web.",
5
5
  "keywords": [
6
6
  "calendar",
@@ -48,7 +48,7 @@
48
48
  "access": "public"
49
49
  },
50
50
  "dependencies": {
51
- "@super-calendar/core": "2.16.0"
51
+ "@super-calendar/core": "2.18.0"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "@legendapp/list": ">=3",
package/src/Agenda.tsx CHANGED
@@ -2,7 +2,13 @@ import { LegendList } from "@legendapp/list/react";
2
2
  import { format, isSameDay, type Locale, startOfDay } from "date-fns";
3
3
  import { type ComponentType, type CSSProperties, type ReactElement, useMemo } from "react";
4
4
  import type { CalendarEvent, EventAccessibilityLabeler } from "@super-calendar/core";
5
- import { eventTimeLabel, getIsToday, isAllDayEvent, isBackgroundEvent } from "@super-calendar/core";
5
+ import {
6
+ eventTimeLabel,
7
+ getIsToday,
8
+ isAllDayEvent,
9
+ isBackgroundEvent,
10
+ nowInTimeZone,
11
+ } from "@super-calendar/core";
6
12
  import { createSlots, type ResolvedSlot, type SlotStyleProps } from "./slots";
7
13
  import { type DomCalendarTheme, mergeDomTheme } from "./theme";
8
14
 
@@ -35,6 +41,13 @@ export interface AgendaProps<T = unknown> extends SlotStyleProps<AgendaSlot> {
35
41
  events: CalendarEvent<T>[];
36
42
  /** date-fns locale for the day headers and time labels. */
37
43
  locale?: Locale;
44
+ /**
45
+ * The instant whose calendar day is highlighted as today. Defaults to the
46
+ * device clock, and is read in `timeZone` when one is set.
47
+ */
48
+ now?: Date;
49
+ /** Highlight today as it is in this IANA time zone (default: the device's). */
50
+ timeZone?: string;
38
51
  /** Render times in 12-hour AM/PM (default false, 24h). */
39
52
  ampm?: boolean;
40
53
  /** Highlight this date's header instead of the real "today". */
@@ -104,6 +117,8 @@ function DefaultAgendaRow<T>({
104
117
  export function Agenda<T = unknown>({
105
118
  events,
106
119
  locale,
120
+ now,
121
+ timeZone,
107
122
  ampm = false,
108
123
  activeDate,
109
124
  theme: themeOverrides,
@@ -118,6 +133,7 @@ export function Agenda<T = unknown>({
118
133
  styles,
119
134
  }: AgendaProps<T>): ReactElement {
120
135
  const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
136
+ const today = nowInTimeZone(now, timeZone);
121
137
  const slot = createSlots<AgendaSlot>({ classNames, styles });
122
138
  const Renderer = renderEvent;
123
139
 
@@ -153,7 +169,7 @@ export function Agenda<T = unknown>({
153
169
  if (item.kind === "header") {
154
170
  const highlighted = activeDate
155
171
  ? isSameDay(item.date, activeDate)
156
- : getIsToday(item.date);
172
+ : getIsToday(item.date, today);
157
173
  const label = format(item.date, "EEEE, d LLLL", locale ? { locale } : undefined);
158
174
  const color = highlighted ? theme.todayBackground : theme.textMuted;
159
175
  const headerProps = slot("dayHeader", {
package/src/Calendar.tsx CHANGED
@@ -1,6 +1,7 @@
1
1
  import {
2
2
  addDays,
3
3
  addMonths,
4
+ addWeeks,
4
5
  endOfDay,
5
6
  endOfMonth,
6
7
  endOfWeek,
@@ -34,7 +35,12 @@ import {
34
35
  type DateRange,
35
36
  type DateSelectionConstraints,
36
37
  type EventAccessibilityLabeler,
38
+ buildMultiWeekGrid,
37
39
  eventsInTimeZone,
40
+ fromZonedRange,
41
+ fromZonedTime,
42
+ zonedDragBounds,
43
+ zonedEventSource,
38
44
  expandRecurringEvents,
39
45
  getViewDays,
40
46
  type WeekdayFormat,
@@ -44,6 +50,7 @@ import type { CalendarHandle, CalendarLabels } from "@super-calendar/core";
44
50
  import { Agenda, type AgendaSlot, type DomAgendaEvent } from "./Agenda";
45
51
  import { YearView, type YearViewSlot } from "./YearView";
46
52
  import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
53
+ import { MultiWeekView } from "./MultiWeekView";
47
54
  import type { SlotStyleProps } from "./slots";
48
55
  import { type DomRenderEvent, TimeGrid, type TimeGridSlot } from "./TimeGrid";
49
56
  import type { DomCalendarTheme } from "./theme";
@@ -59,8 +66,9 @@ export type CalendarSlot = MonthViewSlot | TimeGridSlot | AgendaSlot | YearViewS
59
66
  export interface CalendarProps<T = unknown>
60
67
  extends DateSelectionConstraints, SlotStyleProps<CalendarSlot> {
61
68
  /**
62
- * The view to render (default "week"). `month` renders a month grid, `schedule`
63
- * a day-grouped agenda list, and the others a time grid.
69
+ * The view to render (default "week"). `month` renders a month grid,
70
+ * `multiweek` stacked week rows, `schedule` a day-grouped agenda list, `year`
71
+ * twelve mini months, and the others a time grid.
64
72
  */
65
73
  mode?: CalendarMode;
66
74
  /**
@@ -73,8 +81,9 @@ export interface CalendarProps<T = unknown>
73
81
  date: Date;
74
82
  /**
75
83
  * Fires with the next/previous period's date when the user pages the focused
76
- * calendar with **PageDown** / **PageUp** (a month in `month`, a week in
77
- * `schedule`, else the view's day span). It's controlled, so update `date` in
84
+ * calendar with **PageDown** / **PageUp** (a month in `month`,
85
+ * `numberOfWeeks` weeks in `multiweek`, a week in `schedule`, else the view's
86
+ * day span). It's controlled, so update `date` in
78
87
  * response. Omit it to leave paging to your own controls.
79
88
  */
80
89
  onChangeDate?: (date: Date) => void;
@@ -85,19 +94,27 @@ export interface CalendarProps<T = unknown>
85
94
  /** Weekdays (0=Sunday…6=Saturday) hidden from the grid, e.g. `[0, 6]` for weekends off. */
86
95
  hiddenDays?: number[];
87
96
  /**
88
- * Fixed "now" instant for the current-time indicator (doesn't tick), e.g. a
89
- * server-synced clock. Defaults to the device clock, shifted into `timeZone`
90
- * when one is set so the line matches the displayed events.
97
+ * Fixed "now" instant for the current-time indicator (doesn't tick) and for
98
+ * the day highlighted as today in every mode, e.g. a server-synced clock.
99
+ * Defaults to the device clock, shifted into `timeZone` when one is set so
100
+ * both match the displayed events.
91
101
  */
92
102
  now?: Date;
93
103
  /** Column count for `mode="custom"`. */
94
104
  numberOfDays?: number;
105
+ /**
106
+ * Week rows for `mode="multiweek"`: a positive whole number, default 2. The
107
+ * rows start on the week containing `date`. Other values throw a `RangeError`.
108
+ */
109
+ numberOfWeeks?: number;
95
110
  /** date-fns locale for titles, headers, and time labels. */
96
111
  locale?: Locale;
97
112
  /**
98
113
  * Display events in this IANA time zone (e.g. `"America/New_York"`), DST-correct
99
114
  * and independent of the device zone. Display-only: it shifts the wall-clock the
100
- * grid lays out from, it doesn't change your `Date`s. Uses `eventsInTimeZone`.
115
+ * grid lays out from, it doesn't change your `Date`s, and callbacks report your
116
+ * own events and real instants. All-day events stay on their days. Uses
117
+ * `eventsInTimeZone`.
101
118
  */
102
119
  timeZone?: string;
103
120
  /** Theme overrides; falls back to the default light theme. */
@@ -194,8 +211,9 @@ export interface CalendarProps<T = unknown>
194
211
  */
195
212
  onCreateEvent?: (start: Date, end: Date) => void;
196
213
  /**
197
- * A component that draws content inside the time-grid drag-to-create preview;
198
- * see `TimeGrid`'s prop of the same name. Applies to the week/day grid only.
214
+ * A component that draws content inside a creation preview in time-grid, month
215
+ * and multi-week modes. Month rows receive the full all-day range with an
216
+ * exclusive end, once per covered row. Requires onCreateEvent.
199
217
  */
200
218
  renderCreateGhost?: ComponentType<CreateGhostArgs>;
201
219
  /** Fires when an event drag begins. */
@@ -206,7 +224,7 @@ export interface CalendarProps<T = unknown>
206
224
  * days dragged so the time of day and duration are kept.
207
225
  */
208
226
  onDragEvent?: (event: CalendarEvent<T>, start: Date, end: Date) => void | boolean;
209
- /** Stable, unique event identity for the web editing dialog across data refreshes. */
227
+ /** Stable, unique identity for the editing dialog and time-grid all-day bars across data refreshes. */
210
228
  getEventId?: (event: CalendarEvent<T>) => string | number;
211
229
  /** Tap a day's column header. */
212
230
  onPressDateHeader?: (day: Date) => void;
@@ -220,7 +238,7 @@ export interface CalendarProps<T = unknown>
220
238
  */
221
239
  keyboardEventNavigation?: boolean;
222
240
 
223
- // --- Month mode ---
241
+ // --- Month and multiweek modes ---
224
242
  /** Max chips per day before a "+N more" row. */
225
243
  maxVisibleEventCount?: number;
226
244
  /** Month chip height in pixels; omit to keep the renderer default. */
@@ -278,14 +296,20 @@ export interface CalendarProps<T = unknown>
278
296
  const EMPTY_EVENTS: CalendarEvent<never>[] = [];
279
297
 
280
298
  // Recurrence is expanded over the range a mode renders: the month grid for
281
- // `month`, the day columns for the time-grid modes, and a forward window for the
282
- // `schedule` agenda (which has no bounded viewport of its own).
299
+ // `month`, the week rows for `multiweek`, the day columns for the time-grid
300
+ // modes, and a forward window for the `schedule` agenda (which has no bounded
301
+ // viewport of its own).
283
302
  function expansionRange(
284
303
  mode: CalendarMode,
285
304
  date: Date,
286
305
  weekStartsOn: WeekStartsOn,
287
306
  numberOfDays: number | undefined,
307
+ numberOfWeeks: number,
288
308
  ): [Date, Date] {
309
+ if (mode === "multiweek") {
310
+ const { period } = buildMultiWeekGrid(date, { weekStartsOn, numberOfWeeks });
311
+ return [period.start, endOfDay(addDays(period.endExclusive, -1))];
312
+ }
289
313
  if (mode === "month") {
290
314
  return [
291
315
  startOfWeek(startOfMonth(date), { weekStartsOn }),
@@ -308,16 +332,19 @@ function expansionRange(
308
332
  }
309
333
 
310
334
  // The date one page away in `direction` (+1 next, −1 previous): a year for
311
- // `year`, a month for `month`, a week for `schedule`, else the view's day span.
335
+ // `year`, a month for `month`, the shown weeks for `multiweek`, a week for
336
+ // `schedule`, else the view's day span.
312
337
  function pageStep(
313
338
  mode: CalendarMode,
314
339
  date: Date,
315
340
  direction: number,
316
341
  weekStartsOn: WeekStartsOn,
317
342
  numberOfDays: number | undefined,
343
+ numberOfWeeks: number,
318
344
  ): Date {
319
345
  if (mode === "year") return addYears(date, direction);
320
346
  if (mode === "month") return addMonths(date, direction);
347
+ if (mode === "multiweek") return addWeeks(date, direction * numberOfWeeks);
321
348
  if (mode === "schedule") return addDays(date, direction * 7);
322
349
  return addDays(date, direction * getViewDays(mode, date, weekStartsOn, numberOfDays ?? 1).length);
323
350
  }
@@ -347,6 +374,7 @@ function CalendarInner<T = unknown>(
347
374
  hiddenDays,
348
375
  now,
349
376
  numberOfDays,
377
+ numberOfWeeks = 2,
350
378
  locale,
351
379
  timeZone,
352
380
  theme,
@@ -433,27 +461,86 @@ function CalendarInner<T = unknown>(
433
461
  const displayEvents = useMemo(() => {
434
462
  let out: CalendarEvent<T>[] = events ?? EMPTY_EVENTS;
435
463
  if (out.some((e) => e.recurrence)) {
436
- let [start, end] = expansionRange(mode, date, weekStartsOn, numberOfDays);
437
- // A display zone shifts each occurrence's wall-clock by up to ~a day, which
438
- // can move an edge occurrence into a visible column; widen so it's generated.
439
- if (timeZone) {
440
- start = addDays(start, -1);
441
- end = addDays(end, 1);
442
- }
443
- out = expandRecurringEvents(out, start, end);
464
+ const [start, end] = expansionRange(mode, date, weekStartsOn, numberOfDays, numberOfWeeks);
465
+ // The range is the days on screen, which under a display zone are that
466
+ // zone's days: expand on its clock, over the instants those days cover.
467
+ out = timeZone
468
+ ? expandRecurringEvents(out, fromZonedTime(start, timeZone), fromZonedTime(end, timeZone), {
469
+ timeZone,
470
+ })
471
+ : expandRecurringEvents(out, start, end);
444
472
  }
445
473
  if (timeZone) out = eventsInTimeZone(out, timeZone);
446
474
  return out;
447
475
  // `date.getTime()`: recompute on the instant, not a re-created Date identity.
448
- }, [events, mode, date.getTime(), weekStartsOn, numberOfDays, timeZone]);
476
+ }, [events, mode, date.getTime(), weekStartsOn, numberOfDays, numberOfWeeks, timeZone]);
477
+
478
+ // With a display zone the views lay out wall-clock copies of the events and
479
+ // report wall-clock dates. Hand back the consumer's own events and real
480
+ // instants. Whole days (`onPressDay`, a month sweep, ...) stay device-local
481
+ // dates, as `date` is, so only the time grid's cell callbacks convert.
482
+ // A time-grid move keeps the event's elapsed duration; a month drop keeps the
483
+ // clock time of both edges.
484
+ const timeGridMode = mode !== "month" && mode !== "multiweek";
485
+ const zoned = useMemo(() => {
486
+ if (!timeZone) {
487
+ return {
488
+ onPressEvent,
489
+ onDragStart,
490
+ onDragEvent,
491
+ onPressMore,
492
+ onPressTime: onPressCell,
493
+ onCreateTimed: onCreateEvent,
494
+ };
495
+ }
496
+ const instant = (wallClock: Date) => fromZonedTime(wallClock, timeZone);
497
+ return {
498
+ onPressEvent:
499
+ onPressEvent && ((event: CalendarEvent<T>) => onPressEvent(zonedEventSource(event))),
500
+ onDragStart:
501
+ onDragStart && ((event: CalendarEvent<T>) => onDragStart(zonedEventSource(event))),
502
+ onDragEvent:
503
+ onDragEvent &&
504
+ ((event: CalendarEvent<T>, start: Date, end: Date) => {
505
+ const bounds = zonedDragBounds(event, start, end, { keepDuration: timeGridMode });
506
+ // An edge dropped into an hour the zone's clock skips can leave no
507
+ // usable span; reject the drop, so the event snaps back.
508
+ if (!bounds) return false;
509
+ return onDragEvent(zonedEventSource(event), bounds.start, bounds.end);
510
+ }),
511
+ onPressMore:
512
+ onPressMore &&
513
+ ((dayEvents: CalendarEvent<T>[], day: Date) =>
514
+ onPressMore(dayEvents.map(zonedEventSource), day)),
515
+ onPressTime: onPressCell && ((time: Date) => onPressCell(instant(time))),
516
+ onCreateTimed:
517
+ onCreateEvent &&
518
+ ((start: Date, end: Date) => {
519
+ // A sweep that collapses inside a skipped hour creates nothing.
520
+ const range = fromZonedRange(start, end, timeZone);
521
+ if (range) onCreateEvent(range.start, range.end);
522
+ }),
523
+ };
524
+ }, [
525
+ timeZone,
526
+ timeGridMode,
527
+ onPressEvent,
528
+ onDragStart,
529
+ onDragEvent,
530
+ onPressMore,
531
+ onPressCell,
532
+ onCreateEvent,
533
+ ]);
449
534
 
450
535
  // PageDown / PageUp page the calendar when the consumer opts in with
451
536
  // `onChangeDate`; keydowns bubble up from the focused grid to this handler.
452
537
  const handlePageKeys = (e: ReactKeyboardEvent) => {
453
538
  if (!onChangeDate) return;
454
- if (e.key === "PageDown") onChangeDate(pageStep(mode, date, 1, weekStartsOn, numberOfDays));
455
- else if (e.key === "PageUp") onChangeDate(pageStep(mode, date, -1, weekStartsOn, numberOfDays));
456
- else return;
539
+ if (e.key === "PageDown") {
540
+ onChangeDate(pageStep(mode, date, 1, weekStartsOn, numberOfDays, numberOfWeeks));
541
+ } else if (e.key === "PageUp") {
542
+ onChangeDate(pageStep(mode, date, -1, weekStartsOn, numberOfDays, numberOfWeeks));
543
+ } else return;
457
544
  e.preventDefault();
458
545
  };
459
546
 
@@ -466,6 +553,8 @@ function CalendarInner<T = unknown>(
466
553
  weekStartsOn={weekStartsOn}
467
554
  hiddenDays={hiddenDays}
468
555
  locale={locale}
556
+ now={now}
557
+ timeZone={timeZone}
469
558
  labels={labels}
470
559
  theme={theme}
471
560
  className={className}
@@ -488,6 +577,8 @@ function CalendarInner<T = unknown>(
488
577
  <Agenda<T>
489
578
  events={displayEvents}
490
579
  locale={locale}
580
+ now={now}
581
+ timeZone={timeZone}
491
582
  ampm={ampm}
492
583
  theme={theme}
493
584
  height={height}
@@ -498,7 +589,7 @@ function CalendarInner<T = unknown>(
498
589
  styles={styles}
499
590
  renderEvent={renderScheduleEvent}
500
591
  eventAccessibilityLabel={eventAccessibilityLabel}
501
- onPressEvent={onPressEvent}
592
+ onPressEvent={zoned.onPressEvent}
502
593
  onPressDay={onPressDay}
503
594
  />
504
595
  );
@@ -512,6 +603,8 @@ function CalendarInner<T = unknown>(
512
603
  weekdayFormat={weekdayFormat}
513
604
  highlightWeekends={highlightWeekends}
514
605
  locale={locale}
606
+ now={now}
607
+ timeZone={timeZone}
515
608
  labels={labels}
516
609
  theme={theme}
517
610
  className={className}
@@ -534,13 +627,60 @@ function CalendarInner<T = unknown>(
534
627
  onPressDay={onPressDay}
535
628
  onPressCell={onPressCell}
536
629
  onCreateEvent={onCreateEvent}
630
+ renderCreateGhost={renderCreateGhost}
631
+ onSelectDrag={onSelectDrag}
632
+ onDragEvent={zoned.onDragEvent}
633
+ onDragStart={zoned.onDragStart}
634
+ eventStartEditable={eventStartEditable}
635
+ eventOverlap={eventOverlap}
636
+ onPressEvent={zoned.onPressEvent}
637
+ onPressMore={zoned.onPressMore}
638
+ renderEvent={renderMonthEvent}
639
+ eventAccessibilityLabel={eventAccessibilityLabel}
640
+ />
641
+ );
642
+ } else if (mode === "multiweek") {
643
+ view = (
644
+ <MultiWeekView<T>
645
+ date={date}
646
+ numberOfWeeks={numberOfWeeks}
647
+ events={displayEvents}
648
+ weekStartsOn={weekStartsOn}
649
+ hiddenDays={hiddenDays}
650
+ weekdayFormat={weekdayFormat}
651
+ highlightWeekends={highlightWeekends}
652
+ locale={locale}
653
+ now={now}
654
+ timeZone={timeZone}
655
+ labels={labels}
656
+ theme={theme}
657
+ className={className}
658
+ style={height != null ? { height, ...style } : style}
659
+ classNames={classNames}
660
+ styles={styles}
661
+ maxVisibleEventCount={maxVisibleEventCount}
662
+ chipHeight={chipHeight}
663
+ chipGap={chipGap}
664
+ moreLabel={moreLabel}
665
+ showTitle={showTitle}
666
+ fillCellOnSelection={fillCellOnSelection}
667
+ selectedRange={selectedRange}
668
+ selectedDates={selectedDates}
669
+ minDate={minDate}
670
+ maxDate={maxDate}
671
+ isDateDisabled={isDateDisabled}
672
+ keyboardDayNavigation={keyboardDayNavigation}
673
+ onPressDay={onPressDay}
674
+ onPressCell={onPressCell}
675
+ onCreateEvent={onCreateEvent}
676
+ renderCreateGhost={renderCreateGhost}
537
677
  onSelectDrag={onSelectDrag}
538
- onDragEvent={onDragEvent}
539
- onDragStart={onDragStart}
678
+ onDragEvent={zoned.onDragEvent}
679
+ onDragStart={zoned.onDragStart}
540
680
  eventStartEditable={eventStartEditable}
541
681
  eventOverlap={eventOverlap}
542
- onPressEvent={onPressEvent}
543
- onPressMore={onPressMore}
682
+ onPressEvent={zoned.onPressEvent}
683
+ onPressMore={zoned.onPressMore}
544
684
  renderEvent={renderMonthEvent}
545
685
  eventAccessibilityLabel={eventAccessibilityLabel}
546
686
  />
@@ -590,12 +730,12 @@ function CalendarInner<T = unknown>(
590
730
  dragStepMinutes={dragStepMinutes}
591
731
  touchDragDelay={touchDragDelay}
592
732
  touchDragThreshold={touchDragThreshold}
593
- onPressEvent={onPressEvent}
594
- onPressCell={onPressCell}
595
- onCreateEvent={onCreateEvent}
733
+ onPressEvent={zoned.onPressEvent}
734
+ onPressCell={zoned.onPressTime}
735
+ onCreateEvent={zoned.onCreateTimed}
596
736
  renderCreateGhost={renderCreateGhost}
597
- onDragStart={onDragStart}
598
- onDragEvent={onDragEvent}
737
+ onDragStart={zoned.onDragStart}
738
+ onDragEvent={zoned.onDragEvent}
599
739
  getEventId={getEventId}
600
740
  onChangeDate={onChangeDate}
601
741
  onPressDateHeader={onPressDateHeader}