Scheduler API Reference

API reference › The resource scheduler

All 24 pages Everything on one page → Developer guide →

The resource scheduler

modules/scheduler is an opt-in resource scheduler: resources as rows in a real Lattice grid on the left and each event as a bar in its resource's row on a shared time axis on the right. It is a separate bundle in the same shape as the other view modules - it adds no weight to a page that does not load it, changes nothing in grid core, and pulls in no dependency beyond the Gantt's shared time scale, zoom presets, calendar and non-working rules, which it reuses rather than copies so both views read the same numbers. The left grid is the page's own createGrid, injected - never bundled - so the scheduler shares the page's one licensed core. It is just another dataset viewer: scheduler.rows.apply({ add, update, remove }) feeds the resources and scheduler.events.apply(...) the events, so a Data Router can attach(value, scheduler) beside a grid, a kanban and a chart.

The data layer. The events can come from three sources without hand-rolling the mapping: schedulerFromGantt(el, gantt, opts) expands a Gantt plan's assignments into one event per task/resource and wires the scheduler's change event back through gantt.applyEdit so a reassign updates the Gantt; schedulerFromRows(el, rows, opts) builds straight over any dataset whose rows carry a resource, start and end (mapped by fields, the Gantt's own vocabulary); and schedulerFromCalendar(el, calendar, opts) reads a calendar's events. With no resources list the scheduler derives its resource rows from the events' resource field. scheduler.reassign(key, resourceId) moves one event between rows and fires change { id, kind, resource: { from, to }, row }, and getState()/setState(state) carry the zoom and scroll across browser history.

import { createScheduler } from '@toclocoinc/lattice-grid/modules/scheduler';

const scheduler = createScheduler(document.querySelector('#scheduler'), {
  resources: [{ id: 'alice', name: 'Alice', role: 'Design', capacity: 4 }],
  events: [{ id: 1, resourceId: 'alice', name: 'Review', startDate: '2026-03-02 09:00', endDate: '2026-03-02 11:00' }],
  createGrid,                   // the page's own grid factory (injected, never bundled)
  zoom: 'day',                  // 'hour' | 'day' | 'week' | 'month' | 'quarter' | px-per-day
  fields: { resourceId: 'resourceId', startDate: 'startDate', endDate: 'endDate', name: 'name' },
});

The time axis reuses the Gantt's own zoom scale - hour, day, week, month and quarter presets, or a bare pixels-per-day number - with pointer-wheel (Ctrl+wheel) and keyboard (+/−) zoom and arrow-key scrolling. A todayLine marks today, and with nonWorking (default on) each resource's own calendar shades its non-working days exactly as the Gantt shades them: a 'weekends' string, a { workdays, holidays } spec, or a name looked up in calendars. Overlapping events in one resource stack into sub-lanes, so a two-hour review never hides the sketch behind it. Rows and time are both virtualised - only the rows and days under the viewport (plus overscan) create DOM, so 500 resources × 20 000 events stays bounded and scrollable. An event whose start cannot be read is counted in unscheduled and reported once, never thrown. With workload: true, each row also draws a histogram band across the bottom of the time axis - one cell per zoom bucket whose fill height is the booked share of the resource's own capacity, computed by the Gantt's computeWorkload against the resource's own calendar and capacity. An over-allocated bucket is highlighted with the theme's danger tokens and a warning glyph (never colour alone), and named resource-by-resource with its periods in an accessible live-region summary, which re-derives live when setEvents(events) replaces the feed. Pass null for the element and the same model answers headlessly.

Find and read the plan. A groupBy - a field name or a per-resource function - groups the resources into collapsible group rows, driven by the left grid's own grouping so the two panes can never disagree; the timeline mirrors the grid's expand/collapse state, and a toggle in either pane collapses the other. A search query narrows both sides at once, matching any string or number field of a resource or event (a row stays when its own text or one of its events' text matches, so a match never orphans its bar). A resourceFilter hides rows, an eventFilter hides bars, and each takes a predicate a row must pass. The Gantt's tooltip card - the same card its bars show - opens on an event's hover and keyboard focus with its start, end, duration and resource. Every bar, row, group header and the time axis is named for screen readers, and the keyboard alone reaches every event: the arrow keys walk between events and rows (roving focus), Enter activates, Home/End jump a row's ends, and +/− zoom - so the scheduler passes the same accessibility audit the grid does.

Events are editable: drag a bar to move it in time, drop it onto another resource row to reassign it, drag either edge to resize it, drag over empty time in a row to create an event, and press Delete (or use the right-click menu) to delete one. Every change snaps to the zoom step, writes back through events.apply - so a bound dataset sees it exactly as it sees a grid edit - and is one undo step: undo()/redo() or Ctrl/Cmd+Z / Ctrl/Cmd+Shift+Z. Each change raises the one cancellable beforeEventChange (call preventDefault() to refuse it, data untouched) and then one event:change carrying the event id and the old and new values. editable: false switches editing off; an event or a resource marked readOnly: true - or named by readOnlyWhen/resourceReadOnlyWhen - refuses the gesture with a catalogued reason.

Placement, lanes, workload, zoom, grouping, search, editing and export, executed

Two resources, three events (two overlapping into two sub-lanes on Alice's row), the day axis, the keyed-diff contract, the per-resource workload band, grouping, search and the two filters, an edit and its undo, and a print-safe SVG export of the visible range, run headless on every build.

const { createScheduler } = await import('../packages/modules/scheduler/index.js');
const sched = createScheduler(null, {
  resources: [
    { id: 'alice', name: 'Alice', role: 'Design', capacity: 4, calendar: 'weekends' },
    { id: 'bob', name: 'Bob', role: 'Dev', capacity: 3 },
  ],
  events: [
    { id: 1, resourceId: 'alice', name: 'Review', startDate: '2026-03-02 09:00', endDate: '2026-03-02 11:00', status: 'done' },
    { id: 2, resourceId: 'alice', name: 'Sketch', startDate: '2026-03-02 10:00', endDate: '2026-03-02 12:00', status: 'wip' },
    { id: 3, resourceId: 'bob', name: 'Build', startDate: '2026-03-03 09:00' },
  ],
  fields: { resourceId: 'resourceId', startDate: 'startDate', endDate: 'endDate', name: 'name' },
  resourceKey: 'id', eventKey: 'id',
  zoom: 'day', date: '2026-03-02',
  defaultDuration: 60, rowHeight: 34, weekStartDay: 1,
  todayLine: true, nonWorking: true,
  calendars: { weekends: 'weekends' },
  workload: true,
  colorProperty: 'status', colorMap: { done: '#16a34a' },
  ariaLabel: 'Scheduler', labels: { resource: 'Resource' },
  overscan: 5,
  groupBy: 'role',
  search: '', resourceFilter: null, eventFilter: null,
  editable: true,
  readOnlyWhen: (e) => e.readOnly,
  resourceReadOnlyWhen: (r) => r.readOnly,
});
const resources = sched.rows.count;                       // 2
const events = sched.events.count;                        // 3
const alice = sched.placement.byResource.get('alice');
const overlap = alice.length;                             // 2 (two sub-lanes)
const unscheduled = sched.model.unscheduled.length;       // 0
const px = sched.model.pxPerDay;                          // 26 (the day preset)
const hasTicks = sched.model.ticks.length > 0;           // true
const groups = sched.displayRows.filter((r) => r.type === 'group').length; // 2
sched.setSearch('review');
const matchedEvents = sched.ctx.visibleEvents.length;     // 1
const matchedResources = sched.ctx.visibleResources.length; // 1
sched.setSearch('');
sched.setEventFilter((e) => e.status === 'done');
const filteredEvents = sched.ctx.visibleEvents.length;    // 1
sched.setEventFilter(null);
sched.setResourceFilter((r) => r.role !== 'Dev');
const filteredResources = sched.ctx.visibleResources.length; // 1
sched.setResourceFilter(null);
const wlRows = sched.workload.rows.size;                  // 2 (one band row per resource)
const wlOver = sched.workload.overAllocated.length;       // 0 (nothing over-allocated)
const changed = sched.edit.move(1, 1).ok;                 // true (moved one day)
const movedStart = sched.events.get(1).startDate;         // 2026-03-03 09:00
sched.undo();
const undone = sched.events.get(1).startDate;             // 2026-03-02 09:00
sched.setZoom('week');
const zoom = sched.getZoom().level;                       // week
sched.rows.apply({ add: [{ id: 'carol', name: 'Carol' }] });
const after = sched.rows.count;                           // 3
const svg = sched.toSVG();                                // the visible range as one standalone SVG
const isSvg = /^<svg /.test(svg);                      // true
const hasBars = (svg.match(/<rect /g) || []).length >= 3;  // true (one bar per placed event)
const noVar = svg.includes('var(') === false;             // true (print-safe palette, no tokens)
const printed = sched.print();                            // false (no window to open, headless)
sched.destroy();
return [resources, events, overlap, unscheduled, px, hasTicks, groups, matchedEvents, matchedResources, filteredEvents, filteredResources, wlRows, wlOver, changed, movedStart, undone, zoom, after, isSvg, hasBars, noVar, printed].join('|');

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The scheduler module

SchedulerFields

The field-to-property mapping naming the data each event and resource reads.

SchedulerCalendar

A non-working calendar spec: the `'weekends'` shorthand, or workdays plus holidays.

SchedulerWorkload

The `workload` band option: a per-resource utilisation strip drawn at the bottom of each row, computed with the Gantt's own `computeWorkload` against each resource's calendar and capacity.

SchedulerKeyedRows

A keyed-diff consumer surface, the same contract a grid's `rows` exposes.

SchedulerModel

The scheduler's computed model, for tests and headless callers.

SchedulerPlacement

The event placement, for tests and headless callers.

SchedulerConfig

The configuration for {@link createScheduler}. `resources` are the left grid's rows; `events` draw as bars. `createGrid` is the page's own grid factory, injected so the scheduler shares the page's one core.

Properties

Methods

Events

No events.

SchedulerEventChange

The payload every scheduler edit event carries: the event id, the changed fields and the before/after snapshots.

SchedulerEventChangeEvent

The cancellable `beforeEventChange` payload: cancelling it refuses the edit, data untouched.

SchedulerEventChangeCancelled

The `eventChange:cancelled` payload: a `beforeEventChange` was vetoed.

SchedulerZoomChangeEvent

The `zoom:change` payload: the new zoom level and px-per-day.

SchedulerReassignEvent

The `change` payload: a reassign moved an event to another resource row.

SchedulerEventPayloads

The payload each scheduler event name carries.

Scheduler

The scheduler instance {@link createScheduler} returns.

Properties

Methods

Events