@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/scheduler/core/gantt.js

@@ -0,0 +1,226 @@
+/**
+ * Gantt scheduling core: task tree flattening, summary roll-ups, cycle detection and forward
+ * scheduling of finish-to-start links (working-day aware). React-free.
+ *
+ * Dates are `YYYY-MM-DD`; `end` is the last day of the task, inclusive. A milestone has
+ * `start === end`.
+ */
+import { addDays, compareIsoDate, diffDays } from "../../locale-data/core/date.js";
+import { addWorkingDays, countWorkingDays, nextWorkingDay } from "../../locale-data/core/working-days.js";
+/** Depth-first order of a task forest (input order is kept among siblings). */
+export function flattenTasks(tasks) {
+    const ids = new Set(tasks.map((t) => t.id));
+    const children = new Map();
+    for (const t of tasks) {
+        const parent = t.parentId && ids.has(t.parentId) && t.parentId !== t.id ? t.parentId : undefined;
+        const list = children.get(parent) ?? [];
+        list.push(t);
+        children.set(parent, list);
+    }
+    const out = [];
+    const seen = new Set();
+    const walk = (parent, depth, prefix) => {
+        (children.get(parent) ?? []).forEach((task, i) => {
+            if (seen.has(task.id))
+                return;
+            seen.add(task.id);
+            const wbs = prefix ? `${prefix}.${i + 1}` : String(i + 1);
+            out.push({ task, depth, wbs, index: out.length + 1, hasChildren: (children.get(task.id)?.length ?? 0) > 0, parentId: parent });
+            walk(task.id, depth + 1, wbs);
+        });
+    };
+    walk(undefined, 0, "");
+    return out;
+}
+/** Visible rows given a set of collapsed task ids. */
+export function visibleTasks(flat, collapsed) {
+    const out = [];
+    let hideBelow = Infinity;
+    for (const row of flat) {
+        if (row.depth > hideBelow)
+            continue;
+        hideBelow = Infinity;
+        out.push(row);
+        if (row.hasChildren && collapsed.has(row.task.id))
+            hideBelow = row.depth;
+    }
+    return out;
+}
+/**
+ * Summary tasks (and any task with children) span their children: earliest start, latest end,
+ * duration-weighted progress. Returns new task objects for changed summaries only.
+ */
+export function rollupSummaries(tasks) {
+    const byId = new Map(tasks.map((t) => [t.id, { ...t }]));
+    const kids = new Map();
+    for (const t of tasks)
+        if (t.parentId && byId.has(t.parentId))
+            kids.set(t.parentId, [...(kids.get(t.parentId) ?? []), t.id]);
+    const done = new Set();
+    const visit = (id, stack) => {
+        const t = byId.get(id);
+        const c = kids.get(id);
+        if (!c || done.has(id) || stack.has(id))
+            return t;
+        stack.add(id);
+        let start;
+        let end;
+        let weight = 0;
+        let progress = 0;
+        for (const k of c) {
+            const child = visit(k, stack);
+            if (!start || compareIsoDate(child.start, start) < 0)
+                start = child.start;
+            if (!end || compareIsoDate(child.end, end) > 0)
+                end = child.end;
+            const w = Math.max(1, diffDays(child.start, child.end) + 1);
+            weight += w;
+            progress += w * (child.progress ?? 0);
+        }
+        stack.delete(id);
+        done.add(id);
+        if (start && end) {
+            t.start = start;
+            t.end = end;
+            t.progress = weight ? progress / weight : 0;
+            if (!t.type || t.type === "task")
+                t.type = "summary";
+        }
+        return t;
+    };
+    for (const id of byId.keys())
+        visit(id, new Set());
+    return tasks.map((t) => byId.get(t.id));
+}
+/**
+ * Cycles in the dependency graph, each as a list of task ids (`["a", "b", "c"]` for a → b → c → a).
+ * Empty when the graph is acyclic.
+ */
+export function detectCycles(links) {
+    const adj = new Map();
+    for (const l of links)
+        adj.set(l.from, [...(adj.get(l.from) ?? []), l.to]);
+    const state = new Map(); // 1 visiting, 2 done
+    const stack = [];
+    const cycles = [];
+    const dfs = (n) => {
+        state.set(n, 1);
+        stack.push(n);
+        for (const m of adj.get(n) ?? []) {
+            const s = state.get(m);
+            if (s === 1)
+                cycles.push(stack.slice(stack.indexOf(m)));
+            else if (!s)
+                dfs(m);
+        }
+        stack.pop();
+        state.set(n, 2);
+    };
+    for (const n of adj.keys())
+        if (!state.has(n))
+            dfs(n);
+    return cycles;
+}
+/** Would adding `from → to` create a cycle? */
+export function createsCycle(links, from, to) {
+    if (from === to)
+        return true;
+    return detectCycles([...links, { from, to }]).length > 0;
+}
+/** Task length in days or working days (inclusive of both ends). Milestones are 0. */
+export function taskDuration(task, cal, unit = "workdays") {
+    if (task.type === "milestone")
+        return 0;
+    if (unit === "days" || !cal)
+        return diffDays(task.start, task.end) + 1;
+    return countWorkingDays(task.start, task.end, cal);
+}
+/** Moves a task so it starts on `start`, keeping its length (working days when a calendar is given). */
+export function moveTaskTo(task, start, cal, unit = "workdays") {
+    if (task.type === "milestone")
+        return { ...task, start, end: start };
+    if (unit === "days" || !cal)
+        return { ...task, start, end: addDays(start, diffDays(task.start, task.end)) };
+    const s = nextWorkingDay(start, cal, 1);
+    const len = Math.max(1, countWorkingDays(task.start, task.end, cal));
+    return { ...task, start: s, end: addWorkingDays(s, len - 1, cal) };
+}
+/**
+ * Forward scheduling of finish-to-start links: every successor starts no earlier than the day
+ * after its predecessor ends (+ `lagDays`), skipping non-working days when a calendar is given.
+ * Successors are only pushed later, never pulled earlier. Returns a new array with moved tasks
+ * replaced; unchanged tasks keep their identity. Links in a cycle are ignored.
+ *
+ * ```ts
+ * const next = scheduleForward(tasks, links, trWorkCalendar);
+ * const moved = next.filter((t, i) => t !== tasks[i]);
+ * ```
+ */
+export function scheduleForward(tasks, links, cal, unit = "workdays") {
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const fs = links.filter((l) => (l.type ?? "FS") === "FS" && byId.has(l.from) && byId.has(l.to));
+    const cyclic = new Set(detectCycles(fs).flat());
+    const usable = fs.filter((l) => !(cyclic.has(l.from) && cyclic.has(l.to)));
+    const incoming = new Map();
+    const indeg = new Map();
+    for (const l of usable) {
+        incoming.set(l.to, [...(incoming.get(l.to) ?? []), l]);
+        indeg.set(l.to, (indeg.get(l.to) ?? 0) + 1);
+    }
+    const out = new Map(byId);
+    // Kahn order so predecessors settle first.
+    const queue = tasks.filter((t) => !indeg.get(t.id)).map((t) => t.id);
+    const order = [];
+    const remaining = new Map(indeg);
+    while (queue.length) {
+        const id = queue.shift();
+        order.push(id);
+        for (const l of usable) {
+            if (l.from !== id)
+                continue;
+            const n = (remaining.get(l.to) ?? 1) - 1;
+            remaining.set(l.to, n);
+            if (n === 0)
+                queue.push(l.to);
+        }
+    }
+    for (const id of order) {
+        const ins = incoming.get(id);
+        if (!ins)
+            continue;
+        const task = out.get(id);
+        let earliest;
+        for (const l of ins) {
+            const pred = out.get(l.from);
+            const lag = l.lagDays ?? 0;
+            let candidate = pred.type === "milestone" ? pred.end : addDays(pred.end, 1);
+            if (cal && unit === "workdays") {
+                candidate = nextWorkingDay(candidate, cal, 1);
+                if (lag)
+                    candidate = addWorkingDays(candidate, lag, cal);
+            }
+            else if (lag)
+                candidate = addDays(candidate, lag);
+            if (!earliest || compareIsoDate(candidate, earliest) > 0)
+                earliest = candidate;
+        }
+        if (earliest && compareIsoDate(task.start, earliest) < 0)
+            out.set(id, moveTaskTo(task, earliest, cal, unit));
+    }
+    return tasks.map((t) => out.get(t.id));
+}
+/** Links whose successor starts before its predecessor allows (FS violated). */
+export function linkViolations(tasks, links) {
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const bad = new Set();
+    for (const l of links) {
+        const a = byId.get(l.from);
+        const b = byId.get(l.to);
+        if (!a || !b || (l.type ?? "FS") !== "FS")
+            continue;
+        const limit = a.type === "milestone" ? a.end : addDays(a.end, 1);
+        if (compareIsoDate(b.start, limit) < 0)
+            bad.add(l.id);
+    }
+    return bad;
+}

package/dist/scheduler/core/index.d.ts

@@ -0,0 +1,6 @@
+export { createTimeScale, toEpoch, minutesToClock, clockToMinutes, TIME_SCALE_PRESETS, type TimeScale, type TimeScaleOptions, type TimeScalePreset, type TimeScaleUnit, type TickUnit, type TimeTick, type TimeInput, } from "./time-scale.js";
+export { countWorkingDays, addWorkingDays, isWorkingDay, workingValue, nextWorkingDay } from "../../locale-data/core/working-days.js";
+export type { WorkCalendar, HolidayProvider, Holiday, BusinessHours } from "../../locale-data/core/types.js";
+export { layoutDayEvents, packLanes, laneCount, isLaneEvent, eventDays, eventsInRange, compareEvents, shiftEvent, localDate, localMinutes, instantAt, weekDays, monthWeeks, type LayoutEvent, type PositionedEvent, type LaneAssignment, } from "./layout.js";
+export { flattenTasks, visibleTasks, rollupSummaries, detectCycles, createsCycle, taskDuration, moveTaskTo, scheduleForward, linkViolations, type GanttTaskCore, type GanttLinkCore, type GanttTaskType, type FlatTask, } from "./gantt.js";
+export { parseDuration, formatDuration, entryMinutes, timesheetTotals, toLineItems, lineItemsTotal, type TimeEntry, type LineItemDraft, } from "./duration.js";

package/dist/scheduler/core/index.js

@@ -0,0 +1,7 @@
+// React-free core of @vamos-ui/react/scheduler: time scale, working-day math, event layout,
+// Gantt scheduling and time-tracking helpers. Importable from server components and workers.
+export { createTimeScale, toEpoch, minutesToClock, clockToMinutes, TIME_SCALE_PRESETS, } from "./time-scale.js";
+export { countWorkingDays, addWorkingDays, isWorkingDay, workingValue, nextWorkingDay } from "../../locale-data/core/working-days.js";
+export { layoutDayEvents, packLanes, laneCount, isLaneEvent, eventDays, eventsInRange, compareEvents, shiftEvent, localDate, localMinutes, instantAt, weekDays, monthWeeks, } from "./layout.js";
+export { flattenTasks, visibleTasks, rollupSummaries, detectCycles, createsCycle, taskDuration, moveTaskTo, scheduleForward, linkViolations, } from "./gantt.js";
+export { parseDuration, formatDuration, entryMinutes, timesheetTotals, toLineItems, lineItemsTotal, } from "./duration.js";

package/dist/scheduler/core/layout.d.ts

@@ -0,0 +1,97 @@
+import type { IsoDate } from "../../locale-data/core/types.js";
+/** Minimal shape the layout functions need (SchedulerEvent satisfies it). */
+export interface LayoutEvent {
+    id: string;
+    start: string;
+    end: string;
+    allDay?: boolean;
+}
+export interface PositionedEvent<E extends LayoutEvent = LayoutEvent> {
+    event: E;
+    /** Minutes after local midnight of the day, clipped to the day (0–1440). */
+    startMin: number;
+    endMin: number;
+    /** 0-based column inside its overlap cluster. */
+    column: number;
+    /** Number of columns in the cluster. */
+    columns: number;
+    /** Columns this event may stretch over to its inline-end (free neighbours), ≥ 1. */
+    span: number;
+    /** The event started before / ends after this day. */
+    continuesBefore: boolean;
+    continuesAfter: boolean;
+}
+export interface LaneAssignment<E extends LayoutEvent = LayoutEvent> {
+    event: E;
+    lane: number;
+    /** First and last visible day (clipped to the range), inclusive. */
+    startDay: IsoDate;
+    endDay: IsoDate;
+    /** Index of `startDay` in the range and number of days covered. */
+    startIndex: number;
+    span: number;
+    continuesBefore: boolean;
+    continuesAfter: boolean;
+}
+/** True when the event is laid out in the all-day lane (all-day, or a timed event of 24 h or more). */
+export declare function isLaneEvent(e: LayoutEvent, timeZone?: string): boolean;
+/** Local first and last day (inclusive) an event touches in `timeZone`. */
+export declare function eventDays(e: LayoutEvent, timeZone?: string): {
+    start: IsoDate;
+    end: IsoDate;
+};
+/** Local calendar date of an instant in a zone. */
+export declare function localDate(t: number | string | Date, timeZone?: string): IsoDate;
+/** Wall-clock minutes after midnight of an instant in a zone (0–1439). */
+export declare function localMinutes(t: number | string | Date, timeZone?: string): number;
+/** UTC ISO instant of a local wall-clock time (`minutes` after local midnight of `date`, may overflow into later days). */
+export declare function instantAt(date: IsoDate, minutes: number, timeZone?: string): string;
+/** Shifts an event by whole days and minutes, keeping its kind. Returns new `{ start, end }`. */
+export declare function shiftEvent(e: LayoutEvent, days: number, minutes?: number, timeZone?: string): {
+    start: string;
+    end: string;
+};
+/** Events touching `[start, end]` (inclusive local days). */
+export declare function eventsInRange<E extends LayoutEvent>(events: readonly E[], range: {
+    start: IsoDate;
+    end: IsoDate;
+}, timeZone?: string): E[];
+/** Sort: earlier start first, then longer first, then id (stable across renders). */
+export declare function compareEvents(a: LayoutEvent, b: LayoutEvent, timeZone?: string): number;
+/**
+ * Overlap column packing for one day of a time grid.
+ *
+ * ```ts
+ * layoutDayEvents(events, "2026-11-10", "Europe/Istanbul");
+ * // → [{ event, startMin: 540, endMin: 600, column: 0, columns: 2, span: 1, … }, …]
+ * ```
+ *
+ * Events in the all-day lane (`isLaneEvent`) are skipped. Very short events get at least
+ * `minDuration` minutes of height so they stay clickable (default 15).
+ */
+export declare function layoutDayEvents<E extends LayoutEvent>(events: readonly E[], day: IsoDate, timeZone?: string, opts?: {
+    minDuration?: number;
+}): PositionedEvent<E>[];
+/**
+ * Lane packing for all-day / multi-day bars over a range of days (a week row, the week view's
+ * all-day lane). Each event gets the lowest lane free on all of its days.
+ *
+ * ```ts
+ * packLanes(events, { start: "2026-11-09", end: "2026-11-15" }, "UTC", { include: "all" });
+ * ```
+ *
+ * `include: "lane"` (default) keeps only lane events (all-day or ≥ 24 h); `"all"` also packs
+ * timed events as one-day bars (month view).
+ */
+export declare function packLanes<E extends LayoutEvent>(events: readonly E[], range: {
+    start: IsoDate;
+    end: IsoDate;
+}, timeZone?: string, opts?: {
+    include?: "lane" | "all";
+}): LaneAssignment<E>[];
+/** Lane count needed by a packing result. */
+export declare const laneCount: (lanes: readonly LaneAssignment[]) => number;
+/** Days of the week containing `date`, given the first weekday (1 = Monday … 7 = Sunday). */
+export declare function weekDays(date: IsoDate, firstDay: number): IsoDate[];
+/** The week rows (4–6, each 7 days) of the month containing `date`, starting on `firstDay`. */
+export declare function monthWeeks(date: IsoDate, firstDay: number): IsoDate[][];

package/dist/scheduler/core/layout.js

@@ -0,0 +1,249 @@
+/**
+ * Event layout for the Agenda / scheduler: overlap column packing for time grids and lane
+ * packing for all-day / multi-day events and month weeks. React-free.
+ *
+ * Conventions:
+ * - Timed events: `start` / `end` are instants (UTC ISO strings), `end` exclusive.
+ * - All-day events: `start` / `end` are `YYYY-MM-DD`, `end` **inclusive** (a one-day event has
+ *   `start === end`).
+ * - Every function takes an explicit IANA `timeZone`; day boundaries are local midnight there.
+ */
+import { addDays, diffDays, compareIsoDate } from "../../locale-data/core/date.js";
+import { TZDate } from "@date-fns/tz";
+import { toEpoch } from "./time-scale.js";
+const MIN = 60_000;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+/** True when the event is laid out in the all-day lane (all-day, or a timed event of 24 h or more). */
+export function isLaneEvent(e, timeZone = "UTC") {
+    if (e.allDay || DATE_ONLY.test(e.start))
+        return true;
+    return toEpoch(e.end, timeZone) - toEpoch(e.start, timeZone) >= 24 * 60 * MIN;
+}
+/** Local first and last day (inclusive) an event touches in `timeZone`. */
+export function eventDays(e, timeZone = "UTC") {
+    if (e.allDay || DATE_ONLY.test(e.start)) {
+        const s = e.start.slice(0, 10);
+        const en = e.end ? e.end.slice(0, 10) : s;
+        return { start: s, end: compareIsoDate(en, s) < 0 ? s : en };
+    }
+    const s = toEpoch(e.start, timeZone);
+    const en = Math.max(s, toEpoch(e.end, timeZone) - 1); // end is exclusive
+    return { start: localDate(s, timeZone), end: localDate(en, timeZone) };
+}
+const dtfCache = new Map();
+function partsFmt(timeZone) {
+    let f = dtfCache.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+        dtfCache.set(timeZone, f);
+    }
+    return f;
+}
+/** Local calendar date of an instant in a zone. */
+export function localDate(t, timeZone = "UTC") {
+    const ms = typeof t === "number" ? t : t instanceof Date ? t.getTime() : toEpoch(t, timeZone);
+    const p = partsFmt(timeZone).formatToParts(ms);
+    const get = (type) => p.find((x) => x.type === type)?.value ?? "00";
+    return `${get("year")}-${get("month")}-${get("day")}`;
+}
+/** Wall-clock minutes after midnight of an instant in a zone (0–1439). */
+export function localMinutes(t, timeZone = "UTC") {
+    const ms = typeof t === "number" ? t : t instanceof Date ? t.getTime() : toEpoch(t, timeZone);
+    const p = partsFmt(timeZone).formatToParts(ms);
+    const h = Number(p.find((x) => x.type === "hour")?.value ?? 0) % 24;
+    const m = Number(p.find((x) => x.type === "minute")?.value ?? 0);
+    return h * 60 + m;
+}
+/** UTC ISO instant of a local wall-clock time (`minutes` after local midnight of `date`, may overflow into later days). */
+export function instantAt(date, minutes, timeZone = "UTC") {
+    const [y, m, d] = date.split("-").map(Number);
+    const whole = Math.round(minutes);
+    return new Date(new TZDate(y, m - 1, d, 0, whole, timeZone).getTime()).toISOString();
+}
+/** Shifts an event by whole days and minutes, keeping its kind. Returns new `{ start, end }`. */
+export function shiftEvent(e, days, minutes = 0, timeZone = "UTC") {
+    if (e.allDay || DATE_ONLY.test(e.start)) {
+        return { start: addDays(e.start.slice(0, 10), days), end: addDays((e.end || e.start).slice(0, 10), days) };
+    }
+    const s = toEpoch(e.start, timeZone);
+    const en = toEpoch(e.end, timeZone);
+    const sd = localDate(s, timeZone);
+    const start = instantAt(addDays(sd, days), localMinutes(s, timeZone) + minutes, timeZone);
+    const startMs = Date.parse(start);
+    return { start, end: new Date(startMs + (en - s)).toISOString() };
+}
+/** Events touching `[start, end]` (inclusive local days). */
+export function eventsInRange(events, range, timeZone = "UTC") {
+    return events.filter((e) => {
+        const d = eventDays(e, timeZone);
+        return compareIsoDate(d.end, range.start) >= 0 && compareIsoDate(d.start, range.end) <= 0;
+    });
+}
+/** Sort: earlier start first, then longer first, then id (stable across renders). */
+export function compareEvents(a, b, timeZone = "UTC") {
+    const as = toEpoch(a.start, timeZone);
+    const bs = toEpoch(b.start, timeZone);
+    if (as !== bs)
+        return as - bs;
+    const al = toEpoch(a.end || a.start, timeZone) - as;
+    const bl = toEpoch(b.end || b.start, timeZone) - bs;
+    if (al !== bl)
+        return bl - al;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/**
+ * Overlap column packing for one day of a time grid.
+ *
+ * ```ts
+ * layoutDayEvents(events, "2026-11-10", "Europe/Istanbul");
+ * // → [{ event, startMin: 540, endMin: 600, column: 0, columns: 2, span: 1, … }, …]
+ * ```
+ *
+ * Events in the all-day lane (`isLaneEvent`) are skipped. Very short events get at least
+ * `minDuration` minutes of height so they stay clickable (default 15).
+ */
+export function layoutDayEvents(events, day, timeZone = "UTC", opts = {}) {
+    const minDur = opts.minDuration ?? 15;
+    const dayStart = toEpoch(day, timeZone);
+    const dayEnd = toEpoch(addDays(day, 1), timeZone);
+    const dayLen = (dayEnd - dayStart) / MIN;
+    const items = [];
+    const timed = events.filter((e) => !isLaneEvent(e, timeZone)).slice().sort((a, b) => compareEvents(a, b, timeZone));
+    for (const event of timed) {
+        const s = toEpoch(event.start, timeZone);
+        const en = Math.max(s, toEpoch(event.end, timeZone));
+        if (en <= dayStart || s >= dayEnd) {
+            if (!(s === en && s >= dayStart && s < dayEnd))
+                continue;
+        }
+        const startMin = Math.max(0, (s - dayStart) / MIN);
+        let endMin = Math.min(dayLen, (en - dayStart) / MIN);
+        if (endMin - startMin < minDur)
+            endMin = Math.min(dayLen, startMin + minDur);
+        items.push({ event, startMin, endMin, column: 0, columns: 1, span: 1, continuesBefore: s < dayStart, continuesAfter: en > dayEnd });
+    }
+    // Clusters of transitively overlapping events share a column count.
+    let cluster = [];
+    let clusterEnd = -Infinity;
+    const flush = () => {
+        if (!cluster.length)
+            return;
+        const colEnds = [];
+        for (const it of cluster) {
+            let col = colEnds.findIndex((end) => end <= it.startMin);
+            if (col === -1) {
+                col = colEnds.length;
+                colEnds.push(it.endMin);
+            }
+            else
+                colEnds[col] = it.endMin;
+            it.column = col;
+        }
+        const columns = colEnds.length;
+        for (const it of cluster) {
+            it.columns = columns;
+            // Stretch into free columns to the inline-end.
+            let span = 1;
+            for (let c = it.column + 1; c < columns; c++) {
+                const blocked = cluster.some((o) => o !== it && o.column === c && o.startMin < it.endMin && o.endMin > it.startMin);
+                if (blocked)
+                    break;
+                span++;
+            }
+            it.span = span;
+        }
+        cluster = [];
+    };
+    for (const it of items) {
+        if (it.startMin >= clusterEnd) {
+            flush();
+            clusterEnd = it.endMin;
+        }
+        else
+            clusterEnd = Math.max(clusterEnd, it.endMin);
+        cluster.push(it);
+    }
+    flush();
+    return items;
+}
+/**
+ * Lane packing for all-day / multi-day bars over a range of days (a week row, the week view's
+ * all-day lane). Each event gets the lowest lane free on all of its days.
+ *
+ * ```ts
+ * packLanes(events, { start: "2026-11-09", end: "2026-11-15" }, "UTC", { include: "all" });
+ * ```
+ *
+ * `include: "lane"` (default) keeps only lane events (all-day or ≥ 24 h); `"all"` also packs
+ * timed events as one-day bars (month view).
+ */
+export function packLanes(events, range, timeZone = "UTC", opts = {}) {
+    const include = opts.include ?? "lane";
+    const length = diffDays(range.start, range.end) + 1;
+    if (length <= 0)
+        return [];
+    const chosen = eventsInRange(events, range, timeZone).filter((e) => include === "all" || isLaneEvent(e, timeZone));
+    const withDays = chosen.map((event) => ({ event, days: eventDays(event, timeZone), lane: isLaneEvent(event, timeZone) }));
+    // Multi-day bars first (they are hardest to place), then by start.
+    withDays.sort((a, b) => {
+        const la = diffDays(a.days.start, a.days.end);
+        const lb = diffDays(b.days.start, b.days.end);
+        const c = compareIsoDate(a.days.start, b.days.start);
+        if (c !== 0)
+            return c;
+        if (a.lane !== b.lane)
+            return a.lane ? -1 : 1;
+        if (la !== lb)
+            return lb - la;
+        return compareEvents(a.event, b.event, timeZone);
+    });
+    const occupied = []; // lane → day index
+    const out = [];
+    for (const { event, days } of withDays) {
+        const startDay = compareIsoDate(days.start, range.start) < 0 ? range.start : days.start;
+        const endDay = compareIsoDate(days.end, range.end) > 0 ? range.end : days.end;
+        const startIndex = diffDays(range.start, startDay);
+        const span = diffDays(startDay, endDay) + 1;
+        let lane = 0;
+        for (;; lane++) {
+            const row = (occupied[lane] ??= new Array(length).fill(false));
+            let free = true;
+            for (let i = startIndex; i < startIndex + span; i++)
+                if (row[i]) {
+                    free = false;
+                    break;
+                }
+            if (free) {
+                for (let i = startIndex; i < startIndex + span; i++)
+                    row[i] = true;
+                break;
+            }
+        }
+        out.push({ event, lane, startDay, endDay, startIndex, span, continuesBefore: compareIsoDate(days.start, range.start) < 0, continuesAfter: compareIsoDate(days.end, range.end) > 0 });
+    }
+    return out;
+}
+/** Lane count needed by a packing result. */
+export const laneCount = (lanes) => lanes.reduce((m, l) => Math.max(m, l.lane + 1), 0);
+/** Days of the week containing `date`, given the first weekday (1 = Monday … 7 = Sunday). */
+export function weekDays(date, firstDay) {
+    const wd = isoWeekdayOf(date);
+    const back = (wd - firstDay + 7) % 7;
+    const start = addDays(date, -back);
+    return Array.from({ length: 7 }, (_, i) => addDays(start, i));
+}
+/** The week rows (4–6, each 7 days) of the month containing `date`, starting on `firstDay`. */
+export function monthWeeks(date, firstDay) {
+    const first = `${date.slice(0, 7)}-01`;
+    const last = addDays(`${addDays(first, 32).slice(0, 7)}-01`, -1);
+    const weeks = [];
+    for (let cur = weekDays(first, firstDay)[0]; compareIsoDate(cur, last) <= 0; cur = addDays(cur, 7)) {
+        weeks.push(Array.from({ length: 7 }, (_, i) => addDays(cur, i)));
+    }
+    return weeks;
+}
+function isoWeekdayOf(date) {
+    const [y, m, d] = date.split("-").map(Number);
+    const wd = new Date(Date.UTC(y, m - 1, d)).getUTCDay();
+    return wd === 0 ? 7 : wd;
+}

package/dist/scheduler/core/time-scale.d.ts

@@ -0,0 +1,89 @@
+import type { IsoDate, WorkCalendar } from "../../locale-data/core/types.js";
+export type TimeScaleUnit = "hour" | "day" | "week" | "month" | "quarter";
+export type TickUnit = "minute15" | "minute30" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+export interface TimeScalePreset {
+    /** Pixels per 24 hours. */
+    pxPerDay: number;
+    /** Fine header row / grid lines. */
+    minor: TickUnit;
+    /** Coarse header row. */
+    major: TickUnit;
+}
+/** Zoom presets: hour (rooms × hours), day (people × days), week / month / quarter (Gantt). */
+export declare const TIME_SCALE_PRESETS: Readonly<Record<TimeScaleUnit, TimeScalePreset>>;
+/** An instant: `Date`, epoch ms, ISO instant ("2026-11-10T09:00:00Z") or date-only (local midnight in the zone). */
+export type TimeInput = Date | number | string;
+export interface TimeScaleOptions {
+    start: TimeInput;
+    end: TimeInput;
+    /** Zoom preset. Default `"day"`. */
+    scale?: TimeScaleUnit;
+    /** Overrides the preset's density. */
+    pxPerDay?: number;
+    /** IANA zone for ticks and date-only inputs. Default `"UTC"`. */
+    timeZone?: string;
+    /** Locale for the week start. Default `"en-US"`. */
+    locale?: string;
+    /** Marks day ticks with their working value. */
+    workCalendar?: WorkCalendar;
+}
+export interface TimeTick {
+    unit: TickUnit;
+    /** Epoch ms of the tick start (inclusive) and end (exclusive). */
+    start: number;
+    end: number;
+    /** Pixel offset and width. */
+    x: number;
+    width: number;
+    /** Local calendar date of the tick start in the scale's zone. */
+    date: IsoDate;
+    /** Day ticks with a `workCalendar`: 1 working, 0.5 half day, 0 off. */
+    working?: number;
+}
+export interface TimeScale {
+    readonly start: number;
+    readonly end: number;
+    readonly unit: TimeScaleUnit;
+    readonly timeZone: string;
+    readonly pxPerDay: number;
+    readonly pxPerMs: number;
+    /** Total width in px. */
+    readonly width: number;
+    /** 0 = Sunday … 6 = Saturday (date-fns numbering). */
+    readonly weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    toPx(t: TimeInput): number;
+    /** Epoch ms at a pixel offset. */
+    toTime(px: number): number;
+    toDate(px: number): Date;
+    durationToPx(ms: number): number;
+    pxToDuration(px: number): number;
+    /** Rounds an instant to the nearest tick boundary (`"day"`) or step in minutes (15). */
+    snap(t: TimeInput, step: TickUnit | number, mode?: "round" | "floor" | "ceil"): number;
+    /** Ticks of `unit` covering the range (clipped to it). */
+    ticks(unit?: TickUnit): TimeTick[];
+    /** Time window visible in a viewport, with optional overscan in px. */
+    visibleRange(scrollLeft: number, viewportWidth: number, overscanPx?: number): {
+        start: number;
+        end: number;
+    };
+    /** The local date of an instant in the scale's zone. */
+    dateOf(t: TimeInput): IsoDate;
+    /** Epoch ms of local midnight of a date in the scale's zone. */
+    startOfDate(date: IsoDate): number;
+}
+/** Resolves a `TimeInput` to epoch ms; date-only strings are local midnight in `timeZone`. */
+export declare function toEpoch(t: TimeInput, timeZone?: string): number;
+/**
+ * Creates a time scale.
+ *
+ * ```ts
+ * const scale = createTimeScale({ start: "2026-11-01", end: "2026-12-01", scale: "day", timeZone: "Europe/Istanbul", locale: "tr-TR" });
+ * scale.toPx("2026-11-02"); // 44
+ * scale.ticks("week");      // week columns starting Monday
+ * ```
+ */
+export declare function createTimeScale(options: TimeScaleOptions): TimeScale;
+/** Converts a minute offset into "HH:mm" (wall clock), e.g. for drag labels. */
+export declare function minutesToClock(minutes: number): string;
+/** Parses "HH:mm" into minutes since midnight. */
+export declare function clockToMinutes(clock: string): number;