@super-calendar/dom 2.5.0 → 2.7.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.5.0",
3
+ "version": "2.7.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.5.0"
51
+ "@super-calendar/core": "2.7.0"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "@legendapp/list": ">=3",
package/src/Agenda.tsx CHANGED
@@ -2,7 +2,7 @@ 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 } from "@super-calendar/core";
5
+ import { eventTimeLabel, getIsToday, isAllDayEvent, isBackgroundEvent } from "@super-calendar/core";
6
6
  import { createSlots, type ResolvedSlot, type SlotStyleProps } from "./slots";
7
7
  import { type DomCalendarTheme, mergeDomTheme } from "./theme";
8
8
 
@@ -122,7 +122,10 @@ export function Agenda<T = unknown>({
122
122
  const Renderer = renderEvent;
123
123
 
124
124
  const rows = useMemo<Row<T>[]>(() => {
125
- const sorted = [...events].sort((a, b) => a.start.getTime() - b.start.getTime());
125
+ const sorted = events
126
+ // Background events shade the grids; they have no agenda row.
127
+ .filter((event) => !isBackgroundEvent(event))
128
+ .sort((a, b) => a.start.getTime() - b.start.getTime());
126
129
  const out: Row<T>[] = [];
127
130
  let currentDay: Date | null = null;
128
131
  sorted.forEach((event, index) => {
package/src/Calendar.tsx CHANGED
@@ -8,6 +8,9 @@ import {
8
8
  startOfDay,
9
9
  startOfMonth,
10
10
  startOfWeek,
11
+ addYears,
12
+ endOfYear,
13
+ startOfYear,
11
14
  } from "date-fns";
12
15
  import {
13
16
  type CSSProperties,
@@ -17,7 +20,9 @@ import {
17
20
  useMemo,
18
21
  } from "react";
19
22
  import {
23
+ type CalendarMode,
20
24
  type BusinessHours,
25
+ type BusinessHoursBand,
21
26
  type CalendarEvent,
22
27
  type DateRange,
23
28
  type DateSelectionConstraints,
@@ -25,11 +30,11 @@ import {
25
30
  eventsInTimeZone,
26
31
  expandRecurringEvents,
27
32
  getViewDays,
28
- type TimeGridMode,
29
33
  type WeekdayFormat,
30
34
  type WeekStartsOn,
31
35
  } from "@super-calendar/core";
32
36
  import { Agenda, type AgendaSlot, type DomAgendaEvent } from "./Agenda";
37
+ import { YearView, type YearViewSlot } from "./YearView";
33
38
  import { type DomMonthEvent, MonthView, type MonthViewSlot } from "./MonthView";
34
39
  import type { SlotStyleProps } from "./slots";
35
40
  import { type DomRenderEvent, TimeGrid, type TimeGridSlot } from "./TimeGrid";
@@ -40,7 +45,7 @@ import type { DomCalendarTheme } from "./theme";
40
45
  * for the active `mode` apply; the rest are ignored. See {@link MonthViewSlot},
41
46
  * {@link TimeGridSlot}, and {@link AgendaSlot}.
42
47
  */
43
- export type CalendarSlot = MonthViewSlot | TimeGridSlot | AgendaSlot;
48
+ export type CalendarSlot = MonthViewSlot | TimeGridSlot | AgendaSlot | YearViewSlot;
44
49
 
45
50
  /** Props for {@link Calendar}. */
46
51
  export interface CalendarProps<T = unknown>
@@ -49,7 +54,7 @@ export interface CalendarProps<T = unknown>
49
54
  * The view to render (default "week"). `month` renders a month grid, `schedule`
50
55
  * a day-grouped agenda list, and the others a time grid.
51
56
  */
52
- mode?: "month" | "schedule" | TimeGridMode;
57
+ mode?: CalendarMode;
53
58
  /** Controlled anchor date. Change it (e.g. from your own header) to navigate. */
54
59
  date: Date;
55
60
  /**
@@ -63,6 +68,14 @@ export interface CalendarProps<T = unknown>
63
68
  events?: CalendarEvent<T>[];
64
69
  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
65
70
  weekStartsOn?: WeekStartsOn;
71
+ /** Weekdays (0=Sunday…6=Saturday) hidden from the grid, e.g. `[0, 6]` for weekends off. */
72
+ hiddenDays?: number[];
73
+ /**
74
+ * Fixed "now" instant for the current-time indicator (doesn't tick), e.g. a
75
+ * server-synced clock. Defaults to the device clock, shifted into `timeZone`
76
+ * when one is set so the line matches the displayed events.
77
+ */
78
+ now?: Date;
66
79
  /** Column count for `mode="custom"`. */
67
80
  numberOfDays?: number;
68
81
  /** date-fns locale for titles, headers, and time labels. */
@@ -112,10 +125,19 @@ export interface CalendarProps<T = unknown>
112
125
  weekNumberPrefix?: string;
113
126
  /** Shade the hours outside business hours. */
114
127
  businessHours?: BusinessHours;
128
+ /**
129
+ * Render a closed-hours band's content yourself (a label, icon, pattern).
130
+ * The grid keeps positioning the band; when set, the themed tint is dropped
131
+ * and your output fills the band instead. Decorative only: the
132
+ * band stays non-interactive and hidden from assistive tech.
133
+ */
134
+ renderBusinessHours?: (band: BusinessHoursBand) => ReactNode;
115
135
  /** Show the current-time indicator (default true). */
116
136
  showNowIndicator?: boolean;
117
137
  /** Show the all-day lane (default true). */
118
138
  showAllDayEventCell?: boolean;
139
+ /** Tint weekend columns (default true). Set false to treat weekends normally. */
140
+ highlightWeekends?: boolean;
119
141
  /** Snap dragged/created events to this many minutes. */
120
142
  dragStepMinutes?: number;
121
143
  /** Tap empty grid space. */
@@ -161,6 +183,8 @@ export interface CalendarProps<T = unknown>
161
183
  keyboardDayNavigation?: boolean;
162
184
  /** Tap a day cell. */
163
185
  onPressDay?: (date: Date) => void;
186
+ /** Tap a month's title in the year view — e.g. jump to that month. */
187
+ onPressMonth?: (month: Date) => void;
164
188
  /** Tap the "+N more" overflow row. */
165
189
  onPressMore?: (events: CalendarEvent<T>[], date: Date) => void;
166
190
  /** Custom month chip renderer. */
@@ -179,7 +203,7 @@ const EMPTY_EVENTS: CalendarEvent<never>[] = [];
179
203
  // `month`, the day columns for the time-grid modes, and a forward window for the
180
204
  // `schedule` agenda (which has no bounded viewport of its own).
181
205
  function expansionRange(
182
- mode: "month" | "schedule" | TimeGridMode,
206
+ mode: CalendarMode,
183
207
  date: Date,
184
208
  weekStartsOn: WeekStartsOn,
185
209
  numberOfDays: number | undefined,
@@ -190,6 +214,12 @@ function expansionRange(
190
214
  endOfWeek(endOfMonth(date), { weekStartsOn }),
191
215
  ];
192
216
  }
217
+ if (mode === "year") {
218
+ return [
219
+ startOfWeek(startOfYear(date), { weekStartsOn }),
220
+ endOfWeek(endOfYear(date), { weekStartsOn }),
221
+ ];
222
+ }
193
223
  if (mode === "schedule") {
194
224
  // The agenda lists forward from the anchor date; three months is a sensible
195
225
  // default look-ahead. Pre-expand for a different window.
@@ -199,15 +229,16 @@ function expansionRange(
199
229
  return [startOfDay(days[0]), endOfDay(days[days.length - 1])];
200
230
  }
201
231
 
202
- // The date one page away in `direction` (+1 next, −1 previous): a month for
203
- // `month`, a week for `schedule`, else the view's day span.
232
+ // The date one page away in `direction` (+1 next, −1 previous): a year for
233
+ // `year`, a month for `month`, a week for `schedule`, else the view's day span.
204
234
  function pageStep(
205
- mode: "month" | "schedule" | TimeGridMode,
235
+ mode: CalendarMode,
206
236
  date: Date,
207
237
  direction: number,
208
238
  weekStartsOn: WeekStartsOn,
209
239
  numberOfDays: number | undefined,
210
240
  ): Date {
241
+ if (mode === "year") return addYears(date, direction);
211
242
  if (mode === "month") return addMonths(date, direction);
212
243
  if (mode === "schedule") return addDays(date, direction * 7);
213
244
  return addDays(date, direction * getViewDays(mode, date, weekStartsOn, numberOfDays ?? 1).length);
@@ -230,6 +261,8 @@ export function Calendar<T = unknown>({
230
261
  events,
231
262
  onChangeDate,
232
263
  weekStartsOn = 0,
264
+ hiddenDays,
265
+ now,
233
266
  numberOfDays,
234
267
  locale,
235
268
  timeZone,
@@ -250,8 +283,10 @@ export function Calendar<T = unknown>({
250
283
  showWeekNumber,
251
284
  weekNumberPrefix,
252
285
  businessHours,
286
+ renderBusinessHours,
253
287
  showNowIndicator,
254
288
  showAllDayEventCell,
289
+ highlightWeekends,
255
290
  dragStepMinutes,
256
291
  onPressCell,
257
292
  onCreateEvent,
@@ -274,6 +309,7 @@ export function Calendar<T = unknown>({
274
309
  isDateDisabled,
275
310
  keyboardDayNavigation,
276
311
  onPressDay,
312
+ onPressMonth,
277
313
  onPressMore,
278
314
  renderMonthEvent,
279
315
  // schedule
@@ -313,7 +349,24 @@ export function Calendar<T = unknown>({
313
349
  };
314
350
 
315
351
  let view: ReactElement;
316
- if (mode === "schedule") {
352
+ if (mode === "year") {
353
+ view = (
354
+ <YearView<T>
355
+ date={date}
356
+ events={displayEvents}
357
+ weekStartsOn={weekStartsOn}
358
+ hiddenDays={hiddenDays}
359
+ locale={locale}
360
+ theme={theme}
361
+ className={className}
362
+ style={height != null ? { height, ...style } : style}
363
+ classNames={classNames}
364
+ styles={styles}
365
+ onPressDay={onPressDay}
366
+ onPressMonth={onPressMonth}
367
+ />
368
+ );
369
+ } else if (mode === "schedule") {
317
370
  view = (
318
371
  <Agenda<T>
319
372
  events={displayEvents}
@@ -338,6 +391,7 @@ export function Calendar<T = unknown>({
338
391
  date={date}
339
392
  events={displayEvents}
340
393
  weekStartsOn={weekStartsOn}
394
+ hiddenDays={hiddenDays}
341
395
  weekdayFormat={weekdayFormat}
342
396
  locale={locale}
343
397
  theme={theme}
@@ -370,6 +424,9 @@ export function Calendar<T = unknown>({
370
424
  mode={mode}
371
425
  events={displayEvents}
372
426
  weekStartsOn={weekStartsOn}
427
+ hiddenDays={hiddenDays}
428
+ now={now}
429
+ timeZone={timeZone}
373
430
  weekdayFormat={weekdayFormat}
374
431
  numberOfDays={numberOfDays}
375
432
  locale={locale}
@@ -389,14 +446,17 @@ export function Calendar<T = unknown>({
389
446
  showWeekNumber={showWeekNumber}
390
447
  weekNumberPrefix={weekNumberPrefix}
391
448
  businessHours={businessHours}
449
+ renderBusinessHours={renderBusinessHours}
392
450
  showNowIndicator={showNowIndicator}
393
451
  showAllDayEventCell={showAllDayEventCell}
452
+ highlightWeekends={highlightWeekends}
394
453
  dragStepMinutes={dragStepMinutes}
395
454
  onPressEvent={onPressEvent}
396
455
  onPressCell={onPressCell}
397
456
  onCreateEvent={onCreateEvent}
398
457
  onDragStart={onDragStart}
399
458
  onDragEvent={onDragEvent}
459
+ onChangeDate={onChangeDate}
400
460
  onPressDateHeader={onPressDateHeader}
401
461
  renderEvent={renderTimeEvent}
402
462
  eventAccessibilityLabel={eventAccessibilityLabel}
package/src/MonthList.tsx CHANGED
@@ -9,6 +9,7 @@ import {
9
9
  type DateSelectionConstraints,
10
10
  type EventAccessibilityLabeler,
11
11
  groupEventsByDay,
12
+ isBackgroundEvent,
12
13
  type WeekdayFormat,
13
14
  type WeekStartsOn,
14
15
  } from "@super-calendar/core";
@@ -133,7 +134,8 @@ export function MonthList<T = unknown>({
133
134
  // Build the day→events index once for the whole list rather than per month.
134
135
  const eventsByDay = useMemo(() => {
135
136
  if (!events) return undefined;
136
- const map = groupEventsByDay(events);
137
+ // Background events shade the time grid; the month grids ignore them.
138
+ const map = groupEventsByDay(events.filter((event) => !isBackgroundEvent(event)));
137
139
  // Each day reads all-day events first, then timed events by start.
138
140
  for (const list of map.values()) list.sort(compareDayEvents);
139
141
  return map;
package/src/MonthView.tsx CHANGED
@@ -27,6 +27,7 @@ import {
27
27
  type DateSelectionConstraints,
28
28
  type EventAccessibilityLabeler,
29
29
  groupEventsByDay,
30
+ isBackgroundEvent,
30
31
  isAllDayEvent,
31
32
  type MonthGridDay,
32
33
  monthVisibleCount,
@@ -53,7 +54,8 @@ export type MonthViewSlot =
53
54
  | "events"
54
55
  | "chipButton"
55
56
  | "chip"
56
- | "more";
57
+ | "more"
58
+ | "morePopover";
57
59
 
58
60
  // Chip metrics for the events layout (when `events` is provided).
59
61
  const DATE_ROW = 24;
@@ -79,6 +81,8 @@ export interface MonthViewProps<T = unknown>
79
81
  date: Date;
80
82
  /** First day of the week. Sunday = 0 (default) … Saturday = 6. */
81
83
  weekStartsOn?: WeekStartsOn;
84
+ /** Weekdays (0=Sunday…6=Saturday) hidden from the grid, e.g. `[0, 6]` for weekends off. */
85
+ hiddenDays?: number[];
82
86
  /** Weekday header label width: `narrow` ("M"), `short` ("Mon", default), or `long` ("Monday"). */
83
87
  weekdayFormat?: WeekdayFormat;
84
88
  /**
@@ -367,6 +371,7 @@ interface MonthViewInternalProps<T = unknown> extends MonthViewProps<T> {
367
371
  export function MonthView<T = unknown>({
368
372
  date,
369
373
  weekStartsOn = 0,
374
+ hiddenDays,
370
375
  weekdayFormat = "short",
371
376
  events,
372
377
  eventsByDay: eventsByDayProp,
@@ -411,11 +416,49 @@ export function MonthView<T = unknown>({
411
416
  // The list (MonthList) sorts before passing its index in; only sort here when
412
417
  // building our own, so each day reads all-day events first, then by start.
413
418
  if (eventsByDayProp) return eventsByDayProp;
414
- const map = groupEventsByDay(events ?? []);
419
+ // Background events shade the time grid; the month grid ignores them.
420
+ const map = groupEventsByDay((events ?? []).filter((event) => !isBackgroundEvent(event)));
415
421
  for (const list of map.values()) list.sort(compareDayEvents);
416
422
  return map;
417
423
  }, [eventsByDayProp, events]);
418
424
  const Chip = renderEvent;
425
+ // Built-in "+N more" popover: opens when the consumer doesn't handle
426
+ // `onPressMore` themselves. Keyed by the day id; closes on outside click,
427
+ // Escape, or picking an event.
428
+ const [moreOpenFor, setMoreOpenFor] = useState<string | null>(null);
429
+ const morePopoverRef = useRef<HTMLDivElement | null>(null);
430
+ // The "+N more" button that opened the popover, so focus can return to it.
431
+ const moreTriggerRef = useRef<HTMLButtonElement | null>(null);
432
+ useEffect(() => {
433
+ if (moreOpenFor) {
434
+ // Move focus into the dialog so keyboard users land on the first event.
435
+ morePopoverRef.current?.querySelector<HTMLElement>("button")?.focus();
436
+ return;
437
+ }
438
+ // Return focus to the trigger when the popover closes.
439
+ moreTriggerRef.current?.focus();
440
+ moreTriggerRef.current = null;
441
+ }, [moreOpenFor]);
442
+ useEffect(() => {
443
+ if (!moreOpenFor) return;
444
+ const onDocPointerDown = (e: PointerEvent) => {
445
+ if (!morePopoverRef.current?.contains(e.target as Node)) {
446
+ // A pointer dismissal moves focus to whatever was clicked; don't yank
447
+ // it back to the trigger (that's for Escape and event selection).
448
+ moreTriggerRef.current = null;
449
+ setMoreOpenFor(null);
450
+ }
451
+ };
452
+ const onKey = (e: KeyboardEvent) => {
453
+ if (e.key === "Escape") setMoreOpenFor(null);
454
+ };
455
+ document.addEventListener("pointerdown", onDocPointerDown);
456
+ document.addEventListener("keydown", onKey);
457
+ return () => {
458
+ document.removeEventListener("pointerdown", onDocPointerDown);
459
+ document.removeEventListener("keydown", onKey);
460
+ };
461
+ }, [moreOpenFor]);
419
462
  // Reserve `maxVisibleEventCount` rows below the date so every cell is uniform;
420
463
  // when a day overflows, the last row becomes the "+N more" affordance.
421
464
  const eventRowHeight = CELL_PAD * 2 + DATE_ROW + maxVisibleEventCount * (CHIP_HEIGHT + CHIP_GAP);
@@ -423,6 +466,7 @@ export function MonthView<T = unknown>({
423
466
  () =>
424
467
  buildMonthGrid(date, {
425
468
  weekStartsOn,
469
+ hiddenDays,
426
470
  weekdayFormat,
427
471
  selectedRange,
428
472
  selectedDates,
@@ -710,16 +754,104 @@ export function MonthView<T = unknown>({
710
754
  {overflow ? (
711
755
  <button
712
756
  type="button"
757
+ // In built-in-popover mode, keep the document
758
+ // pointerdown dismiss from firing before this click's
759
+ // toggle, so pressing the button again closes it.
760
+ onPointerDown={onPressMore ? undefined : (e) => e.stopPropagation()}
713
761
  onClick={(e) => {
714
762
  e.stopPropagation();
715
- onPressMore?.(rest, day.date);
763
+ if (onPressMore) onPressMore(rest, day.date);
764
+ else {
765
+ moreTriggerRef.current = e.currentTarget;
766
+ setMoreOpenFor((open) => (open === day.id ? null : day.id));
767
+ }
716
768
  }}
717
769
  {...slot("more", moreButtonDefault(theme))}
718
770
  aria-label={`${rest.length} more events, ${dayLabel}`}
771
+ aria-expanded={onPressMore ? undefined : moreOpenFor === day.id}
719
772
  >
720
773
  {moreLabel.replace("{moreCount}", String(rest.length))}
721
774
  </button>
722
775
  ) : null}
776
+ {moreOpenFor === day.id ? (
777
+ <div
778
+ ref={morePopoverRef}
779
+ // A non-modal dialog: Tab stays inside and Escape closes,
780
+ // but the page behind is not inert (outside clicks work),
781
+ // so no aria-modal claim.
782
+ role="dialog"
783
+ aria-label={dayLabel}
784
+ onPointerDown={(e) => e.stopPropagation()}
785
+ // Contain Tab inside the dialog; Escape (handled on the
786
+ // document) closes it and restores focus to the trigger.
787
+ onKeyDown={(e) => {
788
+ if (e.key !== "Tab") return;
789
+ const buttons =
790
+ morePopoverRef.current?.querySelectorAll<HTMLElement>("button");
791
+ if (!buttons?.length) return;
792
+ const first = buttons[0];
793
+ const last = buttons[buttons.length - 1];
794
+ if (e.shiftKey && document.activeElement === first) {
795
+ e.preventDefault();
796
+ last.focus();
797
+ } else if (!e.shiftKey && document.activeElement === last) {
798
+ e.preventDefault();
799
+ first.focus();
800
+ }
801
+ }}
802
+ {...slot("morePopover", {
803
+ base: {
804
+ position: "absolute",
805
+ top: 2,
806
+ left: 2,
807
+ right: 2,
808
+ zIndex: 10,
809
+ display: "flex",
810
+ flexDirection: "column",
811
+ gap: 2,
812
+ maxHeight: 240,
813
+ overflowY: "auto",
814
+ },
815
+ themed: {
816
+ background: theme.surface,
817
+ border: `1px solid ${theme.gridLine}`,
818
+ borderRadius: 8,
819
+ padding: 6,
820
+ boxShadow: "0 4px 16px rgba(0,0,0,0.12)",
821
+ },
822
+ })}
823
+ >
824
+ <div style={{ fontSize: 11, fontWeight: 600, color: theme.textMuted }}>
825
+ {dayLabel}
826
+ </div>
827
+ {dayEvents.map((event, i) => (
828
+ <button
829
+ key={i}
830
+ type="button"
831
+ onClick={() => {
832
+ setMoreOpenFor(null);
833
+ onPressEvent?.(event);
834
+ }}
835
+ style={{
836
+ display: "block",
837
+ width: "100%",
838
+ border: "none",
839
+ background: "transparent",
840
+ padding: 0,
841
+ font: "inherit",
842
+ textAlign: "left",
843
+ cursor: "pointer",
844
+ }}
845
+ >
846
+ {Chip ? (
847
+ <Chip event={event} onPress={() => onPressEvent?.(event)} />
848
+ ) : (
849
+ <span {...slot("chip", chipDefault(theme))}>{event.title}</span>
850
+ )}
851
+ </button>
852
+ ))}
853
+ </div>
854
+ ) : null}
723
855
  </div>
724
856
  </div>
725
857
  );