@bimetal/temporal 0.35.0

package/dist/datetime.js

@@ -0,0 +1,289 @@
+/**
+ * CalendarDateTime — creation, arithmetic, and queries.
+ *
+ * Internal representation: UTC epoch milliseconds + IANA timezone string.
+ *
+ * Two arithmetic models, named by contract (not by accident):
+ *  - CIVIL   (addDays / addWeeks / addMonths / addYears): wall-clock preserving
+ *            and DST-safe. "Add 1 unit" means "same wall-clock time, one unit
+ *            later", even when the elapsed time differs (a DST day is 23 or 25h).
+ *  - ELAPSED (addHours / addMinutes): exact physical milliseconds. A duration is
+ *            a physical quantity, so across a DST transition the wall clock may
+ *            shift. This is intentional — durations and timeline drags rely on it
+ *            (a 60-minute event stays 60 minutes), NOT a missing DST fix.
+ */
+import { CalendarValidationError } from './errors.js';
+import { MS_PER_MINUTE, MS_PER_HOUR, MS_PER_EXACT_DAY, MINUTES_PER_HOUR, } from './constants.js';
+// ── Timezone helpers (Intl-based, no external deps) ─────────────
+/** Cache for Intl.DateTimeFormat instances. */
+const formatCache = new Map();
+function getFormatter(timezone) {
+    let fmt = formatCache.get(timezone);
+    if (!fmt) {
+        try {
+            fmt = new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                year: 'numeric',
+                month: 'numeric',
+                day: 'numeric',
+                hour: 'numeric',
+                minute: 'numeric',
+                second: 'numeric',
+                hour12: false,
+            });
+        }
+        catch {
+            throw new CalendarValidationError({ type: 'INVALID_TIMEZONE', timezone });
+        }
+        formatCache.set(timezone, fmt);
+    }
+    return fmt;
+}
+/** Parse Intl.DateTimeFormat parts into components. */
+function getWallClockParts(epochMs, timezone) {
+    const fmt = getFormatter(timezone);
+    const parts = fmt.formatToParts(new Date(epochMs));
+    const get = (type) => Number(parts.find(p => p.type === type).value);
+    return {
+        year: get('year'),
+        month: get('month') - 1, // 0-based
+        day: get('day'),
+        hour: get('hour') === 24 ? 0 : get('hour'),
+        minute: get('minute'),
+        second: get('second'),
+    };
+}
+/**
+ * Convert wall-clock time in a timezone to UTC epoch milliseconds.
+ * Handles DST gaps by snapping forward to the first valid instant.
+ * Handles DST overlaps by preferring the earlier occurrence.
+ */
+function wallClockToEpochMs(year, month, day, hour, minute, timezone) {
+    // Try two offsets: the one before and after a potential DST transition.
+    // We sample the offset at two known-good points: midnight of the requested
+    // day and noon. One of them should be on the correct side of any transition.
+    const midnightUtc = Date.UTC(year, month, day, 0, 0, 0, 0);
+    const noonUtc = Date.UTC(year, month, day, 12, 0, 0, 0);
+    const offsetAtMidnight = getUtcOffset(midnightUtc, timezone);
+    const offsetAtNoon = getUtcOffset(noonUtc, timezone);
+    // Try both offsets and see which gives the correct wall-clock time
+    const candidates = [offsetAtMidnight, offsetAtNoon];
+    // Remove duplicates
+    const uniqueOffsets = [...new Set(candidates)];
+    const requestedMinutes = hour * MINUTES_PER_HOUR + minute;
+    for (const offset of uniqueOffsets) {
+        const epochMs = Date.UTC(year, month, day, hour, minute, 0, 0) - offset;
+        const verify = getWallClockParts(epochMs, timezone);
+        if (verify.year === year && verify.month === month && verify.day === day
+            && verify.hour === hour && verify.minute === minute) {
+            return epochMs;
+        }
+    }
+    // DST gap: requested time doesn't exist.
+    // Snap forward: try with the pre-transition offset (typically midnight's).
+    // This produces a UTC instant that, when interpreted in the timezone,
+    // lands on the post-gap wall-clock time (e.g., 02:30 CET → 03:30 CEST).
+    const preTransitionOffset = offsetAtMidnight;
+    const snapped = Date.UTC(year, month, day, hour, minute, 0, 0) - preTransitionOffset;
+    return snapped;
+}
+/** Get the UTC offset in milliseconds for a given instant in a timezone. */
+function getUtcOffset(epochMs, timezone) {
+    const wall = getWallClockParts(epochMs, timezone);
+    const wallAsUtc = Date.UTC(wall.year, wall.month, wall.day, wall.hour, wall.minute, wall.second);
+    return wallAsUtc - epochMs;
+}
+/** Number of days in a 0-based month of a year (leap-year aware). Timezone-agnostic:
+ *  only the day component of the constructed local date is read. */
+function daysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+// ── Creation ────────────────────────────────────────────────────
+/** Create a CalendarDateTime from wall-clock components in a timezone. */
+export function createDateTime(year, month, day, hour, minute, timezone) {
+    // Reject NaN, Infinity, non-integer for all numeric components
+    if (!Number.isInteger(year))
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'year', message: `year must be an integer, got ${year}` });
+    if (!Number.isInteger(month) || month < 0 || month > 11)
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'month', message: `month must be 0-11, got ${month}` });
+    if (!Number.isInteger(hour) || hour < 0 || hour > 23)
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'hour', message: `hour must be 0-23, got ${hour}` });
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59)
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'minute', message: `minute must be 0-59, got ${minute}` });
+    // Validate day against actual month length
+    if (!Number.isInteger(day) || day < 1)
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'day', message: `day must be >= 1, got ${day}` });
+    const maxDay = daysInMonth(year, month); // last day of month
+    if (day > maxDay)
+        throw new CalendarValidationError({ type: 'INVALID_EVENT', field: 'day', message: `day ${day} does not exist in month ${month} of year ${year} (max: ${maxDay})` });
+    const epochMs = wallClockToEpochMs(year, month, day, hour, minute, timezone);
+    return { epochMs, timezone };
+}
+/** Create a CalendarDateTime from a UTC epoch and timezone. */
+export function fromEpochMs(epochMs, timezone) {
+    if (!Number.isFinite(epochMs)) {
+        throw new CalendarValidationError({
+            type: 'INVALID_TIME_RANGE',
+            message: 'epochMs must be a finite number',
+        });
+    }
+    // Validate timezone by attempting to use it
+    getFormatter(timezone);
+    return { epochMs, timezone };
+}
+/** Get the current time in a timezone. Uses config.clock if provided. */
+export function now(timezone, clock) {
+    const epochMs = clock ? clock.now() : Date.now();
+    return fromEpochMs(epochMs, timezone);
+}
+// ── Civil (wall-clock) arithmetic — days and up, DST-safe ───────
+/**
+ * Add days, preserving wall-clock time (DST-safe).
+ *
+ * "Add 1 day" means "same time tomorrow", not "+24 hours".
+ * On a DST transition day, the actual elapsed time may be 23 or 25 hours.
+ */
+export function addDays(dt, n) {
+    const wall = getWallClockParts(dt.epochMs, dt.timezone);
+    const epochMs = wallClockToEpochMs(wall.year, wall.month, wall.day + n, wall.hour, wall.minute, dt.timezone);
+    return { epochMs, timezone: dt.timezone };
+}
+/**
+ * Add weeks (n × 7 days), preserving wall-clock time. DST-safe. A CIVIL unit:
+ * delegates to addDays, so "add 1 week" means "same weekday and time, seven
+ * days later", not "+168 hours".
+ */
+export function addWeeks(dt, n) {
+    return addDays(dt, n * 7);
+}
+/**
+ * Add calendar months, preserving wall-clock time, with year carry. DST-safe.
+ *
+ * "Add 1 month" means "same day-of-month next month", not "+30 days". The
+ * day-of-month is clamped to the target month's length (31 Jan + 1 month →
+ * 28/29 Feb, never 3 March). Negative n and multi-year carry are handled via
+ * integer division, so December + 1 → January of the next year. Symmetric to
+ * addDays: computed through the wall-clock helpers, not naive epoch arithmetic.
+ */
+export function addMonths(dt, n) {
+    const wall = getWallClockParts(dt.epochMs, dt.timezone);
+    const totalMonths = wall.year * 12 + wall.month + n;
+    const year = Math.floor(totalMonths / 12);
+    const month = totalMonths - year * 12; // 0-11, non-negative even for negative n
+    const day = Math.min(wall.day, daysInMonth(year, month));
+    const epochMs = wallClockToEpochMs(year, month, day, wall.hour, wall.minute, dt.timezone);
+    return { epochMs, timezone: dt.timezone };
+}
+/**
+ * Add calendar years, preserving wall-clock time. DST-safe. A CIVIL unit:
+ * delegates to addMonths (n × 12 months), so the day-of-month is clamped to the
+ * target month's length (29 Feb + 1 year → 28 Feb in a non-leap year).
+ */
+export function addYears(dt, n) {
+    return addMonths(dt, n * 12);
+}
+// ── Elapsed (physical) time — hours and minutes ─────────────────
+// These add exact elapsed milliseconds. ELAPSED, not civil, BY CONTRACT: a
+// duration is a physical quantity, so across a DST transition the wall clock
+// may shift. For calendar-unit arithmetic use the CIVIL functions above.
+/**
+ * Add exact elapsed hours (n × 3 600 000 ms). ELAPSED semantics by contract:
+ * a physical duration, so across a DST transition the wall-clock hour shifts.
+ * For "same time n hours later" use civil day/week/month/year arithmetic.
+ */
+export function addHours(dt, n) {
+    return { epochMs: dt.epochMs + n * MS_PER_HOUR, timezone: dt.timezone };
+}
+/**
+ * Add exact elapsed minutes (n × 60 000 ms). ELAPSED semantics by contract —
+ * see addHours. Event durations and timeline drags depend on this being physical
+ * time (a 60-minute event stays 60 minutes across a DST change).
+ */
+export function addMinutes(dt, n) {
+    return { epochMs: dt.epochMs + n * MS_PER_MINUTE, timezone: dt.timezone };
+}
+/** Re-interpret the same instant in a different timezone. */
+export function withTimezone(dt, timezone) {
+    getFormatter(timezone); // validate
+    return { epochMs: dt.epochMs, timezone };
+}
+/** Get 00:00:00.000 of the day containing dt, in dt's timezone. */
+export function startOfDay(dt) {
+    const wall = getWallClockParts(dt.epochMs, dt.timezone);
+    const epochMs = wallClockToEpochMs(wall.year, wall.month, wall.day, 0, 0, dt.timezone);
+    return { epochMs, timezone: dt.timezone };
+}
+/** Get 23:59:59.999 of the day containing dt, in dt's timezone. */
+export function endOfDay(dt) {
+    const wall = getWallClockParts(dt.epochMs, dt.timezone);
+    const epochMs = wallClockToEpochMs(wall.year, wall.month, wall.day + 1, 0, 0, dt.timezone) - 1;
+    return { epochMs, timezone: dt.timezone };
+}
+// ── Queries ─────────────────────────────────────────────────────
+/** Get the wall-clock year of dt in its own timezone. */
+export function getYear(dt) {
+    return getWallClockParts(dt.epochMs, dt.timezone).year;
+}
+/** Returns 0-based month (0 = January). */
+export function getMonth(dt) {
+    return getWallClockParts(dt.epochMs, dt.timezone).month;
+}
+/** Get the wall-clock day of month (1-based) of dt in its own timezone. */
+export function getDayOfMonth(dt) {
+    return getWallClockParts(dt.epochMs, dt.timezone).day;
+}
+/** Returns the Weekday (Monday = 0 … Sunday = 6). HOUSE convention — NOT ISO-8601 (1–7) and NOT
+ *  JS `Date.getDay()` (0 = Sunday); this remaps getDay's Sunday-first to Monday-first. */
+export function getDayOfWeek(dt) {
+    // We need wall-clock day, not UTC day
+    const wall = getWallClockParts(dt.epochMs, dt.timezone);
+    const wallDate = new Date(wall.year, wall.month, wall.day);
+    const jsWallDay = wallDate.getDay();
+    return (jsWallDay === 0 ? 6 : jsWallDay - 1);
+}
+/** Get the wall-clock hour (0-23) of dt in its own timezone. */
+export function getHours(dt) {
+    return getWallClockParts(dt.epochMs, dt.timezone).hour;
+}
+/** Get the wall-clock minute (0-59) of dt in its own timezone. */
+export function getMinutes(dt) {
+    return getWallClockParts(dt.epochMs, dt.timezone).minute;
+}
+/** Wall-clock minutes since midnight in dt's timezone — `hour*60 + minute`. */
+export function toMinutesOfDay(dt) {
+    const w = getWallClockParts(dt.epochMs, dt.timezone);
+    return w.hour * MINUTES_PER_HOUR + w.minute;
+}
+/** Check if two DateTimes fall on the same calendar day (in their respective timezones). */
+export function isSameDay(a, b) {
+    const wa = getWallClockParts(a.epochMs, a.timezone);
+    const wb = getWallClockParts(b.epochMs, b.timezone);
+    return wa.year === wb.year && wa.month === wb.month && wa.day === wb.day;
+}
+/** Check if a is strictly before b (by epoch instant, not wall-clock day). */
+export function isBefore(a, b) {
+    return a.epochMs < b.epochMs;
+}
+/** Check if a is strictly after b (by epoch instant, not wall-clock day). */
+export function isAfter(a, b) {
+    return a.epochMs > b.epochMs;
+}
+/** Check if a and b refer to the same instant (same epoch, regardless of timezone). */
+export function isEqual(a, b) {
+    return a.epochMs === b.epochMs;
+}
+/**
+ * Count calendar days between two DateTimes (in their respective timezones).
+ * Returns positive if b is after a.
+ * This counts actual calendar days, NOT epochMs / MS_PER_EXACT_DAY — it is DST-safe.
+ */
+export function daysBetween(a, b) {
+    const wa = getWallClockParts(a.epochMs, a.timezone);
+    const wb = getWallClockParts(b.epochMs, b.timezone);
+    // Use UTC dates (no timezone shifts) for a clean day count; safe to divide
+    // by MS_PER_EXACT_DAY here because both endpoints are UTC midnight (no DST).
+    const utcA = Date.UTC(wa.year, wa.month, wa.day);
+    const utcB = Date.UTC(wb.year, wb.month, wb.day);
+    return Math.round((utcB - utcA) / MS_PER_EXACT_DAY);
+}
+//# sourceMappingURL=datetime.js.map

package/dist/datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.js","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"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"}

package/dist/duration.d.ts

@@ -0,0 +1,25 @@
+import type { CalendarDateTime, Duration, TimeRange } from './types.js';
+/** Create a Duration from minutes. */
+export declare function minutes(n: number): Duration;
+/** Create a Duration from hours. */
+export declare function hours(n: number): Duration;
+/** Create a Duration from days (24-hour periods, NOT DST-safe — see MS_PER_EXACT_DAY). */
+export declare function days(n: number): Duration;
+/** Duration between two CalendarDateTimes. */
+export declare function between(a: CalendarDateTime, b: CalendarDateTime): Duration;
+/** Duration of a TimeRange. */
+export declare function duration(range: TimeRange): Duration;
+/** Convert Duration to fractional minutes. */
+export declare function toMinutes(d: Duration): number;
+/** Convert Duration to fractional hours. */
+export declare function toHours(d: Duration): number;
+/** Convert Duration to fractional days (24-hour periods, NOT DST-safe). */
+export declare function toDays(d: Duration): number;
+/**
+ * Length of a TimeRange in fractional minutes. Convenience for the
+ * very common `(range.end.epochMs - range.start.epochMs) / MS_PER_MINUTE`
+ * pattern in interaction/rule code. Composition with `toMinutes(duration(range))`
+ * would do the same thing in two steps.
+ */
+export declare function durationInMinutes(range: TimeRange): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGxE,sCAAsC;AACtC,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,CAE3C;AAED,oCAAoC;AACpC,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,CAEzC;AAED,0FAA0F;AAC1F,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,QAAQ,CAExC;AAED,8CAA8C;AAC9C,wBAAgB,OAAO,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,QAAQ,CAE1E;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAEnD;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE7C;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE3C;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAE1D"}

package/dist/duration.js

@@ -0,0 +1,43 @@
+import { MS_PER_MINUTE, MS_PER_HOUR, MS_PER_EXACT_DAY } from './constants.js';
+/** Create a Duration from minutes. */
+export function minutes(n) {
+    return { ms: n * MS_PER_MINUTE };
+}
+/** Create a Duration from hours. */
+export function hours(n) {
+    return { ms: n * MS_PER_HOUR };
+}
+/** Create a Duration from days (24-hour periods, NOT DST-safe — see MS_PER_EXACT_DAY). */
+export function days(n) {
+    return { ms: n * MS_PER_EXACT_DAY };
+}
+/** Duration between two CalendarDateTimes. */
+export function between(a, b) {
+    return { ms: Math.abs(b.epochMs - a.epochMs) };
+}
+/** Duration of a TimeRange. */
+export function duration(range) {
+    return { ms: range.end.epochMs - range.start.epochMs };
+}
+/** Convert Duration to fractional minutes. */
+export function toMinutes(d) {
+    return d.ms / MS_PER_MINUTE;
+}
+/** Convert Duration to fractional hours. */
+export function toHours(d) {
+    return d.ms / MS_PER_HOUR;
+}
+/** Convert Duration to fractional days (24-hour periods, NOT DST-safe). */
+export function toDays(d) {
+    return d.ms / MS_PER_EXACT_DAY;
+}
+/**
+ * Length of a TimeRange in fractional minutes. Convenience for the
+ * very common `(range.end.epochMs - range.start.epochMs) / MS_PER_MINUTE`
+ * pattern in interaction/rule code. Composition with `toMinutes(duration(range))`
+ * would do the same thing in two steps.
+ */
+export function durationInMinutes(range) {
+    return (range.end.epochMs - range.start.epochMs) / MS_PER_MINUTE;
+}
+//# sourceMappingURL=duration.js.map

package/dist/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,sCAAsC;AACtC,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC;AACnC,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC;AACjC,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC;AACtC,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,OAAO,CAAC,CAAmB,EAAE,CAAmB;IAC9D,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,QAAQ,CAAC,KAAgB;IACvC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,SAAS,CAAC,CAAW;IACnC,OAAO,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC;AAC9B,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,OAAO,CAAC,CAAW;IACjC,OAAO,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC;AAC5B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAC,CAAW;IAChC,OAAO,CAAC,CAAC,EAAE,GAAG,gBAAgB,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgB;IAChD,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC;AACnE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** Typed error union for calendar core operations. */
+export type CalendarError = {
+    readonly type: 'INVALID_TIME_RANGE';
+    readonly message: string;
+} | {
+    readonly type: 'INVALID_TIMEZONE';
+    readonly timezone: string;
+} | {
+    readonly type: 'INVALID_GRANULARITY';
+    readonly minutes: number;
+} | {
+    readonly type: 'INVALID_EVENT';
+    readonly field: string;
+    readonly message: string;
+};
+/** Error thrown by core validation (invalid date components, timezone, granularity, or time range). */
+export declare class CalendarValidationError extends Error {
+    readonly error: CalendarError;
+    /** @param error - The typed error detail; also used to derive `message`. */
+    constructor(error: CalendarError);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAWzF,uGAAuG;AACvG,qBAAa,uBAAwB,SAAQ,KAAK;aAEpB,KAAK,EAAE,aAAa;IADhD,4EAA4E;gBAChD,KAAK,EAAE,aAAa;CAIjD"}

package/dist/errors.js

@@ -0,0 +1,19 @@
+function errorMessage(error) {
+    switch (error.type) {
+        case 'INVALID_TIMEZONE': return `Invalid timezone: ${error.timezone}`;
+        case 'INVALID_GRANULARITY': return `Invalid granularity: ${error.minutes} minutes`;
+        case 'INVALID_TIME_RANGE': return error.message;
+        case 'INVALID_EVENT': return `${error.field}: ${error.message}`;
+    }
+}
+/** Error thrown by core validation (invalid date components, timezone, granularity, or time range). */
+export class CalendarValidationError extends Error {
+    error;
+    /** @param error - The typed error detail; also used to derive `message`. */
+    constructor(error) {
+        super(errorMessage(error));
+        this.error = error;
+        this.name = 'CalendarValidationError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,SAAS,YAAY,CAAC,KAAoB;IACxC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,kBAAkB,CAAC,CAAC,OAAO,qBAAqB,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtE,KAAK,qBAAqB,CAAC,CAAC,OAAO,wBAAwB,KAAK,CAAC,OAAO,UAAU,CAAC;QACnF,KAAK,oBAAoB,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,CAAC;QAChD,KAAK,eAAe,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAClE,CAAC;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAEpB;IAD5B,4EAA4E;IAC5E,YAA4B,KAAoB;QAC9C,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;QADD,UAAK,GAAL,KAAK,CAAe;QAE9C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/format.d.ts

@@ -0,0 +1,13 @@
+import type { CalendarDateTime, Duration, TimeRange, FormatOptions } from './types.js';
+/** Format a CalendarDateTime using Intl.DateTimeFormat. */
+export declare function formatDateTime(dt: CalendarDateTime, options: FormatOptions): string;
+/**
+ * Format a day number label for month grid cells.
+ * Returns just the number for most days, and "1. Mai" (short month name) for the 1st.
+ */
+export declare function formatDayLabel(dt: CalendarDateTime, locale: string): string;
+/** Format a TimeRange. Shows start – end with appropriate formatting. */
+export declare function formatTimeRange(range: TimeRange, options: FormatOptions): string;
+/** Format a Duration in a human-readable way. */
+export declare function formatDuration(d: Duration): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIvF,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAanF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAMhF;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAalD"}

package/dist/format.js

@@ -0,0 +1,51 @@
+import { getDayOfMonth } from './datetime.js';
+import { MS_PER_MINUTE, MINUTES_PER_HOUR } from './constants.js';
+/** Format a CalendarDateTime using Intl.DateTimeFormat. */
+export function formatDateTime(dt, options) {
+    const intlOptions = {
+        timeZone: dt.timezone,
+    };
+    if (options.dateStyle)
+        intlOptions.dateStyle = options.dateStyle;
+    if (options.timeStyle)
+        intlOptions.timeStyle = options.timeStyle;
+    // If neither dateStyle nor timeStyle, default to medium date
+    if (!options.dateStyle && !options.timeStyle) {
+        intlOptions.dateStyle = 'medium';
+    }
+    return new Intl.DateTimeFormat(options.locale, intlOptions).format(new Date(dt.epochMs));
+}
+/**
+ * Format a day number label for month grid cells.
+ * Returns just the number for most days, and "1. Mai" (short month name) for the 1st.
+ */
+export function formatDayLabel(dt, locale) {
+    const d = getDayOfMonth(dt);
+    if (d !== 1)
+        return String(d);
+    const monthName = new Intl.DateTimeFormat(locale, { month: 'short', timeZone: dt.timezone }).format(new Date(dt.epochMs));
+    return `${d}. ${monthName}`;
+}
+/** Format a TimeRange. Shows start – end with appropriate formatting. */
+export function formatTimeRange(range, options) {
+    const start = formatDateTime(range.start, options);
+    const end = formatDateTime(range.end, options);
+    if (start === end)
+        return start;
+    return `${start} – ${end}`;
+}
+/** Format a Duration in a human-readable way. */
+export function formatDuration(d) {
+    const totalMinutes = Math.round(d.ms / MS_PER_MINUTE);
+    const hours = Math.floor(totalMinutes / MINUTES_PER_HOUR);
+    const minutes = totalMinutes % MINUTES_PER_HOUR;
+    const parts = [];
+    if (hours > 0) {
+        parts.push(`${hours} h`);
+    }
+    if (minutes > 0 || parts.length === 0) {
+        parts.push(`${minutes} min`);
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEjE,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,EAAoB,EAAE,OAAsB;IACzE,MAAM,WAAW,GAA+B;QAC9C,QAAQ,EAAE,EAAE,CAAC,QAAQ;KACtB,CAAC;IACF,IAAI,OAAO,CAAC,SAAS;QAAE,WAAW,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACjE,IAAI,OAAO,CAAC,SAAS;QAAE,WAAW,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAEjE,6DAA6D;IAC7D,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC7C,WAAW,CAAC,SAAS,GAAG,QAAQ,CAAC;IACnC,CAAC;IAED,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,EAAoB,EAAE,MAAc;IACjE,MAAM,CAAC,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1H,OAAO,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,KAAgB,EAAE,OAAsB;IACtE,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAE/C,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,GAAG,KAAK,MAAM,GAAG,EAAE,CAAC;AAC7B,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,CAAW;IACxC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,gBAAgB,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,YAAY,GAAG,gBAAgB,CAAC;IAEhD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,MAAM,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/granularity.d.ts

@@ -0,0 +1,13 @@
+import type { CalendarDateTime, Granularity, TimeRange, TimeSlot, SnapStrategy } from './types.js';
+/** Snap a datetime to the granularity grid. */
+export declare function snap(dt: CalendarDateTime, granularity: Granularity, strategy: SnapStrategy): CalendarDateTime;
+/** Generate time slots for a range at the given granularity.
+ *  Contract policies (V1_PUBLIC_CONTRACT §11): the LAST slot is truncated to end
+ *  exactly at `range.end` when the range is not an integer multiple of the
+ *  granularity (final slot width may be shorter — a renderer must not assume
+ *  uniform width); slots advance by ELAPSED milliseconds (§8), not wall-clock,
+ *  so an "hourly" grid drifts off wall-clock hours across a DST transition. */
+export declare function generateSlots(range: TimeRange, granularity: Granularity): TimeSlot[];
+/** Calculate the slot index of a datetime relative to a day start. */
+export declare function slotIndex(dt: CalendarDateTime, dayStart: CalendarDateTime, granularity: Granularity): number;
+//# sourceMappingURL=granularity.d.ts.map

package/dist/granularity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"granularity.d.ts","sourceRoot":"","sources":["../src/granularity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAMnG,+CAA+C;AAC/C,wBAAgB,IAAI,CAClB,EAAE,EAAE,gBAAgB,EACpB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,YAAY,GACrB,gBAAgB,CA8BlB;AAED;;;;;+EAK+E;AAC/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,GAAG,QAAQ,EAAE,CAwBpF;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CACvB,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,WAAW,GACvB,MAAM,CAOR"}

package/dist/granularity.js

@@ -0,0 +1,70 @@
+import { CalendarValidationError } from './errors.js';
+import { getYear, getMonth, getDayOfMonth, createDateTime, addDays, toMinutesOfDay } from './datetime.js';
+import { monthIndex } from './vocabulary.js';
+import { MINUTES_PER_HOUR, MINUTES_PER_DAY, MS_PER_MINUTE } from './constants.js';
+/** Snap a datetime to the granularity grid. */
+export function snap(dt, granularity, strategy) {
+    if (granularity.minutes <= 0) {
+        throw new CalendarValidationError({ type: 'INVALID_GRANULARITY', minutes: granularity.minutes });
+    }
+    const totalMinutes = toMinutesOfDay(dt);
+    const interval = granularity.minutes;
+    let snapped;
+    switch (strategy) {
+        case 'floor':
+            snapped = Math.floor(totalMinutes / interval) * interval;
+            break;
+        case 'ceil':
+            snapped = Math.ceil(totalMinutes / interval) * interval;
+            break;
+        case 'round':
+            snapped = Math.round(totalMinutes / interval) * interval;
+            break;
+    }
+    // Ceil/round past end of day → start of next day
+    if (snapped >= MINUTES_PER_DAY) {
+        return addDays(createDateTime(getYear(dt), monthIndex(getMonth(dt)), getDayOfMonth(dt), 0, 0, dt.timezone), 1);
+    }
+    // Use wall-clock construction (DST-safe) instead of elapsed-time addMinutes
+    const snapH = Math.floor(snapped / MINUTES_PER_HOUR);
+    const snapM = snapped % MINUTES_PER_HOUR;
+    return createDateTime(getYear(dt), monthIndex(getMonth(dt)), getDayOfMonth(dt), snapH, snapM, dt.timezone);
+}
+/** Generate time slots for a range at the given granularity.
+ *  Contract policies (V1_PUBLIC_CONTRACT §11): the LAST slot is truncated to end
+ *  exactly at `range.end` when the range is not an integer multiple of the
+ *  granularity (final slot width may be shorter — a renderer must not assume
+ *  uniform width); slots advance by ELAPSED milliseconds (§8), not wall-clock,
+ *  so an "hourly" grid drifts off wall-clock hours across a DST transition. */
+export function generateSlots(range, granularity) {
+    if (granularity.minutes <= 0) {
+        throw new CalendarValidationError({ type: 'INVALID_GRANULARITY', minutes: granularity.minutes });
+    }
+    const intervalMs = granularity.minutes * MS_PER_MINUTE;
+    const slots = [];
+    let current = range.start.epochMs;
+    let index = 0;
+    while (current < range.end.epochMs) {
+        const next = Math.min(current + intervalMs, range.end.epochMs);
+        slots.push({
+            range: {
+                start: { epochMs: current, timezone: range.start.timezone },
+                end: { epochMs: next, timezone: range.start.timezone },
+            },
+            index,
+        });
+        current = next;
+        index++;
+    }
+    return slots;
+}
+/** Calculate the slot index of a datetime relative to a day start. */
+export function slotIndex(dt, dayStart, granularity) {
+    if (granularity.minutes <= 0) {
+        throw new CalendarValidationError({ type: 'INVALID_GRANULARITY', minutes: granularity.minutes });
+    }
+    const diffMs = dt.epochMs - dayStart.epochMs;
+    const diffMinutes = diffMs / MS_PER_MINUTE;
+    return Math.floor(diffMinutes / granularity.minutes);
+}
+//# sourceMappingURL=granularity.js.map

package/dist/granularity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"granularity.js","sourceRoot":"","sources":["../src/granularity.ts"],"names":[],"mappings":"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"}