@super-calendar/dom 2.6.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.
@@ -4,10 +4,16 @@ import type {
4
4
  CSSProperties,
5
5
  PointerEvent as ReactPointerEvent,
6
6
  ReactElement,
7
+ ReactNode,
7
8
  } from "react";
8
9
  import { useMemo, useRef, useState } from "react";
9
10
  import {
11
+ backgroundBandsForDay,
12
+ type BusinessHoursBand,
13
+ type BusinessHoursValue,
10
14
  type CalendarEvent,
15
+ isSameCalendarDay,
16
+ useNow,
11
17
  cellRangeFromDrag,
12
18
  closedHourBands,
13
19
  eventTimeLabel,
@@ -31,8 +37,10 @@ export type ResourceTimelineSlot =
31
37
  | "track"
32
38
  | "gridLines"
33
39
  | "businessHours"
40
+ | "backgroundEvent"
34
41
  | "event"
35
42
  | "eventBox"
43
+ | "nowIndicator"
36
44
  | "createGhost";
37
45
 
38
46
  /** A schedulable lane (room, person, machine) that events are grouped under. */
@@ -69,6 +77,19 @@ export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<Resou
69
77
  orientation?: "horizontal" | "vertical";
70
78
  /** The resource lanes: rows when horizontal, columns when vertical. */
71
79
  resources: Resource[];
80
+ /**
81
+ * Cap the number of lanes shown at once; the rest sit on further pages. Pair
82
+ * with `resourcePage` and your own prev/next controls to page through them
83
+ * (like `date` drives the time axis). Omit to show every lane, sharing the
84
+ * available space.
85
+ */
86
+ resourcesPerPage?: number;
87
+ /**
88
+ * The 0-based page of lanes to show when `resourcesPerPage` is set (default
89
+ * 0, clamped to the last page). Controlled: update it from your own paging
90
+ * controls.
91
+ */
92
+ resourcePage?: number;
72
93
  /** Events; each is placed in the row named by `resourceId(event)`. */
73
94
  events: CalendarEvent<T>[];
74
95
  /** Read an event's resource id. Default: `event.resourceId`. */
@@ -97,7 +118,12 @@ export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<Resou
97
118
  * Enables drag-to-move and edge-resize along the time axis; called with the
98
119
  * proposed new start/end. Return `false` to reject the drop (it snaps back).
99
120
  */
100
- onDragEvent?: (event: CalendarEvent<T>, start: Date, end: Date) => void | boolean;
121
+ onDragEvent?: (
122
+ event: CalendarEvent<T>,
123
+ start: Date,
124
+ end: Date,
125
+ resource: Resource,
126
+ ) => void | boolean;
101
127
  /** Tap empty lane space; called with the snapped time and the lane's resource. */
102
128
  onPressCell?: (at: Date, resource: Resource) => void;
103
129
  /** Drag empty lane space to create; called with the swept start/end and the lane's resource. */
@@ -107,9 +133,22 @@ export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<Resou
107
133
  * `businessHours` plus the lane's resource, so per-resource opening hours work
108
134
  * (return `null` for a fully closed lane). A date-only function is accepted.
109
135
  */
110
- businessHours?: (date: Date, resource: Resource) => { start: number; end: number } | null;
136
+ businessHours?: (date: Date, resource: Resource) => BusinessHoursValue;
137
+ /**
138
+ * Render a closed-hours band's content yourself (a label, icon, pattern). The
139
+ * board keeps positioning the band; when set, the themed tint is dropped and
140
+ * your output fills the band instead. Receives the lane's resource. Decorative only: the
141
+ * band stays non-interactive and hidden from assistive tech.
142
+ */
143
+ renderBusinessHours?: (band: BusinessHoursBand & { resource: Resource }) => ReactNode;
111
144
  /** Snap dragged events to this many minutes (default 15). */
112
145
  dragStepMinutes?: number;
146
+ /** Show the current-time line when `date` is today (default true). */
147
+ showNowIndicator?: boolean;
148
+ /** Fixed "now" instant for the indicator (doesn't tick). Defaults to the device clock. */
149
+ now?: Date;
150
+ /** Shift the now indicator into this IANA zone (pair with `eventsInTimeZone`). */
151
+ timeZone?: string;
113
152
  /** Class applied to the root element. */
114
153
  className?: string;
115
154
  /** Inline styles applied to the root element. */
@@ -123,9 +162,13 @@ const GUTTER_WIDTH = 56;
123
162
 
124
163
  type DragState = {
125
164
  key: string;
165
+ /** The lane the drag started in, so its row can be lifted while dragging. */
166
+ resourceId: string;
126
167
  kind: "move" | "resize";
127
168
  startHours: number;
128
169
  durationHours: number;
170
+ /** Live cross-axis offset (px) of a move, for the follow-the-pointer ghost. */
171
+ crossPx: number;
129
172
  moved: boolean;
130
173
  };
131
174
 
@@ -198,7 +241,9 @@ function DefaultBar<T>({
198
241
  export function ResourceTimeline<T = unknown>({
199
242
  date,
200
243
  orientation = "horizontal",
201
- resources,
244
+ resources: allResources,
245
+ resourcesPerPage,
246
+ resourcePage = 0,
202
247
  events,
203
248
  resourceId = (event) => (event as { resourceId?: string }).resourceId,
204
249
  startHour = 0,
@@ -215,12 +260,23 @@ export function ResourceTimeline<T = unknown>({
215
260
  onPressCell,
216
261
  onCreateEvent,
217
262
  businessHours,
263
+ renderBusinessHours,
218
264
  dragStepMinutes = 15,
265
+ showNowIndicator = true,
266
+ now: nowProp,
267
+ timeZone,
219
268
  className,
220
269
  style,
221
270
  classNames,
222
271
  styles,
223
272
  }: ResourceTimelineProps<T>): ReactElement {
273
+ // Window the lanes to the requested page when resourcesPerPage caps them.
274
+ const resources = useMemo(() => {
275
+ if (!resourcesPerPage || resourcesPerPage <= 0) return allResources;
276
+ const pages = Math.max(1, Math.ceil(allResources.length / resourcesPerPage));
277
+ const page = Math.min(Math.max(resourcePage, 0), pages - 1);
278
+ return allResources.slice(page * resourcesPerPage, (page + 1) * resourcesPerPage);
279
+ }, [allResources, resourcesPerPage, resourcePage]);
224
280
  const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
225
281
  const slot = createSlots<ResourceTimelineSlot>({ classNames, styles });
226
282
  const Renderer = renderEvent;
@@ -228,12 +284,54 @@ export function ResourceTimeline<T = unknown>({
228
284
  const vertical = orientation === "vertical";
229
285
  // Pixels per hour along whichever axis carries the time.
230
286
  const hourSize = vertical ? hourHeight : hourWidth;
287
+ // The current-time line, shown only when the board's day is the zone's today.
288
+ const now = useNow(showNowIndicator, { now: nowProp, timeZone });
289
+ const nowHours = now.getHours() + now.getMinutes() / 60;
290
+ const showNow =
291
+ showNowIndicator &&
292
+ isSameCalendarDay(now, date) &&
293
+ nowHours >= startHour &&
294
+ nowHours <= endHour;
295
+ const nowLine = (resourceKey: string) =>
296
+ showNow ? (
297
+ <div
298
+ key={`now-${resourceKey}`}
299
+ aria-hidden
300
+ {...slot("nowIndicator", {
301
+ base: vertical
302
+ ? {
303
+ position: "absolute",
304
+ left: 0,
305
+ right: 0,
306
+ top: (nowHours - startHour) * hourSize,
307
+ height: 2,
308
+ pointerEvents: "none",
309
+ zIndex: 2,
310
+ }
311
+ : {
312
+ position: "absolute",
313
+ top: 0,
314
+ bottom: 0,
315
+ left: (nowHours - startHour) * hourSize,
316
+ width: 2,
317
+ pointerEvents: "none",
318
+ zIndex: 2,
319
+ },
320
+ themed: { background: theme.nowIndicator },
321
+ })}
322
+ />
323
+ ) : null;
231
324
 
232
325
  // `drag` drives the visual; `dragRef` is the source of truth the pointer
233
326
  // handlers read so they never see a stale closure between events.
234
327
  const [drag, setDrag] = useState<DragState | null>(null);
235
328
  const dragRef = useRef<DragState | null>(null);
236
- const origin = useRef<{ x: number; startHours: number; durationHours: number } | null>(null);
329
+ const origin = useRef<{
330
+ x: number;
331
+ cross: number;
332
+ startHours: number;
333
+ durationHours: number;
334
+ } | null>(null);
237
335
  const applyDrag = (next: DragState | null) => {
238
336
  dragRef.current = next;
239
337
  setDrag(next);
@@ -242,6 +340,7 @@ export function ResourceTimeline<T = unknown>({
242
340
  const beginDrag = (
243
341
  e: ReactPointerEvent,
244
342
  key: string,
343
+ resourceId: string,
245
344
  kind: "move" | "resize",
246
345
  startHours: number,
247
346
  durationHours: number,
@@ -253,8 +352,13 @@ export function ResourceTimeline<T = unknown>({
253
352
  } catch {
254
353
  // Pointer capture is best-effort.
255
354
  }
256
- origin.current = { x: vertical ? e.clientY : e.clientX, startHours, durationHours };
257
- applyDrag({ key, kind, startHours, durationHours, moved: false });
355
+ origin.current = {
356
+ x: vertical ? e.clientY : e.clientX,
357
+ cross: vertical ? e.clientX : e.clientY,
358
+ startHours,
359
+ durationHours,
360
+ };
361
+ applyDrag({ key, resourceId, kind, startHours, durationHours, crossPx: 0, moved: false });
258
362
  };
259
363
  const moveDrag = (e: ReactPointerEvent) => {
260
364
  const d = dragRef.current;
@@ -267,7 +371,8 @@ export function ResourceTimeline<T = unknown>({
267
371
  startHour,
268
372
  endHour - d.durationHours,
269
373
  );
270
- applyDrag({ ...d, startHours, moved: true });
374
+ const crossPx = (vertical ? e.clientX : e.clientY) - origin.current.cross;
375
+ applyDrag({ ...d, startHours, crossPx, moved: true });
271
376
  } else {
272
377
  const durationHours = clamp(
273
378
  snap(origin.current.durationHours + dHours),
@@ -277,7 +382,35 @@ export function ResourceTimeline<T = unknown>({
277
382
  applyDrag({ ...d, durationHours, moved: true });
278
383
  }
279
384
  };
280
- const endDrag = (e: ReactPointerEvent, event: CalendarEvent<T>, onPress: () => void) => {
385
+ // Which visible lane the pointer is over, found by hit-testing rather than
386
+ // measuring flexed columns. The dragged bar is momentarily made
387
+ // pointer-transparent so `elementFromPoint` sees the lane, not the bar (which
388
+ // stays a DOM child of its origin lane however far it's visually translated).
389
+ const laneAt = (e: ReactPointerEvent, fallback: Resource): Resource => {
390
+ if (typeof document === "undefined" || typeof document.elementFromPoint !== "function") {
391
+ return fallback;
392
+ }
393
+ const bar = e.currentTarget as HTMLElement;
394
+ const prev = bar.style.pointerEvents;
395
+ // Restore in a finally: a left-behind "none" would permanently disable this
396
+ // bar, since React never re-manages this imperatively-set inline style.
397
+ let hit: Element | null;
398
+ bar.style.pointerEvents = "none";
399
+ try {
400
+ hit = document.elementFromPoint(e.clientX, e.clientY);
401
+ } finally {
402
+ bar.style.pointerEvents = prev;
403
+ }
404
+ const laneEl = (hit as HTMLElement | null)?.closest?.("[data-resource-id]");
405
+ const id = laneEl?.getAttribute("data-resource-id");
406
+ return (id && resources.find((r) => r.id === id)) || fallback;
407
+ };
408
+ const endDrag = (
409
+ e: ReactPointerEvent,
410
+ event: CalendarEvent<T>,
411
+ resource: Resource,
412
+ onPress: () => void,
413
+ ) => {
281
414
  const d = dragRef.current;
282
415
  if (!d) return;
283
416
  try {
@@ -290,10 +423,11 @@ export function ResourceTimeline<T = unknown>({
290
423
  onPress();
291
424
  return;
292
425
  }
426
+ const target = d.kind === "move" ? laneAt(e, resource) : resource;
293
427
  const base = startOfDay(date);
294
428
  const start = addMinutes(base, Math.round(d.startHours * 60));
295
429
  const end = addMinutes(base, Math.round((d.startHours + d.durationHours) * 60));
296
- onDragEvent?.(event, start, end);
430
+ onDragEvent?.(event, start, end, target);
297
431
  applyDrag(null);
298
432
  origin.current = null;
299
433
  };
@@ -385,6 +519,18 @@ export function ResourceTimeline<T = unknown>({
385
519
  businessHours
386
520
  ? closedHourBands(date, (d) => businessHours(d, resource), startHour, endHour)
387
521
  : [];
522
+ // `display: "background"` events in a lane, clipped to the visible window.
523
+ const backgroundBandsFor = (resource: Resource) =>
524
+ backgroundBandsForDay(
525
+ events.filter((e) => resourceId(e) === resource.id),
526
+ date,
527
+ )
528
+ .map((b) => ({
529
+ ...b,
530
+ startHours: Math.max(b.startHours, startHour),
531
+ endHours: Math.min(b.endHours, endHour),
532
+ }))
533
+ .filter((b) => b.endHours > b.startHours);
388
534
 
389
535
  const hours = useMemo(
390
536
  () => Array.from({ length: Math.max(0, endHour - startHour) }, (_, i) => startHour + i),
@@ -402,6 +548,10 @@ export function ResourceTimeline<T = unknown>({
402
548
  return map;
403
549
  }, [resources, events, resourceId, date]);
404
550
 
551
+ // The lane a move is dragging in, lifted above its siblings so the ghost
552
+ // stays visible as it crosses into another lane (a later DOM sibling).
553
+ const dragLaneId = drag?.kind === "move" && drag.moved ? drag.resourceId : null;
554
+
405
555
  if (vertical) {
406
556
  // Time flows down like the time grid: hour gutter on the left, one flexed
407
557
  // column per resource, so narrow screens share the width instead of
@@ -481,11 +631,16 @@ export function ResourceTimeline<T = unknown>({
481
631
  <div
482
632
  key={resource.id}
483
633
  {...slot("row", {
484
- base: { flex: 1, minWidth: 0 },
634
+ base: {
635
+ flex: 1,
636
+ minWidth: 0,
637
+ ...(dragLaneId === resource.id ? { position: "relative", zIndex: 5 } : null),
638
+ },
485
639
  themed: { borderLeft: `1px solid ${theme.gridLine}` },
486
640
  })}
487
641
  >
488
642
  <div
643
+ data-resource-id={resource.id}
489
644
  {...trackInteractionProps(resource)}
490
645
  {...slot("track", { base: { position: "relative", height: trackHeight } })}
491
646
  >
@@ -504,7 +659,30 @@ export function ResourceTimeline<T = unknown>({
504
659
  pointerEvents: "none",
505
660
  zIndex: 0,
506
661
  },
507
- themed: { background: theme.outsideHoursBackground },
662
+ themed: renderBusinessHours
663
+ ? undefined
664
+ : { background: theme.outsideHoursBackground },
665
+ })}
666
+ >
667
+ {renderBusinessHours?.({ date, start: b.start, end: b.end, resource })}
668
+ </div>
669
+ ))}
670
+ {backgroundBandsFor(resource).map((b, i) => (
671
+ <div
672
+ key={`bg-${i}`}
673
+ aria-hidden
674
+ title={b.event.title}
675
+ {...slot("backgroundEvent", {
676
+ base: {
677
+ position: "absolute",
678
+ left: 0,
679
+ right: 0,
680
+ top: (b.startHours - startHour) * hourHeight,
681
+ height: (b.endHours - b.startHours) * hourHeight,
682
+ pointerEvents: "none",
683
+ zIndex: 0,
684
+ },
685
+ themed: { background: theme.backgroundEvent },
508
686
  })}
509
687
  />
510
688
  ))}
@@ -533,7 +711,8 @@ export function ResourceTimeline<T = unknown>({
533
711
  height,
534
712
  onPress,
535
713
  };
536
- const draggable = !!onDragEvent;
714
+ // `draggable: false` locks a single bar (keeps clicks, blocks drag).
715
+ const draggable = !!onDragEvent && pe.event.draggable !== false;
537
716
  return (
538
717
  <button
539
718
  key={idx}
@@ -543,11 +722,21 @@ export function ResourceTimeline<T = unknown>({
543
722
  {...dataState({ "data-dragging": !!active })}
544
723
  onPointerDown={
545
724
  draggable
546
- ? (e) => beginDrag(e, key, "move", pe.startHours, pe.durationHours)
725
+ ? (e) =>
726
+ beginDrag(
727
+ e,
728
+ key,
729
+ resource.id,
730
+ "move",
731
+ pe.startHours,
732
+ pe.durationHours,
733
+ )
547
734
  : undefined
548
735
  }
549
736
  onPointerMove={draggable ? moveDrag : undefined}
550
- onPointerUp={draggable ? (e) => endDrag(e, pe.event, onPress) : undefined}
737
+ onPointerUp={
738
+ draggable ? (e) => endDrag(e, pe.event, resource, onPress) : undefined
739
+ }
551
740
  onPointerCancel={draggable ? cancelDrag : undefined}
552
741
  {...slot("event", {
553
742
  base: {
@@ -556,6 +745,10 @@ export function ResourceTimeline<T = unknown>({
556
745
  height,
557
746
  left: `${pe.column * lanePct}%`,
558
747
  width: `${lanePct}%`,
748
+ transform:
749
+ active?.kind === "move"
750
+ ? `translateX(${active.crossPx}px)`
751
+ : undefined,
559
752
  padding: 1,
560
753
  border: "none",
561
754
  background: "transparent",
@@ -579,7 +772,14 @@ export function ResourceTimeline<T = unknown>({
579
772
  aria-hidden
580
773
  onPointerDown={(e) => {
581
774
  e.stopPropagation();
582
- beginDrag(e, key, "resize", pe.startHours, pe.durationHours);
775
+ beginDrag(
776
+ e,
777
+ key,
778
+ resource.id,
779
+ "resize",
780
+ pe.startHours,
781
+ pe.durationHours,
782
+ );
583
783
  }}
584
784
  style={{
585
785
  position: "absolute",
@@ -595,6 +795,7 @@ export function ResourceTimeline<T = unknown>({
595
795
  </button>
596
796
  );
597
797
  })}
798
+ {nowLine(resource.id)}
598
799
  {createBox?.resourceKey === resource.id ? (
599
800
  <div
600
801
  aria-hidden
@@ -666,7 +867,11 @@ export function ResourceTimeline<T = unknown>({
666
867
  <div
667
868
  key={resource.id}
668
869
  {...slot("row", {
669
- base: { display: "flex", height: rowHeight },
870
+ base: {
871
+ display: "flex",
872
+ height: rowHeight,
873
+ ...(dragLaneId === resource.id ? { position: "relative", zIndex: 5 } : null),
874
+ },
670
875
  themed: { borderBottom: `1px solid ${theme.gridLine}` },
671
876
  })}
672
877
  >
@@ -690,6 +895,7 @@ export function ResourceTimeline<T = unknown>({
690
895
  {resource.title ?? resource.id}
691
896
  </div>
692
897
  <div
898
+ data-resource-id={resource.id}
693
899
  {...trackInteractionProps(resource)}
694
900
  {...slot("track", { base: { position: "relative", width: trackWidth } })}
695
901
  >
@@ -708,7 +914,30 @@ export function ResourceTimeline<T = unknown>({
708
914
  pointerEvents: "none",
709
915
  zIndex: 0,
710
916
  },
711
- themed: { background: theme.outsideHoursBackground },
917
+ themed: renderBusinessHours
918
+ ? undefined
919
+ : { background: theme.outsideHoursBackground },
920
+ })}
921
+ >
922
+ {renderBusinessHours?.({ date, start: b.start, end: b.end, resource })}
923
+ </div>
924
+ ))}
925
+ {backgroundBandsFor(resource).map((b, i) => (
926
+ <div
927
+ key={`bg-${i}`}
928
+ aria-hidden
929
+ title={b.event.title}
930
+ {...slot("backgroundEvent", {
931
+ base: {
932
+ position: "absolute",
933
+ top: 0,
934
+ bottom: 0,
935
+ left: (b.startHours - startHour) * hourWidth,
936
+ width: (b.endHours - b.startHours) * hourWidth,
937
+ pointerEvents: "none",
938
+ zIndex: 0,
939
+ },
940
+ themed: { background: theme.backgroundEvent },
712
941
  })}
713
942
  />
714
943
  ))}
@@ -742,11 +971,21 @@ export function ResourceTimeline<T = unknown>({
742
971
  {...dataState({ "data-dragging": !!active })}
743
972
  onPointerDown={
744
973
  draggable
745
- ? (e) => beginDrag(e, key, "move", pe.startHours, pe.durationHours)
974
+ ? (e) =>
975
+ beginDrag(
976
+ e,
977
+ key,
978
+ resource.id,
979
+ "move",
980
+ pe.startHours,
981
+ pe.durationHours,
982
+ )
746
983
  : undefined
747
984
  }
748
985
  onPointerMove={draggable ? moveDrag : undefined}
749
- onPointerUp={draggable ? (e) => endDrag(e, pe.event, onPress) : undefined}
986
+ onPointerUp={
987
+ draggable ? (e) => endDrag(e, pe.event, resource, onPress) : undefined
988
+ }
750
989
  onPointerCancel={draggable ? cancelDrag : undefined}
751
990
  {...slot("event", {
752
991
  base: {
@@ -755,6 +994,8 @@ export function ResourceTimeline<T = unknown>({
755
994
  width,
756
995
  top: pe.column * laneHeight,
757
996
  height: laneHeight,
997
+ transform:
998
+ active?.kind === "move" ? `translateY(${active.crossPx}px)` : undefined,
758
999
  padding: 1,
759
1000
  border: "none",
760
1001
  background: "transparent",
@@ -778,7 +1019,14 @@ export function ResourceTimeline<T = unknown>({
778
1019
  aria-hidden
779
1020
  onPointerDown={(e) => {
780
1021
  e.stopPropagation();
781
- beginDrag(e, key, "resize", pe.startHours, pe.durationHours);
1022
+ beginDrag(
1023
+ e,
1024
+ key,
1025
+ resource.id,
1026
+ "resize",
1027
+ pe.startHours,
1028
+ pe.durationHours,
1029
+ );
782
1030
  }}
783
1031
  style={{
784
1032
  position: "absolute",
@@ -794,6 +1042,7 @@ export function ResourceTimeline<T = unknown>({
794
1042
  </button>
795
1043
  );
796
1044
  })}
1045
+ {nowLine(resource.id)}
797
1046
  {createBox?.resourceKey === resource.id ? (
798
1047
  <div
799
1048
  aria-hidden