@rapidmx/web-client 0.26.0 → 0.27.0

package/lib/components/avatar/ContactAvatar.tsx

@@ -2,16 +2,19 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React from "react";
+import React, { useEffect, useState } from "react";
+import { gravatarEnabled, gravatarUrl } from "../../contacts/gravatar.js";
 
 export interface ContactAvatarProps {
     displayName: string;
     size?: number;
+    /** The contact's own picture (see `contactPhotoUrl()`); shown in preference to anything else. */
+    photoUrl?: string;
+    /** The contact's address: without a picture of their own, its Gravatar is shown when there is one (and the reader hasn't turned that off). */
+    email?: string;
 }
 
-/** 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. */
+/** A fixed palette of background colors, cycled by a hash of the contact's name, for the initials shown when there is no picture. */
 const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
 
 function initialsOf(displayName: string): string {
@@ -32,9 +35,42 @@ function colorOf(displayName: string): string {
     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) {
+/**
+ * A small circular avatar for a contact, matching Outlook People's: the contact's own picture when they have one, else their Gravatar (when `email`
+ * is given), else initials on a color that is deterministic per name. A picture that fails to load falls through to the next.
+ */
+export default function ContactAvatar({ displayName, size = 32, photoUrl, email }: ContactAvatarProps) {
+    const [gravatar, setGravatar] = useState<string | undefined>();
+    const [failed, setFailed] = useState<string[]>([]);
+
+    useEffect(() => {
+        setGravatar(undefined);
+        if (!email || !gravatarEnabled()) {
+            return;
+        }
+        let cancelled = false;
+        void gravatarUrl(email, size * 2).then((url) => !cancelled && setGravatar(url));
+        return () => {
+            cancelled = true;
+        };
+    }, [email, size]);
+
+    const src = [photoUrl, gravatar].find((url) => url && !failed.includes(url));
+    if (src) {
+        return (
+            <img
+                src={src}
+                alt=""
+                aria-hidden="true"
+                width={size}
+                height={size}
+                referrerPolicy="no-referrer"
+                onError={() => setFailed((list) => [...list, src])}
+                className="inline-block rounded-full object-cover shrink-0"
+                style={{ width: size, height: size }}
+            />
+        );
+    }
     return (
         <span
             aria-hidden="true"

package/lib/components/buttons/CopyIconButton.tsx

@@ -0,0 +1,49 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { HiCheck, HiOutlineClipboardDocument } from "react-icons/hi2";
+import useCopyToClipboard from "../../util/useCopyToClipboard.js";
+
+export interface CopyIconButtonProps {
+    /** The text put on the clipboard. */
+    value: string;
+    /** The button's accessible name and tooltip - say what is copied, e.g. "Copy address". */
+    label: string;
+    className?: string;
+}
+
+/**
+ * A small icon-only "copy" button to sit right after a value (an email address). The icon turns into a check mark for a moment once the value is on
+ * the clipboard, and a polite live region says "Copied" (or "Couldn't copy") for screen readers.
+ */
+export default function CopyIconButton({ value, label, className }: CopyIconButtonProps) {
+    const { status, copy } = useCopyToClipboard();
+
+    return (
+        <span className="inline-flex items-center align-middle">
+            <button
+                type="button"
+                aria-label={label}
+                title={label}
+                onClick={() => void copy(value)}
+                className={[
+                    "inline-flex items-center justify-center rounded-sm p-1 text-text-muted hover:text-text hover:bg-surface-alt focus-visible:outline-2 focus-visible:outline-primary",
+                    className,
+                ]
+                    .filter(Boolean)
+                    .join(" ")}
+            >
+                {status === "copied" ? (
+                    <HiCheck aria-hidden="true" className="size-4 text-success" />
+                ) : (
+                    <HiOutlineClipboardDocument aria-hidden="true" className="size-4" />
+                )}
+            </button>
+            <span role="status" aria-live="polite" className="sr-only">
+                {status === "copied" ? "Copied" : status === "failed" ? "Couldn’t copy" : ""}
+            </span>
+        </span>
+    );
+}

package/lib/contacts/contactsApi.ts

@@ -5,7 +5,7 @@
 /** Typed wrappers over `@rapidmx/restapi`'s `/mail/contacts` REST surface — see `mailApi.ts`'s own header
  * comment for the shared ACL/authorization model every wrapper file here follows. */
 
-import { ApiClient, withClient } from "../util/api.js";
+import { ApiClient, ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
 import { ListParams, buildQuery } from "../util/apiQuery.js";
 import {
     type EncryptionPreference,
@@ -252,6 +252,39 @@ export function setContactFavorite(contact: Contact, favorite: boolean, client?:
     return updateContact({ uid: contact.uid, version: contact.version, favorite }, client);
 }
 
+/**
+ * The URL of a contact's own picture, or `undefined` when they have none. The version is part of it so a replaced picture is fetched again rather than
+ * served from the browser's cache.
+ */
+export function contactPhotoUrl(contact: Pick<Contact, "uid" | "version" | "photoBlobKey">): string | undefined {
+    return contact.photoBlobKey ? apiUrl(`/mail/contacts/${encodeURIComponent(contact.uid)}/photo?v=${contact.version}`) : undefined;
+}
+
+/** The picture types the server accepts for a contact, and the most bytes it takes. */
+export const CONTACT_PHOTO_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export const CONTACT_PHOTO_MAX_BYTES = 1024 * 1024;
+
+/** Sets a contact's own picture from an image file (the file's own bytes go up, not JSON) and returns the updated contact. */
+export async function uploadContactPhoto(uid: string, version: number, file: Blob): Promise<Contact> {
+    const res = await fetch(apiUrl(`/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`), {
+        method: "PUT",
+        credentials: "include",
+        headers: withCsrfHeader({ "Content-Type": file.type }, "PUT"),
+        body: file,
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
+    if (!res.ok) {
+        throw new ApiRequestError((body && (body.message || body.error)) || res.statusText || "Upload failed.", res.status, body?.code);
+    }
+    return body as Contact;
+}
+
+/** Removes a contact's own picture and returns the updated contact. */
+export function deleteContactPhoto(uid: string, version: number, client?: ApiClient): Promise<Contact> {
+    return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}/photo?version=${version}`, { method: "DELETE" });
+}
+
 export function deleteContact(uid: string, version: number, client?: ApiClient): Promise<void> {
     return withClient(client, `/mail/contacts/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
 }

package/lib/contacts/gravatar.ts

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+
+/** The `localStorage` key of the privacy preference: `"off"` stops contact avatars from asking Gravatar for a picture. */
+export const GRAVATAR_PREFERENCE_KEY = "rapidmx:gravatar";
+
+/**
+ * Whether avatars may look a person up at Gravatar by the SHA-256 hash of their address (never the address itself). On unless the reader turned
+ * it off (`localStorage["rapidmx:gravatar"] = "off"`); a browser without storage keeps the default.
+ */
+export function gravatarEnabled(): boolean {
+    try {
+        return globalThis.localStorage?.getItem(GRAVATAR_PREFERENCE_KEY) !== "off";
+    } catch {
+        return true;
+    }
+}
+
+const hashes = new Map<string, Promise<string | undefined>>();
+
+/** The lowercase-hex SHA-256 of a trimmed, lowercased `email`, or `undefined` where the browser has no Web Crypto (an insecure page). */
+function hashOf(email: string): Promise<string | undefined> {
+    const normalized = email.trim().toLowerCase();
+    let hash = hashes.get(normalized);
+    if (!hash) {
+        hash = (async () => {
+            const digest = await globalThis.crypto?.subtle?.digest("SHA-256", new TextEncoder().encode(normalized));
+            return digest && Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        })().catch(() => undefined);
+        hashes.set(normalized, hash);
+    }
+    return hash;
+}
+
+/**
+ * The Gravatar picture URL for `email`, `size` pixels square. It answers `404` (`d=404`) for a person with no Gravatar, so an `<img>` fails to load
+ * and the caller falls back to initials rather than showing Gravatar's placeholder. `undefined` for an empty address or without Web Crypto.
+ */
+export async function gravatarUrl(email: string, size: number): Promise<string | undefined> {
+    if (!email.trim()) {
+        return undefined;
+    }
+    const hash = await hashOf(email);
+    return hash && `https://gravatar.com/avatar/${hash}?s=${Math.max(1, Math.round(size))}&d=404`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",