@inxee_npm/scheduler
v0.2.2
Published
A time-accurate timeline for **resource occupancy**: one row per resource (e.g. an airport stand), one tile per time interval (e.g. an aircraft turnaround, arrival -> departure), minute accuracy, virtualized rendering for thousands of tiles, drag to anoth
Maintainers
Readme
@inxee_npm/scheduler
A time-accurate timeline for resource occupancy: one row per resource (e.g. an airport stand), one tile per time interval (e.g. an aircraft turnaround, arrival -> departure), minute accuracy, virtualized rendering for thousands of tiles, drag to another row, resize, conflict detection.
React + TypeScript + styled-components. Fork of the bitnoise react-scheduler, rebuilt in 0.2.0.
Installation
yarn add @inxee_npm/scheduler react react-dom dayjs styled-components
# npm
npm install @inxee_npm/scheduler react react-dom dayjs styled-componentsreact / react-dom (^18 || ^19), dayjs (^1.11) and styled-components (^6) are peer
dependencies - the package uses your single instance of each.
Example usage
- import the styles once (loads the Inter font)
import "@inxee_npm/scheduler/dist/style.css";- render the Scheduler. It is positioned absolutely and fills its nearest positioned parent.
import { useCallback, useState } from "react";
import { Scheduler } from "@inxee_npm/scheduler";
import type { DatesRange, Row, Tile } from "@inxee_npm/scheduler";
const data: Row[] = [
{
id: "stand-12",
label: { title: "Stand 12", subtitle: "Contact" },
data: [
{
id: "turn-1",
title: "6E6186 -> 6E6729",
subtitle: "A21N VTIRV",
startDate: "2026-10-28T08:10:00.000Z", // ISO string or Date
endDate: "2026-10-28T10:05:00.000Z",
bgColor: "#2F6FB5",
tooltip: { title: "6E6186 -> 6E6729", lines: ["A21N from VTIRV", "08:10 - 10:05"] },
meta: { flightId: 4711 }
},
{
id: "turn-2", // starts exactly when turn-1 ends -> shares the sub-row, no conflict
title: "AI101 -> AI102",
startDate: new Date("2026-10-28T10:05:00.000Z"),
endDate: new Date("2026-10-28T12:00:00.000Z"),
provisional: true // hatched, dashed border
}
]
}
];
export default function Occupancy() {
const [range, setRange] = useState<DatesRange>();
// stable callback: the Scheduler reports the loaded window (incl. buffer), debounced by 250 ms
const onRangeChange = useCallback((r: DatesRange) => setRange(r), []);
// -> fetch `range.startDate .. range.endDate` from your API and pass it as `data`
return (
<div style={{ position: "relative", height: "100vh" }}>
<Scheduler
data={data}
config={{ hourWidth: 120, dragEnabled: true, resizeEnabled: true, defaultTheme: "dark" }}
onRangeChange={onRangeChange}
onTileClick={(tile, row) => console.log(tile.id, tile.conflict, row.id)}
onTileMove={async ({ tile, fromRowId, toRowId }) => {
const ok = await api.moveTile(tile.id, toRowId); // your server call
return ok; // false / rejected promise -> the tile snaps back
}}
onTileResize={async ({ tile, edge, newDate }) => {
await api.setTime(tile.id, edge, newDate);
// true / undefined -> supply the new data, the tile keeps the new size until then
}}
/>
</div>
);
}Scheduler API
Scheduler props
| Property | Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data | Row[] | rows with their tiles |
| isLoading | boolean | shows a loading bar |
| config | Config | see below |
| startDate | Date | the time placed at ~25% from the left on mount / when it changes (default: now) |
| onRangeChange | (r: { startDate: Date; endDate: Date }) => void | the loaded time window including the buffer. Called (debounced 250 ms, with the newest range) on mount, after the window shifted, after zoom changes and after prev / next / now |
| onTileClick | (tile: Tile, row: { id; label }) => void | click on a tile (also fired for keyboard Enter / Space). Not fired after a drag / resize |
| onTileMove | (e: { tile; fromRowId; toRowId }) => Promise<boolean \| void> \| boolean \| void | drag released over another row. While the promise is pending the tile shows a busy state. false / rejection -> the tile animates back. true / undefined -> supply new data |
| onTileResize | (e: { tile; edge: "start" \| "end"; newDate: Date }) => Promise<boolean \| void> \| boolean \| void | same contract as onTileMove for resizing |
| onItemClick | (row: { id; label }) => void | click on a row in the left column |
| onFilterData | () => void | filter button clicked (visible when config.filterButtonState >= 0) |
| onClearFilterData | () => void | clear-filters button clicked (visible when filterButtonState > 0) |
Config
| Property | Type | Default | Description |
| ----------------- | ---------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| hourWidth | number | 120 | pixels per hour |
| zoomLevels | number[] | [40, 60, 90, 120, 180, 300] | hourWidth steps of the zoom buttons. Zooming keeps the time at the viewport centre |
| bufferHours | number | 24 | hours rendered left and right of the visible area (canvas = (2 * buffer + visible) * hourWidth) |
| snapMinutes | number | 5 | drag / resize snapping |
| showNowLine | boolean | true | vertical line at the current time, moved every 30 s |
| showLegend | boolean | false | show legend in the toolbar |
| legend | { color; label; hatched? }[] | - | legend items |
| dragEnabled | boolean | false | vertical drag of a tile to another row |
| resizeEnabled | boolean | false | resize handles on both tile edges |
| defaultTheme | "light" \| "dark" | "light" | |
| showThemeToggle | boolean | false | theme toggle in the toolbar |
| theme | Theme | - | per theme colour overrides ({ light?: {...}, dark?: {...} }) |
| lang | "en" \| "pl" \| "de" \| "lt" \| string | "en" | |
| translations | LocaleType[] | - | add / override translations |
| showTooltip | boolean | true | hover tooltip on tiles |
| filterButtonState | number | -1 | < 0 hidden, 0 visible, > 0 filters applied (shows a clear button) |
Removed in 0.2.0 and ignored: zoom, maxRecordsPerPage, defaultStartDate,
includeTakenHoursOnWeekendsInDayView, isFiltersButtonVisible.
Row
| Property | Type | Description |
| -------- | ----------------------------------------------------- | ---------------------------------------- |
| id | string | unique row id |
| label | { title: string; subtitle?: string; icon?: string } | left column content (icon = image URL) |
| data | Tile[] | tiles of the row |
Tile
| Property | Type | Description |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| id | string | unique id |
| startDate | Date \| string | ISO strings accepted. Local time is used for display |
| endDate | Date \| string | |
| title | string | hidden when the tile is narrower than ~44px (still in the tooltip) |
| subtitle | string? | second line (description is a legacy alias) |
| bgColor | string? | any CSS background, e.g. #2F6FB5 or a gradient |
| provisional | boolean? | hatched stripes over bgColor + dashed border |
| cancelled | boolean? | strike-through / red style, never counts for conflicts |
| locked | { move?; start?; end? }? | disables drag / left resize / right resize |
| tooltip | { title: string; lines: (string \| { text; label?; tone? })[] }? | hover content (300 ms delay). A line is a string or { text, label?, tone? }: label is bold in front of the text, tone is "warning" (amber), "danger" (red) or "muted". Fallback: title + subtitle + start - end |
| meta | unknown? | opaque, returned in callbacks |
| conflict | boolean? | output only: true on tiles passed to callbacks when they overlap another non-cancelled tile |
Behaviour notes:
- Overlapping tiles of a row are stacked into sub-rows, the left column row grows with them
(
subRows * 65px). Boundaries are exclusive: a tile ending exactly when the next one starts shares the sub-row and is not a conflict. - Minimal rendered width is 3px (1 minute and zero length tiles stay visible). Tiles clipped by the loaded window show a chevron.
- The layout is cached per row (row id + content signature of ids, dates, status fields, colours,
tooltip and
meta). A refetch that returns new arrays with identical content costs a signature comparison and causes no re-render of unchanged rows / tiles. - Drag and resize use pointer events (mouse, touch, pen). Tiles with
dragEnabled/resizeEnabledsettouch-action: none.Esccancels a drag / resize.
Translation object example
import enDayjsTranslations from "dayjs/locale/en";
import type { LocaleType } from "@inxee_npm/scheduler";
const langs: LocaleType[] = [
{
id: "en",
lang: {
feelingEmpty: "I feel so empty...",
free: "Free",
loadNext: "Next",
loadPrevious: "Previous",
over: "over",
taken: "Taken",
topbar: {
filters: "Filters",
next: "next",
prev: "prev",
today: "Today",
now: "Now",
view: "View"
},
search: "search",
week: "week"
},
translateCode: "en-EN",
dayjsTranslations: enDayjsTranslations
}
];
<Scheduler data={data} config={{ lang: "en", translations: langs }} />;Using it with a server (live stand occupancy)
The pattern used by the SVDGS dashboard, for any server-driven timeline:
- Load by window. Keep the last
DatesRangefromonRangeChangeand fetch only that window (?from=<ISO>&to=<ISO>). The range already includes the buffer, so scrolling a few hours needs no request. Debounce your own fetch a little and abort the previous one when a new range arrives. - Keep identities stable. The package caches the layout per row signature. When a refetch returns
an unchanged row, reuse the previous
Rowobject (or at least identical content) so nothing re-renders. - Size the view with
hourWidth. For "N hours on screen" usehourWidth = Math.floor((containerWidth - leftColumnWidth) / N)and set a small minimum (e.g. 24). - Let the server decide moves and resizes. Return a promise from
onTileMove/onTileResize: resolvetrueonce the server accepted the change (then refetch), resolvefalseto snap the tile back. Ask the user on conflicts inside the handler (e.g. a confirm dialog) and resolve with the answer. - Lock what cannot change with
tile.locked(for example a docked aircraft) instead of rejecting later. - Push or poll for freshness. A websocket message that triggers a debounced refetch plus a slow fallback interval (30 s) keeps the board live without reloading everything on every record.
Time values travel as ISO strings (UTC) and are shown in the browser's local time zone.
Troubleshooting
- For using Scheduler with RemixJS add
@inxee_npm/schedulertoserverDependenciesToBundleinremix.config.js. - With NextJS (app router) wrap the Scheduler in a component with
"use client"; with the pages router import it withdynamic(() => import("@inxee_npm/scheduler").then((m) => m.Scheduler), { ssr: false }). - Dimensions: the Scheduler is positioned absolutely and takes all available space of the nearest
positioned ancestor. Wrap it in a
position: relativeelement with a fixed height. - Time zone: the browser's local time zone is used (tile dates are converted with
Date).
Known issues
- The hour grid / header use DOM elements (not canvas), only for the loaded window; very large
hourWidth * bufferHoursvalues just mean a wider scroll area. - No responsiveness below ~600px width.
Development
See development.md. Release notes: CHANGELOG.md.
License
MIT Licensed. Copyright (c) Inxee 2025.
