@cocoar/vue-calendar 1.16.0

package/dist/core/recurrence-public.d.ts

@@ -0,0 +1,59 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { CalendarEvent, RecurrenceExpansionWindow, RecurringSeries } from './types';
+import { DstPolicy } from './dnd/move-math';
+/**
+ * Expand a `RecurringSeries` into the concrete occurrences that fall
+ * within `window`, applying `dstPolicy` to any occurrence whose
+ * wall-time hits a DST gap or overlap in the series' source zone.
+ *
+ * **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.
+ *
+ * **Output**
+ *
+ * `CalendarEvent<TMeta>[]` where every occurrence:
+ *   - shares the series' `id` (use `start` to distinguish).
+ *   - 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.
+ *   - has `end` computed from `series.duration` if present.
+ *   - has `meta` shallow-copied from `series.meta`.
+ *
+ * **Throws**
+ *
+ * Until Phase 4: a `TypeError` with an informative message. Consumers
+ * can rely on the type contract NOW; expansion arrives without an
+ * API change.
+ *
+ * After Phase 4 (planned): a `DstResolutionError` if any occurrence
+ * lands in a DST gap/overlap and `dstPolicy === 'reject'`.
+ */
+export declare function expandSeries<TMeta extends Record<string, unknown> = Record<string, unknown>>(_series: RecurringSeries<TMeta>, _window: RecurrenceExpansionWindow, _dstPolicy: DstPolicy): CalendarEvent<TMeta>[];
+/**
+ * Re-export for ergonomics — consumers usually `import { expandSeries }`
+ * alongside the types they're constructing.
+ *
+ * Session 2 also re-uses this constant in tests to assert the stub
+ * shape without duplicating the message.
+ */
+export declare const EXPAND_SERIES_NOT_IMPLEMENTED_MESSAGE = "[@cocoar/vue-calendar] expandSeries() is not implemented yet \u2014 the recurrence engine integration is Phase 4. The TYPE contract for RecurringSeries is enforced from Session 2 so your data layer can build against it now; expansion will become available without API changes.";
+/**
+ * Type-only re-exports so consumers writing `import { ... } from '@cocoar/vue-calendar'`
+ * find the recurrence types alongside `expandSeries` without needing
+ * to know they were declared in `core/types.ts`.
+ */
+export type { RecurringSeries, RecurrencePattern, RecurrenceExpansionWindow, } from './types';
+/**
+ * Re-exported `Temporal` for convenience when constructing series.
+ *
+ * Without it consumers would have to add a separate
+ * `@js-temporal/polyfill` import for `Temporal.ZonedDateTime.from(...)`.
+ */
+export type { Temporal };
+//# sourceMappingURL=recurrence-public.d.ts.map

package/dist/core/recurrence-public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence-public.d.ts","sourceRoot":"","sources":["../../src/core/recurrence-public.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EACV,aAAa,EACb,yBAAyB,EACzB,eAAe,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAC1B,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAG/D,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,EAE/B,OAAO,EAAE,yBAAyB,EAElC,UAAU,EAAE,SAAS,GACpB,aAAa,CAAC,KAAK,CAAC,EAAE,CAExB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC,yRAAkB,CAAC;AAErE;;;;GAIG;AACH,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/core/recurrence.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Recurrence engine — main-thread API.
+ *
+ * Two paths sharing one request/response shape:
+ *
+ *   - `expandSync`  — runs `rrule-rust` in the calling thread.
+ *                     Cheapest for small workloads (single rule,
+ *                     one-shot expansion). Blocks the main thread.
+ *
+ *   - `expandAsync` — dispatches to a long-lived worker. Cheapest
+ *                     for large workloads where main-thread blocking
+ *                     would jank the UI. Pays a postMessage round-
+ *                     trip (~ 1-2 ms) on top of the actual expansion.
+ *
+ * Spike E benchmarks both at four scales (W1-W4) and locks the
+ * auto-dispatch threshold — when does the worker round-trip beat
+ * in-thread? Per Spike B's measurements (`rrule-rust` warm path =
+ * 0.6 ms / expansion), the in-thread cost is much lower than the
+ * spike-plan hypothesis suggested, so the auto-dispatch threshold
+ * lands at higher series counts than originally estimated.
+ *
+ * Wire format is the same in both modes; consumers swap engines by
+ * choosing which function to call. A higher-level
+ * `<CoarCalendar :recurrence-engine="...">` prop in Phase 1 will
+ * pick automatically based on `series.length` against the locked
+ * threshold.
+ */
+export interface RecurrenceRequest {
+    rules: ReadonlyArray<{
+        seriesId: string;
+        rruleString: string;
+    }>;
+    /** Window start as unix-ms (absolute timestamp). */
+    windowStart: number;
+    /** Window end as unix-ms (absolute timestamp), exclusive-ish. */
+    windowEnd: number;
+}
+export interface RecurrenceRuleResult {
+    seriesId: string;
+    /** Unix-ms timestamps of every occurrence inside the window. */
+    timestamps: Float64Array;
+}
+export interface RecurrenceResponse {
+    results: RecurrenceRuleResult[];
+    /** Time spent in actual expansion (ms). Excludes worker round-trip. */
+    expansionMs: number;
+    /** Per-rule errors; empty on full success. */
+    errors: Array<{
+        seriesId: string;
+        message: string;
+    }>;
+}
+/**
+ * Synchronous in-thread expansion. Runs in the caller's thread; for
+ * large workloads (≥ threshold), prefer `expandAsync`.
+ */
+export declare function expandSync(req: RecurrenceRequest): RecurrenceResponse;
+/**
+ * Asynchronous expansion via a long-lived worker. The worker is
+ * lazily created on first use and reused for the lifetime of the
+ * page. Cold-start (~ 175 ms WASM init) hits the first call; warm
+ * calls cost ~ 1-2 ms postMessage round-trip plus the expansion
+ * time.
+ */
+export declare function expandAsync(req: RecurrenceRequest): Promise<RecurrenceResponse>;
+/**
+ * Tear down the worker. Useful for tests or for apps that know
+ * recurrence won't be needed any more.
+ */
+export declare function shutdownRecurrenceWorker(): void;
+export interface RecurrenceEngine {
+    /**
+     * Expand a batch of recurring rules over a window. The engine
+     * decides whether to run sync (in-thread) or async (worker)
+     * per-call; consumers always await regardless.
+     */
+    expand(request: RecurrenceRequest): Promise<RecurrenceResponse>;
+}
+export interface DefaultRecurrenceEngineOptions {
+    /**
+     * Auto-dispatch threshold. Rules >= threshold → worker. Default
+     * 200, locked empirically in Phase 0 Spike E (W1 sync stays
+     * under one frame, W2+ blocks UI).
+     */
+    threshold?: number;
+}
+/**
+ * Default engine: rrule-rust with auto-dispatch at the locked
+ * threshold (200 rules by default, configurable).
+ */
+export declare class DefaultRecurrenceEngine implements RecurrenceEngine {
+    private threshold;
+    constructor(opts?: DefaultRecurrenceEngineOptions);
+    expand(request: RecurrenceRequest): Promise<RecurrenceResponse>;
+}
+/**
+ * Forces every expansion through the synchronous in-thread path.
+ * Useful for tests (no worker setup) and SSR (no Worker API).
+ */
+export declare class SyncOnlyRecurrenceEngine implements RecurrenceEngine {
+    expand(request: RecurrenceRequest): Promise<RecurrenceResponse>;
+}
+/**
+ * Forces every expansion through the worker. Useful for diagnostic
+ * purposes — never blocks the main thread, even for tiny inputs.
+ * Production consumers should prefer `DefaultRecurrenceEngine` so
+ * the small-batch fast path stays sync.
+ */
+export declare class WorkerOnlyRecurrenceEngine implements RecurrenceEngine {
+    expand(request: RecurrenceRequest): Promise<RecurrenceResponse>;
+}
+//# sourceMappingURL=recurrence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence.d.ts","sourceRoot":"","sources":["../../src/core/recurrence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAgCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,kBAAkB,CAErE;AAsCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAO/E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAO/C;AAoBD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,GAAE,8BAAmC;IAI/C,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAMtE;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IACzD,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGtE;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,gBAAgB;IAC3D,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGtE"}

package/dist/core/recurrenceWorker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Recurrence expansion worker — runs `rrule-rust` off the main
+ * thread. Imported via Vite's `?worker` syntax; only this file
+ * actually executes in the worker context.
+ *
+ * The worker pays ~ 175 ms WASM init on first instantiation (per
+ * Spike B browser cold-start measurement). Subsequent expansions
+ * are sub-millisecond. The main thread keeps this worker alive for
+ * the lifetime of the calendar; warm-path expansions cost only the
+ * postMessage round-trip.
+ *
+ * Wire format (request → response):
+ *
+ *   self.postMessage({
+ *     id: 7,
+ *     rules: [{ seriesId: 'standup', rruleString: 'DTSTART:...\nRRULE:...' }, …],
+ *     windowStart: 1717200000000,
+ *     windowEnd:   1719792000000,
+ *   });
+ *
+ *   self.onmessage = (e) => {
+ *     // e.data: {
+ *     //   id: 7,
+ *     //   results: [{ seriesId, timestamps: Float64Array }, …],
+ *     //   expansionMs: 0.6,
+ *     //   errors: [{ seriesId, message }, …]  // empty on success
+ *     // }
+ *     // Transferred: the Float64Array buffers themselves.
+ *   };
+ *
+ * Float64Array is a Transferable. Sending 7.000 timestamps as a
+ * 56 KB ArrayBuffer is roughly free; structured-cloning the same
+ * count of plain-object dates would cost milliseconds.
+ */
+export interface RecurrenceRequest {
+    id: number;
+    rules: ReadonlyArray<{
+        seriesId: string;
+        rruleString: string;
+    }>;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface RecurrenceRuleResult {
+    seriesId: string;
+    /**
+     * Unix-ms timestamps of every occurrence in the window. Always
+     * sent as a Float64Array whose `.buffer` is in the transferList.
+     */
+    timestamps: Float64Array;
+}
+export interface RecurrenceResponse {
+    id: number;
+    results: RecurrenceRuleResult[];
+    /** Worker-side time spent on actual expansion, in milliseconds. */
+    expansionMs: number;
+    errors: Array<{
+        seriesId: string;
+        message: string;
+    }>;
+}
+//# sourceMappingURL=recurrenceWorker.d.ts.map

package/dist/core/recurrenceWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrenceWorker.d.ts","sourceRoot":"","sources":["../../src/core/recurrenceWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD"}

package/dist/core/temporal.d.ts

@@ -0,0 +1,214 @@
+import { Temporal } from '@js-temporal/polyfill';
+export { Temporal };
+/** 0 = Sun … 6 = Sat. Matches `Date.prototype.getDay()`. */
+export type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Convert Temporal's 1..7 (Mon..Sun) to the 0..6 (Sun..Sat)
+ * convention the calendar uses publicly.
+ */
+export declare function temporalDowToCalendarDow(isoDow: number): DayOfWeek;
+/**
+ * Convert calendar 0..6 (Sun..Sat) to Temporal's 1..7 (Mon..Sun).
+ */
+export declare function calendarDowToTemporalDow(calDow: DayOfWeek): 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export declare function detectFirstDayOfWeekFromLocale(locale: string): DayOfWeek;
+/**
+ * Detect 12-vs-24-hour preference for a locale via Intl. Returns
+ * `true` for 12-hour locales (en-US), `false` for 24-hour
+ * (de-DE, fr-FR).
+ */
+export declare function detectHour12FromLocale(locale: string): boolean;
+/**
+ * The browser's IANA timezone, e.g. `'Europe/Vienna'`. Falls back to
+ * `'UTC'` on environments without `Intl.DateTimeFormat` (SSR / locked
+ * runtimes / very old browsers).
+ *
+ * **The fallback is the article-4 anti-pattern.** A UTC display zone
+ * for a Vienna user makes 09:00 wall-clock render as 11:00 in summer.
+ * To make this loud, we `console.warn` ONCE per process when the
+ * fallback fires — including in production, because the data
+ * corruption risk is identical in dev and prod (Article 8: don't lie
+ * about what's stored). Consumers who really do live in UTC should
+ * pass `'UTC'` explicitly to `builder.timezone('UTC')` to silence
+ * the warning.
+ */
+export declare function detectBrowserTimezone(): string;
+/**
+ * Article-9 helper: merge consumer-set verbosity / clock overrides
+ * into a per-call `Intl.DateTimeFormatOptions` literal. Intl is strict
+ * about combinations — `dateStyle` excludes the field-level options
+ * (`weekday`/`day`/`month`/`year`/`era`), and `timeStyle` excludes
+ * `hour`/`minute`/`second`/`fractionalSecondDigits`. This helper
+ * applies the overrides AND prunes the conflicting fields so callers
+ * just hand it the natural literal.
+ *
+ *   buildFormatOptions(
+ *     { weekday: 'short', day: 'numeric', month: 'short', timeZone: tz },
+ *     { dateStyle: 'long', hour12: false },
+ *   )
+ *   //  → { dateStyle: 'long', hour12: false, timeZone: tz }
+ */
+export interface FormatOverrides {
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
+    hour12?: boolean;
+}
+export declare function buildFormatOptions(base: Intl.DateTimeFormatOptions, overrides: FormatOverrides | undefined): Intl.DateTimeFormatOptions;
+/**
+ * Move `date` backwards (or stay) until it lands on the configured
+ * `firstDayOfWeek`. Idempotent.
+ *
+ * @example
+ *   startOfWeek(2026-04-15 (Wed), 1) → 2026-04-13 (Mon)
+ *   startOfWeek(2026-04-15 (Wed), 0) → 2026-04-12 (Sun)
+ */
+export declare function startOfWeek(date: Temporal.PlainDate, firstDayOfWeek: DayOfWeek): Temporal.PlainDate;
+/**
+ * Last day of the week (one day before the next firstDayOfWeek).
+ */
+export declare function endOfWeek(date: Temporal.PlainDate, firstDayOfWeek: DayOfWeek): Temporal.PlainDate;
+/** First day of the month containing `date`. */
+export declare function startOfMonth(date: Temporal.PlainDate): Temporal.PlainDate;
+/** Last day of the month containing `date`. */
+export declare function endOfMonth(date: Temporal.PlainDate): Temporal.PlainDate;
+/**
+ * ISO 8601 week number (1..53). Week 1 is the week containing the
+ * first Thursday of the year.
+ */
+export declare function isoWeekNumber(date: Temporal.PlainDate): number;
+/**
+ * 7 dates of the week containing `date`, starting at firstDayOfWeek.
+ *
+ * Used by week / day views.
+ */
+export declare function weekDates(date: Temporal.PlainDate, firstDayOfWeek: DayOfWeek): Temporal.PlainDate[];
+/**
+ * Fixed 6 × 7 = 42-cell month grid: leading days from the previous
+ * month + the month's days + trailing days from the next month.
+ *
+ * Always 42 cells so the month view doesn't reflow when the month
+ * changes (a month spanning 4, 5, or 6 visual rows; we always
+ * render 6).
+ *
+ * @param yearMonth — month to render
+ * @param firstDayOfWeek — 0..6 calendar convention
+ */
+export declare function monthGridDates(yearMonth: Temporal.PlainYearMonth, firstDayOfWeek: DayOfWeek): Temporal.PlainDate[];
+/**
+ * Localized weekday names ('Sun', 'Mon', …) for headings, in the
+ * order dictated by `firstDayOfWeek`.
+ *
+ * @param locale BCP-47, e.g. 'de-AT'
+ * @param firstDayOfWeek 0..6
+ * @param format 'long' | 'short' | 'narrow' — Intl.DateTimeFormat options
+ */
+export declare function localizedWeekdayNames(locale: string, firstDayOfWeek: DayOfWeek, format?: 'long' | 'short' | 'narrow'): string[];
+/**
+ * Stable `YYYY-MM-DD` key, suitable for use in a `Map` for the
+ * event index. Same shape as `Temporal.PlainDate.toString()`.
+ */
+export declare function dateKey(date: Temporal.PlainDate): string;
+/**
+ * Resolve an event's start to a `Temporal.PlainDate` (the "day" the
+ * event lives on for indexing purposes), in the supplied DISPLAY zone.
+ *
+ *   - `PlainDate`     → returned as-is (all-day events have no zone).
+ *   - `ZonedDateTime` → re-zoned into `displayZone`, then truncated to
+ *     the calendar day. Cross-zone events are bucketed by what the
+ *     viewer actually sees.
+ *
+ * Used by the EventIndex to bucket events by day key.
+ */
+export declare function eventStartDateInZone(start: Temporal.ZonedDateTime | Temporal.PlainDate, displayZone: string): Temporal.PlainDate;
+/** Today's date in the given IANA zone. */
+export declare function todayInZone(zone: string): Temporal.PlainDate;
+/** Current ZonedDateTime in the given IANA zone. */
+export declare function nowInZone(zone: string): Temporal.ZonedDateTime;
+/**
+ * DST policy mirror of the type in `dnd/move-math`. Re-declared here
+ * so `core/temporal.ts` stays import-graph-clean (move-math is
+ * downstream of temporal helpers, not the other way around).
+ *
+ * The values + semantics are identical; both files compile against
+ * the same Temporal `disambiguation` option.
+ */
+export type DstPolicy = 'compatible' | 'reject' | 'earlier' | 'later';
+/**
+ * Wire shape for a scheduled time. Mirrors Article 8's recommended
+ * API contract: store the human's intent (`local + timeZoneId`)
+ * separately from the derived UTC instant (which the backend
+ * computes per Article 4's "store intent, derive math" rule).
+ *
+ * Field naming matches `Appointment.LocalStart` / `TimeZoneId`
+ * conventions used in Articles 6 + 7 (.NET / PostgreSQL chapters)
+ * so frontend ↔ backend DTOs line up without translation.
+ */
+export interface ScheduledTimeWire {
+    /**
+     * ISO-8601 local datetime, NO offset, NO `Z`:
+     * `'2026-06-05T10:00:00'`. The wall-clock value the user chose.
+     */
+    local: string;
+    /** IANA timezone, e.g. `'Europe/Vienna'`. NOT an offset like `+02:00`
+     *  (Article 4: offsets are snapshots, not meaning). */
+    timeZoneId: string;
+}
+/**
+ * Parse a wire `{ local, timeZoneId }` shape into a
+ * `Temporal.ZonedDateTime`, applying the caller's `dstPolicy` to
+ * resolve any DST gap or overlap on the local wall-time.
+ *
+ * @example
+ * ```ts
+ * const start = parseScheduledTime({
+ *   local: '2026-06-05T10:00:00',
+ *   timeZoneId: 'Europe/Vienna',
+ * });
+ * // → Temporal.ZonedDateTime in Europe/Vienna, intent preserved.
+ * ```
+ *
+ * **Throws** `TypeError` if `timeZoneId` isn't a recognised IANA name
+ * (probes via `toInstant()` — same trick as `validateCalendarEvent`).
+ *
+ * **Throws** `RangeError` if `local` isn't a parseable ISO-8601
+ * datetime.
+ *
+ * **Throws** if `dstPolicy === 'reject'` and the local wall-time
+ * lands in a DST gap (Article 5 explicit-policy contract).
+ */
+export declare function parseScheduledTime(input: ScheduledTimeWire & {
+    dstPolicy?: DstPolicy;
+}): Temporal.ZonedDateTime;
+/**
+ * Parse a wire `'YYYY-MM-DD'` ISO date string into a
+ * `Temporal.PlainDate` — the all-day counterpart to
+ * `parseScheduledTime`.
+ *
+ * @example
+ * ```ts
+ * const dob = parsePlainDate('1990-03-15');
+ * ```
+ *
+ * **Throws** `RangeError` if `iso` isn't a parseable date.
+ */
+export declare function parsePlainDate(iso: string): Temporal.PlainDate;
+/**
+ * Format a `Temporal.ZonedDateTime` back into the wire shape — the
+ * round-trip companion to `parseScheduledTime`. Use when shipping a
+ * `CalendarEvent.start` to a backend that expects the
+ * `{ local, timeZoneId }` contract.
+ *
+ * @example
+ * ```ts
+ * const wire = formatScheduledTime(event.start);
+ * // → { local: '2026-06-05T10:00:00', timeZoneId: 'Europe/Vienna' }
+ * await fetch('/appointments', { method: 'POST', body: JSON.stringify({ start: wire }) });
+ * ```
+ *
+ * **Round-trip property** (tested):
+ * `formatScheduledTime(parseScheduledTime(wire)) === wire` for any
+ * non-DST-edge wire input. DST-edge inputs round-trip into the
+ * unambiguous-after-policy value the engine resolved them to.
+ */
+export declare function formatScheduledTime(zdt: Temporal.ZonedDateTime): ScheduledTimeWire;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/core/temporal.d.ts.map

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

package/dist/core/timeGridLayout.d.ts

@@ -0,0 +1,109 @@
+import { CalendarEvent } from './types';
+import { Temporal } from './temporal';
+export interface PositionedEvent<TMeta extends Record<string, unknown> = Record<string, unknown>> {
+    /** The event itself (flyweight; consumer can render it). */
+    event: CalendarEvent<TMeta>;
+    /** Lane within the day column. 0 is leftmost. */
+    lane: number;
+    /** Total lanes used in this day. width per lane = 1 / laneCount. */
+    laneCount: number;
+    /**
+     * Minutes from `dayStartHour * 60` to the event's visible start.
+     * `0` = event begins at the top of the time range.
+     */
+    startMinutes: number;
+    /**
+     * Minutes from `dayStartHour * 60` to the event's visible end.
+     * Strictly greater than `startMinutes`. Always within
+     * `[0, (dayEndHour - dayStartHour) * 60]`.
+     */
+    endMinutes: number;
+    /**
+     * True when the event was clipped at the top of the day range
+     * (its real start is before `dayStartHour`).
+     */
+    clippedTop: boolean;
+    /**
+     * True when the event was clipped at the bottom (real end is past
+     * `dayEndHour`).
+     */
+    clippedBottom: boolean;
+}
+export interface DayLayoutOptions {
+    /** The day this layout is for. */
+    day: Temporal.PlainDate;
+    /** Visible hour range. `[6, 22]` = 6 AM to 10 PM. */
+    timeRange: [number, number];
+    /** IANA timezone for resolving timed events. */
+    timezone: string;
+    /**
+     * Optional event id that should always be placed on the
+     * RIGHTMOST lane (`laneCount - 1`) within its overlap component.
+     * Used during drag-preview so the dragged ghost stays anchored
+     * on the trailing edge regardless of which other events it
+     * transitively overlaps — keeps it from jumping side-to-side as
+     * the user moves the mouse across slots with different overlap
+     * shapes. Other events in the same component shift down by one
+     * lane to preserve the no-conflict invariant; events in
+     * unrelated components are untouched.
+     */
+    priorityId?: string;
+}
+/**
+ * Layout all timed events for a single day. Returns one
+ * `PositionedEvent` per event that intersects the visible time
+ * range, with lane assignments for overlap resolution.
+ *
+ * All-day events and events outside the time range are excluded;
+ * those belong to a separate all-day band, rendered above the time
+ * grid by week / day views.
+ */
+export declare function layoutDayEvents<TMeta extends Record<string, unknown> = Record<string, unknown>>(events: ReadonlyArray<CalendarEvent<TMeta>>, opts: DayLayoutOptions): PositionedEvent<TMeta>[];
+/**
+ * An all-day event positioned within a visible-day-range. Used by
+ * the time grid's all-day band (above the hour grid) to render
+ * multi-day events as horizontal bars spanning multiple day-columns.
+ */
+export interface AllDayBar<TMeta extends Record<string, unknown> = Record<string, unknown>> {
+    event: CalendarEvent<TMeta>;
+    /** Lane (vertical row inside the band). 0 = topmost. */
+    lane: number;
+    /** Total lanes used. Caller picks the band height from this. */
+    laneCount: number;
+    /** First column the bar covers, 0-indexed. Inclusive. */
+    startCol: number;
+    /** Last column the bar covers, 0-indexed. Inclusive. */
+    endCol: number;
+    /** True when the event extends earlier than `days[0]`. */
+    clippedStart: boolean;
+    /** True when the event extends later than `days[days.length-1]`. */
+    clippedEnd: boolean;
+}
+export interface AllDayBandOptions {
+    /** Days to render (one column each). Length = number of columns. */
+    days: ReadonlyArray<Temporal.PlainDate>;
+    /**
+     * Timezone used to bucket date-time events by local day. Date-only
+     * events are timezone-independent.
+     */
+    timezone: string;
+}
+/**
+ * Lay out all-day + multi-day events for a week / day view's
+ * all-day band.
+ *
+ * Includes:
+ *   - Events with `allDay: true`
+ *   - Events with date-only `start` (no time component)
+ *
+ * Excludes (these go in the time grid):
+ *   - Timed events that start AND end within a single visible day
+ *   - Timed events with end-after-midnight (handled per-column by
+ *     the time grid via clipping)
+ *
+ * For each included event, computes `[startCol, endCol]` clipped to
+ * the visible day range, runs `layoutOverlappingIntervals`, returns
+ * one `AllDayBar` per event.
+ */
+export declare function layoutAllDayBand<TMeta extends Record<string, unknown> = Record<string, unknown>>(events: ReadonlyArray<CalendarEvent<TMeta>>, opts: AllDayBandOptions): AllDayBar<TMeta>[];
+//# sourceMappingURL=timeGridLayout.d.ts.map

package/dist/core/timeGridLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeGridLayout.d.ts","sourceRoot":"","sources":["../../src/core/timeGridLayout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAE,QAAQ,EAAW,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9F,4DAA4D;IAC5D,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC;IACxB,qDAAqD;IACrD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7F,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAC3C,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAAC,KAAK,CAAC,EAAE,CAyJ1B;AAMD;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxF,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACxC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9F,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAC3C,IAAI,EAAE,iBAAiB,GACtB,SAAS,CAAC,KAAK,CAAC,EAAE,CAiGpB"}