@cocoar/vue-calendar 1.18.0 → 2.1.0

package/dist/move-math-vYSpEW-r.js

@@ -0,0 +1,215 @@
+import { Temporal as e } from "@js-temporal/polyfill";
+//#region src/core/types.ts
+function t(e) {
+	return "timeZoneId" in e.start;
+}
+function n(e) {
+	return !("timeZoneId" in e.start);
+}
+function r(t) {
+	let { id: n, start: r, end: a } = t, o = r instanceof e.ZonedDateTime, s = r instanceof e.PlainDate;
+	if (!o && !s) throw TypeError(`[CalendarEvent ${n}] start must be Temporal.ZonedDateTime or Temporal.PlainDate. Got ${r?.constructor?.name ?? typeof r}.`);
+	if (o) try {
+		r.toInstant();
+	} catch (e) {
+		let t = r.timeZoneId;
+		throw TypeError(`[CalendarEvent ${n}] start.timeZoneId='${t}' is not a recognised IANA zone (Temporal threw '${e.message}'). Use a real IANA name like 'Europe/Vienna' / 'America/Los_Angeles'.`, { cause: e });
+	}
+	if (a !== void 0) {
+		let t = a instanceof e.ZonedDateTime, i = a instanceof e.PlainDate;
+		if (!t && !i) throw TypeError(`[CalendarEvent ${n}] end must be Temporal.ZonedDateTime or Temporal.PlainDate. Got ${a?.constructor?.name ?? typeof a}.`);
+		if (o !== t) throw TypeError(`[CalendarEvent ${n}] start and end must be the same shape. Got start=${o ? "ZonedDateTime" : "PlainDate"}, end=${t ? "ZonedDateTime" : "PlainDate"}.`);
+		if (o) {
+			if (e.Instant.compare(r.toInstant(), a.toInstant()) >= 0) throw RangeError(`[CalendarEvent ${n}] end must be strictly after start.`);
+		} else if (e.PlainDate.compare(r, a) >= 0) throw RangeError(`[CalendarEvent ${n}] end must be strictly after start.`);
+	}
+	let c = t.meta;
+	if ((c?.rrule !== void 0 || c?.rdate !== void 0 || c?.exdate !== void 0 || c?.recurrenceId !== void 0) && !i.has(n)) {
+		i.add(n);
+		let e = `[@cocoar/vue-calendar] [CalendarEvent ${n}] meta.rrule / .rdate / .exdate / .recurrenceId is set, but recurrence is not yet wired (Phase 4). The event will render only as a single occurrence at \`start\`. Construct a \`RecurringSeries\` and use \`expandSeries()\` (when available) instead of stuffing rrule into meta.`;
+		typeof console < "u" && console.warn(e);
+	}
+}
+var i = /* @__PURE__ */ new Set(), a = 15, o = class extends Error {
+	disambiguation;
+	constructor(e, t) {
+		super(t), this.name = "DstResolutionError", this.disambiguation = e;
+	}
+};
+function s(t, n) {
+	let r;
+	try {
+		r = e.PlainDateTime.from({
+			year: n.year,
+			month: n.month,
+			day: n.day,
+			hour: n.hour,
+			minute: n.minute,
+			second: n.second ?? 0
+		});
+	} catch {
+		return null;
+	}
+	try {
+		return r.toZonedDateTime(t, { disambiguation: "reject" }), null;
+	} catch {}
+	let i;
+	try {
+		i = r.toZonedDateTime(t, { disambiguation: "earlier" });
+	} catch {
+		return null;
+	}
+	let a = i.toPlainDateTime();
+	return e.PlainDateTime.compare(a, r) === 0 ? "overlap" : "gap";
+}
+function c(e, t, n, r, i, a) {
+	let o = l(t, r, i, e);
+	return {
+		event: t,
+		original: {
+			start: n.start,
+			...n.end === void 0 ? {} : { end: n.end },
+			displayZone: n.displayZone
+		},
+		next: o,
+		target: {
+			...r,
+			date: r.date,
+			minutes: r.minutes,
+			displayZone: r.displayZone,
+			disambiguation: o.disambiguation ?? null
+		},
+		native: a
+	};
+}
+function l(r, i, a, c = "compatible") {
+	if (n(r)) {
+		let t = r.start, n = r.end ?? t.add({ days: 1 }), o = e.PlainDate.from(i.date);
+		if (a === "allDay-resize-start" || a === "month-resize-start") {
+			let t = n.subtract({ days: 1 });
+			return {
+				start: e.PlainDate.compare(o, t) > 0 ? t : o,
+				end: n
+			};
+		}
+		if (a === "allDay-resize-end" || a === "month-resize-end") {
+			let n = t.add({ days: 1 }), r = o.add({ days: 1 });
+			return {
+				start: t,
+				end: e.PlainDate.compare(r, n) < 0 ? n : r
+			};
+		}
+		let s = t.until(n).total({ unit: "days" }), c = o, l = c.add({ days: s });
+		return r.end ? {
+			start: c,
+			end: l
+		} : { start: c };
+	}
+	if (!t(r)) throw TypeError(`[applyMoveToEvent] event ${r.id} has unrecognised start shape`);
+	let l = r.start.timeZoneId, u = r.end?.timeZoneId ?? l, d = r.start, f = r.end ?? null, p = e.PlainDate.from(i.date);
+	if (i.minutes === null && (a === "timed" || a === "timed-resize-start" || a === "timed-resize-end")) throw TypeError(`[applyMoveToEvent] timed event ${r.id} cannot be dropped onto an all-day target (target.minutes === null). To convert a timed event to all-day, change the event's start to a Temporal.PlainDate explicitly in your event-source — the drop API does not auto-convert.`);
+	let m = e.PlainTime.from({
+		hour: Math.floor(i.minutes / 60),
+		minute: i.minutes % 60
+	}), h = s(i.displayZone, {
+		year: p.year,
+		month: p.month,
+		day: p.day,
+		hour: m.hour,
+		minute: m.minute
+	});
+	if (h && c === "reject") throw new o(h, `[applyMoveToEvent] target ${i.date}T${String(m.hour).padStart(2, "0")}:${String(m.minute).padStart(2, "0")} is a DST ${h} in ${i.displayZone}; policy='reject'.`);
+	let g = c === "reject" ? "compatible" : c, _ = e.PlainDateTime.from({
+		year: p.year,
+		month: p.month,
+		day: p.day,
+		hour: m.hour,
+		minute: m.minute
+	}).toZonedDateTime(i.displayZone, { disambiguation: g }), v = _.withTimeZone(l), y = _.withTimeZone(u), b = h;
+	if (a === "timed-resize-start") {
+		let t = v;
+		if (f) {
+			let n = f.subtract({ minutes: 15 }).withTimeZone(l);
+			e.Instant.compare(t.toInstant(), n.toInstant()) > 0 && (t = n);
+		}
+		return {
+			start: t,
+			...f ? { end: f } : {},
+			disambiguation: b
+		};
+	}
+	if (a === "timed-resize-end") {
+		let t = d.add({ minutes: 15 }).withTimeZone(u), n = y;
+		return e.Instant.compare(n.toInstant(), t.toInstant()) < 0 && (n = t), {
+			start: d,
+			end: n,
+			disambiguation: b
+		};
+	}
+	if (a === "month-resize-start") {
+		let t = d.withTimeZone(i.displayZone), n = s(i.displayZone, {
+			year: p.year,
+			month: p.month,
+			day: p.day,
+			hour: t.hour,
+			minute: t.minute,
+			second: t.second
+		});
+		if (n && c === "reject") throw new o(n, `[applyMoveToEvent] month-resize-start lands in a DST ${n} in ${i.displayZone}; policy='reject'.`);
+		let r = c === "reject" ? "compatible" : c, a = e.PlainDateTime.from({
+			year: p.year,
+			month: p.month,
+			day: p.day,
+			hour: t.hour,
+			minute: t.minute,
+			second: t.second
+		}).toZonedDateTime(i.displayZone, { disambiguation: r }).withTimeZone(l);
+		if (f) {
+			let t = f.subtract({ minutes: 15 }).withTimeZone(l);
+			e.Instant.compare(a.toInstant(), t.toInstant()) > 0 && (a = t);
+		}
+		return {
+			start: a,
+			...f ? { end: f } : {},
+			disambiguation: n
+		};
+	}
+	if (a === "month-resize-end") {
+		let t = f ?? d, n = f ? u : l, r = t.withTimeZone(i.displayZone), a = s(i.displayZone, {
+			year: p.year,
+			month: p.month,
+			day: p.day,
+			hour: r.hour,
+			minute: r.minute,
+			second: r.second
+		});
+		if (a && c === "reject") throw new o(a, `[applyMoveToEvent] month-resize-end lands in a DST ${a} in ${i.displayZone}; policy='reject'.`);
+		let m = c === "reject" ? "compatible" : c, h = e.PlainDateTime.from({
+			year: p.year,
+			month: p.month,
+			day: p.day,
+			hour: r.hour,
+			minute: r.minute,
+			second: r.second
+		}).toZonedDateTime(i.displayZone, { disambiguation: m }).withTimeZone(n), g = d.add({ minutes: 15 }).withTimeZone(n);
+		return e.Instant.compare(h.toInstant(), g.toInstant()) < 0 && (h = g), {
+			start: d,
+			end: h,
+			disambiguation: a
+		};
+	}
+	if (f) {
+		let e = f.epochMilliseconds - d.epochMilliseconds;
+		return {
+			start: v,
+			end: v.add({ milliseconds: e }).withTimeZone(u),
+			disambiguation: b
+		};
+	}
+	return {
+		start: v,
+		disambiguation: b
+	};
+}
+//#endregion
+export { s as a, r as c, c as i, a as n, n as o, l as r, t as s, o as t };

package/dist/recurrence/index.d.ts

@@ -0,0 +1,70 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { CalendarEvent, RecurringSeries, RecurrenceExpansionWindow } from '../core/types';
+import { DstPolicy } from '../core/dnd/move-math';
+import { RecurrenceEngine } from './types';
+/**
+ * Expand a `RecurringSeries` into the concrete occurrences that fall
+ * within `window`.
+ *
+ * **Inputs**
+ *   - `series` — the rule + dtstart + optional duration / rdate /
+ *     exdate.
+ *   - `window` — inclusive-start / exclusive-end. Typically the
+ *     calendar's `_visibleRange` plus a small overscan.
+ *   - `dstPolicy` — required (C4). Same options as the drag pipeline:
+ *     `'compatible' | 'reject' | 'earlier' | 'later'`. **Step 2:
+ *     accepted but not yet applied — engine-default disambiguation
+ *     wins.** Step 3 wires the post-processing layer that enforces
+ *     the policy uniformly across engines.
+ *   - `engine` — optional. Defaults to a lazy-constructed
+ *     rrule-temporal adapter from
+ *     `@cocoar/vue-calendar/recurrence-rrule-temporal`.
+ *
+ * **Output**
+ *
+ * `CalendarEvent<TMeta>[]` where every occurrence:
+ *   - has a UNIQUE synthetic `id` of shape
+ *     `${series.id}__${recurrenceId}` so the layout pipeline can
+ *     distinguish occurrences (it dedupes by `event.id`). The
+ *     original series identifier is in `meta.__recurrence.seriesId`
+ *     — read via `getRecurrenceMeta(event)`.
+ *   - has `start` typed identically to `series.dtstart` (timed → ZDT,
+ *     all-day → PD).
+ *   - has `start.timeZoneId === series.dtstart.timeZoneId` for
+ *     timed series — the engine never collapses to UTC or to the
+ *     calendar's display zone (C3).
+ *   - has `end` computed from `series.duration` if present.
+ *   - carries provenance under `meta.__recurrence` (A4) — read via
+ *     `getRecurrenceMeta(event)`.
+ *
+ * **Throws**
+ *
+ * - `TypeError` for shape mismatches (PlainDate RDATE on a timed
+ *   series, etc.).
+ * - Step 3: `DstResolutionError` when `dstPolicy === 'reject'` and
+ *   any occurrence falls in a DST gap.
+ */
+export declare function expandSeries<TMeta extends Record<string, unknown> = Record<string, unknown>>(series: RecurringSeries<TMeta>, window: RecurrenceExpansionWindow, dstPolicy: DstPolicy, engine?: RecurrenceEngine): Promise<CalendarEvent<TMeta>[]>;
+/**
+ * Public accessor for the lib-managed recurrence metadata on an
+ * expanded occurrence. Returns `null` for non-recurring events.
+ *
+ * Use this instead of reading `event.meta.__recurrence` directly —
+ * the storage key is library-managed and may change between minor
+ * versions.
+ */
+export { getRecurrenceMeta } from './internal/engine-to-events';
+export type { RecurrenceMeta } from './internal/engine-to-events';
+/**
+ * Type-only re-exports — single-import ergonomics for consumers who
+ * `import { ... } from '@cocoar/vue-calendar/recurrence'`.
+ */
+export type { RecurringSeries, RecurrencePattern, RecurrenceExpansionWindow, } from '../core/types';
+export type { RecurrenceEngine, EngineRequest, EngineResponse, EngineResult, EngineResultTimed, EngineResultAllDay, EngineSeries, EngineSeriesTimed, EngineSeriesAllDay, EngineWindow, EngineSeriesError, RuleSpec, WallclockTimed, WallclockDate, OriginCode, } from './types';
+export { ORIGIN_RRULE, ORIGIN_RDATE } from './types';
+export type { DstPolicy } from '../core/dnd/move-math';
+/**
+ * Re-exported `Temporal` for convenience when constructing series.
+ */
+export type { Temporal };
+//# sourceMappingURL=index.d.ts.map

package/dist/recurrence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/recurrence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,yBAAyB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAKvD,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,YAAY,CAChC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE/D,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAC9B,MAAM,EAAE,yBAAyB,EACjC,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAwBjC;AAED;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE;;;GAGG;AACH,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAErD,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/recurrence/internal/default-engine.d.ts

@@ -0,0 +1,20 @@
+import { RecurrenceEngine } from '../types';
+/**
+ * Resolve the default engine. Dynamic-imports
+ * `recurrence-rrule-temporal` once, then caches the instance for
+ * subsequent calls.
+ *
+ * The loader is process-global by design — the engine is stateless
+ * and reuse is safe. Builders that want a different engine pass it
+ * explicitly via `builder.recurrenceEngine(...)`.
+ */
+export declare function getDefaultEngine(): Promise<RecurrenceEngine>;
+/**
+ * Test-only helper: clear the cached engine. Lets test suites
+ * inject engines without leaking across tests.
+ *
+ * Not part of the public API surface (re-exported only from the
+ * recurrence subpath for internal test use).
+ */
+export declare function _resetDefaultEngineForTests(): void;
+//# sourceMappingURL=default-engine.d.ts.map

package/dist/recurrence/internal/default-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-engine.d.ts","sourceRoot":"","sources":["../../../src/recurrence/internal/default-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAKjD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAsBlE;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

package/dist/recurrence/internal/dst-resolve.d.ts

@@ -0,0 +1,12 @@
+import { DstPolicy } from '../../core/dnd/move-math';
+import { CalendarEvent, RecurringSeries } from '../../core/types';
+/**
+ * Apply `dstPolicy` to every timed rule-generated occurrence in
+ * `events`, in place of returning the engine's native DST behavior.
+ * All-day events and RDATE-originated occurrences pass through.
+ *
+ * Throws `DstResolutionError` if any occurrence falls in a DST
+ * gap/overlap and `dstPolicy === 'reject'`.
+ */
+export declare function applyDstPolicy<TMeta extends Record<string, unknown>>(events: CalendarEvent<TMeta>[], series: RecurringSeries<TMeta>, dstPolicy: DstPolicy): CalendarEvent<TMeta>[];
+//# sourceMappingURL=dst-resolve.d.ts.map

package/dist/recurrence/internal/dst-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dst-resolve.d.ts","sourceRoot":"","sources":["../../../src/recurrence/internal/dst-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,EAC9B,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,EAC9B,SAAS,EAAE,SAAS,GACnB,aAAa,CAAC,KAAK,CAAC,EAAE,CA+ExB"}

package/dist/recurrence/internal/engine-to-events.d.ts

@@ -0,0 +1,38 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { CalendarEvent, RecurringSeries } from '../../core/types';
+import { EngineResult } from '../types';
+/**
+ * Internal provenance attached to every expanded `CalendarEvent`
+ * under `meta.__recurrence`. Public consumers read it via
+ * `getRecurrenceMeta(event)`.
+ *
+ * The double-underscore prefix marks the key as library-managed.
+ * Consumers MUST NOT read or write it directly — that contract may
+ * change between minor versions.
+ */
+export interface RecurrenceMeta {
+    /** Stable id of the source `RecurringSeries`. */
+    readonly seriesId: string;
+    /**
+     * RECURRENCE-ID per RFC 5545 — the original wallclock value of
+     * this occurrence. For unmodified occurrences `recurrenceId`
+     * equals `event.start`; Phase-5 single-instance edits will let
+     * `event.start` differ while `recurrenceId` keeps pointing at
+     * the original slot.
+     */
+    readonly recurrenceId: Temporal.ZonedDateTime | Temporal.PlainDate;
+    /** Where this occurrence came from in the source series. */
+    readonly source: 'rrule' | 'rdate';
+}
+/**
+ * The lib-managed key under `event.meta`. Consumers should treat it
+ * as opaque — read via `getRecurrenceMeta(event)`.
+ */
+export declare const RECURRENCE_META_KEY: "__recurrence";
+export declare function decodeEngineResult<TMeta extends Record<string, unknown>>(result: EngineResult, series: RecurringSeries<TMeta>): CalendarEvent<TMeta>[];
+/**
+ * Public helper to read the lib-managed recurrence metadata off an
+ * expanded occurrence. Returns `null` for non-recurring events.
+ */
+export declare function getRecurrenceMeta<TMeta extends Record<string, unknown>>(event: CalendarEvent<TMeta>): RecurrenceMeta | null;
+//# sourceMappingURL=engine-to-events.d.ts.map

package/dist/recurrence/internal/engine-to-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-to-events.d.ts","sourceRoot":"","sources":["../../../src/recurrence/internal/engine-to-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,aAAa,GAAG,QAAQ,CAAC,SAAS,CAAC;IACnE,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;CACpC;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAG,cAAuB,CAAC;AAE3D,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAC7B,aAAa,CAAC,KAAK,CAAC,EAAE,CAKxB;AA2HD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,GAC1B,cAAc,GAAG,IAAI,CAMvB"}

package/dist/recurrence/internal/series-to-engine.d.ts

@@ -0,0 +1,4 @@
+import { RecurringSeries } from '../../core/types';
+import { EngineSeries } from '../types';
+export declare function seriesToEngineSeries<TMeta extends Record<string, unknown>>(series: RecurringSeries<TMeta>): EngineSeries;
+//# sourceMappingURL=series-to-engine.d.ts.map

package/dist/recurrence/internal/series-to-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"series-to-engine.d.ts","sourceRoot":"","sources":["../../../src/recurrence/internal/series-to-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,UAAU,CAAC;AAElB,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,GAC7B,YAAY,CAWd"}

package/dist/recurrence/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Public engine interface for recurrence expansion (Phase 4 §A5).
+ *
+ * Engines implement `RecurrenceEngine`; consumers can replace the
+ * default engine via `builder.recurrenceEngine(custom)` or by
+ * passing a 4th arg to `expandSeries(...)`. The contract
+ * intentionally stays small and stable: the lib does the heavy
+ * lifting (RecurringSeries → EngineSeries conversion, source-zone
+ * preservation, DstPolicy post-processing, provenance) so engines
+ * focus only on RRULE expansion.
+ *
+ * One engine adapter ships in-tree:
+ *   - `@cocoar/vue-calendar/recurrence-rrule-temporal` — pure JS,
+ *     Temporal-native, the lazy default.
+ *
+ * Custom engines (e.g. WASM-backed for high-volume workloads,
+ * server-side delegation, or test mocks) implement `RecurrenceEngine`
+ * in consumer code and register via `builder.recurrenceEngine(...)`.
+ *
+ * **Wire format invariants**
+ *   - All times travel as numeric components (year/month/day/hour
+ *     /minute/second). No `Date`, no `Temporal` objects in the wire —
+ *     so Worker postMessage stays cheap and structured-clone friendly.
+ *   - Source zones travel per-endpoint (DTSTART, each RDATE, each
+ *     EXDATE). The library NEVER collapses to one zone before calling
+ *     the engine — C3.
+ *   - Output `timestamps` are unix-ms (UTC instants). The library
+ *     reconstructs each occurrence's `Temporal.ZonedDateTime` in its
+ *     source zone using the parallel `seriesTzid` + `occurrenceTzids`
+ *     fields — no zone identity is lost.
+ *   - All-day series travel through a separate `kind: 'allDay'`
+ *     branch with packed `Int32Array` dates. No instants exist for
+ *     all-day events (Article 4) so `timestamps` would be a category
+ *     error.
+ */
+/**
+ * Components of a wallclock time. Used for DTSTART, RDATE, EXDATE,
+ * and the `UNTIL` field of an RRULE in the timed path. Plain numbers
+ * so the structure clones cheaply across the worker boundary.
+ */
+export interface WallclockTimed {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly tzid: string;
+}
+/**
+ * Components of a wallclock date (no time, no zone). Used for
+ * DTSTART, RDATE, EXDATE, and `UNTIL` of an RRULE in the all-day
+ * path. Article 4: a date is not a point in time.
+ */
+export interface WallclockDate {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+}
+/**
+ * RFC-5545 RRULE in string form, e.g. `'FREQ=WEEKLY;BYDAY=MO,WE,FR'`.
+ *
+ * Stored as a string because:
+ *   - Engines parse RRULE natively; pre-parsing into a structured
+ *     form would require us to re-emit RFC-compliant syntax for any
+ *     engine using a typed constructor.
+ *   - Adding a structured representation here would lock the lib
+ *     into a specific RRULE-feature subset; the string form lets
+ *     each engine accept whatever RFC features it supports natively.
+ *
+ * The optional `until` is split out so the lib can pass it as a
+ * properly-typed value (matching DTSTART's value class) instead of
+ * embedding it in the string.
+ */
+export interface RuleSpec {
+    readonly rrule: string;
+    /**
+     * Optional override for `UNTIL` from the rrule string. When set,
+     * adapters use this typed value instead of parsing the embedded
+     * `UNTIL` from the string. Lets the lib enforce value-class
+     * matching with DTSTART (per A6).
+     */
+    readonly until?: WallclockTimed | WallclockDate;
+}
+/**
+ * Engine-side representation of a `RecurringSeries`.
+ *
+ * Discriminated by `kind` so timed and all-day series travel through
+ * separate code paths inside the engine — no synthetic 00:00 in a
+ * zone (per A6).
+ */
+export type EngineSeries = EngineSeriesTimed | EngineSeriesAllDay;
+export interface EngineSeriesTimed {
+    readonly seriesId: string;
+    readonly kind: 'timed';
+    readonly dtstart: WallclockTimed;
+    readonly rules: readonly RuleSpec[];
+    readonly rdates: readonly WallclockTimed[];
+    readonly exdates: readonly WallclockTimed[];
+}
+export interface EngineSeriesAllDay {
+    readonly seriesId: string;
+    readonly kind: 'allDay';
+    readonly dtstart: WallclockDate;
+    readonly rules: readonly RuleSpec[];
+    readonly rdates: readonly WallclockDate[];
+    readonly exdates: readonly WallclockDate[];
+}
+/**
+ * Window for the engine call. Bounds are absolute instants (unix-ms);
+ * the engine clips occurrences to `[start, end)`. Inclusive-start /
+ * exclusive-end (same convention as `RecurrenceExpansionWindow` and
+ * `ViewWindow`).
+ *
+ * For all-day series the lib still passes instants — the engine
+ * computes the date-only window by taking each date's UTC-midnight
+ * instant. The bounds are wide enough that DST near the edge can't
+ * flip an occurrence out of the window.
+ */
+export interface EngineWindow {
+    readonly startMs: number;
+    readonly endMs: number;
+}
+/**
+ * Batched engine request. The library collects all visible series,
+ * dispatches once. Engines that can parallelize (worker-backed) get
+ * the most leverage from large batches.
+ */
+export interface EngineRequest {
+    readonly window: EngineWindow;
+    readonly series: readonly EngineSeries[];
+}
+/**
+ * Origin marker for one occurrence. Packed into a `Uint8Array` per
+ * series-result for transferable round-trip. Used by Step 3 to set
+ * `__recurrence.source` on each `CalendarEvent`.
+ */
+export declare const ORIGIN_RRULE = 0;
+export declare const ORIGIN_RDATE = 1;
+export type OriginCode = typeof ORIGIN_RRULE | typeof ORIGIN_RDATE;
+/**
+ * Engine result — discriminated union mirroring `EngineSeries.kind`.
+ *
+ * `Float64Array` / `Int32Array` / `Uint16Array` / `Uint8Array` are
+ * all Transferable; the worker round-trip stays zero-copy.
+ */
+export type EngineResult = EngineResultTimed | EngineResultAllDay;
+export interface EngineResultTimed {
+    readonly seriesId: string;
+    readonly kind: 'timed';
+    /** Unix-ms instants of every occurrence inside the window. */
+    readonly timestamps: Float64Array;
+    /**
+     * The series source zone (matches `EngineSeriesTimed.dtstart.tzid`).
+     * Set unconditionally so the library can reconstruct
+     * `Temporal.ZonedDateTime` for rule-generated occurrences without
+     * looking elsewhere.
+     */
+    readonly seriesTzid: string;
+    /**
+     * Per-occurrence zone overrides — used only when at least one
+     * RDATE has a different `tzid` than `seriesTzid`. When present,
+     * `indices[i]` is the index into `pool` for the i-th occurrence.
+     * When omitted, every occurrence uses `seriesTzid`.
+     *
+     * Hot-path optimization (A1 fast-path): the homogeneous-zone case
+     * pays no extra bytes.
+     */
+    readonly occurrenceTzids?: {
+        readonly pool: readonly string[];
+        readonly indices: Uint16Array;
+    };
+    /**
+     * One byte per occurrence — `ORIGIN_RRULE` or `ORIGIN_RDATE`. Step
+     * 3 uses this to populate `__recurrence.source`.
+     */
+    readonly origins: Uint8Array;
+}
+export interface EngineResultAllDay {
+    readonly seriesId: string;
+    readonly kind: 'allDay';
+    /**
+     * Packed dates: each entry is `(year * 512 + month * 32 + day)`.
+     * Decoded by the library into `Temporal.PlainDate`.
+     *
+     * Why packed: instants don't exist for all-day events (Article 4),
+     * but a numeric encoding still rides the transferable fast-path.
+     * The `512 * 32` packing fits 11 bits of year + 4 bits of month +
+     * 5 bits of day in 20 bits — well inside Int32.
+     */
+    readonly dates: Int32Array;
+    readonly origins: Uint8Array;
+}
+/**
+ * Batched engine response — one result per input series, in the same
+ * order. Errors are surfaced per-series so a single bad rule doesn't
+ * fail the whole batch.
+ */
+export interface EngineResponse {
+    readonly results: readonly EngineResult[];
+    /**
+     * Per-series errors. Empty on full success. When non-empty, the
+     * corresponding entry in `results` may be missing (engines may
+     * skip failed series rather than emitting an empty result).
+     */
+    readonly errors: readonly EngineSeriesError[];
+}
+export interface EngineSeriesError {
+    readonly seriesId: string;
+    readonly message: string;
+}
+/**
+ * Recurrence engine contract.
+ *
+ * Implementations parse + expand RRULE/RDATE/EXDATE for a batch of
+ * series over a window. The library does NOT expect the engine to
+ * apply `DstPolicy` — that's post-processing in `dst-resolve.ts`
+ * (Step 3) so engine-swap never changes observable semantics.
+ *
+ * The interface is `async` so worker-backed engines fit the same
+ * shape as in-thread engines. Consumers always `await`.
+ *
+ * **Engine implementer responsibilities:**
+ *   - Use the `series.dtstart.tzid` (or per-RDATE/EXDATE `tzid`) for
+ *     wallclock interpretation. Never collapse to one zone.
+ *   - For timed `EngineResultTimed`: emit `timestamps` as unix-ms
+ *     UTC instants, and populate `seriesTzid` + optional
+ *     `occurrenceTzids` so the lib can reconstruct ZDTs in the
+ *     correct zone per occurrence.
+ *   - For all-day `EngineResultAllDay`: emit packed `dates`. Never
+ *     pass through an `Instant` for all-day series (Article 4).
+ *   - EXDATE matching: against the series source zone (A7).
+ *   - `origins`: set `ORIGIN_RRULE` for rule-generated occurrences
+ *     and `ORIGIN_RDATE` for occurrences originating from an RDATE.
+ *
+ * **What engines MUST NOT do:**
+ *   - Apply `DstPolicy` — that's the lib's job (Step 3).
+ *   - Add `meta.__recurrence` provenance — that's the lib's job
+ *     (Step 3).
+ *   - Reorder occurrences inside one series-result. Within each
+ *     `EngineResult.timestamps` (or `dates`), occurrences must be
+ *     sorted ascending. The lib relies on this.
+ */
+export interface RecurrenceEngine {
+    /**
+     * Expand a batch of recurring series over a window.
+     * Always async. Consumers await regardless of whether the engine
+     * is in-thread or worker-backed.
+     */
+    expand(request: EngineRequest): Promise<EngineResponse>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/recurrence/types.d.ts.map

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

package/dist/recurrence-rrule-temporal/index.d.ts

@@ -0,0 +1,12 @@
+import { EngineRequest, EngineResponse, RecurrenceEngine } from '../recurrence/types';
+/**
+ * Default recurrence engine — pure JS, Temporal-native.
+ *
+ * Stateless. Construction is cheap (no module init). Reuse one
+ * instance per builder; the lib does that automatically when no
+ * explicit engine is configured.
+ */
+export declare class RruleTemporalEngine implements RecurrenceEngine {
+    expand(request: EngineRequest): Promise<EngineResponse>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/recurrence-rrule-temporal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/recurrence-rrule-temporal/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EAMd,gBAAgB,EAGjB,MAAM,qBAAqB,CAAC;AAK7B;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IACpD,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;CAkB9D"}