@dataverse-kit/calendar-kit 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @dataverse-kit/calendar-kit
+
+A calendar for the Microsoft stack, built on [FullCalendar v7](https://fullcalendar.io) (MIT
+views only). You give it plain event objects; it knows nothing about Dataverse. The Dataverse
+rules live in separate entries, so the same calendar serves a PCF control, a Power Apps code app
+and a Power Pages site.
+
+```bash
+npm install @dataverse-kit/calendar-kit
+# peers: react@18, react-dom@18; @fluentui/react-components@9 only for ./v9
+```
+
+## Entries
+
+| Import | What | Pulls in |
+|---|---|---|
+| `@dataverse-kit/calendar-kit` | `CalendarView` — no Fluent (use this on Power Pages) | React, FullCalendar |
+| `…/v9` | `FluentCalendar` — themed from the surrounding `FluentProvider` | + Fluent v9 |
+| `…/core` | event contract, value kinds, zone conversion, colours | nothing |
+| `…/dataverse` | DateTime behaviours, column mapping, Web API / form-parameter writers | nothing |
+| `…/adapters/pcf-dataset` | PCF dataset → events, range filter, not-found detection | nothing |
+| `…/fake` | seeded sample events and an in-memory data source | nothing |
+
+## Use it
+
+```tsx
+import { FluentCalendar } from '@dataverse-kit/calendar-kit/v9';
+
+<FluentCalendar
+  events={[
+    { id: '1', title: 'Consultation', start: '2026-09-30T15:00:00Z', end: '2026-09-30T15:30:00Z' },
+    { id: '2', title: 'Clinic closed', start: '2026-10-02', end: '2026-10-03' },
+  ]}
+  view="week"
+  editable
+  onEventChange={async (change) => {
+    await save(change); // reject → the event snaps back and a message is shown
+  }}
+  onSelectRange={(slot) => openQuickCreate(slot)}
+  onEventClick={(event) => openRecord(event.id)}
+  onRangeChange={(range) => load(range)}
+/>;
+```
+
+### Values: the shape of the text is its meaning
+
+| Text | Kind | Dataverse behaviour |
+|---|---|---|
+| `2026-09-29` | a day (all-day) | DateOnly |
+| `2026-09-29T23:30:00` | a wall-clock time, same face everywhere | TimeZoneIndependent |
+| `2026-09-30T06:30:00Z` | an instant, shown in the viewer's zone | UserLocal |
+
+An event keeps its kind through a drag. All-day `end` is **exclusive** (the day after).
+
+### Time zone
+
+Pass `zone` — a function returning minutes **east** of UTC for an instant. In a PCF control that
+is the Dynamics user's zone:
+
+```ts
+const zone = (d: Date) => context.userSettings.getTimeZoneOffsetMinutes(d);
+```
+
+Without it the browser's zone is used, which is wrong whenever the two differ.
+
+### In a PCF dataset control
+
+```ts
+import { resolveColumnMap, resolveBehaviors, readDatasetEvents, buildRangeFilter } from '@dataverse-kit/calendar-kit/adapters/pcf-dataset';
+import { toWebApiPatch, toQuickCreateParameters } from '@dataverse-kit/calendar-kit/dataverse';
+```
+
+Map columns with manifest property-sets named `startColumn`, `endColumn`, `titleColumn`,
+`colorColumn`, `groupColumn`, `allDayColumn`.
+
+## Measured facts this package encodes
+
+Measured on a live Dataverse org, not taken from documentation; each is pinned by a test.
+
+- A dataset's `getValue()` on a date column returns an **ISO string**, not a `Date` — for all three
+  behaviours. DateOnly arrives as UTC midnight, so reading it through `new Date()` gives the
+  previous day west of UTC.
+- TimeZoneIndependent and UserLocal columns report the same `dataType`; only metadata
+  (`Behavior` 1/2/3) tells them apart.
+- `webAPI.updateRecord` and `navigation.openForm` parameters are **different contracts** — see
+  `src/dataverse/dates.ts`. A bare `YYYY-MM-DD` quick-create parameter stored the previous day.
+- A dataset range filter is ANDed with the view's own filter.
+
+## Known limits
+
+- The root and `./v9` entries import FullCalendar (ESM) and its CSS, so they are for **bundlers**
+  (Vite, webpack, pcf-scripts). Their `.cjs` builds cannot be `require()`d from plain Node. The
+  pure entries (`./core`, `./dataverse`, `./adapters/*`, `./fake`) work anywhere.
+- Importing both the root and `./v9` bundles `CalendarView` twice. Pick one.
+- On a spring-forward day a selection inside the missing hour has zero length (that hour does
+  not exist in the zone).
+
+## Licensing
+
+MIT. Uses only FullCalendar's MIT views (day grid, time grid, list, multi-month, interaction).
+FullCalendar Premium (resource and timeline views) is **not** included or required.
+
+**Stack:** React 18 · FullCalendar 7.1 · Fluent UI v9 (optional) · TypeScript · tsup

package/dist/CalendarView-CShiWFsR.d.ts

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import { a as CalendarEvent, Z as ZoneOffset, B as BusinessHours, S as SlotSelection, b as CalendarEventChange, d as VisibleRange } from './types-u3Gpxk53.js';
+
+/**
+ * The colours a calendar can be themed with, as plain CSS values (hex, rgb(), or `var(--x)`).
+ * Each maps onto one of FullCalendar v7's classic-theme custom properties, so theming is just
+ * setting variables on the calendar's own container — no stylesheet override, nothing global.
+ *
+ * ★ Scoped to the container on purpose: FullCalendar's palette declares its defaults on `:root`,
+ *   and a PCF control shares `:root` with the whole form. Two calendars on one form each set
+ *   their own, and neither touches the host.
+ */
+interface CalendarTheme {
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    foreground?: string;
+    mutedForeground?: string;
+    faint?: string;
+    muted?: string;
+    strong?: string;
+    border?: string;
+    strongBorder?: string;
+    today?: string;
+    highlight?: string;
+    now?: string;
+    button?: string;
+    buttonForeground?: string;
+    buttonBorder?: string;
+    buttonStrong?: string;
+    buttonStrongBorder?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    /** Rendered as a banner above the calendar when a save fails. */
+    error?: string;
+}
+/** The container style that applies `theme`. Unset keys keep FullCalendar's defaults. */
+declare function themeStyle(theme: CalendarTheme | undefined): React.CSSProperties;
+
+/** The views a host can ask for, by plain name. */
+type CalendarViewName = 'month' | 'week' | 'workWeek' | 'day' | 'list';
+interface CalendarViewProps {
+    /** Plain event objects. See `CalendarEvent` for how a value's shape sets its kind. */
+    events: readonly CalendarEvent[];
+    /** The zone to show instants in. Default: the browser's. A PCF host passes the USER's. */
+    zone?: ZoneOffset;
+    /** Starting view. Default `week`. */
+    view?: CalendarViewName;
+    /** View buttons offered, in order. Default: month, week, day, list. */
+    views?: readonly CalendarViewName[];
+    /** `YYYY-MM-DD` to open on. Default today (in `zone`). */
+    initialDate?: string;
+    /** Allow drag and resize. Default false — read-only is the safe default. */
+    editable?: boolean;
+    /** Allow selecting an empty range (→ `onSelectRange`). Default: true when a handler is given. */
+    selectable?: boolean;
+    businessHours?: readonly BusinessHours[];
+    /** 0 = Sunday. */
+    firstDay?: number;
+    /** `HH:mm:ss` bounds of the time grid. */
+    slotMinTime?: string;
+    slotMaxTime?: string;
+    /** Where the time grid first scrolls to. Default `08:00:00`. */
+    scrollTime?: string;
+    /** Any CSS height, `'auto'`, or a number of pixels. Default `'auto'`. */
+    height?: number | string;
+    theme?: CalendarTheme;
+    /** Shown while data for a new range loads. */
+    loading?: boolean;
+    className?: string;
+    /**
+     * Classes for FullCalendar's own parts. ★ v7 HASHES its class names (`fc-classic-1El`), so a
+     * descendant selector like `.fc-button` matches NOTHING — measured: 0 of 7 buttons. These go
+     * through FullCalendar's `buttonClass` / `headerToolbarClass` options instead.
+     */
+    classNames?: {
+        button?: string;
+        toolbar?: string;
+    };
+    /** Accessible name for the calendar region. */
+    'aria-label'?: string;
+    onEventClick?: (event: CalendarEvent) => void;
+    onSelectRange?: (selection: SlotSelection) => void;
+    /**
+     * A move or resize. Return a promise to make it OPTIMISTIC: the event stays where it was
+     * dropped while the promise runs, and goes back — with a message — if it rejects.
+     */
+    onEventChange?: (change: CalendarEventChange) => void | Promise<void>;
+    onRangeChange?: (range: VisibleRange) => void;
+    /** Called after a failed change has been reverted. The banner is shown either way. */
+    onChangeError?: (error: unknown, change: CalendarEventChange) => void;
+}
+/**
+ * FullCalendar v7 (MIT views only), fed plain events. Knows nothing about Dataverse and nothing
+ * about Fluent — this entry is what a Power Pages site uses. `FluentCalendar` (`./v9`) wraps it
+ * with Fluent tokens.
+ *
+ * ★ Nothing here portals and nothing uses tabster, so it cannot join the Fluent/tabster
+ *   singleton race that has taken down PCF controls on model-driven forms. The error banner is
+ *   in-tree for the same reason: a Toast or Dialog would portal to `document.body`.
+ */
+declare function CalendarView(props: CalendarViewProps): React.ReactElement;
+
+export { type CalendarTheme as C, CalendarView as a, type CalendarViewName as b, type CalendarViewProps as c, themeStyle as t };

package/dist/CalendarView-Dd8BHOLE.d.cts

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import { a as CalendarEvent, Z as ZoneOffset, B as BusinessHours, S as SlotSelection, b as CalendarEventChange, d as VisibleRange } from './types-u3Gpxk53.cjs';
+
+/**
+ * The colours a calendar can be themed with, as plain CSS values (hex, rgb(), or `var(--x)`).
+ * Each maps onto one of FullCalendar v7's classic-theme custom properties, so theming is just
+ * setting variables on the calendar's own container — no stylesheet override, nothing global.
+ *
+ * ★ Scoped to the container on purpose: FullCalendar's palette declares its defaults on `:root`,
+ *   and a PCF control shares `:root` with the whole form. Two calendars on one form each set
+ *   their own, and neither touches the host.
+ */
+interface CalendarTheme {
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    foreground?: string;
+    mutedForeground?: string;
+    faint?: string;
+    muted?: string;
+    strong?: string;
+    border?: string;
+    strongBorder?: string;
+    today?: string;
+    highlight?: string;
+    now?: string;
+    button?: string;
+    buttonForeground?: string;
+    buttonBorder?: string;
+    buttonStrong?: string;
+    buttonStrongBorder?: string;
+    fontFamily?: string;
+    fontSize?: string;
+    /** Rendered as a banner above the calendar when a save fails. */
+    error?: string;
+}
+/** The container style that applies `theme`. Unset keys keep FullCalendar's defaults. */
+declare function themeStyle(theme: CalendarTheme | undefined): React.CSSProperties;
+
+/** The views a host can ask for, by plain name. */
+type CalendarViewName = 'month' | 'week' | 'workWeek' | 'day' | 'list';
+interface CalendarViewProps {
+    /** Plain event objects. See `CalendarEvent` for how a value's shape sets its kind. */
+    events: readonly CalendarEvent[];
+    /** The zone to show instants in. Default: the browser's. A PCF host passes the USER's. */
+    zone?: ZoneOffset;
+    /** Starting view. Default `week`. */
+    view?: CalendarViewName;
+    /** View buttons offered, in order. Default: month, week, day, list. */
+    views?: readonly CalendarViewName[];
+    /** `YYYY-MM-DD` to open on. Default today (in `zone`). */
+    initialDate?: string;
+    /** Allow drag and resize. Default false — read-only is the safe default. */
+    editable?: boolean;
+    /** Allow selecting an empty range (→ `onSelectRange`). Default: true when a handler is given. */
+    selectable?: boolean;
+    businessHours?: readonly BusinessHours[];
+    /** 0 = Sunday. */
+    firstDay?: number;
+    /** `HH:mm:ss` bounds of the time grid. */
+    slotMinTime?: string;
+    slotMaxTime?: string;
+    /** Where the time grid first scrolls to. Default `08:00:00`. */
+    scrollTime?: string;
+    /** Any CSS height, `'auto'`, or a number of pixels. Default `'auto'`. */
+    height?: number | string;
+    theme?: CalendarTheme;
+    /** Shown while data for a new range loads. */
+    loading?: boolean;
+    className?: string;
+    /**
+     * Classes for FullCalendar's own parts. ★ v7 HASHES its class names (`fc-classic-1El`), so a
+     * descendant selector like `.fc-button` matches NOTHING — measured: 0 of 7 buttons. These go
+     * through FullCalendar's `buttonClass` / `headerToolbarClass` options instead.
+     */
+    classNames?: {
+        button?: string;
+        toolbar?: string;
+    };
+    /** Accessible name for the calendar region. */
+    'aria-label'?: string;
+    onEventClick?: (event: CalendarEvent) => void;
+    onSelectRange?: (selection: SlotSelection) => void;
+    /**
+     * A move or resize. Return a promise to make it OPTIMISTIC: the event stays where it was
+     * dropped while the promise runs, and goes back — with a message — if it rejects.
+     */
+    onEventChange?: (change: CalendarEventChange) => void | Promise<void>;
+    onRangeChange?: (range: VisibleRange) => void;
+    /** Called after a failed change has been reverted. The banner is shown either way. */
+    onChangeError?: (error: unknown, change: CalendarEventChange) => void;
+}
+/**
+ * FullCalendar v7 (MIT views only), fed plain events. Knows nothing about Dataverse and nothing
+ * about Fluent — this entry is what a Power Pages site uses. `FluentCalendar` (`./v9`) wraps it
+ * with Fluent tokens.
+ *
+ * ★ Nothing here portals and nothing uses tabster, so it cannot join the Fluent/tabster
+ *   singleton race that has taken down PCF controls on model-driven forms. The error banner is
+ *   in-tree for the same reason: a Toast or Dialog would portal to `document.body`.
+ */
+declare function CalendarView(props: CalendarViewProps): React.ReactElement;
+
+export { type CalendarTheme as C, CalendarView as a, type CalendarViewName as b, type CalendarViewProps as c, themeStyle as t };

package/dist/core.cjs

@@ -0,0 +1,192 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  GROUP_PALETTE: () => GROUP_PALETTE,
+  addDays: () => addDays,
+  browserZone: () => browserZone,
+  contrastRatio: () => contrastRatio,
+  fixedZone: () => fixedZone,
+  fromWall: () => fromWall,
+  groupColor: () => groupColor,
+  kindOf: () => kindOf,
+  normaliseFloating: () => normaliseFloating,
+  parseHex: () => parseHex,
+  readableTextOn: () => readableTextOn,
+  toDate: () => toDate,
+  toInstant: () => toInstant,
+  toWall: () => toWall,
+  utcFieldsToWall: () => utcFieldsToWall
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/datetime.ts
+var DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+var FLOATING_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?$/;
+var INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})$/i;
+var pad = (n, w = 2) => String(n).padStart(w, "0");
+var browserZone = (instant) => -instant.getTimezoneOffset();
+var fixedZone = (minutesEast) => () => minutesEast;
+function kindOf(value) {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new RangeError("Invalid Date");
+    return "instant";
+  }
+  const local = DATE_RE.test(value) ? "date" : FLOATING_RE.test(value) ? "floating" : null;
+  if (local) {
+    const m = FLOATING_RE.exec(value) ?? DATE_RE.exec(value);
+    const [, y, mo, d, h = "0", mi = "0", sec = "0"] = m;
+    const t = new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +sec));
+    if (t.getUTCFullYear() !== +y || t.getUTCMonth() !== +mo - 1 || t.getUTCDate() !== +d || +h > 23 || +mi > 59 || +sec > 59) {
+      throw new RangeError(`Not a real calendar date or time: ${JSON.stringify(value)}`);
+    }
+    return local;
+  }
+  if (INSTANT_RE.test(value) && !Number.isNaN(new Date(value).getTime())) return "instant";
+  throw new RangeError(`Not an ISO-8601 date, wall-clock time or instant: ${JSON.stringify(value)}`);
+}
+function toInstant(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (kindOf(value) !== "instant") throw new RangeError(`Not an instant: ${value}`);
+  return new Date(value).toISOString();
+}
+function wallMillis(wall) {
+  const m = FLOATING_RE.exec(wall) ?? DATE_RE.exec(wall);
+  if (!m) throw new RangeError(`Not a date or wall-clock time: ${wall}`);
+  const [, y, mo, d, h = "0", mi = "0", s = "0"] = m;
+  return Date.UTC(+y, +mo - 1, +d, +h, +mi, +s);
+}
+function formatWall(ms) {
+  const d = new Date(ms);
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+function toWall(instant, zone) {
+  const at = instant instanceof Date ? instant : new Date(toInstant(instant));
+  return formatWall(at.getTime() + zone(at) * 6e4);
+}
+function fromWall(wall, zone) {
+  const w = wallMillis(wall);
+  const before = zone(new Date(w - 864e5));
+  const after = zone(new Date(w + 864e5));
+  const fits = (offset) => {
+    const t2 = w - offset * 6e4;
+    return zone(new Date(t2)) === offset ? t2 : null;
+  };
+  const candidates = [fits(before), fits(after)].filter((t2) => t2 !== null);
+  const t = candidates.length > 0 ? Math.min(...candidates) : w - before * 6e4;
+  return new Date(t).toISOString();
+}
+function toDate(value, zone) {
+  const k = kindOf(value);
+  if (k === "date") return value;
+  if (k === "floating") return value.slice(0, 10);
+  return toWall(value, zone).slice(0, 10);
+}
+function addDays(date, days) {
+  if (kindOf(date) !== "date") throw new RangeError(`addDays needs a date, got ${date}`);
+  return formatWall(wallMillis(date) + days * 864e5).slice(0, 10);
+}
+function utcFieldsToWall(d) {
+  return formatWall(d.getTime());
+}
+function normaliseFloating(value) {
+  return formatWall(wallMillis(value));
+}
+
+// src/core/colors.ts
+var GROUP_PALETTE = [
+  "#0f6cbd",
+  // blue
+  "#107c10",
+  // green
+  "#c50f1f",
+  // red
+  "#8764b8",
+  // lavender
+  "#ae4b00",
+  // dark orange
+  "#03787c",
+  // teal
+  "#4f52b2",
+  // indigo
+  "#8a5b00",
+  // dark gold
+  "#c0077d",
+  // magenta
+  "#5c2e91"
+  // purple
+];
+function hash(key) {
+  let h = 2166136261;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function groupColor(key, palette = GROUP_PALETTE) {
+  return palette[hash(key) % palette.length];
+}
+function parseHex(color) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+function luminance([r, g, b]) {
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+function contrastRatio(a, b) {
+  const pa = parseHex(a);
+  const pb = parseHex(b);
+  if (!pa || !pb) return null;
+  const [hi, lo] = [luminance(pa), luminance(pb)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+function readableTextOn(background) {
+  const onWhite = contrastRatio(background, "#ffffff");
+  const onBlack = contrastRatio(background, "#000000");
+  if (onWhite === null || onBlack === null) return void 0;
+  return onWhite >= onBlack ? "#ffffff" : "#000000";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GROUP_PALETTE,
+  addDays,
+  browserZone,
+  contrastRatio,
+  fixedZone,
+  fromWall,
+  groupColor,
+  kindOf,
+  normaliseFloating,
+  parseHex,
+  readableTextOn,
+  toDate,
+  toInstant,
+  toWall,
+  utcFieldsToWall
+});
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/index.ts","../src/core/datetime.ts","../src/core/colors.ts"],"sourcesContent":["/**\n * `@dataverse-kit/calendar-kit/core` — the framework-agnostic layer: the event contract, value\n * kinds and zone conversion, and colours. No React, no FullCalendar, no Fluent, no Dataverse.\n */\nexport type {\n  BusinessHours,\n  CalendarDataSource,\n  CalendarEvent,\n  CalendarEventChange,\n  CalendarValue,\n  SlotSelection,\n  ValueKind,\n  VisibleRange,\n  ZoneOffset,\n} from './types';\nexport {\n  addDays,\n  browserZone,\n  fixedZone,\n  fromWall,\n  kindOf,\n  normaliseFloating,\n  toDate,\n  toInstant,\n  toWall,\n  utcFieldsToWall,\n} from './datetime';\nexport { GROUP_PALETTE, contrastRatio, groupColor, parseHex, readableTextOn } from './colors';\n","import type { CalendarValue, ValueKind, ZoneOffset } from './types';\n\n/**\n * Value-kind detection and zone conversion.\n *\n * ★★ Nothing in this file may read the PROCESS time zone. Every `Date` is built and read through\n *    its UTC fields, so the same input gives the same output on a laptop in Auckland and a CI\n *    runner in UTC. `npm test` runs the suite under three TZ values to prove it — a single-zone\n *    run cannot see a leak, because the developer's zone is the one the code was written in.\n */\n\nconst DATE_RE = /^(\\d{4})-(\\d{2})-(\\d{2})$/;\nconst FLOATING_RE = /^(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2})(?::(\\d{2})(?:\\.\\d{1,9})?)?$/;\nconst INSTANT_RE = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,9})?)?(?:Z|[+-]\\d{2}:?\\d{2})$/i;\n\nconst pad = (n: number, w = 2): string => String(n).padStart(w, '0');\n\n/** The browser's own zone, east-positive. The default when a host supplies none. */\nexport const browserZone: ZoneOffset = (instant) => -instant.getTimezoneOffset();\n\n/** A fixed zone (no daylight saving). Mostly for tests and demos. */\nexport const fixedZone =\n  (minutesEast: number): ZoneOffset =>\n  () =>\n    minutesEast;\n\nexport function kindOf(value: CalendarValue | Date): ValueKind {\n  if (value instanceof Date) {\n    if (Number.isNaN(value.getTime())) throw new RangeError('Invalid Date');\n    return 'instant';\n  }\n  const local = DATE_RE.test(value) ? 'date' : FLOATING_RE.test(value) ? 'floating' : null;\n  if (local) {\n    // ★ The regex accepts `2026-02-31`; Date.UTC would silently roll it to March 3rd. Reject\n    //   any date whose fields do not survive a round trip.\n    const m = (FLOATING_RE.exec(value) ?? DATE_RE.exec(value))!;\n    const [, y, mo, d, h = '0', mi = '0', sec = '0'] = m;\n    const t = new Date(Date.UTC(+y, +mo - 1, +d, +h, +mi, +sec));\n    if (t.getUTCFullYear() !== +y || t.getUTCMonth() !== +mo - 1 || t.getUTCDate() !== +d || +h > 23 || +mi > 59 || +sec > 59) {\n      throw new RangeError(`Not a real calendar date or time: ${JSON.stringify(value)}`);\n    }\n    return local;\n  }\n  if (INSTANT_RE.test(value) && !Number.isNaN(new Date(value).getTime())) return 'instant';\n  throw new RangeError(`Not an ISO-8601 date, wall-clock time or instant: ${JSON.stringify(value)}`);\n}\n\n/** An instant as canonical UTC ISO text (`…T…Z`, milliseconds kept). */\nexport function toInstant(value: CalendarValue | Date): CalendarValue {\n  if (value instanceof Date) return value.toISOString();\n  if (kindOf(value) !== 'instant') throw new RangeError(`Not an instant: ${value}`);\n  return new Date(value).toISOString();\n}\n\n/** `Date.UTC` from wall-clock fields — i.e. the wall clock treated AS IF it were UTC. */\nfunction wallMillis(wall: string): number {\n  const m = FLOATING_RE.exec(wall) ?? DATE_RE.exec(wall);\n  if (!m) throw new RangeError(`Not a date or wall-clock time: ${wall}`);\n  const [, y, mo, d, h = '0', mi = '0', s = '0'] = m;\n  return Date.UTC(+y, +mo - 1, +d, +h, +mi, +s);\n}\n\nfunction formatWall(ms: number): string {\n  const d = new Date(ms);\n  return (\n    `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +\n    `T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`\n  );\n}\n\n/** The wall-clock reading of an instant in `zone`, as floating text (`YYYY-MM-DDTHH:mm:ss`). */\nexport function toWall(instant: CalendarValue | Date, zone: ZoneOffset): CalendarValue {\n  const at = instant instanceof Date ? instant : new Date(toInstant(instant));\n  return formatWall(at.getTime() + zone(at) * 60_000);\n}\n\n/**\n * The instant at which `zone`'s clocks read `wall`.\n *\n * The offset depends on the instant being solved for, so this takes the offset in force a day\n * BEFORE and a day AFTER the wall reading (no zone changes offset twice in 48 h) and tries both:\n *  - an ordinary time: both give the same instant;\n *  - a wall time that exists TWICE (fall-back): both round-trip, and the EARLIER is returned;\n *  - a wall time that DOES NOT EXIST (spring-forward gap): neither round-trips, and the\n *    pre-transition offset is used, which pushes it forward by the gap (02:30 → 03:30), as JS\n *    `Date` does. What Dataverse does with one is UNMEASURED.\n *\n * ★ A reviewer caught the first version returning the LATER occurrence east of UTC (Berlin) and\n *   the earlier one west of it (Pacific): the two-pass guess settled on whichever offset the\n *   first guess happened to land in. Tests now pin both hemispheres with synthetic zones.\n */\nexport function fromWall(wall: CalendarValue, zone: ZoneOffset): CalendarValue {\n  const w = wallMillis(wall);\n  const before = zone(new Date(w - 86_400_000));\n  const after = zone(new Date(w + 86_400_000));\n  const fits = (offset: number): number | null => {\n    const t = w - offset * 60_000;\n    return zone(new Date(t)) === offset ? t : null;\n  };\n  const candidates = [fits(before), fits(after)].filter((t): t is number => t !== null);\n  const t = candidates.length > 0 ? Math.min(...candidates) : w - before * 60_000;\n  return new Date(t).toISOString();\n}\n\n/** The calendar day (`YYYY-MM-DD`) of any value, in `zone` for instants. */\nexport function toDate(value: CalendarValue | Date, zone: ZoneOffset): CalendarValue {\n  const k = kindOf(value);\n  if (k === 'date') return value as string;\n  if (k === 'floating') return (value as string).slice(0, 10);\n  return toWall(value, zone).slice(0, 10);\n}\n\n/** Calendar-day arithmetic on a `YYYY-MM-DD` value (no zone involved). */\nexport function addDays(date: CalendarValue, days: number): CalendarValue {\n  if (kindOf(date) !== 'date') throw new RangeError(`addDays needs a date, got ${date}`);\n  return formatWall(wallMillis(date) + days * 86_400_000).slice(0, 10);\n}\n\n/**\n * The UTC fields of a `Date` as floating text. For reading a `Date` that some library has\n * produced in a \"UTC-as-wall-clock\" convention (FullCalendar with `timeZone: 'UTC'`).\n */\nexport function utcFieldsToWall(d: Date): CalendarValue {\n  return formatWall(d.getTime());\n}\n\n/** Normalise floating text to seconds precision (`…T09:00` → `…T09:00:00`). */\nexport function normaliseFloating(value: CalendarValue): CalendarValue {\n  return formatWall(wallMillis(value));\n}\n","/**\n * Event colours.\n *\n * ★ Without FullCalendar Premium there are no resource lanes, so \"appointments by location\"\n *   is expressed as ONE COLOUR PER GROUP. `groupColor` is deterministic (same key → same colour\n *   on every load and every machine), which is what lets a person learn the legend.\n * ★ Every palette entry carries white text at >= 4.5:1 (WCAG AA, normal text) — asserted by a\n *   test, not by eye. Host-supplied colours (Dataverse option colours are often pale) get their\n *   text colour from `readableTextOn` instead of assuming white; a well-known client control\n *   hard-coded white on yellow, which is ~1.4:1.\n */\nexport const GROUP_PALETTE: readonly string[] = [\n  '#0f6cbd', // blue\n  '#107c10', // green\n  '#c50f1f', // red\n  '#8764b8', // lavender\n  '#ae4b00', // dark orange\n  '#03787c', // teal\n  '#4f52b2', // indigo\n  '#8a5b00', // dark gold\n  '#c0077d', // magenta\n  '#5c2e91', // purple\n];\n\n/** FNV-1a — tiny, stable across engines, good enough spread for a 10-colour palette. */\nfunction hash(key: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < key.length; i++) {\n    h ^= key.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\nexport function groupColor(key: string, palette: readonly string[] = GROUP_PALETTE): string {\n  return palette[hash(key) % palette.length];\n}\n\n/** `#rgb` / `#rrggbb` → [r, g, b] 0-255, or null for anything else (named colours, var()). */\nexport function parseHex(color: string): [number, number, number] | null {\n  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());\n  if (!m) return null;\n  const h = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];\n  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number];\n}\n\nfunction luminance([r, g, b]: [number, number, number]): number {\n  const lin = (c: number): number => {\n    const s = c / 255;\n    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;\n  };\n  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);\n}\n\n/** WCAG contrast ratio between two hex colours, or null if either cannot be parsed. */\nexport function contrastRatio(a: string, b: string): number | null {\n  const pa = parseHex(a);\n  const pb = parseHex(b);\n  if (!pa || !pb) return null;\n  const [hi, lo] = [luminance(pa), luminance(pb)].sort((x, y) => y - x);\n  return (hi + 0.05) / (lo + 0.05);\n}\n\n/**\n * Black or white text, whichever reads better on `background`. Unparseable backgrounds\n * (a CSS variable, a named colour) get `undefined`, i.e. the theme's own event text colour.\n */\nexport function readableTextOn(background: string): '#000000' | '#ffffff' | undefined {\n  const onWhite = contrastRatio(background, '#ffffff');\n  const onBlack = contrastRatio(background, '#000000');\n  if (onWhite === null || onBlack === null) return undefined;\n  return onWhite >= onBlack ? '#ffffff' : '#000000';\n}\n"],"mappings":"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","names":["t"]}

package/dist/core.d.cts

@@ -0,0 +1,64 @@
+import { c as CalendarValue, Z as ZoneOffset, V as ValueKind } from './types-u3Gpxk53.cjs';
+export { B as BusinessHours, C as CalendarDataSource, a as CalendarEvent, b as CalendarEventChange, S as SlotSelection, d as VisibleRange } from './types-u3Gpxk53.cjs';
+
+/** The browser's own zone, east-positive. The default when a host supplies none. */
+declare const browserZone: ZoneOffset;
+/** A fixed zone (no daylight saving). Mostly for tests and demos. */
+declare const fixedZone: (minutesEast: number) => ZoneOffset;
+declare function kindOf(value: CalendarValue | Date): ValueKind;
+/** An instant as canonical UTC ISO text (`…T…Z`, milliseconds kept). */
+declare function toInstant(value: CalendarValue | Date): CalendarValue;
+/** The wall-clock reading of an instant in `zone`, as floating text (`YYYY-MM-DDTHH:mm:ss`). */
+declare function toWall(instant: CalendarValue | Date, zone: ZoneOffset): CalendarValue;
+/**
+ * The instant at which `zone`'s clocks read `wall`.
+ *
+ * The offset depends on the instant being solved for, so this takes the offset in force a day
+ * BEFORE and a day AFTER the wall reading (no zone changes offset twice in 48 h) and tries both:
+ *  - an ordinary time: both give the same instant;
+ *  - a wall time that exists TWICE (fall-back): both round-trip, and the EARLIER is returned;
+ *  - a wall time that DOES NOT EXIST (spring-forward gap): neither round-trips, and the
+ *    pre-transition offset is used, which pushes it forward by the gap (02:30 → 03:30), as JS
+ *    `Date` does. What Dataverse does with one is UNMEASURED.
+ *
+ * ★ A reviewer caught the first version returning the LATER occurrence east of UTC (Berlin) and
+ *   the earlier one west of it (Pacific): the two-pass guess settled on whichever offset the
+ *   first guess happened to land in. Tests now pin both hemispheres with synthetic zones.
+ */
+declare function fromWall(wall: CalendarValue, zone: ZoneOffset): CalendarValue;
+/** The calendar day (`YYYY-MM-DD`) of any value, in `zone` for instants. */
+declare function toDate(value: CalendarValue | Date, zone: ZoneOffset): CalendarValue;
+/** Calendar-day arithmetic on a `YYYY-MM-DD` value (no zone involved). */
+declare function addDays(date: CalendarValue, days: number): CalendarValue;
+/**
+ * The UTC fields of a `Date` as floating text. For reading a `Date` that some library has
+ * produced in a "UTC-as-wall-clock" convention (FullCalendar with `timeZone: 'UTC'`).
+ */
+declare function utcFieldsToWall(d: Date): CalendarValue;
+/** Normalise floating text to seconds precision (`…T09:00` → `…T09:00:00`). */
+declare function normaliseFloating(value: CalendarValue): CalendarValue;
+
+/**
+ * Event colours.
+ *
+ * ★ Without FullCalendar Premium there are no resource lanes, so "appointments by location"
+ *   is expressed as ONE COLOUR PER GROUP. `groupColor` is deterministic (same key → same colour
+ *   on every load and every machine), which is what lets a person learn the legend.
+ * ★ Every palette entry carries white text at >= 4.5:1 (WCAG AA, normal text) — asserted by a
+ *   test, not by eye. Host-supplied colours (Dataverse option colours are often pale) get their
+ *   text colour from `readableTextOn` instead of assuming white; a well-known client control
+ *   hard-coded white on yellow, which is ~1.4:1.
+ */
+declare const GROUP_PALETTE: readonly string[];
+declare function groupColor(key: string, palette?: readonly string[]): string;
+/** `#rgb` / `#rrggbb` → [r, g, b] 0-255, or null for anything else (named colours, var()). */
+declare function parseHex(color: string): [number, number, number] | null;
+/** WCAG contrast ratio between two hex colours, or null if either cannot be parsed. */
+declare function contrastRatio(a: string, b: string): number | null;
+/**
+ * Black or white text, whichever reads better on `background`. Unparseable backgrounds
+ * (a CSS variable, a named colour) get `undefined`, i.e. the theme's own event text colour.
+ */
+declare function readableTextOn(background: string): '#000000' | '#ffffff' | undefined;
+
+export { CalendarValue, GROUP_PALETTE, ValueKind, ZoneOffset, addDays, browserZone, contrastRatio, fixedZone, fromWall, groupColor, kindOf, normaliseFloating, parseHex, readableTextOn, toDate, toInstant, toWall, utcFieldsToWall };

package/dist/core.d.ts

@@ -0,0 +1,64 @@
+import { c as CalendarValue, Z as ZoneOffset, V as ValueKind } from './types-u3Gpxk53.js';
+export { B as BusinessHours, C as CalendarDataSource, a as CalendarEvent, b as CalendarEventChange, S as SlotSelection, d as VisibleRange } from './types-u3Gpxk53.js';
+
+/** The browser's own zone, east-positive. The default when a host supplies none. */
+declare const browserZone: ZoneOffset;
+/** A fixed zone (no daylight saving). Mostly for tests and demos. */
+declare const fixedZone: (minutesEast: number) => ZoneOffset;
+declare function kindOf(value: CalendarValue | Date): ValueKind;
+/** An instant as canonical UTC ISO text (`…T…Z`, milliseconds kept). */
+declare function toInstant(value: CalendarValue | Date): CalendarValue;
+/** The wall-clock reading of an instant in `zone`, as floating text (`YYYY-MM-DDTHH:mm:ss`). */
+declare function toWall(instant: CalendarValue | Date, zone: ZoneOffset): CalendarValue;
+/**
+ * The instant at which `zone`'s clocks read `wall`.
+ *
+ * The offset depends on the instant being solved for, so this takes the offset in force a day
+ * BEFORE and a day AFTER the wall reading (no zone changes offset twice in 48 h) and tries both:
+ *  - an ordinary time: both give the same instant;
+ *  - a wall time that exists TWICE (fall-back): both round-trip, and the EARLIER is returned;
+ *  - a wall time that DOES NOT EXIST (spring-forward gap): neither round-trips, and the
+ *    pre-transition offset is used, which pushes it forward by the gap (02:30 → 03:30), as JS
+ *    `Date` does. What Dataverse does with one is UNMEASURED.
+ *
+ * ★ A reviewer caught the first version returning the LATER occurrence east of UTC (Berlin) and
+ *   the earlier one west of it (Pacific): the two-pass guess settled on whichever offset the
+ *   first guess happened to land in. Tests now pin both hemispheres with synthetic zones.
+ */
+declare function fromWall(wall: CalendarValue, zone: ZoneOffset): CalendarValue;
+/** The calendar day (`YYYY-MM-DD`) of any value, in `zone` for instants. */
+declare function toDate(value: CalendarValue | Date, zone: ZoneOffset): CalendarValue;
+/** Calendar-day arithmetic on a `YYYY-MM-DD` value (no zone involved). */
+declare function addDays(date: CalendarValue, days: number): CalendarValue;
+/**
+ * The UTC fields of a `Date` as floating text. For reading a `Date` that some library has
+ * produced in a "UTC-as-wall-clock" convention (FullCalendar with `timeZone: 'UTC'`).
+ */
+declare function utcFieldsToWall(d: Date): CalendarValue;
+/** Normalise floating text to seconds precision (`…T09:00` → `…T09:00:00`). */
+declare function normaliseFloating(value: CalendarValue): CalendarValue;
+
+/**
+ * Event colours.
+ *
+ * ★ Without FullCalendar Premium there are no resource lanes, so "appointments by location"
+ *   is expressed as ONE COLOUR PER GROUP. `groupColor` is deterministic (same key → same colour
+ *   on every load and every machine), which is what lets a person learn the legend.
+ * ★ Every palette entry carries white text at >= 4.5:1 (WCAG AA, normal text) — asserted by a
+ *   test, not by eye. Host-supplied colours (Dataverse option colours are often pale) get their
+ *   text colour from `readableTextOn` instead of assuming white; a well-known client control
+ *   hard-coded white on yellow, which is ~1.4:1.
+ */
+declare const GROUP_PALETTE: readonly string[];
+declare function groupColor(key: string, palette?: readonly string[]): string;
+/** `#rgb` / `#rrggbb` → [r, g, b] 0-255, or null for anything else (named colours, var()). */
+declare function parseHex(color: string): [number, number, number] | null;
+/** WCAG contrast ratio between two hex colours, or null if either cannot be parsed. */
+declare function contrastRatio(a: string, b: string): number | null;
+/**
+ * Black or white text, whichever reads better on `background`. Unparseable backgrounds
+ * (a CSS variable, a named colour) get `undefined`, i.e. the theme's own event text colour.
+ */
+declare function readableTextOn(background: string): '#000000' | '#ffffff' | undefined;
+
+export { CalendarValue, GROUP_PALETTE, ValueKind, ZoneOffset, addDays, browserZone, contrastRatio, fixedZone, fromWall, groupColor, kindOf, normaliseFloating, parseHex, readableTextOn, toDate, toInstant, toWall, utcFieldsToWall };