@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/scheduler/state.js

@@ -0,0 +1,496 @@
+// Ported from @malva-ui/scheduler (src/lib/scheduler/scheduler.ts models, computeds and public methods,
+// src/lib/scheduler/scheduler-context.ts `commitChange` / `announce`), MIT, © 2026 Malva UI.
+// Rivet:
+// - Angular `model()` / `input()` / `computed()` on a component class → `createSchedulerState(props)`: plain data
+//   (region state) of `controllable` values (`events`, `view`, `date`), the caller's option values / accessors as
+//   given (never wrapped: closures built in a `.ts` module do not resume) and interaction signals holding strings /
+//   numbers only. Derived values are pure free functions over the state (`schedulerVisibleRange(state)`,
+//   `schedulerTitle(state)`, `schedulerMonthLayout(…)`, …); components memoize them in `computed`s of their own
+//   (`.tsx`, resumable), so the server-rendered layout is rebuilt from serialized inputs.
+// - Methods → free functions: `next()` → `schedulerNext(state)`, `previous()` → `schedulerPrevious`, `goToToday()` →
+//   `schedulerToday`, `goTo(d)` → `schedulerGoTo`, `setView(v)` → `schedulerSetView`, `scrollToTime(t)` →
+//   `schedulerScrollToTime`; `commitChange(kind, normalized, next, source)` → `commitChange(state, change)`.
+// - `MlvDateAdapter` → integer layout (`dates.ts`); written-back dates keep the form of the value they replace.
+// - Announcements: malva's two alternating polite regions → `announcement` signal pair (`schedulerAnnounce`), the
+//   root renders them (kept over the cdk `announcer`, T8 ruling: server-rendered regions exist before the first
+//   message — no Safari 100 ms creation skip — and a repeat is still a change, the two-slot rule).
+// Deviation: `onVisibleRangeChange` fires when a state function moves the range bounds (toolbar, keys, API) — not on
+// init (the initial range belongs to the route loader: no client work at load) and not for writes the caller makes
+// to its own `date` / `view` signal (the caller made that change).
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { DEV, devWhere } from "#dev";
+import { controllable, controlledValue, setControlledValue } from "../interactions/controllable.js";
+import { CalendarDate } from "../date/CalendarDate.js";
+import { getDayOfWeek, getLocalTimeZone, isWeekend } from "../date/queries.js";
+import { addCalendarMonths, civilFromDay, dayFromCivil, dayOf, dayOfWeek, formatDay, formatWall, fromLayout, minuteOf, todayDay, toWallMinutes, } from "./dates.js";
+import { assignLanes, clusterColumns, computeVisibleRange, layoutRow, nextVisibleDate, normalizeEvents, rowLength as computeRowLength, sliceColumns, sliceRows, visibleDays, } from "./layout.js";
+import { schedulerString, schedulerStrings } from "./intl.js";
+import { MINUTES_PER_DAY, parseTime } from "./time.js";
+import { schedulerDaysKey, schedulerSelectionBounds } from "./selection.js";
+export * from "./selection.js";
+const read = (value) => (typeof value === "function" ? value() : value);
+/** Lanes per month row / all-day band when `visibleLanes` is `"auto"` (malva's fallback before measuring). */
+export const DEFAULT_VISIBLE_LANES = 3;
+const isServer = () => typeof document === "undefined";
+/** Creates the scheduler state (region state: a re-created region of a resumed page keeps it). */
+export function createSchedulerState(props = {}) {
+    return _regionState(() => {
+        const { events, defaultEvents, onEventsChange, view, defaultView, onViewChange, date, defaultDate, onDateChange, canMove, canResize, onEventMove, onEventResize, onVisibleRangeChange, onRangeSelect, onExternalDrop, onEventAction, onEventDoubleClick, onEventContextMenu, onEventDelete, onSlotAction, onSlotDoubleClick, onSlotContextMenu, ...options } = props;
+        const given = untrack(() => read(options.timeZone));
+        const zone = defaultTimeZone();
+        if (DEV && given === undefined && isServer() && !warnedZone) {
+            warnedZone = true;
+            console.warn('[rivet:cdk] scheduler: no `timeZone` on a server-rendered Scheduler: the page lays out in "UTC" (the server\'s ' +
+                "default, kept on the resumed page). Pass `timeZone` (e.g. the user's zone from a cookie) for local time." +
+                devWhere());
+        }
+        const timeZone = given ?? zone;
+        return {
+            events: controllable(events, defaultEvents ?? [], onEventsChange),
+            view: controllable(view, defaultView ?? "month", onViewChange),
+            date: controllable(date, defaultDate ?? todayString(timeZone), onDateChange),
+            options,
+            zone,
+            canMove,
+            canResize,
+            onEventMove,
+            onEventResize,
+            onVisibleRangeChange,
+            onRangeSelect,
+            onExternalDrop,
+            onEventAction,
+            onEventDoubleClick,
+            onEventContextMenu,
+            onEventDelete,
+            onSlotAction,
+            onSlotDoubleClick,
+            onSlotContextMenu,
+            selection: signal(null),
+            dragPreview: signal(null),
+            dragging: signal(false),
+            scrollRequest: signal(null),
+            pendingFocus: signal(null),
+            popoverDay: signal(null),
+            announcement: signal(["", ""]),
+        };
+    });
+}
+let warnedZone = false;
+function defaultTimeZone() {
+    return isServer() ? "UTC" : getLocalTimeZone();
+}
+function todayString(timeZone) {
+    const [y, m, d] = civilFromDay(todayDay(timeZone));
+    return new CalendarDate(y, m, d).toString();
+}
+// ─── Options ───────────────────────────────────────────────────────────────
+/** The layout zone: `timeZone`, else the zone resolved when the state was created (`state.zone`). */
+export function schedulerTimeZone(state) {
+    return read(state.options.timeZone) ?? state.zone;
+}
+/** The locale. */
+export function schedulerLocale(state) {
+    return read(state.options.locale) ?? "en-US";
+}
+const DAY_OF_WEEK = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+const localeWeek = new Map();
+function weekInfo(locale) {
+    let info = localeWeek.get(locale);
+    if (!info) {
+        // 1970-01-04 is a Sunday (weekday 0).
+        const sunday = new CalendarDate(1970, 1, 4);
+        const first = (7 - getDayOfWeek(sunday, locale)) % 7;
+        const weekend = [];
+        for (let i = 0; i < 7; i++)
+            if (isWeekend(sunday.add({ days: i }), locale))
+                weekend.push(i);
+        if (localeWeek.size >= 64)
+            localeWeek.clear();
+        localeWeek.set(locale, (info = { first, weekend }));
+    }
+    return info;
+}
+/** First day of the week, 0 = Sunday (`firstDayOfWeek` or the locale's). */
+export function schedulerFirstDay(state) {
+    const first = read(state.options.firstDayOfWeek);
+    return first ? DAY_OF_WEEK[first] : weekInfo(schedulerLocale(state)).first;
+}
+/** Weekend weekdays (`weekendDays` or the locale's). */
+export function schedulerWeekendDays(state) {
+    return read(state.options.weekendDays) ?? weekInfo(schedulerLocale(state)).weekend;
+}
+/** `hiddenDays` (raw; layout functions repair it). */
+export function schedulerHiddenDays(state) {
+    return read(state.options.hiddenDays) ?? [];
+}
+/** Slot duration in minutes. */
+export function schedulerSlotDuration(state) {
+    return read(state.options.slotDuration) ?? 30;
+}
+/** Effective snap: `snapDuration` or `slotDuration`. */
+export function schedulerSnap(state) {
+    return read(state.options.snapDuration) ?? schedulerSlotDuration(state);
+}
+/** `defaultEventDuration` in minutes. */
+export function schedulerDefaultDuration(state) {
+    return read(state.options.defaultEventDuration) ?? 60;
+}
+/** Lane cap of month rows (the time grid's all-day band never collapses: it passes `Infinity`). */
+export function schedulerVisibleLanes(state) {
+    const lanes = read(state.options.visibleLanes);
+    return lanes === undefined || lanes === "auto" ? DEFAULT_VISIBLE_LANES : lanes;
+}
+/** Whether move / resize / delete are allowed (scheduler level). */
+export function schedulerEditable(state) {
+    return !read(state.options.isReadOnly);
+}
+/** Whether the now-line / today highlight shows. */
+export function schedulerShowsCurrentTime(state) {
+    return read(state.options.showCurrentTime) ?? true;
+}
+/**
+ * `[minTime, maxTime)` as minutes of day, validated as one pair: a window that is not strictly ascending would write
+ * `NaN%` / `Infinity%` geometry, so it fails loudly (malva text).
+ */
+export function schedulerTimeWindow(state) {
+    const minTime = read(state.options.minTime) ?? "00:00";
+    const maxTime = read(state.options.maxTime) ?? "24:00";
+    const min = parseTime(minTime);
+    const max = parseTime(maxTime);
+    if (max <= min)
+        throw new Error(`[rivet:cdk] scheduler: Invalid scheduler time window "${minTime}"–"${maxTime}". minTime must be earlier than maxTime.`);
+    return { min, max };
+}
+/** Resolved strings (locale table + `strings` overrides). */
+export function schedulerStringTable(state) {
+    return schedulerStrings(schedulerLocale(state), read(state.options.strings));
+}
+/** One translated message (`schedulerString` over the resolved table). */
+export function schedulerTranslate(state, key, vars) {
+    return schedulerString(schedulerStringTable(state), key, vars, schedulerLocale(state));
+}
+// ─── Derived values (pure; components memoize them) ────────────────────────
+/** Day number of the anchor date (today when it does not parse). */
+export function schedulerAnchorDay(state, date = state.date.value()) {
+    const wall = toWallMinutes(date, schedulerTimeZone(state));
+    return wall === null ? todayDay(schedulerTimeZone(state)) : dayOf(wall);
+}
+/** The rendered period in day numbers. */
+export function schedulerDayRange(state, view = state.view.value(), date) {
+    return computeVisibleRange(view, schedulerAnchorDay(state, date ?? state.date.value()), schedulerFirstDay(state));
+}
+/** The rendered period, dates in the form of the anchor date (malva public `visibleRange`). */
+export function schedulerVisibleRange(state) {
+    return toDateRange(state, schedulerDayRange(state), state.date.value());
+}
+function toDateRange(state, range, like) {
+    const timeZone = schedulerTimeZone(state);
+    return { view: range.view, start: fromLayout(range.start, 0, like, timeZone, true), end: fromLayout(range.end, 0, like, timeZone, true) };
+}
+/**
+ * Days rendered by the active view, after `hiddenDays`. In the day view `hiddenDays` steers navigation but never
+ * blanks the grid: an anchor on a hidden weekday renders that day as asked.
+ */
+export function schedulerDays(state, range = schedulerDayRange(state)) {
+    const days = visibleDays(range, schedulerHiddenDays(state));
+    return days.length === 0 && range.view === "day" ? visibleDays(range, []) : days;
+}
+/** Visible days per month week row. */
+export function schedulerRowLength(state) {
+    return computeRowLength(schedulerHiddenDays(state));
+}
+/** Localized title: month-year, "Aug 31 – Sep 6, 2026", or the full day label. */
+export function schedulerTitle(state) {
+    const locale = schedulerLocale(state);
+    const range = schedulerDayRange(state);
+    const anchor = schedulerAnchorDay(state);
+    switch (range.view) {
+        case "month":
+            return formatDay(anchor, locale, { month: "long", year: "numeric" });
+        case "week":
+            return (formatDay(range.start, locale, { day: "numeric", month: "short" }) +
+                " – " +
+                formatDay(range.end - 1, locale, { day: "numeric", month: "short", year: "numeric" }));
+        case "day":
+            return formatDay(anchor, locale, { weekday: "long", year: "numeric", month: "long", day: "numeric" });
+    }
+}
+/** `events` normalized (wall minutes in `timeZone`; unparsable dates dropped, dev warning once per event object). */
+export function schedulerNormalizedEvents(state) {
+    const events = state.events.value();
+    const normalized = normalizeEvents(events, schedulerDefaultDuration(state), schedulerTimeZone(state));
+    if (DEV && normalized.length < events.length)
+        warnUnplaced(events, normalized);
+    return normalized;
+}
+let warned;
+function warnUnplaced(events, normalized) {
+    const placed = new Set(normalized.map((n) => n.event));
+    for (const event of events) {
+        if (placed.has(event) || (warned ??= new WeakSet()).has(event))
+            continue;
+        warned.add(event);
+        console.warn(`[rivet:cdk] scheduler: event "${event.id}" is not shown: its start / end does not parse as a date (${String(event.start)} – ${String(event.end)}).` +
+            devWhere());
+    }
+}
+/** Ghost id suffix of the drag preview copy. */
+export const GHOST_SUFFIX = "__rv-ghost";
+/**
+ * `normalized` plus the drag preview ghost (a copy of the dragged event at its would-be dates, `ghost: true`, id
+ * suffixed with `GHOST_SUFFIX`) while a gesture is in flight.
+ */
+export function schedulerWithPreview(state, normalized) {
+    const preview = state.dragPreview();
+    if (!preview)
+        return normalized;
+    const source = normalized.find((n) => n.event.id === preview.id);
+    if (!source)
+        return normalized;
+    const ghost = {
+        event: { ...source.event, id: source.event.id + GHOST_SUFFIX },
+        start: preview.start,
+        end: preview.end,
+        allDay: preview.allDay,
+        ghost: true,
+    };
+    return [...normalized, ghost];
+}
+/** Month rows → lane-packed segments with the lane budget applied (server-exact: no measurement). */
+export function schedulerMonthLayout(events, days, rowLength, visibleLanes) {
+    const segments = sliceRows(events, days, rowLength, "all");
+    const byRow = [];
+    for (const segment of segments)
+        (byRow[Math.floor(segment.startIndex / rowLength)] ??= []).push(segment);
+    const rows = [];
+    for (let row = 0; row * rowLength < days.length; row++) {
+        const rowSegments = byRow[row] ?? [];
+        rows.push({
+            index: row,
+            startIndex: row * rowLength,
+            endIndex: Math.min(days.length, (row + 1) * rowLength) - 1,
+            segments: rowSegments,
+            layout: layoutRow(assignLanes(rowSegments), visibleLanes),
+        });
+    }
+    return rows;
+}
+/** Time-grid layout (lanes for all-day / ≥ 24 h events, clusters for timed ones). */
+export function schedulerTimeGridLayout(events, days, window, visibleLanes) {
+    const lanes = assignLanes(sliceRows(events, days, Math.max(1, days.length), "lane"));
+    const columns = days.map(() => []);
+    for (const segment of clusterColumns(sliceColumns(events, days, window.min, window.max)))
+        columns[segment.dayIndex].push(segment);
+    return { allDay: layoutRow(lanes, visibleLanes), allDaySegments: lanes, columns };
+}
+/** ISO week number (Monday-based) of a day number — month grid week-number column. */
+export function isoWeekNumber(day) {
+    const thursday = day - ((dayOfWeek(day) + 6) % 7) + 3;
+    const [year] = civilFromDay(thursday);
+    return Math.floor((thursday - dayFromCivil(year, 1, 1)) / 7) + 1;
+}
+// ─── Mutations (free functions) ────────────────────────────────────────────
+function emitRange(state, before) {
+    const view = controlledValue(state.view);
+    const date = controlledValue(state.date);
+    const after = schedulerDayRange(state, view, date);
+    if (after.view === before.view && after.start === before.start && after.end === before.end)
+        return;
+    state.onVisibleRangeChange?.(toDateRange(state, after, date));
+    // The single place a period change is announced (malva `_announceRange`): title of the range that just won.
+    schedulerAnnounce(state, schedulerTranslate(state, "rangeChanged", { period: titleFor(state, after, date) }));
+}
+function titleFor(state, range, date) {
+    const locale = schedulerLocale(state);
+    const anchor = schedulerAnchorDay(state, date);
+    return range.view === "month"
+        ? formatDay(anchor, locale, { month: "long", year: "numeric" })
+        : range.view === "week"
+            ? formatDay(range.start, locale, { day: "numeric", month: "short" }) +
+                " – " +
+                formatDay(range.end - 1, locale, { day: "numeric", month: "short", year: "numeric" })
+            : formatDay(anchor, locale, { weekday: "long", year: "numeric", month: "long", day: "numeric" });
+}
+function withRange(state, change) {
+    const before = untrack(() => schedulerDayRange(state, controlledValue(state.view), controlledValue(state.date)));
+    change();
+    untrack(() => emitRange(state, before));
+}
+/** Jumps to `date` (the period containing it becomes visible). */
+export function schedulerGoTo(state, date) {
+    withRange(state, () => setControlledValue(state.date, date));
+}
+/** Switches the view. A switch to the month drops a pending `schedulerScrollToTime` request (no grid to apply it). */
+export function schedulerSetView(state, view) {
+    withRange(state, () => setControlledValue(state.view, view));
+    if (view === "month" && untrack(state.scrollRequest))
+        state.scrollRequest.set(null);
+}
+/** Jumps to today (written in the form of the current anchor). */
+export function schedulerToday(state) {
+    const like = untrack(() => controlledValue(state.date));
+    schedulerGoTo(state, fromLayout(todayDay(schedulerTimeZone(state)), 0, like, schedulerTimeZone(state), true));
+}
+/** Moves one period forward (month / week / day per `view`). */
+export function schedulerNext(state) {
+    step(state, 1);
+}
+/** Moves one period back. */
+export function schedulerPrevious(state) {
+    step(state, -1);
+}
+function step(state, direction) {
+    untrack(() => {
+        const date = controlledValue(state.date);
+        const timeZone = schedulerTimeZone(state);
+        const wall = toWallMinutes(date, timeZone) ?? todayDay(timeZone) * MINUTES_PER_DAY;
+        const day = dayOf(wall);
+        let next;
+        switch (controlledValue(state.view)) {
+            case "month":
+                next = addCalendarMonths(day, direction);
+                break;
+            case "week":
+                next = day + 7 * direction;
+                break;
+            case "day":
+                // A single-day range on a hidden weekday would render nothing, so the day view steps over them.
+                next = nextVisibleDate(day, direction, schedulerHiddenDays(state));
+                break;
+        }
+        schedulerGoTo(state, fromLayout(next, minuteOf(wall), date, timeZone));
+    });
+}
+/**
+ * Scrolls the time grid so `time` (`"HH:mm"`) sits at the top. No-op in the settled month view: a request still
+ * standing at the end of the task while the month shows is dropped (malva rule); a switch to week / day in the same
+ * task still wins.
+ */
+export function schedulerScrollToTime(state, time) {
+    const sequence = (untrack(state.scrollRequest)?.sequence ?? 0) + 1;
+    state.scrollRequest.set({ time, sequence });
+    // The settled view decides (malva constructor effect), not the view at call time: a switch to week / day written
+    // after this call in the same task still wins, a month that is still showing once the task settles drops it — a
+    // request left standing would beat the next time grid's documented initial scroll. No load-time effect: the month
+    // view stays boot-free.
+    queueMicrotask(() => untrack(() => {
+        if (controlledValue(state.view) === "month" && state.scrollRequest()?.sequence === sequence)
+            state.scrollRequest.set(null);
+    }));
+}
+/** Time grid → state: clears the request it applied (a newer request survives). */
+export function consumeScrollRequest(state, sequence) {
+    const current = untrack(state.scrollRequest);
+    if (current && current.sequence === sequence)
+        state.scrollRequest.set(null);
+}
+// ─── Range selection ───────────────────────────────────────────────────────
+/**
+ * The selection as a half-open wall-minute range (malva `_selectionRange`): all-day = midnight of the first day →
+ * midnight after the last; timed = first slot start → end of the last slot, capped at `maxTime` (24:00 = the next
+ * day's midnight).
+ */
+export function schedulerSelectionRange(state, bounds) {
+    return untrack(() => {
+        const days = schedulerDays(state);
+        const first = days[Math.max(0, Math.min(days.length - 1, bounds.dayFrom))];
+        const last = days[Math.max(0, Math.min(days.length - 1, bounds.dayTo))];
+        if (bounds.allDay)
+            return { start: first * MINUTES_PER_DAY, end: (last + 1) * MINUTES_PER_DAY, allDay: true };
+        const end = Math.min(bounds.to + schedulerSlotDuration(state), schedulerTimeWindow(state).max);
+        return { start: first * MINUTES_PER_DAY + bounds.from, end: last * MINUTES_PER_DAY + end, allDay: false };
+    });
+}
+/** Wall minutes → the caller's date form (the anchor date's: string in → string out). */
+export function schedulerDateOf(state, wall, allDay) {
+    return untrack(() => fromLayout(dayOf(wall), minuteOf(wall), state.date.value(), schedulerTimeZone(state), allDay));
+}
+/** Commits the pending selection as `onRangeSelect` and clears it (malva `_commitSelection`). */
+export function commitSelection(state, source) {
+    untrack(() => {
+        const bounds = schedulerSelectionBounds(state.selection(), schedulerDays(state));
+        state.selection.set(null);
+        if (!bounds)
+            return;
+        const range = schedulerSelectionRange(state, bounds);
+        state.onRangeSelect?.({
+            start: schedulerDateOf(state, range.start, range.allDay),
+            end: schedulerDateOf(state, range.end, range.allDay),
+            allDay: range.allDay,
+            source,
+        });
+    });
+}
+/** Per-state live-region bookkeeping (runtime only, never region state): next slot + messages of this task. */
+const liveSlots = new WeakMap();
+/**
+ * Announces `message` politely (malva `announce`): written into the region the previous message did not use, the
+ * other one emptied, so a repeat of the same text is a change the screen reader speaks (two-slot rule). The second and
+ * further messages of one task keep the other region (they share one render: a keyboard move that also leaves the
+ * period announces the move and the new period, and clearing would drop the move).
+ */
+export function schedulerAnnounce(state, message) {
+    const [first, second] = untrack(state.announcement);
+    let live = liveSlots.get(state);
+    if (!live)
+        liveSlots.set(state, (live = { slot: first ? 1 : 0, batch: 0 }));
+    const slot = live.slot;
+    const keepOther = live.batch > 0;
+    live.slot = slot === 0 ? 1 : 0;
+    if (live.batch++ === 0)
+        queueMicrotask(() => (live.batch = 0));
+    state.announcement.set(slot === 0 ? [message, keepOther ? second : ""] : [keepOther ? first : "", message]);
+}
+/**
+ * Applies a move / resize: the veto hook decides (`false` → `moveRejected` announced, nothing written), else the
+ * event is replaced in a new array (`onEventsChange` / the Signal), `onEventMove` / `onEventResize` fire and the
+ * change is announced. Dates are written in the form of the values they replace. Returns whether it was applied.
+ */
+export function commitChange(state, change) {
+    return untrack(() => {
+        const list = controlledValue(state.events);
+        const current = list.find((event) => event.id === change.normalized.event.id);
+        if (!current)
+            return false;
+        const timeZone = schedulerTimeZone(state);
+        const { next } = change;
+        const range = {
+            start: fromLayout(dayOf(next.start), minuteOf(next.start), current.start, timeZone, next.allDay),
+            end: fromLayout(dayOf(next.end), minuteOf(next.end), current.end, timeZone, next.allDay),
+            allDay: next.allDay,
+        };
+        const hook = change.kind === "move" ? state.canMove : state.canResize;
+        if (hook && !hook(current, range)) {
+            schedulerAnnounce(state, schedulerTranslate(state, "moveRejected", { title: current.title }));
+            return false;
+        }
+        const updated = { ...current, start: range.start, end: range.end, allDay: range.allDay };
+        setControlledValue(state.events, list.map((event) => (event.id === updated.id ? updated : event)));
+        const previous = { start: current.start, end: current.end, allDay: change.normalized.allDay };
+        const payload = { event: updated, previous, source: change.source };
+        const locale = schedulerLocale(state);
+        if (change.kind === "move") {
+            state.onEventMove?.(payload);
+            const start = next.allDay ? dateLabel(dayOf(next.start), locale) : dateTimeLabel(next.start, locale);
+            schedulerAnnounce(state, schedulerTranslate(state, "eventMoved", { title: updated.title, start }));
+        }
+        else {
+            state.onEventResize?.(payload);
+            const end = next.allDay ? dateLabel(dayOf(next.end) - 1, locale) : dateTimeLabel(next.end, locale);
+            schedulerAnnounce(state, schedulerTranslate(state, "eventResized", { title: updated.title, end }));
+        }
+        return true;
+    });
+}
+/** Full date label (malva `getDateLabel`). */
+export function dateLabel(day, locale) {
+    return formatDay(day, locale, { weekday: "long", year: "numeric", month: "long", day: "numeric" });
+}
+/** Time of day (malva `formatTime`, e.g. "9:30 AM"). */
+export function timeLabel(wall, locale) {
+    return formatWall(wall, locale, { hour: "numeric", minute: "2-digit" });
+}
+/** Date + time (malva `formatDateTime`), used whenever a label crosses a day boundary. */
+export function dateTimeLabel(wall, locale) {
+    return formatWall(wall, locale, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
+}

package/scheduler/time-grid-client.d.ts

@@ -0,0 +1,32 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { SchedulerState } from "./state.js";
+/**
+ * Pixel offset that puts `minutes` at the top of the viewport (malva `scrollOffsetFor`). `headroomPx` = pixels kept
+ * above the target (half an hour label top-aligned, half the visible region centred); clamped at `0`.
+ */
+export declare function scrollOffsetFor(minutes: number, minMinutes: number, slotDuration: number, slotHeightPx: number, headroomPx?: number): number;
+/** `08:00`, or the business-hours start (malva `_initialMinutes`). */
+export declare function initialMinutes(businessStart: string | undefined): number;
+/** Clamps to the rendered rows and snaps down to a slot start (malva `_snapToSlot`). */
+export declare function snapToSlot(minutes: number, min: number, max: number, slotDuration: number): number;
+interface Axis {
+    min: number;
+    max: number;
+    slot: number;
+}
+/**
+ * Scrolls the time grid (malva `_scrollTo`): `"start"` snaps down to the owning slot and keeps half an hour label of
+ * headroom (the label straddles its line); `"center"` keeps the exact minute and centres it in the region below the
+ * sticky header + all-day band. Nothing measurable → no-op.
+ */
+export declare function scrollTimeGrid(scroller: HTMLElement, minutes: number, axis: Axis, align?: "start" | "center"): void;
+export interface SchedulerTimeGridClientProps {
+    state: SchedulerState<any>;
+    /** The scroll container (`.rv-SchedulerTimeGrid-scroller`). */
+    scroller: () => HTMLElement | undefined | null;
+    /** Wall minutes of the clock (region signal of the grid; `null` until the first tick). */
+    now: Signal<number | null>;
+}
+/** Client effects of the time grid (internal; renders nothing). */
+export declare function SchedulerTimeGridClient(props: SchedulerTimeGridClientProps): null;
+export {};

package/scheduler/time-grid-client.jsx

@@ -0,0 +1,133 @@
+// Ported from @malva-ui/scheduler (src/lib/time-grid/scheduler-time-grid.ts `scrollOffsetFor`, `_initialMinutes`,
+// `_snapToSlot`, `_scrollTo`, the initial-scroll + `scrollRequest` `afterRenderEffect`s; src/lib/scheduler/scheduler.ts
+// minute tick), MIT, © 2026 Malva UI.
+// Rivet: the time grid's only load-time client work, in a leaf module (its chunk imports reactivity, `time.ts` and the
+// zone lookup only — never the view's render graph, `docs/guides/resumability.md` "App guidance"):
+// - initial scroll: one `clientEffect` re-applied when the view / `minTime` / `maxTime` / `slotDuration` /
+//   `scrollToCurrentTime` change (week ↔ day reuse one grid, malva rule);
+// - `schedulerScrollToTime` request: applied once, then consumed (registered after the initial scroll: the later
+//   writer wins in the same tick, malva rule);
+// - the minute clock behind the now-line (`when: "visible"`, ticks only while `showCurrentTime` is on and the tab is
+//   visible (`visibilitychange`); never imports drag code; the server
+//   renders no now-line, so no stale time sits in the HTML).
+import { untrack } from "@rivetjs/reactivity";
+import { clientEffect } from "@rivetjs/runtime/dom";
+import { now as zonedNow } from "../date/queries.js";
+import { MINUTES_PER_DAY, parseTime, slotCount } from "./time.js";
+/**
+ * Pixel offset that puts `minutes` at the top of the viewport (malva `scrollOffsetFor`). `headroomPx` = pixels kept
+ * above the target (half an hour label top-aligned, half the visible region centred); clamped at `0`.
+ */
+export function scrollOffsetFor(minutes, minMinutes, slotDuration, slotHeightPx, headroomPx = 0) {
+    return Math.max(0, ((minutes - minMinutes) / slotDuration) * slotHeightPx - headroomPx);
+}
+/** `08:00`, or the business-hours start (malva `_initialMinutes`). */
+export function initialMinutes(businessStart) {
+    return businessStart ? parseTime(businessStart) : 8 * 60;
+}
+/** Clamps to the rendered rows and snaps down to a slot start (malva `_snapToSlot`). */
+export function snapToSlot(minutes, min, max, slotDuration) {
+    const last = min + (slotCount(min, max, slotDuration) - 1) * slotDuration;
+    const clamped = Math.min(last, Math.max(min, minutes));
+    return min + Math.floor((clamped - min) / slotDuration) * slotDuration;
+}
+const read = (value) => (typeof value === "function" ? value() : value);
+function axisOf(state) {
+    const options = state.options;
+    return { min: parseTime(read(options.minTime) ?? "00:00"), max: parseTime(read(options.maxTime) ?? "24:00"), slot: read(options.slotDuration) ?? 30 };
+}
+/** Minutes of day of the wall clock in the scheduler zone. */
+function nowMinutes(state) {
+    const n = zonedNow(read(state.options.timeZone) ?? state.zone);
+    return n.hour * 60 + n.minute;
+}
+/** The current wall minutes (`day * 1440 + minute`) in the scheduler zone. */
+function nowWallMinutes(state) {
+    const n = zonedNow(read(state.options.timeZone) ?? state.zone);
+    return Math.floor(Date.UTC(n.year, n.month - 1, n.day) / 86_400_000) * MINUTES_PER_DAY + n.hour * 60 + n.minute;
+}
+/**
+ * Scrolls the time grid (malva `_scrollTo`): `"start"` snaps down to the owning slot and keeps half an hour label of
+ * headroom (the label straddles its line); `"center"` keeps the exact minute and centres it in the region below the
+ * sticky header + all-day band. Nothing measurable → no-op.
+ */
+export function scrollTimeGrid(scroller, minutes, axis, align = "start") {
+    const slot = scroller.querySelector(".rv-SchedulerTimeGrid-slot");
+    if (!slot)
+        return;
+    if (align === "center") {
+        const top = scroller.querySelector(".rv-SchedulerTimeGrid-top");
+        const target = Math.min(axis.max, Math.max(axis.min, minutes));
+        scroller.scrollTop = scrollOffsetFor(target, axis.min, axis.slot, slot.offsetHeight, (scroller.clientHeight + (top?.offsetHeight ?? 0)) / 2);
+        return;
+    }
+    const label = scroller.querySelector(".rv-SchedulerTimeGrid-hour");
+    scroller.scrollTop = scrollOffsetFor(snapToSlot(minutes, axis.min, axis.max, axis.slot), axis.min, axis.slot, slot.offsetHeight, (label?.offsetHeight ?? 0) / 2);
+}
+/** Client effects of the time grid (internal; renders nothing). */
+export function SchedulerTimeGridClient(props) {
+    const state = props.state;
+    const scroller = props.scroller;
+    const now = props.now;
+    // Initial scroll, re-applied when the axis or the view changes. The clock is read here, untracked, not through the
+    // now-line signal (malva rule: a hidden line never ticks, so its minute would be stale).
+    clientEffect(() => {
+        const element = scroller();
+        state.view.value();
+        const axis = axisOf(state);
+        const centre = !!read(state.options.scrollToCurrentTime);
+        const business = read(state.options.businessHours);
+        if (!element)
+            return;
+        untrack(() => {
+            const minutes = nowMinutes(state);
+            if (centre && minutes >= axis.min && minutes < axis.max)
+                scrollTimeGrid(element, minutes, axis, "center");
+            else
+                scrollTimeGrid(element, initialMinutes(business?.start), axis);
+        });
+    });
+    // `schedulerScrollToTime`: applied once by the live grid, then consumed; only the request is tracked.
+    clientEffect(() => {
+        const request = state.scrollRequest();
+        const element = scroller();
+        if (!request || !element)
+            return;
+        untrack(() => {
+            scrollTimeGrid(element, parseTime(request.time), axisOf(state));
+            if (untrack(state.scrollRequest)?.sequence === request.sequence)
+                state.scrollRequest.set(null);
+        });
+    });
+    // Minute clock of the now-line.
+    clientEffect(() => {
+        if (!(read(state.options.showCurrentTime) ?? true))
+            return void now.set(null);
+        const tick = () => now.set(nowWallMinutes(state));
+        let timeout;
+        let interval;
+        const stop = () => {
+            clearTimeout(timeout);
+            clearInterval(interval);
+            timeout = interval = undefined;
+        };
+        // Ticks on the minute while the tab is visible; a hidden tab runs no timer and catches up on its return.
+        const start = () => {
+            stop();
+            if (document.hidden)
+                return;
+            tick();
+            timeout = setTimeout(() => {
+                tick();
+                interval = setInterval(tick, 60_000);
+            }, 60_000 - (Date.now() % 60_000));
+        };
+        start();
+        document.addEventListener("visibilitychange", start);
+        return () => {
+            stop();
+            document.removeEventListener("visibilitychange", start);
+        };
+    }, { when: "visible" });
+    return null;
+}