@joewinke/jatui 0.41.0 → 0.42.0

package/dist/components/calendar/calendarGrid.js

@@ -0,0 +1,494 @@
+/**
+ * Calendar grid core — the pure half of every jatui date surface.
+ *
+ * CalendarPicker, DatePicker, DateRangePicker (calendar mode), BookingScheduler
+ * and EventCalendar's month switcher all render the same month panel. This
+ * module owns everything about that panel that is not markup, so it can be
+ * unit-tested without a DOM:
+ *
+ * - Local-calendar date math on plain `Date`s (always local midnight) and the
+ *   ISO `YYYY-MM-DD` strings jatui uses at its edges (native `<input
+ *   type="date">` values, `AvailabilityCounts` keys).
+ * - Locale-aware week start (`Intl.Locale#getWeekInfo`, with a region table
+ *   fallback for engines that lack it).
+ * - The month matrix (leading/trailing days from the adjacent months).
+ * - The APG date-grid keyboard model: arrows, Home/End, PageUp/PageDown
+ *   (+Shift for years), clamped to min/max, mirrored for RTL.
+ * - Range state: normalising, membership, band edges, day counts, presets.
+ * - Typed entry: parse and format in the locale's own field order, so en-US
+ *   reads MM/DD/YYYY and en-GB DD/MM/YYYY (never a hardcoded order).
+ *
+ * No `@internationalized/date`: everything here is plain `Date` + `Intl`.
+ */
+const DAY_MS = 86_400_000;
+// ── Date math (local calendar days) ────────────────────────────────────────
+/** Local midnight of `d`. */
+export function startOfDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+export function isSameDay(a, b) {
+    if (!a || !b)
+        return false;
+    return (a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate());
+}
+export function isSameMonth(a, b) {
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+/** `d` plus `n` calendar days (DST-safe: works on the date fields, not ms). */
+export function addDays(d, n) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
+}
+/**
+ * `d` plus `n` months, clamping the day so Jan 31 + 1 month is Feb 28/29
+ * rather than rolling into March.
+ */
+export function addMonths(d, n) {
+    const target = new Date(d.getFullYear(), d.getMonth() + n, 1);
+    const last = daysInMonth(target.getFullYear(), target.getMonth());
+    return new Date(target.getFullYear(), target.getMonth(), Math.min(d.getDate(), last));
+}
+export function startOfMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+export function endOfMonth(d) {
+    return new Date(d.getFullYear(), d.getMonth() + 1, 0);
+}
+export function daysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+/** Whole calendar days from `a` to `b` (positive when `b` is later). */
+export function dayDiff(a, b) {
+    return Math.round((startOfDay(b).getTime() - startOfDay(a).getTime()) / DAY_MS);
+}
+/** First day of the week containing `d`. */
+export function startOfWeek(d, weekStart = 0) {
+    const offset = (d.getDay() - weekStart + 7) % 7;
+    return addDays(d, -offset);
+}
+export function endOfWeek(d, weekStart = 0) {
+    return addDays(startOfWeek(d, weekStart), 6);
+}
+/** Compare by calendar day: negative, 0 or positive. */
+export function compareDays(a, b) {
+    return startOfDay(a).getTime() - startOfDay(b).getTime();
+}
+/** Clamp a day into [min, max] (either bound optional). */
+export function clampDay(d, min, max) {
+    if (min && compareDays(d, min) < 0)
+        return startOfDay(min);
+    if (max && compareDays(d, max) > 0)
+        return startOfDay(max);
+    return startOfDay(d);
+}
+// ── ISO strings ────────────────────────────────────────────────────────────
+/** `YYYY-MM-DD` for the LOCAL calendar day (never `toISOString`, which shifts to UTC). */
+export function toIsoDate(d) {
+    return `${String(d.getFullYear()).padStart(4, '0')}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+/**
+ * Parse `YYYY-MM-DD` as LOCAL midnight (`new Date('2026-03-04')` is UTC
+ * midnight, a day early west of Greenwich). Anything else, or an impossible
+ * date like 2026-02-30, returns null.
+ */
+export function parseIsoDate(s) {
+    if (!s)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(s.trim());
+    if (!m)
+        return null;
+    const y = Number(m[1]);
+    const mo = Number(m[2]) - 1;
+    const day = Number(m[3]);
+    const d = new Date(y, mo, day);
+    if (d.getFullYear() !== y || d.getMonth() !== mo || d.getDate() !== day)
+        return null;
+    return d;
+}
+/** Accept a Date, an ISO string or nothing; always hand back local midnight or null. */
+export function toDay(v) {
+    if (v == null || v === '')
+        return null;
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? null : startOfDay(v);
+    return parseIsoDate(v);
+}
+// ── Locale: week start + labels ────────────────────────────────────────────
+/**
+ * Regions whose week starts on Sunday or Saturday (CLDR `firstDay`). Every
+ * other region starts on Monday. Used only when `Intl.Locale#getWeekInfo` is
+ * missing (Firefox before 2025, older Node).
+ */
+const SUNDAY_REGIONS = new Set([
+    'AG', 'AS', 'BD', 'BR', 'BS', 'BT', 'BW', 'BZ', 'CA', 'CN', 'CO', 'DM', 'DO', 'ET', 'GT', 'GU',
+    'HK', 'HN', 'ID', 'IL', 'IN', 'JM', 'JP', 'KE', 'KH', 'KR', 'LA', 'MH', 'MM', 'MO', 'MT', 'MX',
+    'MZ', 'NI', 'NP', 'PA', 'PE', 'PH', 'PK', 'PR', 'PT', 'PY', 'SA', 'SG', 'SV', 'TH', 'TT', 'TW',
+    'UM', 'US', 'VE', 'VI', 'WS', 'YE', 'ZA', 'ZW'
+]);
+const SATURDAY_REGIONS = new Set(['AE', 'AF', 'BH', 'DJ', 'DZ', 'EG', 'IQ', 'IR', 'JO', 'KW', 'LY', 'OM', 'QA', 'SD', 'SY']);
+/** Likely region for a bare language tag ("en" → US) when the locale has none. */
+const DEFAULT_REGION = {
+    en: 'US', ja: 'JP', zh: 'CN', ko: 'KR', he: 'IL', hi: 'IN', pt: 'BR', ar: 'EG', fa: 'IR', th: 'TH'
+};
+/**
+ * The first day of the week for `locale` (default: the runtime locale).
+ * `Intl.Locale#getWeekInfo` (or the older `weekInfo` getter) when the engine
+ * has it, else the CLDR region table above.
+ */
+export function weekStartForLocale(locale) {
+    let tag = locale;
+    try {
+        tag = tag ?? new Intl.DateTimeFormat().resolvedOptions().locale;
+        const loc = new Intl.Locale(tag);
+        const info = typeof loc.getWeekInfo === 'function' ? loc.getWeekInfo() : loc.weekInfo;
+        if (info && typeof info.firstDay === 'number')
+            return (info.firstDay % 7); // ISO: 7 = Sunday
+        const region = loc.region ?? loc.maximize?.().region ?? DEFAULT_REGION[loc.language];
+        if (region && SUNDAY_REGIONS.has(region))
+            return 0;
+        if (region && SATURDAY_REGIONS.has(region))
+            return 6;
+        return 1;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Resolve a `weekStart` prop: a number wins, `'locale'` (or undefined) asks the locale. */
+export function resolveWeekStart(weekStart, locale) {
+    return typeof weekStart === 'number' ? weekStart : weekStartForLocale(locale);
+}
+/** Weekday column labels in display order, e.g. `['Mo', 'Tu', …]` for a Monday start. */
+export function weekdayLabels(weekStart = 0, locale, width = 'short') {
+    // 2023-01-01 was a Sunday.
+    const shortFmt = new Intl.DateTimeFormat(locale, { weekday: width });
+    const longFmt = new Intl.DateTimeFormat(locale, { weekday: 'long' });
+    return Array.from({ length: 7 }, (_, i) => {
+        const d = new Date(2023, 0, 1 + ((weekStart + i) % 7));
+        return { short: shortFmt.format(d), long: longFmt.format(d) };
+    });
+}
+export function formatMonthYear(d, locale) {
+    return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric' }).format(d);
+}
+/** "Wednesday, March 4, 2026" — the accessible name of a day cell. */
+export function formatLongDate(d, locale) {
+    return new Intl.DateTimeFormat(locale, { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }).format(d);
+}
+/** "Mar 4, 2026" — trigger labels and range chips. */
+export function formatMediumDate(d, locale) {
+    return new Intl.DateTimeFormat(locale, { month: 'short', day: 'numeric', year: 'numeric' }).format(d);
+}
+/**
+ * The weeks of `month` (any date inside it), each exactly seven cells, padded
+ * with days from the adjacent months. `fixedWeeks` always returns six rows so
+ * a panel never changes height between months.
+ */
+export function buildMonthMatrix(month, weekStart = 0, fixedWeeks = false) {
+    const first = startOfMonth(month);
+    const gridStart = startOfWeek(first, weekStart);
+    const total = daysInMonth(first.getFullYear(), first.getMonth());
+    const lead = dayDiff(gridStart, first);
+    const rows = fixedWeeks ? 6 : Math.ceil((lead + total) / 7);
+    const weeks = [];
+    for (let r = 0; r < rows; r++) {
+        const week = [];
+        for (let c = 0; c < 7; c++) {
+            const date = addDays(gridStart, r * 7 + c);
+            week.push({ date, iso: toIsoDate(date), inMonth: isSameMonth(date, first), column: c });
+        }
+        weeks.push(week);
+    }
+    return weeks;
+}
+/**
+ * The day focus moves to for `key`, or null when the key is not a grid key.
+ *
+ * | Key | Move |
+ * |---|---|
+ * | ←/→ | ∓1 day (mirrored in RTL) |
+ * | ↑/↓ | ∓1 week |
+ * | Home/End | first/last day of the week |
+ * | PageUp/PageDown | ∓1 month (Shift: ∓1 year), day clamped to the month length |
+ *
+ * The result is clamped to [min, max]. Disabled dates stay focusable (APG:
+ * they are announced as unavailable rather than skipped), so the caller only
+ * gates selection.
+ */
+export function nextFocusDate(current, key, opts = {}) {
+    const { weekStart = 0, min, max, rtl = false, shiftKey = false } = opts;
+    let next;
+    switch (key) {
+        case 'ArrowLeft':
+            next = addDays(current, rtl ? 1 : -1);
+            break;
+        case 'ArrowRight':
+            next = addDays(current, rtl ? -1 : 1);
+            break;
+        case 'ArrowUp':
+            next = addDays(current, -7);
+            break;
+        case 'ArrowDown':
+            next = addDays(current, 7);
+            break;
+        case 'Home':
+            next = startOfWeek(current, weekStart);
+            break;
+        case 'End':
+            next = endOfWeek(current, weekStart);
+            break;
+        case 'PageUp':
+            next = addMonths(current, shiftKey ? -12 : -1);
+            break;
+        case 'PageDown':
+            next = addMonths(current, shiftKey ? 12 : 1);
+            break;
+        default:
+            return null;
+    }
+    return clampDay(next, min, max);
+}
+/** One predicate out of min/max/weekday/custom rules. */
+export function makeIsDisabled(rules) {
+    const min = toDay(rules.min ?? null);
+    const max = toDay(rules.max ?? null);
+    return (date) => {
+        if (min && compareDays(date, min) < 0)
+            return true;
+        if (max && compareDays(date, max) > 0)
+            return true;
+        if (rules.weekdaysOnly) {
+            const dow = date.getDay();
+            if (dow === 0 || dow === 6)
+                return true;
+        }
+        if (rules.isDateEnabled && !rules.isDateEnabled(date))
+            return true;
+        return false;
+    };
+}
+// ── Ranges ─────────────────────────────────────────────────────────────────
+/** Order a range's ends (a range picked right-to-left is still start ≤ end). */
+export function normalizeRange(range) {
+    const { start, end } = range;
+    if (start && end && compareDays(end, start) < 0)
+        return { start: startOfDay(end), end: startOfDay(start) };
+    return { start: start ? startOfDay(start) : null, end: end ? startOfDay(end) : null };
+}
+export function isInRange(d, range) {
+    if (!range?.start || !range.end)
+        return false;
+    const r = normalizeRange(range);
+    return compareDays(d, r.start) >= 0 && compareDays(d, r.end) <= 0;
+}
+/** Inclusive day count of a complete range, else 0. */
+export function rangeDayCount(range) {
+    if (!range?.start || !range.end)
+        return 0;
+    return Math.abs(dayDiff(range.start, range.end)) + 1;
+}
+export function rangeCellState(d, column, range) {
+    const none = { inRange: false, isStart: false, isEnd: false, bandStart: false, bandEnd: false };
+    if (!range?.start)
+        return none;
+    if (!range.end) {
+        const only = isSameDay(d, range.start);
+        return { inRange: only, isStart: only, isEnd: only, bandStart: only, bandEnd: only };
+    }
+    const r = normalizeRange(range);
+    if (!isInRange(d, r))
+        return none;
+    const isStart = isSameDay(d, r.start);
+    const isEnd = isSameDay(d, r.end);
+    return {
+        inRange: true,
+        isStart,
+        isEnd,
+        bandStart: isStart || column === 0 || d.getDate() === 1,
+        bandEnd: isEnd || column === 6 || isSameDay(d, endOfMonth(d))
+    };
+}
+/**
+ * The next range after clicking `date`, picking ends in order:
+ * no start (or a complete range) → start a new range; a start → close it
+ * (swapping when the second click is earlier).
+ */
+export function pickRangeDate(range, date) {
+    const d = startOfDay(date);
+    if (!range.start || range.end)
+        return { start: d, end: null };
+    return normalizeRange({ start: range.start, end: d });
+}
+export function toIsoRange(range) {
+    return { start: range.start ? toIsoDate(range.start) : null, end: range.end ? toIsoDate(range.end) : null };
+}
+export function fromIsoRange(range) {
+    return { start: toDay(range?.start ?? null), end: toDay(range?.end ?? null) };
+}
+/** Resolve a preset's range against `now`. */
+export function resolvePreset(preset, now = new Date()) {
+    return typeof preset.range === 'function' ? preset.range(now) : preset.range;
+}
+/** Today, Yesterday, Last 7 days, Last 30 days, This month, Last month, This year, Last year. */
+export function defaultRangePresets() {
+    const iso = toIsoDate;
+    return [
+        { id: 'today', label: 'Today', range: (n) => ({ start: iso(n), end: iso(n) }) },
+        { id: 'yesterday', label: 'Yesterday', range: (n) => ({ start: iso(addDays(n, -1)), end: iso(addDays(n, -1)) }) },
+        { id: 'week', label: 'Last 7 days', range: (n) => ({ start: iso(addDays(n, -6)), end: iso(n) }) },
+        { id: 'month', label: 'Last 30 days', range: (n) => ({ start: iso(addDays(n, -29)), end: iso(n) }) },
+        { id: 'this-month', label: 'This month', range: (n) => ({ start: iso(startOfMonth(n)), end: iso(endOfMonth(n)) }) },
+        {
+            id: 'last-month',
+            label: 'Last month',
+            range: (n) => {
+                const prev = addMonths(startOfMonth(n), -1);
+                return { start: iso(prev), end: iso(endOfMonth(prev)) };
+            }
+        },
+        {
+            id: 'this-year',
+            label: 'This year',
+            range: (n) => ({ start: iso(new Date(n.getFullYear(), 0, 1)), end: iso(new Date(n.getFullYear(), 11, 31)) })
+        },
+        {
+            id: 'last-year',
+            label: 'Last year',
+            range: (n) => ({ start: iso(new Date(n.getFullYear() - 1, 0, 1)), end: iso(new Date(n.getFullYear() - 1, 11, 31)) })
+        }
+    ];
+}
+/** The id of the preset `range` equals, if any. */
+export function matchPreset(range, presets, now = new Date()) {
+    for (const p of presets) {
+        const r = resolvePreset(p, now);
+        if (r.start === range.start && r.end === range.end)
+            return p.id;
+    }
+    return null;
+}
+/** The locale's numeric field order, e.g. `['month','day','year']` for en-US. */
+export function dateFieldOrder(locale) {
+    const parts = new Intl.DateTimeFormat(locale, { year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(new Date(2026, 10, 22));
+    const order = parts.map((p) => p.type).filter((t) => t === 'year' || t === 'month' || t === 'day');
+    return order.length === 3 ? order : ['year', 'month', 'day'];
+}
+/** The separator the locale uses between numeric date fields ("/", ".", "-"). */
+export function dateSeparator(locale) {
+    const parts = new Intl.DateTimeFormat(locale, { year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(new Date(2026, 10, 22));
+    const lit = parts.find((p) => p.type === 'literal');
+    return lit ? lit.value.trim() || lit.value : '/';
+}
+/** A placeholder hint, e.g. "MM/DD/YYYY" (en-US) or "DD.MM.YYYY" (de-DE). */
+export function datePlaceholder(locale) {
+    const token = { year: 'YYYY', month: 'MM', day: 'DD' };
+    return dateFieldOrder(locale)
+        .map((f) => token[f])
+        .join(dateSeparator(locale));
+}
+/** Format for the typed-entry field: numeric, zero-padded, locale order. */
+export function formatTypedDate(d, locale) {
+    if (!d)
+        return '';
+    const v = {
+        year: String(d.getFullYear()).padStart(4, '0'),
+        month: String(d.getMonth() + 1).padStart(2, '0'),
+        day: String(d.getDate()).padStart(2, '0')
+    };
+    return dateFieldOrder(locale)
+        .map((f) => v[f])
+        .join(dateSeparator(locale));
+}
+/**
+ * Parse what a person typed. Accepts ISO `YYYY-MM-DD` anywhere, else three
+ * numeric groups in the locale's field order with any separator. Two-digit
+ * years land in 2000–2099. Impossible dates (31/02) return null.
+ */
+export function parseTypedDate(text, locale) {
+    const s = text.trim();
+    if (!s)
+        return null;
+    const iso = parseIsoDate(s);
+    if (iso && /^\d{4}-\d{2}-\d{2}$/.test(s))
+        return iso;
+    const groups = s.split(/[^\d]+/).filter(Boolean);
+    if (groups.length !== 3)
+        return null;
+    const order = dateFieldOrder(locale);
+    const v = { year: 0, month: 0, day: 0 };
+    order.forEach((f, i) => (v[f] = Number(groups[i])));
+    const yearRaw = groups[order.indexOf('year')];
+    if (yearRaw.length <= 2)
+        v.year += 2000;
+    else if (yearRaw.length !== 4)
+        return null;
+    if (v.month < 1 || v.month > 12 || v.day < 1)
+        return null;
+    const d = new Date(v.year, v.month - 1, v.day);
+    if (d.getFullYear() !== v.year || d.getMonth() !== v.month - 1 || d.getDate() !== v.day)
+        return null;
+    return d;
+}
+const ACCENTS = new Set(['primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error', 'neutral']);
+/**
+ * Inline custom properties that re-tint a month panel. `'primary'` (and
+ * anything unknown) returns '' so the jatui selection tokens apply as-is.
+ * The old `accentColor` prop interpolated `bg-${accentColor}` classes, which
+ * Tailwind's scanner never emits; this replaces it with token vars.
+ */
+export function calendarAccentStyle(accent) {
+    if (!accent || accent === 'primary' || !ACCENTS.has(accent))
+        return '';
+    return [
+        `--jatui-cal-accent: var(--color-${accent})`,
+        `--jatui-cal-accent-fg: var(--color-${accent}-content)`,
+        `--jatui-cal-band: color-mix(in oklab, var(--color-${accent}) 14%, transparent)`
+    ].join('; ');
+}
+/**
+ * "Mar 4 – 10, 2026" via `Intl.DateTimeFormat#formatRange` (which collapses
+ * the shared month/year), "From Mar 4, 2026" / "Until …" for open ends, '' for
+ * an empty range.
+ */
+export function formatRangeLabel(range, locale) {
+    const fmt = new Intl.DateTimeFormat(locale, { month: 'short', day: 'numeric', year: 'numeric' });
+    const { start, end } = normalizeRange(range);
+    if (start && end) {
+        if (isSameDay(start, end))
+            return fmt.format(start);
+        const f = fmt;
+        return typeof f.formatRange === 'function' ? f.formatRange(start, end) : `${fmt.format(start)} – ${fmt.format(end)}`;
+    }
+    if (start)
+        return `From ${fmt.format(start)}`;
+    if (end)
+        return `Until ${fmt.format(end)}`;
+    return '';
+}
+/** The default calendar-mode presets plus the "All time" (open) sentinel. */
+export function defaultRangePresetsWithAll() {
+    return [...defaultRangePresets(), { id: 'all', label: 'All time', range: { start: null, end: null } }];
+}
+// ── Panel navigation ───────────────────────────────────────────────────────
+/**
+ * The first visible month after focus moves to `date`, for `months` panels
+ * starting at `viewMonth`: unchanged while the day is on screen, otherwise
+ * the minimum shift that brings it back (it lands in the first panel when
+ * moving backwards, the last when moving forwards).
+ */
+export function followFocus(viewMonth, date, months = 1) {
+    const first = startOfMonth(viewMonth);
+    if (date < first)
+        return startOfMonth(date);
+    const afterLast = addMonths(first, months);
+    if (date >= afterLast)
+        return addMonths(startOfMonth(date), -(months - 1));
+    return first;
+}
+/** Whether the panels may step back / forward without leaving [min, max]. */
+export function canStepMonth(viewMonth, dir, opts = {}) {
+    const { min, max, months = 1 } = opts;
+    const first = startOfMonth(viewMonth);
+    if (dir < 0)
+        return !min || startOfMonth(min) < first;
+    return !max || startOfMonth(max) > addMonths(first, months - 1);
+}

package/dist/components/calendar/createCalendarGrid.d.ts

@@ -0,0 +1,25 @@
+export interface CalendarGridOptions {
+    /** Initial focus day (and month). Defaults to today. */
+    initial?: () => Date | null | undefined;
+    min?: () => Date | null | undefined;
+    max?: () => Date | null | undefined;
+    /** Month panels side by side. */
+    months?: () => number;
+}
+export interface CalendarGrid {
+    /** First visible month (local midnight on the 1st). */
+    readonly viewMonth: Date;
+    /** Every visible month, first to last. */
+    readonly panels: Date[];
+    /** The roving-focus day. */
+    readonly focusedDate: Date;
+    readonly canPrev: boolean;
+    readonly canNext: boolean;
+    /** Move focus (keyboard or pointer); the panels follow if it leaves them. */
+    focus: (date: Date) => void;
+    /** Step the panels by `n` months; focus moves with them, clamped. */
+    shift: (n: number) => void;
+    /** Re-key to a date (e.g. when a popover opens on the current value). */
+    reset: (date?: Date | null) => void;
+}
+export declare function createCalendarGrid(opts?: CalendarGridOptions): CalendarGrid;

package/dist/components/calendar/createCalendarGrid.js

@@ -0,0 +1,57 @@
+/* createCalendarGrid.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+
+import {
+	addMonths,
+	canStepMonth,
+	clampDay,
+	followFocus,
+	startOfDay,
+	startOfMonth
+} from './calendarGrid';
+
+export function createCalendarGrid(opts = {}) {
+	const min = () => opts.min?.() ?? null;
+	const max = () => opts.max?.() ?? null;
+	const months = () => Math.max(1, opts.months?.() ?? 1);
+	const start = clampDay(opts.initial?.() ?? new Date(), min(), max());
+	let viewMonth = $.state($.proxy(startOfMonth(start)));
+	let focusedDate = $.state($.proxy(startOfDay(start)));
+
+	return {
+		get viewMonth() {
+			return $.get(viewMonth);
+		},
+
+		get panels() {
+			return Array.from({ length: months() }, (_, i) => addMonths($.get(viewMonth), i));
+		},
+
+		get focusedDate() {
+			return $.get(focusedDate);
+		},
+
+		get canPrev() {
+			return canStepMonth($.get(viewMonth), -1, { min: min(), max: max(), months: months() });
+		},
+
+		get canNext() {
+			return canStepMonth($.get(viewMonth), 1, { min: min(), max: max(), months: months() });
+		},
+
+		focus(date) {
+			$.set(focusedDate, startOfDay(date), true);
+			$.set(viewMonth, followFocus($.get(viewMonth), $.get(focusedDate), months()), true);
+		},
+
+		shift(n) {
+			$.set(viewMonth, addMonths($.get(viewMonth), n), true);
+			$.set(focusedDate, clampDay(addMonths($.get(focusedDate), n), min(), max()), true);
+		},
+
+		reset(date) {
+			$.set(focusedDate, clampDay(date ?? new Date(), min(), max()), true);
+			$.set(viewMonth, startOfMonth($.get(focusedDate)), true);
+		}
+	};
+}

package/dist/components/calendar/dayOverlap.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Week/day-view overlap packing.
+ *
+ * Upstreamed from MOS `lib/components/calendar/shared/dayOverlap.ts`
+ * (jatui-lfxyy) with its tests; generic over any `PackableEvent`.
+ *
+ * Month view stacks intervals across seven discrete day columns into vertical
+ * lanes (`monthPacking.ts`). Week and day view have the same interval-graph
+ * problem on the other axis: events run over continuous time inside ONE day
+ * column, so concurrent events have to be sliced into side-by-side
+ * sub-columns. Same shape, different axis — which is why this is a sibling
+ * module rather than a mode flag on `packWeek`.
+ *
+ * The allocator hands out a horizontal slot for every timed event and the grid
+ * renders it as a percentage `left`/`width`, so two meetings at 2pm sit beside
+ * each other instead of one hiding the other.
+ *
+ * The intervals compared here are RENDERED extents, not literal ones. The grid
+ * gives an event with no end a one-hour block and never draws anything shorter
+ * than half an hour, so two five-minute events ten minutes apart really do
+ * collide on screen even though their times do not. Packing the literal times
+ * would call that pair disjoint and stack them back on top of each other.
+ */
+import { type PackableEvent } from "./monthPacking";
+/** Grid block for an event with no end — matches `eventHeightPx`'s 48px. */
+export declare const DEFAULT_DURATION_MIN = 60;
+/** Shortest block the grid will draw — matches `eventHeightPx`'s 24px floor. */
+export declare const MIN_DURATION_MIN = 30;
+export interface DayOverlapOptions {
+    /** Height, in minutes, given to an event with no (or unusable) `end`. */
+    defaultDurationMin?: number;
+    /** Floor applied to every event's rendered height. */
+    minDurationMin?: number;
+    /**
+     * Let an event widen into later sub-columns that nothing overlapping it
+     * occupies. Off makes every event in a cluster exactly `100/columns` wide.
+     */
+    expand?: boolean;
+}
+export interface DayInterval {
+    /** Minutes from local midnight of the event's start. */
+    startMin: number;
+    /** Minutes from that same midnight to the BOTTOM of the rendered block. */
+    endMin: number;
+}
+export interface DayPlacement<E extends PackableEvent = PackableEvent> extends DayInterval {
+    ev: E;
+    /** 0-based index of the transitively-overlapping group this event is in. */
+    cluster: number;
+    /** 0-based sub-column within that cluster. */
+    column: number;
+    /** Sub-columns the cluster was split into. */
+    columns: number;
+    /** Sub-columns this event widens across (>= 1). */
+    span: number;
+    /** CSS `left`, as a percentage of the day column. */
+    leftPct: number;
+    /** CSS `width`, as a percentage of the day column. */
+    widthPct: number;
+}
+/**
+ * The vertical extent the grid will actually draw for `ev`, in minutes.
+ *
+ * `start` is read in local time and measured from its own midnight, so an
+ * event running past midnight simply reports an `endMin` above 1440 rather
+ * than wrapping — the comparisons below only ever need it to be monotonic.
+ */
+export declare function eventInterval(ev: PackableEvent, opts?: DayOverlapOptions): DayInterval;
+/** Half-open overlap: two blocks that merely touch do NOT overlap. */
+export declare function intervalsOverlap(a: DayInterval, b: DayInterval): boolean;
+/**
+ * Split one day's timed events into side-by-side sub-columns.
+ *
+ * Three passes over the events sorted by start time:
+ *
+ * 1. **Cluster.** Walk in start order carrying the furthest end seen; an event
+ *    starting at or after that end can share no space with anything before it,
+ *    so it opens a new cluster. This is exactly the transitive closure of
+ *    "overlaps" — A and C never touching still share a cluster if B bridges
+ *    them, and they must, or the two halves would be scaled differently and
+ *    B would collide with one of them.
+ * 2. **Assign columns.** Greedily take the first sub-column whose last event
+ *    has already ended. On an interval graph this uses exactly as many columns
+ *    as the busiest instant needs — no cluster is ever sliced thinner than the
+ *    real peak concurrency.
+ * 3. **Widen.** Let each event grow rightward while no event in the next
+ *    sub-column overlaps it, so a lone 4pm event beside a busy 2pm stack still
+ *    reads full width. This cannot reintroduce a collision: for A to widen
+ *    past column c it must be disjoint from everything in column c, and any B
+ *    widening out of column c is in column c.
+ */
+export declare function layoutDay<E extends PackableEvent>(events: E[], opts?: DayOverlapOptions): DayPlacement<E>[];