@super-calendar/dom 2.15.0 → 2.17.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.15.0",
3
+ "version": "2.17.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.15.0"
51
+ "@super-calendar/core": "2.17.0"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "@legendapp/list": ">=3",
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,
@@ -13,6 +14,7 @@ import {
13
14
  startOfYear,
14
15
  } from "date-fns";
15
16
  import {
17
+ type ComponentType,
16
18
  type CSSProperties,
17
19
  type ForwardedRef,
18
20
  forwardRef,
@@ -29,9 +31,11 @@ import {
29
31
  type BusinessHours,
30
32
  type BusinessHoursBand,
31
33
  type CalendarEvent,
34
+ type CreateGhostArgs,
32
35
  type DateRange,
33
36
  type DateSelectionConstraints,
34
37
  type EventAccessibilityLabeler,
38
+ buildMultiWeekGrid,
35
39
  eventsInTimeZone,
36
40
  expandRecurringEvents,
37
41
  getViewDays,
@@ -42,6 +46,7 @@ import type { CalendarHandle, CalendarLabels } from "@super-calendar/core";
42
46
  import { Agenda, type AgendaSlot, type DomAgendaEvent } from "./Agenda";
43
47
  import { YearView, type YearViewSlot } from "./YearView";
44
48
  import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
49
+ import { MultiWeekView } from "./MultiWeekView";
45
50
  import type { SlotStyleProps } from "./slots";
46
51
  import { type DomRenderEvent, TimeGrid, type TimeGridSlot } from "./TimeGrid";
47
52
  import type { DomCalendarTheme } from "./theme";
@@ -57,8 +62,9 @@ export type CalendarSlot = MonthViewSlot | TimeGridSlot | AgendaSlot | YearViewS
57
62
  export interface CalendarProps<T = unknown>
58
63
  extends DateSelectionConstraints, SlotStyleProps<CalendarSlot> {
59
64
  /**
60
- * The view to render (default "week"). `month` renders a month grid, `schedule`
61
- * a day-grouped agenda list, and the others a time grid.
65
+ * The view to render (default "week"). `month` renders a month grid,
66
+ * `multiweek` stacked week rows, `schedule` a day-grouped agenda list, `year`
67
+ * twelve mini months, and the others a time grid.
62
68
  */
63
69
  mode?: CalendarMode;
64
70
  /**
@@ -71,8 +77,9 @@ export interface CalendarProps<T = unknown>
71
77
  date: Date;
72
78
  /**
73
79
  * Fires with the next/previous period's date when the user pages the focused
74
- * calendar with **PageDown** / **PageUp** (a month in `month`, a week in
75
- * `schedule`, else the view's day span). It's controlled, so update `date` in
80
+ * calendar with **PageDown** / **PageUp** (a month in `month`,
81
+ * `numberOfWeeks` weeks in `multiweek`, a week in `schedule`, else the view's
82
+ * day span). It's controlled, so update `date` in
76
83
  * response. Omit it to leave paging to your own controls.
77
84
  */
78
85
  onChangeDate?: (date: Date) => void;
@@ -90,6 +97,11 @@ export interface CalendarProps<T = unknown>
90
97
  now?: Date;
91
98
  /** Column count for `mode="custom"`. */
92
99
  numberOfDays?: number;
100
+ /**
101
+ * Week rows for `mode="multiweek"`: a positive whole number, default 2. The
102
+ * rows start on the week containing `date`. Other values throw a `RangeError`.
103
+ */
104
+ numberOfWeeks?: number;
93
105
  /** date-fns locale for titles, headers, and time labels. */
94
106
  locale?: Locale;
95
107
  /**
@@ -191,6 +203,11 @@ export interface CalendarProps<T = unknown>
191
203
  * dragged (`start` at midnight of the first, `end` at midnight after the last).
192
204
  */
193
205
  onCreateEvent?: (start: Date, end: Date) => void;
206
+ /**
207
+ * A component that draws content inside the time-grid drag-to-create preview;
208
+ * see `TimeGrid`'s prop of the same name. Applies to the week/day grid only.
209
+ */
210
+ renderCreateGhost?: ComponentType<CreateGhostArgs>;
194
211
  /** Fires when an event drag begins. */
195
212
  onDragStart?: (event: CalendarEvent<T>) => void;
196
213
  /**
@@ -199,6 +216,8 @@ export interface CalendarProps<T = unknown>
199
216
  * days dragged so the time of day and duration are kept.
200
217
  */
201
218
  onDragEvent?: (event: CalendarEvent<T>, start: Date, end: Date) => void | boolean;
219
+ /** Stable, unique event identity for the web editing dialog across data refreshes. */
220
+ getEventId?: (event: CalendarEvent<T>) => string | number;
202
221
  /** Tap a day's column header. */
203
222
  onPressDateHeader?: (day: Date) => void;
204
223
  /** Custom time-grid event renderer. */
@@ -211,7 +230,7 @@ export interface CalendarProps<T = unknown>
211
230
  */
212
231
  keyboardEventNavigation?: boolean;
213
232
 
214
- // --- Month mode ---
233
+ // --- Month and multiweek modes ---
215
234
  /** Max chips per day before a "+N more" row. */
216
235
  maxVisibleEventCount?: number;
217
236
  /** Month chip height in pixels; omit to keep the renderer default. */
@@ -269,14 +288,20 @@ export interface CalendarProps<T = unknown>
269
288
  const EMPTY_EVENTS: CalendarEvent<never>[] = [];
270
289
 
271
290
  // Recurrence is expanded over the range a mode renders: the month grid for
272
- // `month`, the day columns for the time-grid modes, and a forward window for the
273
- // `schedule` agenda (which has no bounded viewport of its own).
291
+ // `month`, the week rows for `multiweek`, the day columns for the time-grid
292
+ // modes, and a forward window for the `schedule` agenda (which has no bounded
293
+ // viewport of its own).
274
294
  function expansionRange(
275
295
  mode: CalendarMode,
276
296
  date: Date,
277
297
  weekStartsOn: WeekStartsOn,
278
298
  numberOfDays: number | undefined,
299
+ numberOfWeeks: number,
279
300
  ): [Date, Date] {
301
+ if (mode === "multiweek") {
302
+ const { period } = buildMultiWeekGrid(date, { weekStartsOn, numberOfWeeks });
303
+ return [period.start, endOfDay(addDays(period.endExclusive, -1))];
304
+ }
280
305
  if (mode === "month") {
281
306
  return [
282
307
  startOfWeek(startOfMonth(date), { weekStartsOn }),
@@ -299,16 +324,19 @@ function expansionRange(
299
324
  }
300
325
 
301
326
  // The date one page away in `direction` (+1 next, −1 previous): a year for
302
- // `year`, a month for `month`, a week for `schedule`, else the view's day span.
327
+ // `year`, a month for `month`, the shown weeks for `multiweek`, a week for
328
+ // `schedule`, else the view's day span.
303
329
  function pageStep(
304
330
  mode: CalendarMode,
305
331
  date: Date,
306
332
  direction: number,
307
333
  weekStartsOn: WeekStartsOn,
308
334
  numberOfDays: number | undefined,
335
+ numberOfWeeks: number,
309
336
  ): Date {
310
337
  if (mode === "year") return addYears(date, direction);
311
338
  if (mode === "month") return addMonths(date, direction);
339
+ if (mode === "multiweek") return addWeeks(date, direction * numberOfWeeks);
312
340
  if (mode === "schedule") return addDays(date, direction * 7);
313
341
  return addDays(date, direction * getViewDays(mode, date, weekStartsOn, numberOfDays ?? 1).length);
314
342
  }
@@ -338,6 +366,7 @@ function CalendarInner<T = unknown>(
338
366
  hiddenDays,
339
367
  now,
340
368
  numberOfDays,
369
+ numberOfWeeks = 2,
341
370
  locale,
342
371
  timeZone,
343
372
  theme,
@@ -373,8 +402,10 @@ function CalendarInner<T = unknown>(
373
402
  touchDragThreshold,
374
403
  onPressCell,
375
404
  onCreateEvent,
405
+ renderCreateGhost,
376
406
  onDragStart,
377
407
  onDragEvent,
408
+ getEventId,
378
409
  onPressDateHeader,
379
410
  renderTimeEvent,
380
411
  hourComponent,
@@ -422,7 +453,7 @@ function CalendarInner<T = unknown>(
422
453
  const displayEvents = useMemo(() => {
423
454
  let out: CalendarEvent<T>[] = events ?? EMPTY_EVENTS;
424
455
  if (out.some((e) => e.recurrence)) {
425
- let [start, end] = expansionRange(mode, date, weekStartsOn, numberOfDays);
456
+ let [start, end] = expansionRange(mode, date, weekStartsOn, numberOfDays, numberOfWeeks);
426
457
  // A display zone shifts each occurrence's wall-clock by up to ~a day, which
427
458
  // can move an edge occurrence into a visible column; widen so it's generated.
428
459
  if (timeZone) {
@@ -434,15 +465,17 @@ function CalendarInner<T = unknown>(
434
465
  if (timeZone) out = eventsInTimeZone(out, timeZone);
435
466
  return out;
436
467
  // `date.getTime()`: recompute on the instant, not a re-created Date identity.
437
- }, [events, mode, date.getTime(), weekStartsOn, numberOfDays, timeZone]);
468
+ }, [events, mode, date.getTime(), weekStartsOn, numberOfDays, numberOfWeeks, timeZone]);
438
469
 
439
470
  // PageDown / PageUp page the calendar when the consumer opts in with
440
471
  // `onChangeDate`; keydowns bubble up from the focused grid to this handler.
441
472
  const handlePageKeys = (e: ReactKeyboardEvent) => {
442
473
  if (!onChangeDate) return;
443
- if (e.key === "PageDown") onChangeDate(pageStep(mode, date, 1, weekStartsOn, numberOfDays));
444
- else if (e.key === "PageUp") onChangeDate(pageStep(mode, date, -1, weekStartsOn, numberOfDays));
445
- else return;
474
+ if (e.key === "PageDown") {
475
+ onChangeDate(pageStep(mode, date, 1, weekStartsOn, numberOfDays, numberOfWeeks));
476
+ } else if (e.key === "PageUp") {
477
+ onChangeDate(pageStep(mode, date, -1, weekStartsOn, numberOfDays, numberOfWeeks));
478
+ } else return;
446
479
  e.preventDefault();
447
480
  };
448
481
 
@@ -534,6 +567,49 @@ function CalendarInner<T = unknown>(
534
567
  eventAccessibilityLabel={eventAccessibilityLabel}
535
568
  />
536
569
  );
570
+ } else if (mode === "multiweek") {
571
+ view = (
572
+ <MultiWeekView<T>
573
+ date={date}
574
+ numberOfWeeks={numberOfWeeks}
575
+ events={displayEvents}
576
+ weekStartsOn={weekStartsOn}
577
+ hiddenDays={hiddenDays}
578
+ weekdayFormat={weekdayFormat}
579
+ highlightWeekends={highlightWeekends}
580
+ locale={locale}
581
+ labels={labels}
582
+ theme={theme}
583
+ className={className}
584
+ style={height != null ? { height, ...style } : style}
585
+ classNames={classNames}
586
+ styles={styles}
587
+ maxVisibleEventCount={maxVisibleEventCount}
588
+ chipHeight={chipHeight}
589
+ chipGap={chipGap}
590
+ moreLabel={moreLabel}
591
+ showTitle={showTitle}
592
+ fillCellOnSelection={fillCellOnSelection}
593
+ selectedRange={selectedRange}
594
+ selectedDates={selectedDates}
595
+ minDate={minDate}
596
+ maxDate={maxDate}
597
+ isDateDisabled={isDateDisabled}
598
+ keyboardDayNavigation={keyboardDayNavigation}
599
+ onPressDay={onPressDay}
600
+ onPressCell={onPressCell}
601
+ onCreateEvent={onCreateEvent}
602
+ onSelectDrag={onSelectDrag}
603
+ onDragEvent={onDragEvent}
604
+ onDragStart={onDragStart}
605
+ eventStartEditable={eventStartEditable}
606
+ eventOverlap={eventOverlap}
607
+ onPressEvent={onPressEvent}
608
+ onPressMore={onPressMore}
609
+ renderEvent={renderMonthEvent}
610
+ eventAccessibilityLabel={eventAccessibilityLabel}
611
+ />
612
+ );
537
613
  } else {
538
614
  view = (
539
615
  <TimeGrid<T>
@@ -582,8 +658,10 @@ function CalendarInner<T = unknown>(
582
658
  onPressEvent={onPressEvent}
583
659
  onPressCell={onPressCell}
584
660
  onCreateEvent={onCreateEvent}
661
+ renderCreateGhost={renderCreateGhost}
585
662
  onDragStart={onDragStart}
586
663
  onDragEvent={onDragEvent}
664
+ getEventId={getEventId}
587
665
  onChangeDate={onChangeDate}
588
666
  onPressDateHeader={onPressDateHeader}
589
667
  renderEvent={renderTimeEvent}
@@ -29,7 +29,7 @@ interface PickerBaseProps
29
29
  height?: number;
30
30
  /** Placeholder shown on the trigger when nothing is selected. */
31
31
  placeholder?: string;
32
- /** Disable the whole field. */
32
+ /** Disable the field and close its popover. Re-enabling leaves the popover closed. */
33
33
  disabled?: boolean;
34
34
  /** Theme overrides for the calendar. */
35
35
  theme?: Partial<DomCalendarTheme>;
@@ -61,18 +61,34 @@ const popoverDefault: CSSProperties = {
61
61
  minWidth: 300,
62
62
  };
63
63
 
64
+ // Where keyboard focus lands when the popover opens: the picked (or today's)
65
+ // day, else that month's roving tab stop, else an enabled day in that month. Unavailable days
66
+ // stay focusable for arrow navigation but are skipped as a starting point.
67
+ function initialPickerFocus(dialog: HTMLElement, day: string): HTMLElement | null {
68
+ const usable = ':not([aria-disabled="true"]):not([data-outside])';
69
+ return (
70
+ dialog.querySelector<HTMLElement>(`[data-day="${day}"]${usable}`) ??
71
+ dialog.querySelector<HTMLElement>(`[data-day^="${day.slice(0, 7)}"][tabindex="0"]${usable}`) ??
72
+ dialog.querySelector<HTMLElement>(`[data-day^="${day.slice(0, 7)}"]${usable}`)
73
+ );
74
+ }
75
+
64
76
  /**
65
77
  * The shared popover shell: a trigger button and a calendar panel that closes on
66
78
  * outside-click and Escape, and returns focus to the trigger. `renderCalendar`
67
79
  * gets a close callback so a single-date pick can dismiss immediately.
68
80
  */
69
- function usePopover() {
81
+ function usePopover(disabled: boolean | undefined) {
70
82
  const [open, setOpen] = useState(false);
71
83
  const rootRef = useRef<HTMLDivElement>(null);
72
84
  const triggerRef = useRef<HTMLButtonElement>(null);
73
85
 
74
86
  useEffect(() => {
75
87
  if (!open) return;
88
+ if (disabled) {
89
+ setOpen(false);
90
+ return;
91
+ }
76
92
  const onDown = (e: MouseEvent) => {
77
93
  if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
78
94
  };
@@ -88,9 +104,9 @@ function usePopover() {
88
104
  document.removeEventListener("mousedown", onDown);
89
105
  document.removeEventListener("keydown", onKey);
90
106
  };
91
- }, [open]);
107
+ }, [open, disabled]);
92
108
 
93
- return { open, setOpen, rootRef, triggerRef };
109
+ return { open: open && !disabled, setOpen, rootRef, triggerRef };
94
110
  }
95
111
 
96
112
  interface ShellProps {
@@ -107,6 +123,8 @@ interface ShellProps {
107
123
  className?: string;
108
124
  style?: CSSProperties;
109
125
  ariaLabel: string;
126
+ /** The day (`yyyy-MM-dd`) to focus when the popover opens. */
127
+ focusDay: string;
110
128
  children: ReactNode;
111
129
  }
112
130
 
@@ -124,9 +142,39 @@ function PickerShell({
124
142
  className,
125
143
  style,
126
144
  ariaLabel,
145
+ focusDay,
127
146
  children,
128
147
  }: ShellProps): ReactElement {
129
148
  const dialogId = useId();
149
+ const dialogRef = useRef<HTMLDivElement>(null);
150
+ const focusDayRef = useRef(focusDay);
151
+ focusDayRef.current = focusDay;
152
+ // Move focus into the popover once per opening (not on every re-render), so
153
+ // keyboard users land on a date. Wait for the intended month to mount instead
154
+ // of focusing a neighbouring virtualized row that happens to render first.
155
+ useEffect(() => {
156
+ if (!open) return;
157
+ const dialog = dialogRef.current;
158
+ if (!dialog) return;
159
+ const place = () => {
160
+ if (dialog.contains(document.activeElement)) {
161
+ observer.disconnect();
162
+ return;
163
+ }
164
+ const target = initialPickerFocus(dialog, focusDayRef.current);
165
+ const monthMounted = dialog.querySelector(
166
+ `[data-day^="${focusDayRef.current.slice(0, 7)}"]:not([data-outside])`,
167
+ );
168
+ if (target || monthMounted) {
169
+ (target ?? dialog).focus();
170
+ observer.disconnect();
171
+ }
172
+ };
173
+ const observer = new MutationObserver(place);
174
+ observer.observe(dialog, { childList: true, subtree: true });
175
+ place();
176
+ return () => observer.disconnect();
177
+ }, [open]);
130
178
  return (
131
179
  <div
132
180
  ref={rootRef}
@@ -161,8 +209,10 @@ function PickerShell({
161
209
  </button>
162
210
  {open ? (
163
211
  <div
212
+ ref={dialogRef}
164
213
  id={dialogId}
165
214
  role="dialog"
215
+ tabIndex={-1}
166
216
  aria-label={ariaLabel}
167
217
  {...slot("popover", {
168
218
  base: popoverDefault,
@@ -216,7 +266,7 @@ export function DatePicker({
216
266
  }: DatePickerProps): ReactElement {
217
267
  const theme = mergeDomTheme(themeOverrides);
218
268
  const slot = createSlots<DatePickerSlot | MonthListSlot>({ classNames, styles });
219
- const { open, setOpen, rootRef, triggerRef } = usePopover();
269
+ const { open, setOpen, rootRef, triggerRef } = usePopover(disabled);
220
270
 
221
271
  return (
222
272
  <PickerShell
@@ -233,8 +283,10 @@ export function DatePicker({
233
283
  className={className}
234
284
  style={style}
235
285
  ariaLabel="Choose a date"
286
+ focusDay={format(value ?? new Date(), "yyyy-MM-dd")}
236
287
  >
237
288
  <MonthList
289
+ theme={themeOverrides}
238
290
  date={value ?? new Date()}
239
291
  weekStartsOn={weekStartsOn}
240
292
  selectedDates={value ? [value] : []}
@@ -299,7 +351,7 @@ export function DateRangePicker({
299
351
  }: DateRangePickerProps): ReactElement {
300
352
  const theme = mergeDomTheme(themeOverrides);
301
353
  const slot = createSlots<DatePickerSlot | MonthListSlot>({ classNames, styles });
302
- const { open, setOpen, rootRef, triggerRef } = usePopover();
354
+ const { open, setOpen, rootRef, triggerRef } = usePopover(disabled);
303
355
  const constraints: DateSelectionConstraints = { minDate, maxDate, isDateDisabled };
304
356
 
305
357
  return (
@@ -317,8 +369,10 @@ export function DateRangePicker({
317
369
  className={className}
318
370
  style={style}
319
371
  ariaLabel="Choose a date range"
372
+ focusDay={format(value?.start ?? new Date(), "yyyy-MM-dd")}
320
373
  >
321
374
  <MonthList
375
+ theme={themeOverrides}
322
376
  date={value?.start ?? new Date()}
323
377
  weekStartsOn={weekStartsOn}
324
378
  selectedRange={value ?? undefined}