@rapidmx/web-client 0.20.0 → 0.22.0

package/lib/branding/brandingApi.ts

@@ -0,0 +1,97 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s `Branding` route (`BaseBrandingRoute`) — a single, admin-managed,
+ * publicly-readable row of product chrome (logo, title/company name, custom stylesheet, header/footer HTML).
+ * `GET /system/branding` needs no auth (every viewer, including an anonymous booking-page visitor, can read
+ * it); every write is `@RequiresTrustedRole()` on the backend.
+ */
+
+import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+
+export interface Branding {
+    companyName: string;
+    title: string;
+    /** Already a directly-usable `<img src>` value — either an admin-set external URL, or (once uploaded via
+     * `uploadBrandingLogo()`) this server's own resolved asset URL. Never a bare blob key. */
+    logoUrl?: string;
+    /** The compact mark for navigation headers, independently configurable from `logoUrl`'s full logo -
+     * same directly-usable shape as `logoUrl`. Falls back to `logoUrl`, then a built-in default, when unset
+     * (see `useBranding()`'s `iconSrc`) - no fallback is applied here. */
+    iconUrl?: string;
+    /** Same shape as `logoUrl`, directly usable as a `<link href>`. */
+    stylesheetUrl?: string;
+    headerHtml?: string;
+    footerHtml?: string;
+}
+
+/** `client`, given by every function below that isn't a raw-bytes upload, is an explicit `ApiClient` from
+ * `createApiClient()` (e.g. one account of a multi-account app) to call instead of the default global
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+export function getBranding(client?: ApiClient): Promise<Branding> {
+    return withClient(client, "/system/branding");
+}
+
+export interface UpdateBrandingInput {
+    companyName?: string;
+    title?: string;
+    logoUrl?: string;
+    iconUrl?: string;
+    stylesheetUrl?: string;
+    headerHtml?: string;
+    footerHtml?: string;
+}
+
+export function updateBranding(input: UpdateBrandingInput, client?: ApiClient): Promise<Branding> {
+    return withClient(client, "/system/branding", {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+async function uploadBrandingAsset(path: string, file: File): Promise<Branding> {
+    const res = await fetch(apiUrl(path), {
+        method: "POST",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const responseBody = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        const message = (responseBody && (responseBody.message || responseBody.error)) || res.statusText || "Upload failed.";
+        throw new ApiRequestError(message, res.status, responseBody?.code);
+    }
+    return responseBody as Branding;
+}
+
+/** Uploads `file` as the logo, self-hosted via `BlobStore` — bypasses `apiFetch` (which always forces
+ * `Content-Type: application/json`) the same way `mailApi.ts`'s `uploadAttachment()` does, since
+ * `BaseBrandingRoute.uploadLogo()` reads the raw request body directly. */
+export function uploadBrandingLogo(file: File): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/logo", file);
+}
+
+/** Uploads `file` as the compact nav-header icon, independently of `uploadBrandingLogo()`'s full logo. */
+export function uploadBrandingIcon(file: File): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/icon", file);
+}
+
+export function uploadBrandingStylesheet(file: File): Promise<Branding> {
+    return uploadBrandingAsset("/system/branding/stylesheet", file);
+}
+
+export function deleteBrandingLogo(client?: ApiClient): Promise<void> {
+    return withClient(client, "/system/branding/logo", { method: "DELETE" });
+}
+
+export function deleteBrandingIcon(client?: ApiClient): Promise<void> {
+    return withClient(client, "/system/branding/icon", { method: "DELETE" });
+}
+
+export function deleteBrandingStylesheet(client?: ApiClient): Promise<void> {
+    return withClient(client, "/system/branding/stylesheet", { method: "DELETE" });
+}

package/lib/branding/useBranding.ts

@@ -0,0 +1,81 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { Branding, getBranding } from "./brandingApi.js";
+
+const DEFAULT_LOGO_SRC = "/images/logo.svg";
+
+/** `id` of the `<link>` for an uploaded/referenced custom stylesheet — server-rendered directly by
+ * `apps/*​/_layout.tsx` (with this exact id) when one is configured, and kept live by this hook's
+ * background refresh thereafter (matched by this id, rather than always appending a duplicate). */
+export const CUSTOM_STYLESHEET_LINK_ID = "branding-stylesheet";
+
+export interface UseBrandingResult {
+    branding: Branding | null;
+    /** `branding.logoUrl` once loaded, else the built-in default — always a usable `<img src>`. */
+    logoSrc: string;
+    /** `branding.iconUrl` once loaded, falling back to the full logo and then the built-in default — the
+     * compact mark for nav headers (see `Branding.iconUrl`'s doc comment). Always a usable `<img src>`. */
+    iconSrc: string;
+}
+
+/**
+ * Fetches the admin-configured `Branding` singleton once on mount and applies its cosmetic side effects
+ * (browser-tab title, injected custom stylesheet `<link>`) directly to `document` — the same "resolve real
+ * client state once mounted, no SSR prop threading" convention `useIsMobile`/`MailShell`'s query-param reads
+ * already use. `GET /system/branding` needs no auth and never `404`s (see `BaseBrandingRoute.get()`), so a
+ * fetch failure here can only be a real network/server problem — swallowed rather than surfaced, since
+ * branding is purely decorative and every other part of the shell already depends on the same API being
+ * reachable.
+ */
+export default function useBranding(): UseBrandingResult {
+    const [branding, setBranding] = useState<Branding | null>(null);
+
+    useEffect(() => {
+        let cancelled = false;
+        getBranding()
+            .then((result) => {
+                if (!cancelled) {
+                    setBranding(result);
+                }
+            })
+            .catch(() => {
+                // Decorative only — leave `branding` at null, which every consumer already treats as
+                // "use the defaults".
+            });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    useEffect(() => {
+        if (branding?.title) {
+            document.title = branding.title;
+        }
+    }, [branding?.title]);
+
+    useEffect(() => {
+        // Reuses an existing `<link>` (server-rendered by `apps/*​/_layout.tsx` when a stylesheet is already
+        // configured) rather than always appending a duplicate — see `CUSTOM_STYLESHEET_LINK_ID`'s doc comment.
+        let link = document.getElementById(CUSTOM_STYLESHEET_LINK_ID) as HTMLLinkElement | null;
+        if (!branding?.stylesheetUrl) {
+            link?.remove();
+            return;
+        }
+        if (!link) {
+            link = document.createElement("link");
+            link.id = CUSTOM_STYLESHEET_LINK_ID;
+            link.rel = "stylesheet";
+            document.head.appendChild(link);
+        }
+        link.href = branding.stylesheetUrl;
+    }, [branding?.stylesheetUrl]);
+
+    return {
+        branding,
+        logoSrc: branding?.logoUrl || DEFAULT_LOGO_SRC,
+        iconSrc: branding?.iconUrl || branding?.logoUrl || DEFAULT_LOGO_SRC,
+    };
+}

package/lib/calendar/calendarApi.ts

@@ -0,0 +1,309 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/calendar-events` REST surface — see `mailApi.ts`'s own
+ * header comment for the shared ACL/authorization model every wrapper file here follows. Recurrence
+ * expansion happens entirely client-side (see `apps/shared/lib/recurrence.ts`) — the backend stores/returns
+ * `RecurrenceRule` as-is and does no RFC5545 expansion of its own. */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type AttendeeRole = "required" | "optional" | "resource";
+export type AttendeeResponseStatus = "needsAction" | "accepted" | "declined" | "tentative";
+
+export interface Attendee {
+    address: string;
+    displayName?: string;
+    role: AttendeeRole;
+    responseStatus: AttendeeResponseStatus;
+    isOrganizer: boolean;
+}
+
+export type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
+
+/** RFC5545 two-letter weekday codes, matching `rrule`'s own `WeekdayStr` type exactly. */
+export type WeekdayCode = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
+
+export interface RecurrenceRule {
+    freq: RecurrenceFrequency;
+    interval: number;
+    /** Only meaningful for `freq: "weekly"`. */
+    byDay?: WeekdayCode[];
+    byMonthDay?: number[];
+    byMonth?: number[];
+    /** Ends after this many occurrences. Mutually exclusive with `until` — at most one may be set. */
+    count?: number;
+    /** Ends on this date (inclusive). Mutually exclusive with `count`. */
+    until?: string;
+    /** Specific occurrence start dates removed from the recurrence set. */
+    exceptions: string[];
+}
+
+export type CalendarEventStatus = "tentative" | "confirmed" | "cancelled";
+export type BusyStatus = "free" | "busy" | "tentative" | "oof";
+
+/** Who may see an event's details (iCalendar `CLASS`). A private or confidential event is shown to a read-only reader of a shared calendar only as a
+ * busy block (`CalendarEvent.redacted`). `"default"` is what an event with none says. */
+export type EventVisibility = "default" | "public" | "private" | "confidential";
+
+/** What the guests of an event may do (`CalendarEvent.guestsCan*`). */
+export interface GuestPermissions {
+    /** A guest may ask the organizer to change the title, location, description or time. */
+    guestsCanModify: boolean;
+    /** A guest may ask the organizer to add guests. */
+    guestsCanInviteOthers: boolean;
+    /** A guest sees who else was invited. */
+    guestsCanSeeGuestList: boolean;
+}
+
+/** The guest permissions an event has when none were chosen (Google Calendar's own defaults). */
+export const DEFAULT_GUEST_PERMISSIONS: GuestPermissions = { guestsCanModify: false, guestsCanInviteOthers: true, guestsCanSeeGuestList: true };
+
+/** The guest permissions `source` says, a missing (or `null`) flag reading as its default - an event stored before they existed carries none. */
+export function guestPermissionsOf(source: { [K in keyof GuestPermissions]?: boolean | null }): GuestPermissions {
+    return {
+        guestsCanModify: source.guestsCanModify ?? DEFAULT_GUEST_PERMISSIONS.guestsCanModify,
+        guestsCanInviteOthers: source.guestsCanInviteOthers ?? DEFAULT_GUEST_PERMISSIONS.guestsCanInviteOthers,
+        guestsCanSeeGuestList: source.guestsCanSeeGuestList ?? DEFAULT_GUEST_PERMISSIONS.guestsCanSeeGuestList,
+    };
+}
+
+/** The visibility an event has, `"default"` when it says none. */
+export function visibilityOf(event: { visibility?: EventVisibility | null }): EventVisibility {
+    return event.visibility ?? "default";
+}
+
+/**
+ * The organizer's shape is `@rapidmx/restapi`'s general-purpose `Recipient` type (it's reused from the
+ * mail-recipient model), so it requires a `type` field even though a to/cc/bcc distinction is meaningless
+ * for an event organizer — this wrapper always sends `type: "to"` as an inert filler value when building one.
+ */
+export interface CalendarOrganizer {
+    address: string;
+    displayName?: string;
+    type: "to";
+}
+
+export interface CalendarEvent {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    folderUid: string;
+    mailboxUid: string;
+    title: string;
+    location?: string;
+    startDate: string;
+    endDate: string;
+    allDay: boolean;
+    timezone: string;
+    organizer: CalendarOrganizer;
+    attendees: Attendee[];
+    recurrenceRule?: RecurrenceRule;
+    /** For a single occurrence of a recurring event that has been individually modified, its original start date. */
+    recurrenceId?: string;
+    status: CalendarEventStatus;
+    busyStatus: BusyStatus;
+    reminderMinutesBeforeStart?: number;
+    icalUid: string;
+    sequence: number;
+    /** The `sequence` value invites were last sent for (server-internal iTIP tracking) — read-only
+     * display, never sent back in a `CalendarEventInput`. */
+    inviteSequenceSent?: number;
+    /** Set when an iTIP CANCEL was last sent for this event — read-only display, never sent back. */
+    cancelNoticeSentAt?: string;
+    /** When `true`, this event's own [`startDate`, `endDate`] window independently triggers an
+     * automatic-reply period for the mailbox, in addition to (not instead of) the mailbox-level
+     * `Mailbox.oofEnabled` toggle — e.g. a "Vacation" event configuring its own out-of-office window
+     * without touching the mailbox-wide setting. Takes precedence over `Mailbox.oofEnabled` while both
+     * are active (see `@rapidmx/restapi`'s `resolveActiveOof()`). */
+    autoReplyEnabled?: boolean;
+    /** The automatic-reply body while this event's window is active. Only meaningful when
+     * `autoReplyEnabled` is `true`. */
+    autoReplyMessage?: string;
+    /** The `@rapidmx/meet-plugin` `VideoMeeting` minted for this event, when the organizer turned on
+     * video conferencing (see `videoconf/videoMeetingsApi.ts`). Only the link is stored here — each
+     * attendee's own personal join URL is substituted into their own copy of the invitation server-side,
+     * so this event carries no per-attendee link and the organizer's own link is fetched from the meeting
+     * (`getVideoMeeting()`), never read off the event. */
+    videoMeetingUid?: string;
+    /** The description as plain text (at most 32,000 characters). When `descriptionHtml` is set this is its plain-text form. `null` or absent: none. */
+    description?: string | null;
+    /** The description as HTML the server has sanitized down to `b`/`strong`, `i`/`em`, `u`, `br`, `p`, `ul`/`ol`/`li` and `a` (`href` of `http`, `https` or
+     * `mailto` only). Still to be rendered through `sanitizeEventDescriptionHtml()` (`eventDescription.ts`), never trusted as it stands. `null` or absent:
+     * the description, if any, is plain text. */
+    descriptionHtml?: string | null;
+    /** Who may see the event's details - absent (or `null`, on a row stored before this existed) reads as `"default"`; see `visibilityOf()`. */
+    visibility?: EventVisibility | null;
+    /** Whether the guests may ask for the event to change (default `false`). Absent or `null` reads as the default; see `guestPermissionsOf()`. */
+    guestsCanModify?: boolean | null;
+    /** Whether the guests may ask for guests to be added (default `true`). */
+    guestsCanInviteOthers?: boolean | null;
+    /** Whether a guest sees the other guests (default `true`). When `false` a guest's copy lists only themselves. */
+    guestsCanSeeGuestList?: boolean | null;
+    /** Response-only. This reader (of a shared calendar, without edit access) sees the event only as a busy block: the title is `"Busy"` and there are no
+     * attendees, location, description or guest permissions. Never sent back. A live-update notification for such an event carries it too, and the
+     * owner's client refetches by `uid` instead of using the payload. */
+    redacted?: boolean;
+}
+
+const LIST_PAGE_SIZE = 500;
+const LIST_CALENDAR_EVENTS_MAX_PAGES = 100;
+
+/**
+ * Lists every event in a folder (same "fetch the flat list, filter client-side" contract as
+ * `contactsApi.ts`'s `listContacts`/`tasksApi.ts`'s `listTasks`), for the caller to expand and filter
+ * to a visible range itself (see `recurrence.ts`'s `expandAllOccurrences`). This deliberately does
+ * *not* push `startDate`/`endDate` range filtering down to the server via `@rapidmx/restapi`'s
+ * `field=lte(v)`/`gte(v)` query-operator DSL — confirmed directly against a running instance that
+ * `CalendarEventMongo`'s `startDate`/`endDate` are persisted as plain strings despite being typed
+ * `Date`, so a Mongo `$lte`/`$gte` comparison against them (a real `Date` operand) matches nothing at
+ * all, silently returning zero events for *any* date-bounded query. Client-side filtering sidesteps
+ * that entirely and needs no fix to land here.
+ *
+ * Pages through the whole folder (`limit=500`, the server's own page-size cap) until a short page comes
+ * back, so a calendar with more than one page of events isn't silently truncated. A hard cap of
+ * `LIST_CALENDAR_EVENTS_MAX_PAGES` pages guards against looping forever should a server ever ignore
+ * `page` and keep returning full pages.
+ */
+export async function listCalendarEvents(folderUid: string, client?: ApiClient): Promise<CalendarEvent[]> {
+    const events: CalendarEvent[] = [];
+    for (let page = 0; page < LIST_CALENDAR_EVENTS_MAX_PAGES; page++) {
+        const batch = await withClient<CalendarEvent[]>(
+            client,
+            `/mail/calendar-events?${buildQuery({ limit: LIST_PAGE_SIZE, page }, { folderUid })}`,
+        );
+        events.push(...batch);
+        if (batch.length < LIST_PAGE_SIZE) {
+            break;
+        }
+    }
+    return events;
+}
+
+export function getCalendarEvent(uid: string, client?: ApiClient): Promise<CalendarEvent> {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}`);
+}
+
+export interface CalendarEventInput {
+    mailboxUid: string;
+    folderUid: string;
+    title: string;
+    location?: string;
+    startDate: string;
+    endDate: string;
+    allDay?: boolean;
+    timezone: string;
+    organizer: CalendarOrganizer;
+    attendees?: Attendee[];
+    recurrenceRule?: RecurrenceRule;
+    status?: CalendarEventStatus;
+    busyStatus?: BusyStatus;
+    reminderMinutesBeforeStart?: number;
+    autoReplyEnabled?: boolean;
+    autoReplyMessage?: string;
+    /** Set (or, sent as `null` on an update, cleared) when the caller has just minted or cancelled this
+     * event's video meeting — see `CalendarEvent.videoMeetingUid`. */
+    videoMeetingUid?: string;
+    /** Plain-text description (<= 32,000 characters). `null` (or `""`) clears it on an update. Sending only `descriptionHtml` makes the server derive this. */
+    description?: string | null;
+    /** Description HTML (<= 64,000 characters); the server sanitizes it. `null` (or `""`) clears it. Sending only `description` clears the HTML. */
+    descriptionHtml?: string | null;
+    visibility?: EventVisibility;
+    /** Only the organizer's own copy takes these; on a guest's copy they are ignored. Changing any of them, the description or the visibility re-invites. */
+    guestsCanModify?: boolean;
+    guestsCanInviteOthers?: boolean;
+    guestsCanSeeGuestList?: boolean;
+}
+
+export function createCalendarEvent(input: CalendarEventInput, client?: ApiClient): Promise<CalendarEvent> {
+    return withClient(client, "/mail/calendar-events", {
+        method: "POST",
+        body: JSON.stringify({
+            allDay: false,
+            attendees: [],
+            status: "confirmed",
+            busyStatus: "busy",
+            icalUid: crypto.randomUUID(),
+            sequence: 0,
+            ...input,
+        }),
+    });
+}
+
+export interface UpdateCalendarEventInput extends Partial<CalendarEventInput> {
+    uid: string;
+    version: number;
+}
+
+export function updateCalendarEvent(input: UpdateCalendarEventInput, client?: ApiClient): Promise<CalendarEvent> {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteCalendarEvent(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+
+/** The subset of `AttendeeResponseStatus` a caller can actually respond with — `"needsAction"` is only
+ * ever a default/initial value, never a valid response. */
+export type AttendeeResponseInput = Exclude<AttendeeResponseStatus, "needsAction">;
+
+/**
+ * Responds to a meeting invite as the calling mailbox's own attendee entry. Synchronous — unlike
+ * `recallMessage()` in `mailApi.ts`, this immediately mutates and persists the response (the iTIP
+ * REPLY email send is best-effort server-side and never affects this call's outcome). On
+ * `"accepted"`/`"tentative"` the whole updated `CalendarEvent` comes back, with only the calling
+ * attendee's own `responseStatus` changed. On `"declined"`, the backend instead soft-deletes the
+ * mailbox's own copy of the event and returns only `{ uid }` — the caller should treat a decline the
+ * same as a delete rather than expecting an updated event back.
+ */
+export function respondToEvent(
+    uid: string,
+    responseStatus: AttendeeResponseInput,
+    client?: ApiClient,
+): Promise<CalendarEvent | { uid: string }> {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}/respond`, {
+        method: "POST",
+        body: JSON.stringify({ responseStatus }),
+    });
+}
+
+/** A change a guest asks the organizer for (`requestEventChange()`): only what is to differ. */
+export interface EventChangeRequest {
+    /** Non-empty, at most 1,000 characters. A request can set these, not clear them. */
+    title?: string;
+    location?: string;
+    description?: string;
+    descriptionHtml?: string;
+    /** ISO 8601 instants. */
+    startDate?: string;
+    endDate?: string;
+    /** Up to 50 guests to add. */
+    addAttendees?: { address: string; displayName?: string }[];
+}
+
+/** What the server made of a change request. */
+export interface EventChangeRequestResult {
+    requested: true;
+    /** Which fields the request changes (as the server named them, e.g. `title`, `startDate`, `addAttendees`). */
+    changes: string[];
+    addAttendees: { address: string; displayName?: string }[];
+}
+
+/**
+ * Asks the organizer to change an event, as a guest (not the organizer) whose copy allows it: the title, location, description or time need
+ * `guestsCanModify`, added guests need `guestsCanInviteOthers` (403 otherwise; 400 when nothing differs from what the event has, or a value is invalid).
+ * Nothing changes on this mailbox's own copy - the request is mailed to the organizer, and when the change is allowed it is applied there and
+ * arrives back later as an ordinary update of the invitation.
+ */
+export function requestEventChange(uid: string, request: EventChangeRequest, client?: ApiClient): Promise<EventChangeRequestResult> {
+    return withClient(client, `/mail/calendar-events/${encodeURIComponent(uid)}/request-change`, {
+        method: "POST",
+        body: JSON.stringify(request),
+    });
+}

package/lib/calendar/calendarColors.ts

@@ -0,0 +1,45 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** A fixed client-side color palette for calendars, matching the plan's "no new `Category`-style
+ * backend entity" approach already used for Contacts' categories: `Folder.color` just stores one of
+ * these hex values (or, in principle, any string — an unrecognized one still works fine as a raw CSS
+ * color), the palette itself never needs to round-trip through the backend. */
+
+import { Folder } from "../mail/mailApi.js";
+
+export const CALENDAR_COLOR_PALETTE: string[] = [
+    "#2563eb", // blue
+    "#7c3aed", // violet
+    "#db2777", // pink
+    "#dc2626", // red
+    "#ea580c", // orange
+    "#ca8a04", // amber
+    "#16a34a", // green
+    "#0d9488", // teal
+];
+
+/** The color a mailbox's original auto-provisioned calendar effectively had before this field
+ * existed — kept as the fallback so every pre-existing calendar keeps looking the same. */
+export const DEFAULT_CALENDAR_COLOR = CALENDAR_COLOR_PALETTE[0];
+
+/** `fallback` replaces `DEFAULT_CALENDAR_COLOR` for a folder with no color of its own - e.g. a shared
+ * mailbox's calendar falling back to that mailbox's `accentColorForMailbox()`, so it doesn't render in
+ * the same default blue as the caller's own calendar. An explicit `Folder.color` always wins. */
+export function colorForFolder(folder: Pick<Folder, "color">, fallback: string = DEFAULT_CALENDAR_COLOR): string {
+    return folder.color || fallback;
+}
+
+/** A stable per-mailbox color for grouping one mailbox's calendars together (sidebar section accent, and
+ * the fallback color for its uncolored calendars). Deterministic hash of `mailboxUid` into the palette
+ * minus `DEFAULT_CALENDAR_COLOR`, so another mailbox never collides with the default a caller's own
+ * calendar already uses. Client-side only - nothing is persisted. */
+export function accentColorForMailbox(mailboxUid: string): string {
+    const choices = CALENDAR_COLOR_PALETTE.slice(1);
+    let hash = 0;
+    for (let i = 0; i < mailboxUid.length; i++) {
+        hash = (hash * 31 + mailboxUid.charCodeAt(i)) >>> 0;
+    }
+    return choices[hash % choices.length];
+}

package/lib/calendar/calendarDragIds.ts

@@ -0,0 +1,112 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `@dnd-kit/core` identifies draggables/droppables purely by string id — this module owns the
+ * encoding scheme for calendar drag ids and, more importantly, `resolveDragAction()`: a pure
+ * function turning a drag-end's (active id, over id) pair into "move this occurrence by N ms" or
+ * "resize this occurrence's end to this instant", *without* touching `@dnd-kit` itself. Kept pure and
+ * dependency-free from the grid components on purpose: `@dnd-kit`'s pointer-based drag sensors are
+ * awkward to drive from jsdom in tests (they need real `PointerEvent`/`getBoundingClientRect`
+ * behavior a headless DOM doesn't fully provide), but the *decision* a drag-end makes is ordinary
+ * data-in-data-out logic that's trivial to unit test directly — see `calendarDragIds.test.ts`. The
+ * grid views (`MonthView`/`TimeGridView`) only need to tag their draggable/droppable elements with
+ * these ids correctly; the calendar page's `onDragEnd` calls `resolveDragAction` and then one of
+ * `calendarMutations.ts`'s `moveOccurrence`/`resizeOccurrenceEnd`.
+ */
+
+import { CalendarOccurrence } from "./recurrence.js";
+
+const DAY_ID_PREFIX = "day:";
+const SLOT_ID_PREFIX = "slot:";
+const RESIZE_ID_PREFIX = "resize:";
+
+/**
+ * A month-view day cell's droppable id, for the given day (any time-of-day on that calendar date) —
+ * encoded as the runtime's *local* `yyyy-MM-dd`, matching the local-midnight day dates the grid views
+ * build via `date-fns`.
+ */
+export function dayDropId(date: Date): string {
+    const yyyy = String(date.getFullYear()).padStart(4, "0");
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    return `${DAY_ID_PREFIX}${yyyy}-${mm}-${dd}`;
+}
+
+/** A week/day-view time slot's droppable id, rounded to the given date-time instant. */
+export function slotDropId(date: Date): string {
+    return `${SLOT_ID_PREFIX}${date.toISOString()}`;
+}
+
+/** An event chip/block's draggable id (drag-to-move). */
+export function eventDragId(occurrence: CalendarOccurrence): string {
+    return occurrence.occurrenceKey;
+}
+
+/** An event block's resize-handle draggable id (drag-to-resize, week/day view only). */
+export function resizeDragId(occurrence: CalendarOccurrence): string {
+    return `${RESIZE_ID_PREFIX}${occurrence.occurrenceKey}`;
+}
+
+export type DragAction =
+    | { type: "move"; occurrence: CalendarOccurrence; deltaMs: number }
+    | { type: "resize"; occurrence: CalendarOccurrence; newEnd: Date };
+
+/**
+ * Resolves a `@dnd-kit` drag-end's `active`/`over` ids into the action it represents, or `null` if
+ * the drop doesn't correspond to anything actionable (dropped outside any droppable, or the dragged
+ * id doesn't match any occurrence currently on the grid — e.g. it was removed by an in-flight reload
+ * mid-drag).
+ */
+export function resolveDragAction(
+    activeId: string,
+    overId: string | undefined,
+    occurrences: CalendarOccurrence[],
+): DragAction | null {
+    if (!overId) {
+        return null;
+    }
+
+    const isResize = activeId.startsWith(RESIZE_ID_PREFIX);
+    const occurrenceKey = isResize ? activeId.slice(RESIZE_ID_PREFIX.length) : activeId;
+    const occurrence = occurrences.find((o) => o.occurrenceKey === occurrenceKey);
+    if (!occurrence) {
+        return null;
+    }
+
+    if (isResize) {
+        if (!overId.startsWith(SLOT_ID_PREFIX)) {
+            return null;
+        }
+        return { type: "resize", occurrence, newEnd: new Date(overId.slice(SLOT_ID_PREFIX.length)) };
+    }
+
+    if (overId.startsWith(DAY_ID_PREFIX)) {
+        // Moving a timed event to another day keeps the occurrence's local wall-clock start time, so the delta is
+        // "same local time on the target day" minus the original start — a whole number of calendar
+        // days, which is not always a multiple of 24h when the move crosses a DST change.
+        const [year, month, day] = overId.slice(DAY_ID_PREFIX.length).split("-").map(Number);
+        // An all-day event's start is a UTC-midnight date-only value, so its target is that calendar date's
+        // UTC midnight - never "the same local time", which west of UTC reads the stored midnight as the
+        // previous evening and lands the event a day late.
+        const source = new Date(occurrence.startDate);
+        const target = new Date(source.getTime());
+        if (occurrence.allDay) {
+            target.setTime(Date.UTC(year, month - 1, day));
+        } else {
+            target.setFullYear(year, month - 1, day);
+        }
+        if (Number.isNaN(target.getTime())) {
+            return null;
+        }
+        return { type: "move", occurrence, deltaMs: target.getTime() - source.getTime() };
+    }
+
+    if (overId.startsWith(SLOT_ID_PREFIX)) {
+        const targetSlot = new Date(overId.slice(SLOT_ID_PREFIX.length));
+        return { type: "move", occurrence, deltaMs: targetSlot.getTime() - new Date(occurrence.startDate).getTime() };
+    }
+
+    return null;
+}