@svgrid/enterprise 2.2.1 → 2.3.1

package/src/scheduler-dependencies.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildDependencyGraph,
+  cascade,
+  hasCycle,
+  requiredStart,
+  topoOrder,
+  violations,
+  type EventTimes,
+  type SchedulerDependency,
+} from './scheduler-dependencies'
+
+// A fixed base day so the tests are deterministic (no Date.now()).
+const D = (h: number, m = 0) => new Date(2026, 0, 5, h, m, 0, 0)
+const ev = (startH: number, endH: number): EventTimes => ({ start: D(startH), end: D(endH) })
+const times = (m: Record<string, EventTimes>) => new Map(Object.entries(m))
+
+describe('requiredStart', () => {
+  const pred = ev(9, 11) // 09:00 - 11:00
+  const durMs = 60 * 60_000 // 1h successor
+
+  it('FS: successor starts at predecessor end', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'FS' }, durMs)).toEqual(D(11))
+  })
+  it('FS honours lag (minutes)', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'FS', lag: 30 }, durMs)).toEqual(D(11, 30))
+  })
+  it('FS honours negative lag (lead)', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'FS', lag: -60 }, durMs)).toEqual(D(10))
+  })
+  it('SS: successor starts with predecessor start', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'SS' }, durMs)).toEqual(D(9))
+  })
+  it('FF: successor ENDS at predecessor end (start = end - duration)', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'FF' }, durMs)).toEqual(D(10))
+  })
+  it('SF: successor ENDS at predecessor start', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b', type: 'SF' }, durMs)).toEqual(D(8))
+  })
+  it('defaults to FS when type omitted', () => {
+    expect(requiredStart(pred, { id: 'd', from: 'a', to: 'b' }, durMs)).toEqual(D(11))
+  })
+})
+
+describe('buildDependencyGraph', () => {
+  it('indexes successors, predecessors and nodes; drops malformed/self links', () => {
+    const deps: SchedulerDependency[] = [
+      { id: '1', from: 'a', to: 'b' },
+      { id: '2', from: 'b', to: 'c' },
+      { id: '3', from: 'x', to: 'x' }, // self - dropped
+      { id: '4', from: '', to: 'z' }, // malformed - dropped
+    ]
+    const g = buildDependencyGraph(deps)
+    expect(g.deps).toHaveLength(2)
+    expect(g.succ.get('a')?.[0]?.to).toBe('b')
+    expect(g.pred.get('c')?.[0]?.from).toBe('b')
+    expect([...g.nodes].sort()).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('topoOrder / hasCycle', () => {
+  it('orders predecessors before successors', () => {
+    const g = buildDependencyGraph([
+      { id: '1', from: 'a', to: 'b' },
+      { id: '2', from: 'b', to: 'c' },
+    ])
+    const { order, cyclicIds } = topoOrder(g)
+    expect(cyclicIds.size).toBe(0)
+    expect(order.indexOf('a')).toBeLessThan(order.indexOf('b'))
+    expect(order.indexOf('b')).toBeLessThan(order.indexOf('c'))
+  })
+  it('flags cyclic links and reports hasCycle', () => {
+    const deps: SchedulerDependency[] = [
+      { id: '1', from: 'a', to: 'b' },
+      { id: '2', from: 'b', to: 'a' },
+    ]
+    expect(hasCycle(deps)).toBe(true)
+    expect(topoOrder(buildDependencyGraph(deps)).cyclicIds.size).toBeGreaterThan(0)
+  })
+})
+
+describe('cascade', () => {
+  it('pushes an FS successor forward to the predecessor end', () => {
+    const t = times({ a: ev(9, 11), b: ev(9, 10) }) // b overlaps a - illegal
+    const out = cascade(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }])
+    expect(out.get('b')).toEqual({ start: D(11), end: D(12) }) // duration (1h) preserved
+    expect(out.has('a')).toBe(false) // predecessor untouched
+  })
+
+  it('never pulls a successor earlier when already legal', () => {
+    const t = times({ a: ev(9, 10), b: ev(14, 15) }) // b already after a
+    const out = cascade(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }])
+    expect(out.size).toBe(0)
+  })
+
+  it('cascades multi-hop chains in one pass', () => {
+    const t = times({ a: ev(9, 11), b: ev(9, 10), c: ev(9, 10) })
+    const out = cascade(t, [
+      { id: '1', from: 'a', to: 'b', type: 'FS' },
+      { id: '2', from: 'b', to: 'c', type: 'FS' },
+    ])
+    expect(out.get('b')).toEqual({ start: D(11), end: D(12) })
+    expect(out.get('c')).toEqual({ start: D(12), end: D(13) })
+  })
+
+  it('diamond: a successor with two predecessors takes the later constraint', () => {
+    // a ends 11, b ends 13; both feed d. d must start at max(11,13) = 13.
+    const t = times({ a: ev(9, 11), b: ev(9, 13), d: ev(9, 10) })
+    const out = cascade(t, [
+      { id: '1', from: 'a', to: 'd', type: 'FS' },
+      { id: '2', from: 'b', to: 'd', type: 'FS' },
+    ])
+    expect(out.get('d')).toEqual({ start: D(13), end: D(14) })
+  })
+
+  it('respects lag when cascading', () => {
+    const t = times({ a: ev(9, 11), b: ev(9, 10) })
+    const out = cascade(t, [{ id: '1', from: 'a', to: 'b', type: 'FS', lag: 15 }])
+    expect(out.get('b')).toEqual({ start: D(11, 15), end: D(12, 15) })
+  })
+
+  it('applies the snapForward hook (working-time skip)', () => {
+    // Snap any start at/after 12:00 forward to 13:00 (a lunch break).
+    const snapForward = (s: Date) => (s.getHours() === 12 ? new Date(2026, 0, 5, 13, 0) : s)
+    const t = times({ a: ev(10, 12), b: ev(9, 10) })
+    const out = cascade(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }], { snapForward })
+    expect(out.get('b')?.start).toEqual(new Date(2026, 0, 5, 13, 0))
+    expect(out.get('b')?.end).toEqual(new Date(2026, 0, 5, 14, 0)) // duration preserved past the break
+  })
+
+  it('ignores cyclic links without looping', () => {
+    const t = times({ a: ev(9, 11), b: ev(9, 10) })
+    const out = cascade(t, [
+      { id: '1', from: 'a', to: 'b' },
+      { id: '2', from: 'b', to: 'a' }, // cycle - both ignored
+    ])
+    expect(out.size).toBe(0)
+  })
+})
+
+describe('violations', () => {
+  it('reports a link whose successor starts too early', () => {
+    const t = times({ a: ev(9, 11), b: ev(10, 11) }) // b starts before a ends
+    const bad = violations(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }])
+    expect(bad.map((d) => d.id)).toEqual(['1'])
+  })
+  it('reports nothing when the link is satisfied', () => {
+    const t = times({ a: ev(9, 11), b: ev(11, 12) })
+    expect(violations(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }])).toHaveLength(0)
+  })
+  it('treats exact touching (start == pred end) as legal', () => {
+    const t = times({ a: ev(9, 11), b: ev(11, 12) })
+    expect(violations(t, [{ id: '1', from: 'a', to: 'b', type: 'FS' }])).toHaveLength(0)
+  })
+})

package/src/scheduler-dependencies.ts

@@ -0,0 +1,223 @@
+/**
+ * scheduler-dependencies - the pure, framework-free core behind the Scheduler Pro
+ * *event dependencies* feature (predecessor / successor links + auto-reschedule).
+ * No Svelte, no DOM: just graph + date math over the native `Date`, so every rule
+ * here is unit-tested directly (mirrors scheduler-model.ts in @svgrid/grid).
+ *
+ * A dependency links a predecessor event to a successor with one of the four
+ * classic types (FS / SS / FF / SF) and an optional `lag` (minutes; negative = a
+ * lead). When a predecessor moves or resizes, {@link cascade} pushes successors
+ * forward just enough to keep every link legal, preserving each event's duration.
+ * Cascading never pulls an event earlier - it only resolves violations forward,
+ * the standard auto-schedule behaviour.
+ *
+ * Deliberately avoids the arg-less `new Date()` / `Date.now()` - callers pass the
+ * current event times in; working-time skipping is injected as a `snapForward`
+ * hook so this file needs no knowledge of shifts / business hours.
+ */
+
+/** The four dependency kinds. `FS` (finish-to-start) is the default. */
+export type DependencyType = 'FS' | 'SS' | 'FF' | 'SF'
+
+/** A link from a predecessor event (`from`) to a successor (`to`). Keys are row
+ *  keys (the scheduler's `getRowId`). `lag` is minutes; negative = a lead. */
+export type SchedulerDependency = {
+  id: string
+  from: string
+  to: string
+  type?: DependencyType
+  lag?: number
+}
+
+/** The resolved [start, end) of one event, keyed by row key in a time map. */
+export type EventTimes = { start: Date; end: Date }
+
+const MS_MIN = 60_000
+/** Sub-second slack so exact-touching links (successor.start == pred.end) are legal. */
+const EPS_MS = 1_000
+
+/** Indexed view of a dependency set: successors by predecessor, predecessors by
+ *  successor, and lookup by id. Built once, reused by cascade / violations. */
+export type DependencyGraph = {
+  deps: SchedulerDependency[]
+  /** predecessor key -> outgoing links */
+  succ: Map<string, SchedulerDependency[]>
+  /** successor key -> incoming links */
+  pred: Map<string, SchedulerDependency[]>
+  byId: Map<string, SchedulerDependency>
+  /** every key that appears as a `from` or `to`. */
+  nodes: Set<string>
+}
+
+/** Build the adjacency indexes for `deps`. */
+export function buildDependencyGraph(
+  deps: ReadonlyArray<SchedulerDependency>,
+): DependencyGraph {
+  const succ = new Map<string, SchedulerDependency[]>()
+  const pred = new Map<string, SchedulerDependency[]>()
+  const byId = new Map<string, SchedulerDependency>()
+  const nodes = new Set<string>()
+  const list: SchedulerDependency[] = []
+  for (const d of deps) {
+    if (!d || !d.from || !d.to || d.from === d.to) continue // ignore malformed / self links
+    list.push(d)
+    byId.set(d.id, d)
+    nodes.add(d.from)
+    nodes.add(d.to)
+    ;(succ.get(d.from) ?? succ.set(d.from, []).get(d.from)!).push(d)
+    ;(pred.get(d.to) ?? pred.set(d.to, []).get(d.to)!).push(d)
+  }
+  return { deps: list, succ, pred, byId, nodes }
+}
+
+/**
+ * Kahn topological order of the graph's nodes. Returns `{ order, cyclicIds }`:
+ * `order` is a safe processing order for the acyclic part (predecessors before
+ * successors); `cyclicIds` are the ids of links that could not be ordered because
+ * they take part in a cycle (cascade ignores them so it can never loop).
+ */
+export function topoOrder(graph: DependencyGraph): { order: string[]; cyclicIds: Set<string> } {
+  const indeg = new Map<string, number>()
+  for (const n of graph.nodes) indeg.set(n, 0)
+  for (const d of graph.deps) indeg.set(d.to, (indeg.get(d.to) ?? 0) + 1)
+
+  const queue: string[] = []
+  for (const [n, deg] of indeg) if (deg === 0) queue.push(n)
+  // Stable: process in insertion order for deterministic output.
+  const order: string[] = []
+  const settled = new Set<string>()
+  while (queue.length) {
+    const n = queue.shift()!
+    order.push(n)
+    settled.add(n)
+    for (const d of graph.succ.get(n) ?? []) {
+      const deg = (indeg.get(d.to) ?? 0) - 1
+      indeg.set(d.to, deg)
+      if (deg === 0) queue.push(d.to)
+    }
+  }
+  // Any node not settled sits inside (or downstream of) a cycle; links whose
+  // successor never settled are the cyclic ones.
+  const cyclicIds = new Set<string>()
+  for (const d of graph.deps) if (!settled.has(d.to)) cyclicIds.add(d.id)
+  return { order, cyclicIds }
+}
+
+/** True when `deps` contain a cycle. */
+export function hasCycle(deps: ReadonlyArray<SchedulerDependency>): boolean {
+  return topoOrder(buildDependencyGraph(deps)).cyclicIds.size > 0
+}
+
+/**
+ * The earliest legal start for the successor of `dep`, given the predecessor's
+ * resolved times and the successor's own `durationMs` (kept constant). Encodes the
+ * FS / SS / FF / SF semantics plus `lag` (minutes).
+ */
+export function requiredStart(
+  predTimes: EventTimes,
+  dep: SchedulerDependency,
+  successorDurationMs: number,
+): Date {
+  const lagMs = (dep.lag ?? 0) * MS_MIN
+  const type = dep.type ?? 'FS'
+  let t: number
+  switch (type) {
+    case 'FS':
+      t = predTimes.end.getTime() + lagMs
+      break
+    case 'SS':
+      t = predTimes.start.getTime() + lagMs
+      break
+    case 'FF':
+      t = predTimes.end.getTime() + lagMs - successorDurationMs
+      break
+    case 'SF':
+      t = predTimes.start.getTime() + lagMs - successorDurationMs
+      break
+  }
+  return new Date(t)
+}
+
+/** Options for {@link cascade}. */
+export type CascadeOptions = {
+  /**
+   * Optional working-time snap: given a proposed start, return the next start that
+   * begins inside working time (the renderer supplies this from the scheduler's
+   * shifts / business hours; omit for calendar-time scheduling).
+   */
+  snapForward?: (start: Date) => Date
+}
+
+/**
+ * Forward-cascade successors so every dependency is satisfied. `times` maps row
+ * key -> current [start,end] (the just-moved predecessor already carries its NEW
+ * time). Processing runs in topological order, so multi-hop chains and diamonds
+ * (two paths into one successor) resolve to the latest required start in a single
+ * pass. Each shifted event keeps its duration. Returns ONLY the events whose times
+ * changed (never the untouched ones, never the moved predecessor itself unless a
+ * link also forces it). Cyclic links are ignored.
+ */
+export function cascade(
+  times: ReadonlyMap<string, EventTimes>,
+  deps: ReadonlyArray<SchedulerDependency>,
+  opts: CascadeOptions = {},
+): Map<string, EventTimes> {
+  const graph = buildDependencyGraph(deps)
+  const { order, cyclicIds } = topoOrder(graph)
+  // Working copy we mutate as we walk downstream.
+  const cur = new Map<string, EventTimes>()
+  for (const [k, v] of times) cur.set(k, { start: v.start, end: v.end })
+
+  const changed = new Map<string, EventTimes>()
+  for (const key of order) {
+    const links = graph.pred.get(key)
+    if (!links || !links.length) continue
+    const self = cur.get(key)
+    if (!self) continue
+    const durationMs = self.end.getTime() - self.start.getTime()
+
+    let minStartMs = self.start.getTime()
+    for (const dep of links) {
+      if (cyclicIds.has(dep.id)) continue
+      const pred = cur.get(dep.from)
+      if (!pred) continue
+      const req = requiredStart(pred, dep, durationMs).getTime()
+      if (req > minStartMs) minStartMs = req
+    }
+    if (minStartMs <= self.start.getTime()) continue // already legal - never pull earlier
+
+    let newStart = new Date(minStartMs)
+    if (opts.snapForward) newStart = opts.snapForward(newStart)
+    const newEnd = new Date(newStart.getTime() + durationMs)
+    const next = { start: newStart, end: newEnd }
+    cur.set(key, next)
+    changed.set(key, next)
+  }
+  return changed
+}
+
+/**
+ * The dependencies currently unsatisfied by `times` (successor starts too early
+ * for the link). Used to paint violation-state arrows. Cyclic links are skipped.
+ */
+export function violations(
+  times: ReadonlyMap<string, EventTimes>,
+  deps: ReadonlyArray<SchedulerDependency>,
+): SchedulerDependency[] {
+  const graph = buildDependencyGraph(deps)
+  const { cyclicIds } = topoOrder(graph)
+  const out: SchedulerDependency[] = []
+  for (const dep of graph.deps) {
+    if (cyclicIds.has(dep.id)) continue
+    const pred = times.get(dep.from)
+    const succ = times.get(dep.to)
+    if (!pred || !succ) continue
+    const durationMs = succ.end.getTime() - succ.start.getTime()
+    const req = requiredStart(pred, dep, durationMs).getTime()
+    // A link on end (FF / SF) constrains the successor's end; compare that edge.
+    const type = dep.type ?? 'FS'
+    const actual = type === 'FF' || type === 'SF' ? succ.end.getTime() - durationMs : succ.start.getTime()
+    if (actual + EPS_MS < req) out.push(dep)
+  }
+  return out
+}

package/src/scheduler-freebusy.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { commonFree, mergeBusy } from './scheduler-freebusy'
+import type { Interval } from './scheduler-slots'
+
+const D = (h: number, m = 0) => new Date(2026, 0, 5, h, m, 0, 0)
+const iv = (sh: number, sm: number, eh: number, em: number): Interval => ({ start: D(sh, sm), end: D(eh, em) })
+const hhmm = (d: Date) => `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+const show = (list: Interval[]) => list.map((s) => `${hhmm(s.start)}-${hhmm(s.end)}`)
+
+describe('mergeBusy', () => {
+  it('unions overlapping busy blocks', () => {
+    expect(show(mergeBusy([iv(9, 0, 10, 0), iv(9, 30, 11, 0)]))).toEqual(['09:00-11:00'])
+  })
+})
+
+describe('commonFree', () => {
+  const day = [D(9, 0), D(17, 0)] as const
+
+  it('finds windows when everyone is free', () => {
+    // A busy 9-10 and 14-15; B busy 11-12. Common free: 10-11, 12-14, 15-17.
+    const busy = [[iv(9, 0, 10, 0), iv(14, 0, 15, 0)], [iv(11, 0, 12, 0)]]
+    expect(show(commonFree(busy, day[0], day[1], 30))).toEqual(['10:00-11:00', '12:00-14:00', '15:00-17:00'])
+  })
+
+  it('drops windows too short for the meeting', () => {
+    // Leaves only 10:00-10:30 free between busy blocks -> a 60-min meeting has none.
+    const busy = [[iv(9, 0, 10, 0)], [iv(10, 30, 17, 0)]]
+    expect(commonFree(busy, day[0], day[1], 60)).toEqual([])
+    expect(show(commonFree(busy, day[0], day[1], 30))).toEqual(['10:00-10:30'])
+  })
+
+  it('treats an attendee with no busy list as fully free', () => {
+    const busy = [[iv(12, 0, 13, 0)], []]
+    expect(show(commonFree(busy, day[0], day[1], 60))).toEqual(['09:00-12:00', '13:00-17:00'])
+  })
+
+  it('returns nothing when the union covers the whole day', () => {
+    const busy = [[iv(9, 0, 13, 0)], [iv(13, 0, 17, 0)]]
+    expect(commonFree(busy, day[0], day[1], 15)).toEqual([])
+  })
+})

package/src/scheduler-freebusy.ts

@@ -0,0 +1,36 @@
+/**
+ * scheduler-freebusy - the pure core behind Scheduler Pro's *free/busy* and
+ * *cross-attendee find-a-time*. No Svelte, no DOM. Merges each attendee's busy
+ * intervals and finds the windows when EVERYONE is free (long enough for a meeting).
+ * Deterministic - the caller supplies all dates. Reuses the interval algebra from
+ * scheduler-slots (`mergeIntervals` / `subtractIntervals`).
+ */
+import { mergeIntervals, subtractIntervals, type Interval } from './scheduler-slots'
+
+export type { Interval }
+
+const MS_MIN = 60_000
+
+/** Union of a set of busy intervals into a sorted, disjoint list (an alias of the
+ *  slots merge, named for the free/busy domain). */
+export function mergeBusy(intervals: ReadonlyArray<Interval>): Interval[] {
+  return mergeIntervals(intervals)
+}
+
+/**
+ * The windows within `[dayStart, dayEnd]` when EVERY attendee is free, each at
+ * least `durationMin` long. `busyByPerson` is one busy list per attendee; a person
+ * with no entry is treated as fully free. The result is the complement of the union
+ * of all busy time, filtered to windows that can fit the meeting.
+ */
+export function commonFree(
+  busyByPerson: ReadonlyArray<ReadonlyArray<Interval>>,
+  dayStart: Date,
+  dayEnd: Date,
+  durationMin: number,
+): Interval[] {
+  const allBusy = mergeIntervals(busyByPerson.flat())
+  const free = subtractIntervals({ start: dayStart, end: dayEnd }, allBusy)
+  const minMs = Math.max(0, durationMin) * MS_MIN
+  return free.filter((f) => f.end.getTime() - f.start.getTime() >= minMs)
+}

package/src/scheduler-heatmap.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { heatCells, heatPeak } from './scheduler-heatmap'
+
+const ticks = [
+  { leftPct: 0, widthPct: 25 },
+  { leftPct: 25, widthPct: 25 },
+  { leftPct: 50, widthPct: 25 },
+  { leftPct: 75, widthPct: 25 },
+]
+
+describe('heatCells', () => {
+  it('scales load to 0..1 intensity against the peak', () => {
+    const cells = heatCells(ticks, [0, 1, 2, 4], 4, 4)
+    expect(cells.map((c) => c.intensity)).toEqual([0, 0.25, 0.5, 1])
+  })
+
+  it('flags over-capacity cells', () => {
+    const cells = heatCells(ticks, [1, 2, 3, 5], 3, 5)
+    expect(cells.map((c) => c.over)).toEqual([false, false, false, true]) // 5 > capacity 3
+  })
+
+  it('clamps intensity to 1 when load exceeds the peak', () => {
+    const cells = heatCells(ticks, [8], 2, 4)
+    expect(cells[0]!.intensity).toBe(1)
+  })
+
+  it('carries the axis geometry through', () => {
+    const cells = heatCells(ticks, [1, 1, 1, 1], 1, 1)
+    expect(cells.map((c) => c.leftPct)).toEqual([0, 25, 50, 75])
+    expect(cells.every((c) => c.widthPct === 25)).toBe(true)
+  })
+})
+
+describe('heatPeak', () => {
+  it('returns the max load across rows (>= floor)', () => {
+    expect(heatPeak([[0, 1, 2], [3, 0], [1]])).toBe(3)
+    expect(heatPeak([[0, 0]], 1)).toBe(1) // floor
+  })
+})

package/src/scheduler-heatmap.ts

@@ -0,0 +1,55 @@
+/**
+ * scheduler-heatmap - the pure core behind Scheduler Pro's *utilization heatmap*.
+ * No Svelte, no DOM. Distinct from the histogram (a bar strip): the heatmap tints
+ * a resource row's BACKGROUND per time-bucket by how loaded that resource is.
+ *
+ * The renderer computes each bucket's load (with `resourceLoad` / `overlapCount`
+ * from the assignment / model helpers) and passes it here to get a normalized
+ * intensity (0..1) + an over-capacity flag per cell; it then paints the cell with
+ * a theme colour at that intensity.
+ */
+
+/** One background cell: its axis geometry + normalized load intensity. */
+export type HeatCell = {
+  leftPct: number
+  widthPct: number
+  /** 0..1, load scaled against `peak` (clamped). */
+  intensity: number
+  /** True when the raw load exceeds capacity. */
+  over: boolean
+}
+
+/**
+ * Build the per-tick heat cells for one resource row. `ticks` supply the axis
+ * geometry, `loads` the load in each tick (same length/order), `capacity` the
+ * resource's capacity (over that = `over`), and `peak` the normalization scale
+ * (usually a global peak so rows are comparable). Zero-load ticks are still
+ * emitted (intensity 0) so the caller can decide whether to paint them.
+ */
+export function heatCells(
+  ticks: ReadonlyArray<{ leftPct: number; widthPct: number }>,
+  loads: ReadonlyArray<number>,
+  capacity: number,
+  peak: number,
+): HeatCell[] {
+  const scale = Math.max(peak, capacity, 1)
+  const out: HeatCell[] = []
+  for (let i = 0; i < ticks.length; i++) {
+    const t = ticks[i]!
+    const load = loads[i] ?? 0
+    out.push({
+      leftPct: t.leftPct,
+      widthPct: t.widthPct,
+      intensity: Math.max(0, Math.min(1, load / scale)),
+      over: load > capacity + 1e-9,
+    })
+  }
+  return out
+}
+
+/** The peak load across a set of per-resource load rows (for a shared scale). */
+export function heatPeak(loadRows: ReadonlyArray<ReadonlyArray<number>>, floor = 1): number {
+  let peak = floor
+  for (const row of loadRows) for (const v of row) if (v > peak) peak = v
+  return peak
+}

package/src/scheduler-resource-tree.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+import { buildResourceRows, visibleResourceIds, type SchedulerResourceGroup } from './scheduler-resource-tree'
+
+type Res = { id: string; title?: string; group?: string }
+const groupOf = (r: Res) => r.group
+
+const groups: SchedulerResourceGroup[] = [
+  { id: 'clinic', title: 'Clinic' },
+  { id: 'cardio', title: 'Cardiology', parentId: 'clinic' },
+  { id: 'derm', title: 'Dermatology', parentId: 'clinic' },
+]
+const resources: Res[] = [
+  { id: 'dr-a', title: 'Dr A', group: 'cardio' },
+  { id: 'dr-b', title: 'Dr B', group: 'cardio' },
+  { id: 'dr-c', title: 'Dr C', group: 'derm' },
+]
+
+describe('buildResourceRows', () => {
+  it('nests groups and interleaves resources in tree order', () => {
+    const rows = buildResourceRows(resources, groups, groupOf)
+    expect(rows.map((r) => `${r.kind}:${r.id}@${r.depth}`)).toEqual([
+      'group:clinic@0',
+      'group:cardio@1',
+      'resource:dr-a@2',
+      'resource:dr-b@2',
+      'group:derm@1',
+      'resource:dr-c@2',
+    ])
+  })
+
+  it('computes childResourceIds (roll-up) for each group subtree', () => {
+    const rows = buildResourceRows(resources, groups, groupOf)
+    const byId = Object.fromEntries(rows.filter((r) => r.kind === 'group').map((r) => [r.id, r.childResourceIds]))
+    expect(byId.clinic).toEqual(['dr-a', 'dr-b', 'dr-c'])
+    expect(byId.cardio).toEqual(['dr-a', 'dr-b'])
+    expect(byId.derm).toEqual(['dr-c'])
+  })
+
+  it('collapsing a group hides its subtree but keeps the header', () => {
+    const rows = buildResourceRows(resources, groups, groupOf, new Set(['cardio']))
+    expect(rows.map((r) => `${r.kind}:${r.id}`)).toEqual([
+      'group:clinic',
+      'group:cardio', // header stays
+      // dr-a, dr-b hidden
+      'group:derm',
+      'resource:dr-c',
+    ])
+    expect(rows.find((r) => r.id === 'cardio')?.collapsed).toBe(true)
+  })
+
+  it('collapsing an ancestor hides all descendants', () => {
+    const rows = buildResourceRows(resources, groups, groupOf, new Set(['clinic']))
+    expect(rows.map((r) => r.id)).toEqual(['clinic'])
+  })
+
+  it('puts ungrouped / unknown-group resources in a trailing section (no header)', () => {
+    const res: Res[] = [{ id: 'x', group: 'cardio' }, { id: 'y' }, { id: 'z', group: 'nope' }]
+    const rows = buildResourceRows(res, groups, groupOf)
+    const last2 = rows.slice(-2).map((r) => `${r.kind}:${r.id}@${r.depth}`)
+    expect(last2).toEqual(['resource:y@0', 'resource:z@0'])
+  })
+
+  it('treats a group with an unknown parent as a root', () => {
+    const g: SchedulerResourceGroup[] = [{ id: 'a', title: 'A', parentId: 'ghost' }]
+    const rows = buildResourceRows([{ id: 'r', group: 'a' }], g, groupOf)
+    expect(rows[0]).toMatchObject({ kind: 'group', id: 'a', depth: 0 })
+  })
+
+  it('does not loop on a cyclic parent chain', () => {
+    const g: SchedulerResourceGroup[] = [
+      { id: 'a', title: 'A', parentId: 'b' },
+      { id: 'b', title: 'B', parentId: 'a' },
+    ]
+    const rows = buildResourceRows([{ id: 'r', group: 'a' }], g, groupOf)
+    // Should terminate; both groups appear at most once.
+    expect(rows.filter((r) => r.id === 'a').length).toBeLessThanOrEqual(1)
+    expect(rows.filter((r) => r.id === 'b').length).toBeLessThanOrEqual(1)
+  })
+
+  it('visibleResourceIds returns leaf resources in order', () => {
+    const rows = buildResourceRows(resources, groups, groupOf)
+    expect(visibleResourceIds(rows)).toEqual(['dr-a', 'dr-b', 'dr-c'])
+  })
+})