@svgrid/enterprise 2.2.1 → 2.3.1

package/src/scheduler-axis.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import { buildAxis, resolveZoom, timeToX, xToTime, zoomPresets } from './scheduler-axis'
+
+const day = (d: number, h = 0) => new Date(2026, 0, d, h, 0, 0, 0)
+
+describe('buildAxis - linear (no collapse)', () => {
+  it('maps a full day linearly at pxPerMinute', () => {
+    const axis = buildAxis(day(5), day(6), { pxPerMinute: 1 }) // 1px/min => 1440px
+    expect(axis.totalPx).toBe(1440)
+    expect(timeToX(day(5, 12), axis)).toBe(720) // noon = halfway
+  })
+
+  it('timeToX / xToTime round-trip within a working span', () => {
+    const axis = buildAxis(day(5), day(6), { pxPerMinute: 1 })
+    const t = day(5, 9)
+    expect(xToTime(timeToX(t, axis), axis).getTime()).toBe(t.getTime())
+  })
+})
+
+describe('buildAxis - business hours collapse', () => {
+  it('collapses nights to a fixed gap so working hours dominate', () => {
+    const axis = buildAxis(day(5), day(7), {
+      pxPerMinute: 1,
+      businessHours: { start: 9, end: 17 }, // 8h = 480px working
+      collapseNonWorking: true,
+      collapsedGapPx: 10,
+    })
+    const working = axis.segments.filter((s) => s.kind === 'working')
+    const collapsed = axis.segments.filter((s) => s.kind === 'collapsed')
+    expect(working).toHaveLength(2) // two work days
+    expect(working[0]!.px).toBe(480)
+    // Gaps: before day5 9am, night between, after day6 5pm - each a collapsed 10px.
+    expect(collapsed.every((s) => s.px === 10)).toBe(true)
+    expect(axis.totalPx).toBe(480 * 2 + 10 * collapsed.length)
+  })
+
+  it('omits gaps entirely when collapsedGapPx is 0', () => {
+    const axis = buildAxis(day(5), day(6), {
+      pxPerMinute: 1,
+      businessHours: { start: 9, end: 17 },
+      collapseNonWorking: true,
+      collapsedGapPx: 0,
+    })
+    expect(axis.totalPx).toBe(480) // just the working span
+  })
+})
+
+describe('buildAxis - weekend collapse', () => {
+  it('collapses whole non-working days', () => {
+    // Jan 2026: 3rd = Sat, 4th = Sun. Range Fri Jan 2 -> Mon Jan 5.
+    const axis = buildAxis(day(2), day(5), {
+      pxPerMinute: 1,
+      nonWorkingDays: [0, 6],
+      collapseWeekends: true,
+      collapsedGapPx: 8,
+    })
+    const collapsed = axis.segments.filter((s) => s.kind === 'collapsed')
+    // Sat + Sun are contiguous non-working, so they coalesce to ONE 8px gap.
+    expect(collapsed).toHaveLength(1)
+    expect(collapsed[0]!.px).toBe(8)
+    expect(collapsed[0]!.start.getDate()).toBe(3) // Sat
+    expect(collapsed[0]!.end.getDate()).toBe(5) // through to Mon 00:00
+    // Fri (full day) + Mon-partial working stays full width.
+    const working = axis.segments.filter((s) => s.kind === 'working')
+    expect(working.reduce((sum, s) => sum + s.px, 0)).toBe(1440) // Fri = 1440px working (24h, no business hours)
+  })
+})
+
+describe('buildAxis - piecewise mapping across a collapsed gap', () => {
+  it('maps times on either side of a gap to the right x', () => {
+    const axis = buildAxis(day(5), day(7), {
+      pxPerMinute: 1,
+      businessHours: { start: 9, end: 17 },
+      collapseNonWorking: true,
+      collapsedGapPx: 10,
+    })
+    // End of day 5 work (17:00) sits at leading-gap + 480 working px.
+    const lead = axis.segments[0]!.px // leading collapsed gap (00:00-09:00)
+    expect(timeToX(day(5, 17), axis)).toBe(lead + 480)
+    // Start of day 6 work (09:00) sits one more gap past that.
+    expect(timeToX(day(6, 9), axis)).toBe(lead + 480 + 10)
+  })
+
+  it('round-trips a working-time point through x and back', () => {
+    const axis = buildAxis(day(5), day(7), {
+      pxPerMinute: 1,
+      businessHours: { start: 9, end: 17 },
+      collapseNonWorking: true,
+      collapsedGapPx: 10,
+    })
+    const t = day(6, 13)
+    expect(xToTime(timeToX(t, axis), axis).getTime()).toBe(t.getTime())
+  })
+})
+
+describe('resolveZoom', () => {
+  it('passes a ZoomLevel through and computes pxPerMinute', () => {
+    const level = zoomPresets.find((z) => z.id === 'hour')!
+    const r = resolveZoom(level)
+    expect(r.level.id).toBe('hour')
+    expect(r.pxPerMinute).toBeCloseTo(level.pxPerTick / level.tickMinutes)
+  })
+  it('treats a number as a clamped ladder index', () => {
+    expect(resolveZoom(0).level).toBe(zoomPresets[0])
+    expect(resolveZoom(999).level).toBe(zoomPresets[zoomPresets.length - 1])
+    expect(resolveZoom(-5).level).toBe(zoomPresets[0])
+  })
+})

package/src/scheduler-axis.ts

@@ -0,0 +1,238 @@
+/**
+ * scheduler-axis - the pure core behind Scheduler Pro's *non-working-time
+ * collapse* and *continuous zoom*. No Svelte, no DOM.
+ *
+ * Instead of a single linear time<->pixel scale, the timeline axis becomes a
+ * PIECEWISE map: working spans keep a full pixel width (`pxPerMinute`), while
+ * non-working spans (nights / weekends) collapse to a thin fixed-width gap (or
+ * are omitted). {@link buildAxis} produces the ordered segments; {@link timeToX}
+ * / {@link xToTime} map across them. The renderer routes all event positioning
+ * and drag snapping through these so a collapsed axis stays consistent.
+ *
+ * Callers supply the range + working definition; this file never reads the clock.
+ */
+
+const MS_MIN = 60_000
+const MS_DAY = 86_400_000
+
+export type AxisSegmentKind = 'working' | 'break' | 'collapsed'
+
+/** One contiguous stretch of the axis with a resolved pixel width + offset. */
+export type AxisSegment = {
+  start: Date
+  end: Date
+  /** Left offset in px from the axis origin. */
+  x: number
+  /** Rendered width in px (collapsed gaps get a fixed small width). */
+  px: number
+  kind: AxisSegmentKind
+}
+
+export type Axis = {
+  start: Date
+  end: Date
+  segments: AxisSegment[]
+  totalPx: number
+}
+
+export type BuildAxisOptions = {
+  /** Pixel width of one working minute. Default 0.5 (30px/hour). */
+  pxPerMinute?: number
+  /** Business-hours window in hours, e.g. `{ start: 9, end: 17 }`. Omit = 24h working. */
+  businessHours?: { start: number; end: number }
+  /** Weekday numbers (0 = Sun .. 6 = Sat) treated as non-working days. */
+  nonWorkingDays?: ReadonlyArray<number>
+  /** Collapse nights / breaks (time outside business hours) to a gap. */
+  collapseNonWorking?: boolean
+  /** Collapse whole non-working days (weekends) to a gap. */
+  collapseWeekends?: boolean
+  /** Width (px) of a collapsed gap marker. Default 12; 0 omits it entirely. */
+  collapsedGapPx?: number
+}
+
+/** True when `weekday` is a non-working day. */
+function isNonWorkingDay(weekday: number, days: ReadonlyArray<number> | undefined): boolean {
+  return !!days && days.includes(weekday)
+}
+
+/**
+ * The working `[startMs, endMs)` intervals for the local day beginning at
+ * `dayStart`, from `businessHours` (or the whole day when omitted). Empty when the
+ * day is a non-working day.
+ */
+function workingSpansForDay(
+  dayStart: Date,
+  bh: { start: number; end: number } | undefined,
+  nonWorkingDays: ReadonlyArray<number> | undefined,
+): Array<[number, number]> {
+  if (isNonWorkingDay(dayStart.getDay(), nonWorkingDays)) return []
+  const base = dayStart.getTime()
+  if (!bh) return [[base, base + MS_DAY]]
+  const s = base + bh.start * 60 * MS_MIN
+  const e = base + bh.end * 60 * MS_MIN
+  return e > s ? [[s, e]] : []
+}
+
+/**
+ * Build the piecewise axis over `[rangeStart, rangeEnd]`. Walks day by day,
+ * emitting `working` segments (full width) interleaved with `break` (outside
+ * business hours) and whole non-working-day segments. A non-working segment is
+ * rendered `collapsed` (fixed gap px) when the matching collapse flag is on, else
+ * kept at full width with kind `break`.
+ */
+export function buildAxis(rangeStart: Date, rangeEnd: Date, opts: BuildAxisOptions = {}): Axis {
+  const pxPerMinute = opts.pxPerMinute ?? 0.5
+  const gapPx = opts.collapsedGapPx ?? 12
+  const pxOfMs = (ms: number) => (ms / MS_MIN) * pxPerMinute
+
+  // Collect all working spans across the range, clipped to it.
+  const rangeS = rangeStart.getTime()
+  const rangeE = rangeEnd.getTime()
+  const working: Array<[number, number]> = []
+  let day = new Date(rangeStart.getFullYear(), rangeStart.getMonth(), rangeStart.getDate())
+  // Guard: never loop forever; ranges are bounded (days count).
+  let guard = 0
+  while (day.getTime() < rangeE && guard++ < 4000) {
+    for (const [s, e] of workingSpansForDay(day, opts.businessHours, opts.nonWorkingDays)) {
+      const cs = Math.max(s, rangeS)
+      const ce = Math.min(e, rangeE)
+      if (ce > cs) working.push([cs, ce])
+    }
+    day = new Date(day.getTime() + MS_DAY)
+  }
+  working.sort((a, b) => a[0] - b[0])
+
+  // Weave working spans with the non-working gaps between them (and the edges).
+  // Build raw segments (x assigned in a finalize pass so we can coalesce first).
+  type Raw = { start: number; end: number; px: number; kind: AxisSegmentKind }
+  const raw: Raw[] = []
+  let cursor = rangeS
+  const pushSegment = (s: number, e: number, kind: AxisSegmentKind) => {
+    if (e <= s) return
+    if (kind === 'working') {
+      raw.push({ start: s, end: e, px: pxOfMs(e - s), kind })
+      return
+    }
+    // non-working: split into per-day pieces so a whole non-working DAY (weekend)
+    // collapses per `collapseWeekends` while a night / break collapses per
+    // `collapseNonWorking`. Consecutive collapsed pieces are merged below.
+    let a = s
+    while (a < e) {
+      const d = new Date(a)
+      const dayStart = new Date(d.getFullYear(), d.getMonth(), d.getDate())
+      const b = Math.min(e, dayStart.getTime() + MS_DAY)
+      const wholeDayOff = isNonWorkingDay(dayStart.getDay(), opts.nonWorkingDays)
+      const collapse = wholeDayOff ? opts.collapseWeekends : opts.collapseNonWorking
+      if (collapse) raw.push({ start: a, end: b, px: gapPx > 0 ? gapPx : 0, kind: 'collapsed' })
+      else raw.push({ start: a, end: b, px: pxOfMs(b - a), kind: 'break' })
+      a = b
+    }
+  }
+
+  for (const [ws, we] of working) {
+    if (ws > cursor) pushSegment(cursor, ws, 'break') // non-working gap before this span
+    pushSegment(ws, we, 'working')
+    cursor = we
+  }
+  if (cursor < rangeE) pushSegment(cursor, rangeE, 'break') // trailing non-working tail
+
+  // Coalesce consecutive collapsed pieces into one gap marker (a single collapsed
+  // stretch renders as one "gap" of `gapPx`, not one per calendar day), then
+  // assign cumulative x offsets.
+  const segments: AxisSegment[] = []
+  let x = 0
+  for (const r of raw) {
+    const prev = segments[segments.length - 1]
+    if (r.kind === 'collapsed' && prev && prev.kind === 'collapsed') {
+      prev.end = new Date(r.end) // extend the existing gap; px stays fixed
+      continue
+    }
+    segments.push({ start: new Date(r.start), end: new Date(r.end), x, px: r.px, kind: r.kind })
+    x += r.px
+  }
+
+  return { start: rangeStart, end: rangeEnd, segments, totalPx: x }
+}
+
+/** Find the segment containing `t` (by time), or null when outside the axis. */
+function segmentAt(axis: Axis, t: number): AxisSegment | null {
+  for (const seg of axis.segments) {
+    if (t >= seg.start.getTime() && t < seg.end.getTime()) return seg
+  }
+  // Exact end-of-axis maps to the last segment's trailing edge.
+  const last = axis.segments[axis.segments.length - 1]
+  if (last && t === last.end.getTime()) return last
+  return null
+}
+
+/** Map a time to an x offset (px) across the piecewise axis. Clamps to [0,totalPx]. */
+export function timeToX(date: Date, axis: Axis): number {
+  const t = date.getTime()
+  if (t <= axis.start.getTime()) return 0
+  if (t >= axis.end.getTime()) return axis.totalPx
+  const seg = segmentAt(axis, t)
+  if (!seg) return 0
+  const span = seg.end.getTime() - seg.start.getTime()
+  const frac = span > 0 ? (t - seg.start.getTime()) / span : 0
+  return seg.x + frac * seg.px
+}
+
+/** Map an x offset (px) back to a time across the piecewise axis. */
+export function xToTime(x: number, axis: Axis): Date {
+  if (x <= 0) return new Date(axis.start.getTime())
+  if (x >= axis.totalPx) return new Date(axis.end.getTime())
+  for (const seg of axis.segments) {
+    if (x >= seg.x && x < seg.x + seg.px) {
+      const span = seg.end.getTime() - seg.start.getTime()
+      const frac = seg.px > 0 ? (x - seg.x) / seg.px : 0
+      return new Date(seg.start.getTime() + frac * span)
+    }
+  }
+  return new Date(axis.end.getTime())
+}
+
+// --- zoom -------------------------------------------------------------------
+
+export type ZoomMajorUnit = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+/** One zoom preset: tick size + pixel density + the coarser grouping unit. */
+export type ZoomLevel = {
+  id: string
+  label: string
+  /** Minutes per minor tick. */
+  tickMinutes: number
+  /** Pixel width of one minor tick. */
+  pxPerTick: number
+  majorUnit: ZoomMajorUnit
+}
+
+/** The built-in zoom ladder, most zoomed-in first (minute detail -> months). */
+export const zoomPresets: ZoomLevel[] = [
+  { id: '5min', label: '5 min', tickMinutes: 5, pxPerTick: 24, majorUnit: 'hour' },
+  { id: '15min', label: '15 min', tickMinutes: 15, pxPerTick: 30, majorUnit: 'hour' },
+  { id: '30min', label: '30 min', tickMinutes: 30, pxPerTick: 40, majorUnit: 'day' },
+  { id: 'hour', label: 'Hourly', tickMinutes: 60, pxPerTick: 50, majorUnit: 'day' },
+  { id: '3hour', label: '3 hours', tickMinutes: 180, pxPerTick: 44, majorUnit: 'day' },
+  { id: 'day', label: 'Daily', tickMinutes: 1440, pxPerTick: 64, majorUnit: 'week' },
+  { id: 'week', label: 'Weekly', tickMinutes: 10_080, pxPerTick: 80, majorUnit: 'month' },
+  { id: 'month', label: 'Monthly', tickMinutes: 43_200, pxPerTick: 72, majorUnit: 'quarter' },
+]
+
+/**
+ * Resolve `zoom` to a {@link ZoomLevel}. A `ZoomLevel` passes through; a number is
+ * an index into `ladder` (clamped). Returns the pixel density too via
+ * `pxPerMinute = pxPerTick / tickMinutes` (use it as `buildAxis`'s `pxPerMinute`).
+ */
+export function resolveZoom(
+  zoom: number | ZoomLevel,
+  ladder: ReadonlyArray<ZoomLevel> = zoomPresets,
+): { level: ZoomLevel; pxPerMinute: number } {
+  let level: ZoomLevel
+  if (typeof zoom === 'number') {
+    const i = Math.max(0, Math.min(ladder.length - 1, Math.round(zoom)))
+    level = ladder[i]!
+  } else {
+    level = zoom
+  }
+  return { level, pxPerMinute: level.pxPerTick / level.tickMinutes }
+}

package/src/scheduler-booking.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { afterLead, respectsBuffer, withinDurationBounds, type BusyEvent } from './scheduler-booking'
+
+const D = (h: number, m = 0) => new Date(2026, 0, 5, h, m, 0, 0)
+const ev = (key: string, sh: number, eh: number, data?: unknown): BusyEvent => ({ key, start: D(sh), end: D(eh), data })
+
+describe('respectsBuffer', () => {
+  const others = [ev('a', 9, 10), ev('b', 13, 14)]
+
+  it('passes when the gap before and after is large enough', () => {
+    // book 11:00-12:00: 60 min after a(ends 10), 60 min before b(starts 13) -> ok for 30/30 buffers
+    expect(respectsBuffer(D(11), D(12), others, 30, 30)).toBe(true)
+  })
+  it('rejects a direct overlap', () => {
+    expect(respectsBuffer(D(9, 30), D(10, 30), others, 0, 0)).toBe(false)
+  })
+  it('rejects when the gap before is too small', () => {
+    // book 10:15-11:00: only 15 min after a(ends 10); need 30 -> reject
+    expect(respectsBuffer(D(10, 15), D(11), others, 30, 30)).toBe(false)
+  })
+  it('rejects when the gap after is too small', () => {
+    // book 12:00-12:45: only 15 min before b(starts 13); need 30 -> reject
+    expect(respectsBuffer(D(12), D(12, 45), others, 30, 30)).toBe(false)
+  })
+  it('excludes the moving booking by key', () => {
+    const set = [ev('self', 11, 12), ev('a', 9, 10)]
+    // moving self to 10:00-10:30 would clash with its own old slot unless excluded
+    expect(respectsBuffer(D(10), D(10, 30), set, 0, 0, 'self')).toBe(true)
+  })
+  it('supports a per-neighbour gap (travel time by location)', () => {
+    const jobs = [ev('a', 9, 10, 'north'), ev('b', 13, 14, 'south')]
+    const travel = (n: BusyEvent) => (n.data === 'south' ? 90 : 20) // 90 min to/from south
+    // book 11:00-12:00: 60 min before b(south) but travel needs 90 -> reject
+    expect(respectsBuffer(D(11), D(12), jobs, travel, travel)).toBe(false)
+    // 11:00-11:30 leaves 90 before b -> ok
+    expect(respectsBuffer(D(11), D(11, 30), jobs, travel, travel)).toBe(true)
+  })
+})
+
+describe('withinDurationBounds', () => {
+  it('enforces min and max minutes', () => {
+    expect(withinDurationBounds(D(9), D(9, 30), 30, 90)).toBe(true)
+    expect(withinDurationBounds(D(9), D(9, 15), 30, 90)).toBe(false) // too short
+    expect(withinDurationBounds(D(9), D(11), 30, 90)).toBe(false) // too long
+  })
+  it('treats undefined bounds as unbounded', () => {
+    expect(withinDurationBounds(D(9), D(15), undefined, undefined)).toBe(true)
+  })
+})
+
+describe('afterLead', () => {
+  it('requires the start to be at least leadMin after now', () => {
+    const now = D(10)
+    expect(afterLead(D(12), now, 120)).toBe(true) // exactly 120 min ahead
+    expect(afterLead(D(11), now, 120)).toBe(false) // only 60 min ahead
+  })
+})

package/src/scheduler-booking.ts

@@ -0,0 +1,63 @@
+/**
+ * scheduler-booking - pure booking-rule helpers for Scheduler Pro: buffers /
+ * travel time between bookings, minimum lead time, and duration bounds. No Svelte,
+ * no DOM; the renderer folds these into its `bookingBlocked` guard. Callers supply
+ * "now" (never `Date.now()` here) so the rules stay deterministic + unit-testable.
+ */
+
+const MS_MIN = 60_000
+
+/** A booked interval on a resource, keyed for exclusion, carrying optional data
+ *  (e.g. a location) so a per-neighbour gap function can read it. */
+export type BusyEvent<T = unknown> = { start: Date; end: Date; key: string; data?: T }
+
+/** Minutes of gap required before/after, either a flat number or a function of the
+ *  neighbouring booking (used for travel time between locations). */
+export type GapMin<T = unknown> = number | ((neighbour: BusyEvent<T>) => number)
+
+const gapOf = <T>(g: GapMin<T>, ev: BusyEvent<T>): number => (typeof g === 'function' ? g(ev) : g)
+
+/**
+ * True when placing `[start, end]` keeps at least the required gap from every other
+ * booking in `events` (same resource): `gapBefore` minutes clear of the previous
+ * booking's end and `gapAfter` minutes clear of the next booking's start. A direct
+ * overlap always fails. `gapBefore` / `gapAfter` may be functions of the neighbour
+ * for travel time. `excludeKey` skips the booking being moved.
+ */
+export function respectsBuffer<T = unknown>(
+  start: Date,
+  end: Date,
+  events: ReadonlyArray<BusyEvent<T>>,
+  gapBefore: GapMin<T>,
+  gapAfter: GapMin<T>,
+  excludeKey?: string,
+): boolean {
+  const s = start.getTime()
+  const e = end.getTime()
+  for (const ev of events) {
+    if (ev.key === excludeKey) continue
+    const es = ev.start.getTime()
+    const ee = ev.end.getTime()
+    if (s < ee && e > es) return false // direct overlap
+    if (ee <= s) {
+      if (s - ee < gapOf(gapBefore, ev) * MS_MIN) return false
+    } else if (es >= e) {
+      if (es - e < gapOf(gapAfter, ev) * MS_MIN) return false
+    }
+  }
+  return true
+}
+
+/** True when the booking's duration is within `[minMin, maxMin]` (either bound may
+ *  be undefined = unbounded). */
+export function withinDurationBounds(start: Date, end: Date, minMin?: number, maxMin?: number): boolean {
+  const dur = (end.getTime() - start.getTime()) / MS_MIN
+  if (minMin != null && dur < minMin - 1e-9) return false
+  if (maxMin != null && dur > maxMin + 1e-9) return false
+  return true
+}
+
+/** True when the booking starts at least `leadMin` minutes after `now` (min notice). */
+export function afterLead(start: Date, now: Date, leadMin: number): boolean {
+  return start.getTime() >= now.getTime() + leadMin * MS_MIN
+}

package/src/scheduler-config.ts

@@ -0,0 +1,179 @@
+/**
+ * SchedulerProConfig - the Enterprise ("Scheduler Pro") superset of the free grid
+ * {@link SchedulerConfig}. The base scheduler prop + its config type ship in
+ * `@svgrid/grid`; the Pro renderer (SvGridScheduler) reads these extra fields at
+ * runtime (the renderer is registered untyped, so nothing in the free grid needs
+ * to know about them). Consumers using Pro features type their config as
+ * `SchedulerProConfig` - it is structurally assignable to the `scheduler` prop.
+ *
+ * All three feature waves live here:
+ *   - Wave A: event dependencies + auto-reschedule
+ *   - Wave B: multi-assignment + resource histogram + column summary
+ *   - Wave C: non-working-time collapse + continuous zoom
+ */
+import type {
+  SchedulerConfig,
+  SchedulerResource,
+  TableFeatures,
+  RowData,
+} from '@svgrid/grid'
+import type { SchedulerDependency } from './scheduler-dependencies'
+import type { SchedulerAssignment } from './scheduler-assignments'
+import type { ColumnReducer } from './scheduler-summary'
+import type { ZoomLevel } from './scheduler-axis'
+import type { SchedulerResourceGroup } from './scheduler-resource-tree'
+
+export type SchedulerProConfig<
+  TFeatures extends TableFeatures = TableFeatures,
+  TData extends RowData = RowData,
+> = SchedulerConfig<TFeatures, TData> & {
+  // --- Wave A: dependencies + auto-reschedule --------------------------------
+  /**
+   * Event dependency links (predecessor -> successor). `from` / `to` are row ids
+   * (the grid's `getRowId`). Draw arrows between linked events and, with
+   * `autoReschedule`, push successors forward when a predecessor moves.
+   */
+  dependencies?: ReadonlyArray<SchedulerDependency>;
+  /**
+   * Per-row field holding this row's dependency links (as `SchedulerDependency[]`
+   * or a `to`-key list). An alternative to the flat `dependencies` list.
+   */
+  dependencyField?: keyof TData & string;
+  /**
+   * Cascade successors forward on move / resize to keep every link legal.
+   * Defaults to `true` when any dependency is present.
+   */
+  autoReschedule?: boolean;
+  /** When cascading, skip non-working intervals (business hours / shifts). */
+  dependencyRespectWorkingTime?: boolean;
+  /** Fired with the cascaded shifts after a move / resize (never mutates rows). */
+  onDependenciesChange?: (moves: Array<{ id: string; start: Date; end: Date }>) => void;
+  /** Fired when the user draws a new link (drag from one event edge onto another). */
+  onDependencyAdd?: (dep: SchedulerDependency) => void;
+  /** Fired when the user removes a link (arrow context menu). */
+  onDependencyRemove?: (id: string) => void;
+
+  // --- Grouped / tree resources (timeline) -----------------------------------
+  /**
+   * Group the timeline's resource rows into a collapsible tree. `resourceGroups`
+   * defines the group nodes (nest via `parentId`); `resourceGroupOf` maps each
+   * resource to its group id. Resources with no / unknown group trail ungrouped.
+   */
+  resourceGroups?: ReadonlyArray<SchedulerResourceGroup>;
+  resourceGroupOf?: (resource: SchedulerResource) => string | undefined;
+  /** Allow collapsing group headers (default true when `resourceGroups` is set). */
+  collapsibleGroups?: boolean;
+  /** localStorage key to persist which groups are collapsed. */
+  groupPersistKey?: string;
+
+  // --- Eligibility / skill matching (a booking rule) --------------------------
+  /**
+   * Restrict which events may be placed on which resources (provider matching,
+   * room type, technician skills). Return `false` and a drag / resize / create
+   * onto that resource is rejected + a "Not eligible" flash. The most flexible
+   * form; takes precedence over the declarative `requiresField` shortcut.
+   */
+  eligible?: (event: TData, resource: SchedulerResource) => boolean;
+  /**
+   * Declarative shortcut: a per-event field holding the required skill tag(s).
+   * An event is eligible for a resource only if the resource's skills (via
+   * `resourceSkillsOf`, or a `skills` array on the resource) include every tag.
+   */
+  requiresField?: keyof TData & string;
+  /** Where a resource's skill tags come from (default: a `skills` array on it). */
+  resourceSkillsOf?: (resource: SchedulerResource) => ReadonlyArray<string> | undefined;
+
+  // --- Booking-rule depth (buffers / lead time / duration / travel) ----------
+  /** Required clear minutes before / after each booking on a resource (a flat
+   *  number, or a function of the event). A move / create that breaks it is rejected. */
+  bufferBeforeMin?: number | ((event: TData) => number);
+  bufferAfterMin?: number | ((event: TData) => number);
+  /** Minimum notice: a booking must start at least this many minutes after "now". */
+  minLeadMin?: number;
+  /** Min / max booking duration in minutes. */
+  minDurationMin?: number;
+  maxDurationMin?: number;
+  /** Travel time (minutes) required between two consecutive bookings on the same
+   *  resource - widens the buffer by the trip between their locations. */
+  travelTimeOf?: (from: TData, to: TData) => number;
+
+  // --- Bookable slots / find-a-time (Calendly-style) --------------------------
+  /**
+   * Show the open, bookable slots of a fixed duration per resource in the Day
+   * timeline - the free time left after existing bookings, buffers and lead time.
+   * Clicking a slot books it (via `onSlotPick`, else `onEventAdd`).
+   */
+  bookable?: { durationMin: number; stepMin?: number };
+  /** Fired when a bookable slot is clicked. Falls back to `onEventAdd`. */
+  onSlotPick?: (start: Date, end: Date, resourceId?: string) => void;
+
+  // --- Multi-calendar overlay -------------------------------------------------
+  /**
+   * Overlay several calendars, each colour-coded and toggleable from a legend.
+   * Events map to a calendar via `calendarField`; a calendar's colour becomes the
+   * event's default (unless `colorField` overrides), and hiding a calendar filters
+   * its events out of every view.
+   */
+  calendars?: ReadonlyArray<{ id: string; title: string; color?: string; hidden?: boolean }>;
+  calendarField?: keyof TData & string;
+
+  // --- Free/busy availability (for find-a-time) -------------------------------
+  /**
+   * External busy intervals to shade on a resource's timeline row - times it is
+   * unavailable that aren't events in this scheduler (its own calendar). Combine
+   * with the exported `commonFree` helper to find a meeting time across attendees.
+   */
+  freeBusyOf?: (resource: SchedulerResource) => ReadonlyArray<{ start: Date; end: Date }>;
+
+  // --- Wave B: multi-assignment + summaries ----------------------------------
+  /**
+   * Many-to-many event <-> resource assignments. When set, one event can appear
+   * under several resources; drives the timeline / resource-column bucketing
+   * instead of the single `resourceField`.
+   */
+  assignments?: ReadonlyArray<SchedulerAssignment>;
+  /** Per-row field holding an array of resource ids (alt to the flat `assignments`). */
+  assignmentField?: keyof TData & string;
+  /**
+   * Show a per-resource utilization histogram band (timeline views). `true` uses
+   * defaults; the object form sets a capacity field + band height (px).
+   */
+  resourceHistogram?: boolean | { capacityField?: keyof SchedulerResource & string; height?: number };
+  /**
+   * Tint each resource row's BACKGROUND by load per time-bucket (a utilization
+   * heatmap) - distinct from the histogram bar strip. `true` uses defaults; the
+   * object form sets the capacity field (over that = a hot / red cell).
+   */
+  utilizationHeatmap?: boolean | { capacityField?: keyof SchedulerResource & string };
+  /**
+   * A per-time-column summary strip (counts / sums / a custom reducer) aligned to
+   * the axis. `false` (default) hides it.
+   */
+  columnSummary?: false | {
+    reducer: ColumnReducer<TData>;
+    label?: string;
+    position?: 'top' | 'bottom';
+  };
+  /** Fired when an event is dragged from one resource column to another (reassign). */
+  onAssignmentChange?: (change: { eventId: string; from?: string; to?: string }) => void;
+
+  // --- Wave C: axis collapse + zoom ------------------------------------------
+  /** Compress non-working hours out of the time axis (nights collapse to a gap). */
+  collapseNonWorking?: boolean;
+  /** Compress `nonWorkingDays` (e.g. weekends) out of the timeline axis. */
+  collapseWeekends?: boolean;
+  /** Width (px) of a collapsed-gap marker. Default 12; `0` omits it entirely. */
+  collapsedGapPx?: number;
+  /**
+   * Minimum width (px) of one timeline minor tick (a day in Week / Month). Widens
+   * the timeline - and scrolls it horizontally - so narrow, sub-day events (e.g.
+   * hour-scale shifts) have room for their label. Overrides the per-view default.
+   */
+  timelineTickMinWidth?: number;
+  /** Continuous zoom preset - supersedes `slotSizes` when set (minute .. year). */
+  zoom?: number | ZoomLevel;
+  /** Custom zoom-preset ladder (replaces the built-in one). */
+  zoomLevels?: ReadonlyArray<ZoomLevel>;
+  /** Fired when the zoom level changes (slider / wheel). */
+  onZoomChange?: (level: ZoomLevel) => void;
+}