@super-calendar/dom 2.1.5 → 2.2.0

package/src/ResourceTimeline.tsx

@@ -0,0 +1,431 @@
+import { addMinutes, startOfDay } from "date-fns";
+import type {
+  ComponentType,
+  CSSProperties,
+  PointerEvent as ReactPointerEvent,
+  ReactElement,
+} from "react";
+import { useMemo, useRef, useState } from "react";
+import {
+  type CalendarEvent,
+  eventTimeLabel,
+  formatHour,
+  layoutDayEvents,
+} from "@super-calendar/core";
+import { createSlots, dataState, type ResolvedSlot, type SlotStyleProps } from "./slots";
+import { type DomCalendarTheme, mergeDomTheme } from "./theme";
+
+/**
+ * Styleable parts of {@link ResourceTimeline}. Pass a class or inline style per
+ * slot via the `classNames` / `styles` props.
+ */
+export type ResourceTimelineSlot =
+  | "header"
+  | "corner"
+  | "timeAxis"
+  | "hourTick"
+  | "resourceLabel"
+  | "row"
+  | "track"
+  | "gridLines"
+  | "event"
+  | "eventBox";
+
+/** A schedulable lane (room, person, machine) that events are grouped under. */
+export interface Resource {
+  /** Stable id events reference via their `resourceId`. */
+  id: string;
+  /** Row label; falls back to the id. */
+  title?: string;
+}
+
+/** Props passed to a custom resource-timeline event renderer. */
+export interface ResourceEventArgs<T = unknown> {
+  event: CalendarEvent<T>;
+  /** Pixel width of the event bar. */
+  width: number;
+  onPress: () => void;
+}
+
+/** Props for {@link ResourceTimeline}. */
+export interface ResourceTimelineProps<T = unknown> extends SlotStyleProps<ResourceTimelineSlot> {
+  /** The day to lay out along the horizontal axis. */
+  date: Date;
+  /** The rows, top to bottom. */
+  resources: Resource[];
+  /** Events; each is placed in the row named by `resourceId(event)`. */
+  events: CalendarEvent<T>[];
+  /** Read an event's resource id. Default: `event.resourceId`. */
+  resourceId?: (event: CalendarEvent<T>) => string | undefined;
+  /** First hour shown (default 0). */
+  startHour?: number;
+  /** Last hour shown, exclusive (default 24). */
+  endHour?: number;
+  /** Pixels per hour along the axis (default 80). */
+  hourWidth?: number;
+  /** Height of each resource row in px (default 56). */
+  rowHeight?: number;
+  /** Width of the left resource-label column in px (default 140). */
+  labelWidth?: number;
+  /** 12-hour AM/PM axis labels (default false). */
+  ampm?: boolean;
+  /** Theme overrides; falls back to the default light theme. */
+  theme?: Partial<DomCalendarTheme>;
+  /** Custom event renderer; falls back to the built-in bar. */
+  renderEvent?: ComponentType<ResourceEventArgs<T>>;
+  /** Tap an event. */
+  onPressEvent?: (event: CalendarEvent<T>) => void;
+  /**
+   * Enables drag-to-move and edge-resize along the time axis; called with the
+   * proposed new start/end. Return `false` to reject the drop (it snaps back).
+   */
+  onDragEvent?: (event: CalendarEvent<T>, start: Date, end: Date) => void | boolean;
+  /** Snap dragged events to this many minutes (default 15). */
+  dragStepMinutes?: number;
+  /** Class applied to the root element. */
+  className?: string;
+  /** Inline styles applied to the root element. */
+  style?: CSSProperties;
+}
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+type DragState = {
+  key: string;
+  kind: "move" | "resize";
+  startHours: number;
+  durationHours: number;
+  moved: boolean;
+};
+
+function DefaultBar<T>({
+  event,
+  boxProps,
+  theme,
+}: ResourceEventArgs<T> & { boxProps: ResolvedSlot; theme: DomCalendarTheme }) {
+  const time = eventTimeLabel({
+    mode: "day",
+    isAllDay: false,
+    start: event.start,
+    end: event.end,
+    ampm: false,
+    showTime: true,
+  });
+  const base: CSSProperties = { height: "100%", boxSizing: "border-box", overflow: "hidden" };
+  const themed: CSSProperties = {
+    padding: "2px 6px",
+    borderRadius: 6,
+    background: theme.eventBackground,
+    color: theme.eventText,
+    fontSize: 12,
+  };
+  return (
+    <div
+      className={boxProps.className}
+      data-slot={boxProps["data-slot"]}
+      style={
+        boxProps.className
+          ? { ...base, ...boxProps.style }
+          : { ...base, ...themed, ...boxProps.style }
+      }
+    >
+      <div
+        style={{
+          fontWeight: 600,
+          whiteSpace: "nowrap",
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+        }}
+      >
+        {event.title}
+      </div>
+      {time ? <div style={{ opacity: 0.75, fontSize: 11 }}>{time}</div> : null}
+    </div>
+  );
+}
+
+/**
+ * A horizontal resource timeline: rows are resources (rooms, people, machines)
+ * and the x-axis is one day's hours. Events sit in their resource's row, and
+ * overlapping events in the same row stack into sub-lanes (via the shared
+ * `layoutDayEvents`). Pass `onDragEvent` to enable drag-to-move and edge-resize
+ * along the axis.
+ *
+ * @example
+ * ```tsx
+ * <ResourceTimeline
+ *   date={new Date()}
+ *   resources={[{ id: "a", title: "Room A" }, { id: "b", title: "Room B" }]}
+ *   events={events} // each event carries a `resourceId`
+ * />
+ * ```
+ */
+export function ResourceTimeline<T = unknown>({
+  date,
+  resources,
+  events,
+  resourceId = (event) => (event as { resourceId?: string }).resourceId,
+  startHour = 0,
+  endHour = 24,
+  hourWidth = 80,
+  rowHeight = 56,
+  labelWidth = 140,
+  ampm = false,
+  theme: themeOverrides,
+  renderEvent,
+  onPressEvent,
+  onDragEvent,
+  dragStepMinutes = 15,
+  className,
+  style,
+  classNames,
+  styles,
+}: ResourceTimelineProps<T>): ReactElement {
+  const theme = useMemo(() => mergeDomTheme(themeOverrides), [themeOverrides]);
+  const slot = createSlots<ResourceTimelineSlot>({ classNames, styles });
+  const Renderer = renderEvent;
+  const snapHours = dragStepMinutes / 60;
+
+  // `drag` drives the visual; `dragRef` is the source of truth the pointer
+  // handlers read so they never see a stale closure between events.
+  const [drag, setDrag] = useState<DragState | null>(null);
+  const dragRef = useRef<DragState | null>(null);
+  const origin = useRef<{ x: number; startHours: number; durationHours: number } | null>(null);
+  const applyDrag = (next: DragState | null) => {
+    dragRef.current = next;
+    setDrag(next);
+  };
+
+  const beginDrag = (
+    e: ReactPointerEvent,
+    key: string,
+    kind: "move" | "resize",
+    startHours: number,
+    durationHours: number,
+  ) => {
+    if (!onDragEvent) return;
+    e.stopPropagation();
+    try {
+      (e.target as HTMLElement).setPointerCapture?.(e.pointerId);
+    } catch {
+      // Pointer capture is best-effort.
+    }
+    origin.current = { x: 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 snap = (v: number) => Math.round(v / snapHours) * snapHours;
+    if (d.kind === "move") {
+      const startHours = clamp(
+        snap(origin.current.startHours + dHours),
+        startHour,
+        endHour - d.durationHours,
+      );
+      applyDrag({ ...d, startHours, moved: true });
+    } else {
+      const durationHours = clamp(
+        snap(origin.current.durationHours + dHours),
+        snapHours,
+        endHour - d.startHours,
+      );
+      applyDrag({ ...d, durationHours, moved: true });
+    }
+  };
+  const endDrag = (e: ReactPointerEvent, event: CalendarEvent<T>, onPress: () => void) => {
+    const d = dragRef.current;
+    if (!d) return;
+    try {
+      (e.target as HTMLElement).releasePointerCapture?.(e.pointerId);
+    } catch {
+      // Best-effort release.
+    }
+    if (!d.moved) {
+      applyDrag(null);
+      onPress();
+      return;
+    }
+    const base = startOfDay(date);
+    const start = addMinutes(base, Math.round(d.startHours * 60));
+    const end = addMinutes(base, Math.round((d.startHours + d.durationHours) * 60));
+    onDragEvent?.(event, start, end);
+    applyDrag(null);
+    origin.current = null;
+  };
+  const cancelDrag = () => {
+    applyDrag(null);
+    origin.current = null;
+  };
+
+  const hours = useMemo(
+    () => Array.from({ length: Math.max(0, endHour - startHour) }, (_, i) => startHour + i),
+    [startHour, endHour],
+  );
+  const trackWidth = (endHour - startHour) * hourWidth;
+
+  // Group the positioned (overlap-resolved) events by resource, once.
+  const byResource = useMemo(() => {
+    const map = new Map<string, ReturnType<typeof layoutDayEvents<T>>>();
+    for (const resource of resources) {
+      const own = events.filter((e) => resourceId(e) === resource.id);
+      map.set(resource.id, layoutDayEvents(own, date));
+    }
+    return map;
+  }, [resources, events, resourceId, date]);
+
+  const gridLines = `repeating-linear-gradient(to right, transparent 0, transparent ${hourWidth - 1}px, ${theme.gridLine} ${hourWidth - 1}px, ${theme.gridLine} ${hourWidth}px)`;
+
+  return (
+    <div
+      className={className}
+      style={{ fontFamily: theme.fontFamily, color: theme.text, overflowX: "auto", ...style }}
+    >
+      <div style={{ minWidth: labelWidth + trackWidth }}>
+        {/* Header: corner + hour axis */}
+        <div
+          {...slot("header", {
+            base: { display: "flex" },
+            themed: { borderBottom: `1px solid ${theme.gridLine}` },
+          })}
+        >
+          <div {...slot("corner", { base: { width: labelWidth, flex: "none" } })} />
+          <div
+            {...slot("timeAxis", { base: { position: "relative", height: 24, width: trackWidth } })}
+          >
+            {hours.map((h) => (
+              <div
+                key={h}
+                {...slot("hourTick", {
+                  base: { position: "absolute", left: (h - startHour) * hourWidth, top: 4 },
+                  themed: { fontSize: 10, color: theme.textMuted },
+                })}
+              >
+                {formatHour(h, { ampm })}
+              </div>
+            ))}
+          </div>
+        </div>
+
+        {/* Resource rows */}
+        {resources.map((resource) => {
+          const positioned = byResource.get(resource.id) ?? [];
+          return (
+            <div
+              key={resource.id}
+              {...slot("row", {
+                base: { display: "flex", height: rowHeight },
+                themed: { borderBottom: `1px solid ${theme.gridLine}` },
+              })}
+            >
+              <div
+                {...slot("resourceLabel", {
+                  base: {
+                    width: labelWidth,
+                    flex: "none",
+                    display: "flex",
+                    alignItems: "center",
+                    padding: "0 10px",
+                    boxSizing: "border-box",
+                  },
+                  themed: {
+                    fontSize: 13,
+                    fontWeight: 600,
+                    borderRight: `1px solid ${theme.gridLine}`,
+                  },
+                })}
+              >
+                {resource.title ?? resource.id}
+              </div>
+              <div {...slot("track", { base: { position: "relative", width: trackWidth } })}>
+                <div
+                  aria-hidden
+                  {...slot("gridLines", {
+                    base: { position: "absolute", inset: 0, pointerEvents: "none" },
+                    themed: { backgroundImage: gridLines },
+                  })}
+                />
+                {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 left = clamp(startH - startHour, 0, endHour - startHour) * hourWidth;
+                  const right =
+                    clamp(startH + durH - startHour, 0, endHour - startHour) * hourWidth;
+                  const width = Math.max(right - left, 2);
+                  // Overlapping events in a row share the height as stacked sub-lanes.
+                  const laneHeight = rowHeight / pe.columns;
+                  const onPress = () => onPressEvent?.(pe.event);
+                  const args: ResourceEventArgs<T> = { event: pe.event, width, 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",
+                          left,
+                          width,
+                          top: pe.column * laneHeight,
+                          height: laneHeight,
+                          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",
+                            top: 0,
+                            bottom: 0,
+                            right: 0,
+                            width: 8,
+                            cursor: "ew-resize",
+                            touchAction: "none",
+                          }}
+                        />
+                      ) : null}
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}