@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/calendar/inviteApi.ts

@@ -0,0 +1,154 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Typed wrappers over `@rapidmx/restapi`'s `/mail/calendar-events/invite` surface - the calendar invitation (iMIP: an
+ * `.ics` attachment carrying an iTIP `METHOD`) a mail message may hold, read for the reading pane's invitation card. The
+ * server does all the work of an answer: it puts the meeting on the reader's calendar (or takes it off), and sends the
+ * iTIP REPLY to the organizer. The client only reads the state and asks for a change; every call returns the invitation as
+ * it now stands, ready to draw. */
+
+import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
+import type { EventVisibility, GuestPermissions } from "./calendarApi.js";
+
+/** What the reader can answer an invitation with. */
+export type InviteResponse = "accepted" | "tentative" | "declined";
+
+export interface InviteParticipant {
+    address: string;
+    displayName?: string;
+    responseStatus?: "accepted" | "tentative" | "declined" | "needs-action";
+}
+
+/** One of the reader's own events near an invitation, as the server lists it for the RSVP day view and its conflict check. */
+export interface InviteScheduleEntry {
+    uid: string;
+    title: string;
+    /** ISO 8601 instants. */
+    startDate: string;
+    endDate: string;
+    allDay: boolean;
+    /** The event blocks the reader's time (it is not marked free). */
+    busy: boolean;
+    tentative: boolean;
+}
+
+/** The calendar invitation a message carries, together with what the reader's own calendar says about it. */
+export interface MessageInvite {
+    /** The iTIP `METHOD` as sent: `"REQUEST"`, `"CANCEL"`, `"REPLY"`, `"PUBLISH"` or `"COUNTER"`, or `""` when the file names none. */
+    method: string;
+    /** The iCalendar `UID`. */
+    uid: string;
+    sequence: number;
+    summary?: string;
+    location?: string;
+    /** ISO 8601 instant. */
+    startDate?: string;
+    endDate?: string;
+    allDay: boolean;
+    /** The IANA zone the organizer used. */
+    timezone?: string;
+    organizer?: { address: string; displayName?: string };
+    attendees: InviteParticipant[];
+    recurring: boolean;
+    /** The reader's mailbox is the organizer. */
+    isOrganizer: boolean;
+    /** What the reader answered, if anything. */
+    response?: InviteResponse;
+    /** An event for it is on the reader's calendar now. */
+    onCalendar: boolean;
+    /** That event's uid (for a link into the calendar). */
+    calendarEventUid?: string;
+    /** The calendar already holds a newer revision than this message. */
+    outdated: boolean;
+    /** A `REQUEST` addressed to the reader: offer Accept / Tentative / Decline. */
+    canRespond: boolean;
+    /** A `PUBLISH`, or no method at all: offer "Add to calendar". */
+    canAdd: boolean;
+    /** A `CANCEL` whose meeting is on the calendar: offer "Remove from calendar". */
+    canRemove: boolean;
+    /** A `REQUEST` the reader can answer with a different time: offer "Propose new time". */
+    canPropose: boolean;
+    /** A `COUNTER` for a meeting the reader organizes: offer "Accept proposal". */
+    canAcceptProposal: boolean;
+    /** For a `REPLY` or `COUNTER`: the attendee who sent it and what they answered or proposed. For a `COUNTER`,
+     * `startDate`/`endDate` are the proposed time. */
+    reply?: InviteParticipant;
+    /** The reader's busy events that overlap the invitation's time. */
+    conflicts: InviteScheduleEntry[];
+    /** The reader's other events from 12 hours before the invitation's start to 12 hours after its end (recurrences
+     * expanded, this meeting left out) - what the RSVP day view draws around the invitation. */
+    schedule: InviteScheduleEntry[];
+    /** The description as plain text, if the organizer wrote one. */
+    description?: string;
+    /** The description as HTML the server sanitized - still rendered through `sanitizeEventDescriptionHtml()`, never trusted as it stands. */
+    descriptionHtml?: string;
+    /** Who may see the event's details, as the organizer sent it. */
+    visibility?: EventVisibility;
+    /** What the organizer allows the guests to do. Every field is present when the server says any (all optional here so an older server, which says none, reads
+     * as the defaults - see `guestPermissionsOf()`). */
+    guestPermissions?: Partial<GuestPermissions>;
+    /** A guest's copy that allows a change of the title, location, description or time: offer "Request a change" (`requestEventChange()` on `calendarEventUid`). */
+    canRequestChange?: boolean;
+    /** A guest's copy that allows adding guests: offer "Add guests" (`requestEventChange()` with `addAttendees` on `calendarEventUid`). */
+    canRequestInvite?: boolean;
+    /** On a `COUNTER` that is a guest's change request (rather than a proposed time) received by the organizer: whether it was applied automatically. */
+    changeRequest?: { applied: boolean };
+}
+
+/** `client`, given by every function below, 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. */
+/**
+ * Reads the invitation a message carries. Resolves `null` when the message has none the server can read (a `404`) - the
+ * common, expected answer for a message that merely has an attachment - and rejects for any other failure.
+ */
+export async function getMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite | null> {
+    try {
+        return await withClient<MessageInvite>(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}`);
+    } catch (err) {
+        if (err instanceof ApiRequestError && err.status === 404) {
+            return null;
+        }
+        throw err;
+    }
+}
+
+/**
+ * Answers an invitation. The server puts the meeting on the reader's calendar for `"accepted"`/`"tentative"` (or takes it
+ * off for `"declined"`) and sends the organizer the matching iTIP REPLY; for a `PUBLISH`ed event (which has no organizer to
+ * answer) `"accepted"` only adds it to the calendar. Resolves with the invitation as it now stands.
+ */
+export function respondToMessageInvite(messageUid: string, responseStatus: InviteResponse, client?: ApiClient): Promise<MessageInvite> {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/respond`, {
+        method: "POST",
+        body: JSON.stringify({ responseStatus }),
+    });
+}
+
+/** Takes a canceled meeting off the reader's calendar. Resolves with the invitation as it now stands. */
+export function removeMessageInvite(messageUid: string, client?: ApiClient): Promise<MessageInvite> {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/remove`, { method: "POST" });
+}
+
+/** A different time to suggest to the organizer. */
+export interface ProposedTime {
+    /** ISO 8601 instants. */
+    startDate: string;
+    endDate: string;
+    /** A note to the organizer, sent with the proposal. */
+    comment?: string;
+}
+
+/** Proposes a different time to the organizer of a `REQUEST` (an iTIP `COUNTER` sent by the server). Resolves with the invitation as it now stands. */
+export function proposeNewTime(messageUid: string, proposal: ProposedTime, client?: ApiClient): Promise<MessageInvite> {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/propose`, {
+        method: "POST",
+        body: JSON.stringify(proposal),
+    });
+}
+
+/** Accepts an attendee's proposed time (a `COUNTER`) for a meeting the reader organizes: the server moves the event and sends the attendees the update. Resolves with the invitation as it now stands. */
+export function acceptProposal(messageUid: string, client?: ApiClient): Promise<MessageInvite> {
+    return withClient(client, `/mail/calendar-events/invite/${encodeURIComponent(messageUid)}/accept-proposal`, { method: "POST" });
+}

package/lib/calendar/recurrence.ts

@@ -0,0 +1,285 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * RFC5545 recurrence expansion, entirely client-side — `@rapidmx/restapi` stores/returns
+ * `RecurrenceRule` as-is and does no expansion of its own (see `calendarApi.ts`'s own header
+ * comment). Built on the `rrule` package.
+ */
+
+// `rrule` ships a real ESM build (resolved by the client bundler via its own module graph, where
+// named imports work normally) alongside a separate CJS build with no `"exports"` map (resolved by
+// this framework's *server-side* render path via Node's own loader, which falls back to the CJS
+// build since "module" is a bundler-only convention Node itself doesn't honor). Node's static
+// named-export detection for that CJS build doesn't pick up `RRule` (confirmed directly: SSR-ing the
+// calendar page threw "does not provide an export named 'RRule'"), so a plain named import breaks
+// under SSR even though it works in the browser. A namespace import sidesteps the static check
+// entirely; reading `.default` afterward reaches the same class via Node's CJS interop (`default`
+// always aliases `module.exports` for a CJS module) without disturbing the ESM path, where `.default`
+// simply doesn't exist and the direct named property is used instead.
+import * as RRuleNS from "rrule";
+import type { Weekday } from "rrule";
+import { CalendarEvent, RecurrenceRule, WeekdayCode } from "./calendarApi.js";
+
+/** Extracted so the CJS-interop fallback branch can be exercised directly with a plain object,
+ * without needing to fight a module mock into reproducing Node's exact interop shape. */
+export function resolveRRuleExport(ns: typeof RRuleNS): typeof RRuleNS.RRule {
+    return ns.RRule ?? (ns as unknown as { default: typeof RRuleNS }).default.RRule;
+}
+
+const RRule = resolveRRuleExport(RRuleNS);
+
+const FREQ_MAP: Record<RecurrenceRule["freq"], number> = {
+    yearly: RRule.YEARLY,
+    monthly: RRule.MONTHLY,
+    weekly: RRule.WEEKLY,
+    daily: RRule.DAILY,
+};
+
+// `RRule`'s own `.toText()` formatter requires actual `Weekday` instances in `byweekday` — passing the
+// raw two-letter strings works for occurrence expansion (`.between()`) but throws inside `.toText()`
+// (confirmed by reproducing it directly against this exact package version).
+const WEEKDAY_OBJECT: Record<WeekdayCode, Weekday> = {
+    MO: RRule.MO,
+    TU: RRule.TU,
+    WE: RRule.WE,
+    TH: RRule.TH,
+    FR: RRule.FR,
+    SA: RRule.SA,
+    SU: RRule.SU,
+};
+
+function createRRule(rule: RecurrenceRule, dtstart: Date, until: Date | null, tzid: string | null): RRuleNS.RRule {
+    return new RRule({
+        freq: FREQ_MAP[rule.freq],
+        interval: rule.interval,
+        dtstart,
+        tzid,
+        byweekday: rule.byDay?.map((code) => WEEKDAY_OBJECT[code]),
+        bymonthday: rule.byMonthDay,
+        bymonth: rule.byMonth,
+        count: rule.count,
+        until,
+    });
+}
+
+/**
+ * Builds an `RRule` instance from this app's `RecurrenceRule` shape, anchored at `dtstart`. Pass the
+ * event's IANA `tzid` so the rule carries it (e.g. `DTSTART;TZID=America/New_York:...` from
+ * `.toString()`) — note that, per `rrule`'s own convention, a rule with a non-UTC `tzid` expects
+ * `dtstart` to be a "floating" wall-clock time expressed as a UTC `Date` and rezones its generated
+ * dates using the *runtime's* local zone, which is why `expandOccurrences()` below does its own
+ * timezone conversion instead of relying on this.
+ */
+export function buildRRule(rule: RecurrenceRule, dtstart: Date, tzid?: string): RRuleNS.RRule {
+    return createRRule(rule, dtstart, rule.until ? new Date(rule.until) : null, tzid ?? null);
+}
+
+/**
+ * Converts between real instants and "wall-clock as UTC" milliseconds (the local date/time fields of
+ * an instant in some zone, packed into a UTC timestamp) — the standard floating-time trick for
+ * running `rrule`, which does all of its date arithmetic in UTC fields, in an arbitrary zone.
+ */
+interface ZoneConverter {
+    toWall(instantMs: number): number;
+    fromWall(wallMs: number): number;
+}
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function positiveMs(ms: number): number {
+    return ((ms % 1000) + 1000) % 1000;
+}
+
+/** The runtime's own local zone — used for a "floating" event with no (or an unrecognized) timezone. */
+const LOCAL_ZONE: ZoneConverter = {
+    toWall(instantMs) {
+        const d = new Date(instantMs);
+        return Date.UTC(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
+    },
+    fromWall(wallMs) {
+        const w = new Date(wallMs);
+        return new Date(
+            w.getUTCFullYear(),
+            w.getUTCMonth(),
+            w.getUTCDate(),
+            w.getUTCHours(),
+            w.getUTCMinutes(),
+            w.getUTCSeconds(),
+            w.getUTCMilliseconds(),
+        ).getTime();
+    },
+};
+
+/** UTC itself - used for all-day events, whose dates are stored as UTC midnight (date-only values). */
+const UTC_ZONE: ZoneConverter = {
+    toWall: (instantMs) => instantMs,
+    fromWall: (wallMs) => wallMs,
+};
+
+function ianaZone(formatter: Intl.DateTimeFormat): ZoneConverter {
+    const toWall = (instantMs: number): number => {
+        const fields: Record<string, number> = {};
+        for (const part of formatter.formatToParts(new Date(instantMs))) {
+            fields[part.type] = Number(part.value);
+        }
+        // `% 24`: some engines render midnight as hour "24" even with `hourCycle: "h23"`.
+        return Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour % 24, fields.minute, fields.second, positiveMs(instantMs));
+    };
+    return {
+        toWall,
+        // RFC 5545 §3.3.5 resolution against the offsets in effect a day before and a day after (zones
+        // change offset at most once in that window): an ambiguous (fall-back) wall time resolves to its
+        // first occurrence (the earlier instant); a nonexistent (spring-forward) one is interpreted with
+        // the offset from *before* the transition, so 02:30 on a US spring-forward day becomes 03:30 EDT.
+        fromWall(wallMs) {
+            const offsetBefore = toWall(wallMs - MS_PER_DAY) - (wallMs - MS_PER_DAY);
+            const offsetAfter = toWall(wallMs + MS_PER_DAY) - (wallMs + MS_PER_DAY);
+            const valid = [wallMs - offsetBefore, wallMs - offsetAfter].filter((instant) => toWall(instant) === wallMs);
+            return valid.length > 0 ? Math.min(...valid) : wallMs - offsetBefore;
+        },
+    };
+}
+
+const zoneCache = new Map<string, ZoneConverter>();
+
+/** Resolves `timezone` (an IANA zone id) to a converter, falling back to the runtime's local zone when
+ * it's empty or not a zone `Intl` recognizes. */
+function resolveZone(timezone: string | undefined): ZoneConverter {
+    const key = timezone ?? "";
+    let zone = zoneCache.get(key);
+    if (!zone) {
+        try {
+            zone = key
+                ? ianaZone(
+                      new Intl.DateTimeFormat("en-US", {
+                          timeZone: key,
+                          hourCycle: "h23",
+                          year: "numeric",
+                          month: "2-digit",
+                          day: "2-digit",
+                          hour: "2-digit",
+                          minute: "2-digit",
+                          second: "2-digit",
+                      }),
+                  )
+                : LOCAL_ZONE;
+        } catch {
+            zone = LOCAL_ZONE;
+        }
+        zoneCache.set(key, zone);
+    }
+    return zone;
+}
+
+/** A single expanded occurrence of a (possibly recurring) `CalendarEvent`, ready to render on a grid. */
+export interface CalendarOccurrence extends CalendarEvent {
+    /** A key unique per occurrence (`${event.uid}::${occurrence start}`) — use this for React `key`s and
+     * drag-and-drop ids, since a recurring event's `uid` alone isn't unique across its occurrences. */
+    occurrenceKey: string;
+    /** `true` for a generated occurrence of a recurring event (as opposed to the stored master record, or
+     * a genuinely non-recurring event) — moving/resizing one calls `updateCalendarEvent` differently (see
+     * the calendar page's own drag handlers) since it must detach into its own standalone event. */
+    isRecurringOccurrence: boolean;
+}
+
+/**
+ * Converts an instant to the "wall-clock as UTC" milliseconds recurrence expansion works in for an event
+ * with this `timezone`/`allDay` - UTC for an all-day event (stored as UTC-midnight dates), the event's IANA
+ * zone otherwise (the runtime's local zone when empty or unrecognized). Exported for `calendarMutations.ts`,
+ * which shifts a series' exception dates by the same wall-clock delta as its start.
+ */
+export function toEventWallClock(instantMs: number, timezone: string | undefined, allDay: boolean | undefined): number {
+    return (allDay ? UTC_ZONE : resolveZone(timezone)).toWall(instantMs);
+}
+
+/** Inverse of `toEventWallClock()` (DST gaps/overlaps resolved per RFC 5545 - see `ianaZone()`). */
+export function fromEventWallClock(wallMs: number, timezone: string | undefined, allDay: boolean | undefined): number {
+    return (allDay ? UTC_ZONE : resolveZone(timezone)).fromWall(wallMs);
+}
+
+/**
+ * Expands `event` into every occurrence whose interval overlaps `[rangeStart, rangeEnd]`. A
+ * non-recurring event yields itself (in a one-element array) if it overlaps, or `[]` otherwise —
+ * callers don't need to special-case recurring vs. not.
+ *
+ * Recurrence is expanded in the event's own `timezone` (an IANA zone id; an empty or unrecognized
+ * value falls back to the runtime's local zone, i.e. floating time), so every occurrence keeps the
+ * master's local wall-clock start/end time and local weekday — a weekly Monday 23:00
+ * America/New_York event stays on Monday 23:00 New York time across DST changes, rather than being
+ * expanded on the UTC weekday/time of its first instance. An all-day event is the exception: its dates are
+ * UTC-midnight date-only values, so it expands in UTC regardless of `timezone` - expanding a
+ * `2026-09-14T00:00Z` Monday in America/New_York would otherwise see a Sunday-evening start and put every
+ * occurrence on the wrong date. A timed occurrence that falls in a DST gap starts at the pre-transition
+ * offset (RFC 5545) and keeps its wall-clock duration.
+ */
+export function expandOccurrences(event: CalendarEvent, rangeStart: Date, rangeEnd: Date): CalendarOccurrence[] {
+    const start = new Date(event.startDate);
+    const end = new Date(event.endDate);
+
+    if (!event.recurrenceRule) {
+        const overlaps = start < rangeEnd && end > rangeStart;
+        return overlaps ? [{ ...event, occurrenceKey: event.uid, isRecurringOccurrence: false }] : [];
+    }
+
+    const zone = event.allDay ? UTC_ZONE : resolveZone(event.timezone);
+    const startWall = zone.toWall(start.getTime());
+    // The duration in wall-clock terms, so an occurrence also keeps its local end time across DST.
+    const wallDurationMs = zone.toWall(end.getTime()) - startWall;
+    const { until } = event.recurrenceRule;
+    const rule = createRRule(
+        event.recurrenceRule,
+        new Date(startWall),
+        until ? new Date(zone.toWall(new Date(until).getTime())) : null,
+        null,
+    );
+    // Query in the wall-clock frame, widened by one occurrence's duration (so an occurrence that started
+    // before `rangeStart` but is still in progress isn't missed) plus a day on each side to absorb the
+    // zone's offset; the exact instant-based overlap filter at the end trims the excess.
+    const queryStart = new Date(zone.toWall(rangeStart.getTime()) - wallDurationMs - MS_PER_DAY);
+    const queryEnd = new Date(zone.toWall(rangeEnd.getTime()) + MS_PER_DAY);
+    const occurrenceStarts = rule
+        .between(queryStart, queryEnd, true)
+        .map((occWall) => ({ start: new Date(zone.fromWall(occWall.getTime())), wall: occWall.getTime() }));
+    const exceptions = new Set(event.recurrenceRule.exceptions.map((d) => new Date(d).getTime()));
+
+    return occurrenceStarts
+        .filter((occ) => !exceptions.has(occ.start.getTime()))
+        .map(({ start: occStart, wall }) => {
+            // Non-zero only when the start fell in a DST gap and was pushed forward - the end moves with it.
+            const gapShiftMs = zone.toWall(occStart.getTime()) - wall;
+            const occEnd = new Date(zone.fromWall(wall + gapShiftMs + wallDurationMs));
+            return {
+                ...event,
+                startDate: occStart.toISOString(),
+                endDate: occEnd.toISOString(),
+                recurrenceId: occStart.toISOString(),
+                occurrenceKey: `${event.uid}::${occStart.toISOString()}`,
+                isRecurringOccurrence: true,
+            };
+        })
+        .filter((occ) => new Date(occ.startDate) < rangeEnd && new Date(occ.endDate) > rangeStart);
+}
+
+/** Expands every event in `events` and flattens the result — the usual entry point for a grid view. */
+export function expandAllOccurrences(events: CalendarEvent[], rangeStart: Date, rangeEnd: Date): CalendarOccurrence[] {
+    return events.flatMap((event) => expandOccurrences(event, rangeStart, rangeEnd));
+}
+
+/** A human-readable summary of `rule` (e.g. "every 2 weeks on Monday, Wednesday until Jan 1, 2027"). */
+export function describeRecurrence(rule: RecurrenceRule): string {
+    const rrule = buildRRule(rule, new Date());
+    return rrule.toText();
+}
+
+export const WEEKDAY_CODES: WeekdayCode[] = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
+export const WEEKDAY_LABELS: Record<WeekdayCode, string> = {
+    MO: "Mon",
+    TU: "Tue",
+    WE: "Wed",
+    TH: "Thu",
+    FR: "Fri",
+    SA: "Sat",
+    SU: "Sun",
+};

package/lib/components/avatar/ContactAvatar.tsx

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+
+export interface ContactAvatarProps {
+    displayName: string;
+    size?: number;
+}
+
+/** A fixed palette of background colors, cycled by a hash of the contact's name — no photo upload feature
+ * exists yet (`Contact.photoBlobKey` is modeled server-side but nothing in this app sets/reads it), so every
+ * contact gets one of these deterministically rather than a plain generic gray circle for everyone. */
+const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
+
+function initialsOf(displayName: string): string {
+    const parts = displayName.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+        return "?";
+    }
+    const first = parts[0][0];
+    const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
+    return (first + last).toUpperCase();
+}
+
+function colorOf(displayName: string): string {
+    let hash = 0;
+    for (let i = 0; i < displayName.length; i++) {
+        hash = (hash * 31 + displayName.charCodeAt(i)) | 0;
+    }
+    return PALETTE[Math.abs(hash) % PALETTE.length];
+}
+
+/** A small circular initials avatar for a contact, matching Outlook People's list-row avatars — deterministic
+ * per name (same contact always gets the same color/initials), no photo-upload dependency. */
+export default function ContactAvatar({ displayName, size = 32 }: ContactAvatarProps) {
+    return (
+        <span
+            aria-hidden="true"
+            style={{ width: size, height: size, backgroundColor: colorOf(displayName), fontSize: size * 0.4 }}
+            className="inline-flex items-center justify-center rounded-full text-white font-semibold shrink-0"
+        >
+            {initialsOf(displayName)}
+        </span>
+    );
+}

package/lib/components/buttons/Button.tsx

@@ -0,0 +1,40 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ButtonHTMLAttributes } from "react";
+
+export type ButtonVariant = "primary" | "secondary" | "text";
+
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
+    variant?: ButtonVariant;
+    /** Renders a small spinner before the button's content. */
+    loading?: boolean;
+    className?: string;
+}
+
+const BASE =
+    "inline-flex items-center justify-center gap-2 font-semibold text-sm rounded-sm border transition-colors disabled:opacity-55 disabled:cursor-not-allowed active:translate-y-px";
+
+/** Primary is gold (the brand's action color, per the style guide's "gold gradient fill" convention);
+ * secondary/text hover accents follow the guide's "turning gold on hover" rule too. Teal (`primary`
+ * the color token, confusingly named the same as this `primary` variant) stays reserved for
+ * structural/navigational chrome — active nav items, links, focus rings — not call-to-action buttons. */
+const VARIANTS: Record<ButtonVariant, string> = {
+    primary:
+        "w-full py-2.5 px-4 bg-gradient-to-b from-accent-soft to-accent border-transparent text-text-on-accent hover:not-disabled:from-accent hover:not-disabled:to-accent-dark",
+    secondary:
+        "w-full py-2.5 px-4 bg-transparent border-border text-text hover:not-disabled:border-accent hover:not-disabled:text-accent-dark",
+    text: "w-auto py-1 px-0.5 border-transparent bg-transparent text-accent-dark hover:not-disabled:underline",
+};
+
+export default function Button({ variant = "primary", loading, className, children, ...rest }: ButtonProps) {
+    return (
+        <button className={[BASE, VARIANTS[variant], className].filter(Boolean).join(" ")} {...rest}>
+            {loading && (
+                <span className="w-4 h-4 rounded-full border-2 border-current/30 border-t-current animate-spin" />
+            )}
+            {children}
+        </button>
+    );
+}

package/lib/components/buttons/CopyButton.tsx

@@ -0,0 +1,45 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+import useCopyToClipboard from "../../util/useCopyToClipboard.js";
+import Button from "./Button.js";
+
+export interface CopyButtonProps {
+    /** The text put on the clipboard. */
+    value: string;
+    /** The button's accessible name - say what is copied, e.g. "Copy value for the SPF record". */
+    label: string;
+    /** The visible caption. Defaults to "Copy". */
+    children?: ReactNode;
+    className?: string;
+}
+
+/**
+ * A small "Copy" button for a value someone has to paste elsewhere (a DNS record, a code). Copies through
+ * `copyTextToClipboard()` - the async Clipboard API, then a hidden-textarea `execCommand` fallback - and
+ * announces the result next to the button in a polite live region ("Copied", or "Couldn't copy" when both
+ * routes fail, in which case the value is still on screen to select by hand). The live region is always
+ * rendered, empty until there is something to say, so screen readers pick the change up.
+ */
+export default function CopyButton({ value, label, children = "Copy", className }: CopyButtonProps) {
+    const { status, copy } = useCopyToClipboard();
+
+    return (
+        <span className="inline-flex items-center gap-2 shrink-0">
+            <Button
+                type="button"
+                variant="secondary"
+                aria-label={label}
+                className={["!w-auto !py-1 !px-2 text-xs", className].filter(Boolean).join(" ")}
+                onClick={() => void copy(value)}
+            >
+                {children}
+            </Button>
+            <span role="status" aria-live="polite" className={status === "failed" ? "text-xs text-danger" : "text-xs text-success"}>
+                {status === "copied" ? "Copied" : status === "failed" ? "Couldn’t copy" : ""}
+            </span>
+        </span>
+    );
+}

package/lib/components/feedback/Alert.tsx

@@ -0,0 +1,13 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+
+export default function Alert({ children }: { children: ReactNode }) {
+    return (
+        <div className="flex gap-2 items-start py-3 px-3.5 rounded-sm text-sm mb-5 bg-danger-bg text-danger" role="alert">
+            {children}
+        </div>
+    );
+}

package/lib/components/feedback/Skeleton.tsx

@@ -0,0 +1,38 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+
+export interface SkeletonProps {
+    /** Tailwind width class, e.g. `"w-32"` or `"w-full"`. Defaults to full width. */
+    width?: string;
+    /** Tailwind height class, e.g. `"h-4"`. Defaults to a text-line height. */
+    height?: string;
+    /** Extra classes — e.g. `"rounded-full"` for an avatar placeholder instead of the default bar shape. */
+    className?: string;
+}
+
+/** A single pulsing placeholder bar — the shared building block every skeleton layout in this app
+ * composes from, so a loading list/sidebar/page reads as "this shape is about to have real content"
+ * rather than either a blank pane or a spinner (this app's convention going forward for anything that
+ * takes a network round trip to render — see the shells' own `Skeleton`-based "checking" state). */
+export default function Skeleton({ width = "w-full", height = "h-4", className = "" }: SkeletonProps) {
+    return <div aria-hidden="true" className={["animate-pulse rounded-sm bg-border", width, height, className].join(" ")} />;
+}
+
+/** A vertical stack of `count` skeleton rows, each an icon-sized block plus a text-line bar — the
+ * shape shared by every list-style loading state in this app (folder trees, message/contact/task
+ * lists, sidebar nav items). */
+export function SkeletonList({ count = 5, className = "" }: { count?: number; className?: string }) {
+    return (
+        <div aria-hidden="true" className={["flex flex-col gap-2", className].join(" ")}>
+            {Array.from({ length: count }, (_, i) => (
+                <div key={i} className="flex items-center gap-2.5 py-1">
+                    <Skeleton width="w-6" height="h-6" className="rounded-full shrink-0" />
+                    <Skeleton width={i % 2 === 0 ? "w-3/4" : "w-1/2"} />
+                </div>
+            ))}
+        </div>
+    );
+}

package/lib/components/forms/FormField.tsx

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+
+export interface FormFieldProps {
+    label: string;
+    htmlFor: string;
+    children: ReactNode;
+}
+
+/** The repeated `.rr-field` label+input wrapper. The input (and any hint/error text) is passed as children. */
+export default function FormField({ label, htmlFor, children }: FormFieldProps) {
+    return (
+        <div className="mb-4">
+            <label htmlFor={htmlFor} className="block text-sm font-semibold mb-1.5 text-text">
+                {label}
+            </label>
+            {children}
+        </div>
+    );
+}