@rapidmx/web-client 0.10.0 → 0.12.0

package/apps/shared/components/mail/reading/themeAdaptation.ts

@@ -0,0 +1,221 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import {
+    MIN_TEXT_CONTRAST,
+    Rgb,
+    ThemeSurface,
+    adaptForeground,
+    blackOrWhite,
+    composite,
+    contrastRatio,
+    ensureContrast,
+    firstColourStop,
+    formatColour,
+    luminance,
+    parseColour,
+    sameColour,
+} from "./color.js";
+import { LINK_SENTINEL, TEXT_SENTINEL } from "./frameDocument.js";
+import { documentElementOf, viewOf } from "./safeDocument.js";
+
+/**
+ * Makes a message take the app's theme wherever its author left the colours to the reader, and leaves it as authored wherever the
+ * author chose them. Runs in the parent against the display frame's document (which is same-origin only because no script can run
+ * there - see `frameDocument.ts`); reads with `getComputedStyle` and writes nothing but `color` on individual elements, as inline
+ * `!important` declarations built from numbers, never from text of the message.
+ *
+ * **Authored or inherited, without parsing CSS.** The frame's base stylesheet gives the root a sentinel text colour, and unvisited/visited
+ * links another, at zero specificity, so any rule of the message beats them. An element whose computed `color` still equals the sentinel
+ * was never coloured by the message (its text is *unauthored*); any other value - black included - was chosen by somebody. A background
+ * is authored when its computed colour is not transparent or its image is not `none`.
+ *
+ * **What each text becomes**, from its effective background (the nearest authored background up the tree, composited over what is beneath
+ * it, else the theme's surface):
+ * - unauthored text on the theme surface: the theme's text colour; an unauthored link: the theme's link colour;
+ * - authored text on the theme surface: kept if it reads (4.5:1), else adapted (`adaptForeground()`: black becomes white, navy a lighter
+ * navy) - the symmetric case in a light theme included;
+ * - anything on an authored, opaque background (a white cell, a dark banner, a gradient): that region is shown as authored - its own text
+ * colours untouched - except unauthored text, which must not inherit the theme's colour (white on white) and gets black or white by
+ * contrast with that background (black when the background is a picture or a gradient with no first colour to judge by);
+ * - a semi-transparent authored background is composited over what is under it and treated like the theme surface, since how it looks
+ * depends on the theme.
+ *
+ * Every element ends with exactly its target colour: an element is written to only when inheritance would not give it that (which includes
+ * one that may carry a declaration of its own). Images, SVG and everything else that is not text are untouched.
+ */
+
+export interface AdaptationResult {
+    /** Elements examined. */
+    elements: number;
+    /** Elements given an inline colour. */
+    written: number;
+    /** Whether adapting makes a visible difference from the message as authored: a text colour changed a lot, or the canvas is the theme's
+     * dark surface rather than the white a message is authored on. False for e.g. a bare message in a light theme. */
+    material: boolean;
+    /** `<html>` or `<body>` carries an authored background: the whole frame takes it. */
+    authoredCanvas: boolean;
+    /** Stopped because `isCancelled()` said the frame was gone. */
+    cancelled: boolean;
+    /** Puts every colour back as the message had it (paper is not a dark surface: the frame does this for printing). */
+    revert: () => void;
+    /** Puts the adapted colours back after `revert()`. */
+    reapply: () => void;
+}
+
+export interface AdaptOptions {
+    /** How long one slice of work may take before the pass gives the browser a turn. */
+    sliceMs?: number;
+    isCancelled?: () => boolean;
+    /** For tests. */
+    now?: () => number;
+    yieldToBrowser?: () => Promise<void>;
+}
+
+/** Not examined, nor are their children. `head` and its contents never render; `svg` is left as drawn. */
+const SKIPPED = new Set(["head", "script", "style", "title", "meta", "link", "template", "svg", "img"]);
+
+/** What travels down the tree: the effective background, whether it is an authored opaque one, and the colour the parent ends up with. */
+interface Context {
+    background: Rgb;
+    authored: boolean;
+    unknown: boolean;
+    parentColour: Rgb;
+}
+
+/** Classic link blue - what an unauthored link looks like in an authored region, before contrast. */
+const DEFAULT_LINK: Rgb = { r: 0, g: 0, b: 238 };
+/** How much lighter or darker (in luminance) an adapted text colour must be than the original for the difference to be worth an opt-out. */
+const MATERIAL_LUMINANCE_SHIFT = 0.3;
+/** A surface at least this luminous is close enough to the white a message is authored on that it is not, by itself, an adaptation. */
+const LIGHT_SURFACE = 0.85;
+
+/** The elements whose background is the message's canvas: `<html>`, `<body>`, and the wrapper that stands in for the message's own `<body>`. */
+function standsForCanvas(element: HTMLElement, root: HTMLElement): boolean {
+    return element === root || element.localName === "body" || element.parentElement?.id === "rr-body";
+}
+
+function noop(): void {
+    // Nothing was written, so there is nothing to put back.
+}
+
+function nextTurn(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/** The colour a `color` value comes to over a background: opaque, alpha composited. */
+function opaque(css: string, over: Rgb): Rgb | undefined {
+    const colour = parseColour(css);
+    return colour ? composite(colour, over) : undefined;
+}
+
+/**
+ * Adapts `doc` to `surface` - see the file's header. Time-sliced (`sliceMs`, then a turn for the browser) so a very large message never
+ * blocks the page; the frame stays hidden until this resolves, so nothing unreadable is ever shown.
+ */
+export async function adaptDocument(doc: Document, surface: ThemeSurface, options: AdaptOptions = {}): Promise<AdaptationResult> {
+    const { sliceMs = 12, isCancelled = () => false, now = () => performance.now(), yieldToBrowser = nextTurn } = options;
+    const view = viewOf(doc);
+    const result: AdaptationResult = { elements: 0, written: 0, material: false, authoredCanvas: false, cancelled: false, revert: noop, reapply: noop };
+    if (!view) {
+        return result;
+    }
+    const root = documentElementOf(doc);
+    // Every read happens before the first write: a write changes what its descendants inherit, which would make every child of an element
+    // we coloured look authored.
+    const writes: { element: HTMLElement; colour: string }[] = [];
+    const stack: { element: HTMLElement; context: Context }[] = [
+        { element: root, context: { background: surface.background, authored: false, unknown: false, parentColour: surface.text } },
+    ];
+    let sliceStart = now();
+    while (stack.length > 0) {
+        if (now() - sliceStart > sliceMs) {
+            await yieldToBrowser();
+            if (isCancelled()) {
+                result.cancelled = true;
+                return result;
+            }
+            sliceStart = now();
+        }
+        const { element, context } = stack.pop()!;
+        if (SKIPPED.has(element.localName.toLowerCase())) {
+            continue;
+        }
+        result.elements++;
+        const style = view.getComputedStyle(element);
+        let { background, authored, unknown } = context;
+        const own = parseColour(style.backgroundColor);
+        const image = style.backgroundImage;
+        if (image && image !== "none") {
+            const stop = firstColourStop(image) ?? (own && own.a > 0 ? own : undefined);
+            authored = true;
+            unknown = !stop;
+            background = stop ? composite(stop, background) : background;
+            result.authoredCanvas ||= standsForCanvas(element, root);
+        } else if (own && own.a >= 0.98) {
+            authored = true;
+            unknown = false;
+            background = composite(own, background);
+            result.authoredCanvas ||= standsForCanvas(element, root);
+        } else if (own && own.a > 0) {
+            background = composite(own, background);
+        }
+
+        const declared = style.color;
+        const original = opaque(declared, background);
+        let target: { rgb: Rgb; css: string } | undefined;
+        if (declared === TEXT_SENTINEL) {
+            const rgb = authored ? (unknown ? { r: 0, g: 0, b: 0 } : blackOrWhite(background)) : ensureContrast(surface.text, background);
+            target = { rgb, css: formatColour(rgb) };
+        } else if (declared === LINK_SENTINEL) {
+            const rgb = authored ? (unknown ? DEFAULT_LINK : ensureContrast(DEFAULT_LINK, background)) : ensureContrast(surface.link, background);
+            target = { rgb, css: formatColour(rgb) };
+        } else if (original && !authored) {
+            // Authored text on the theme's surface: it stays if it reads, else it is adapted.
+            const readable = contrastRatio(original, background) >= MIN_TEXT_CONTRAST;
+            const rgb = readable ? original : adaptForeground(original, { ...surface, background });
+            target = { rgb, css: readable ? declared : formatColour(rgb) };
+        } else if (original) {
+            // Authored text on an authored background: as its author had it.
+            target = { rgb: original, css: declared };
+        }
+        let parentColour = context.parentColour;
+        if (target) {
+            // An element is written to unless inheritance already gives it its target: the parent must end with that colour, and an element
+            // that may carry a declaration of its own (an authored colour, a link - the sentinel is a rule on it - and the root) must not
+            // be declaring a different one. Text nobody coloured inherits and has nothing of its own to override.
+            const ownDeclaration = declared !== TEXT_SENTINEL || element === root;
+            if (!sameColour(target.rgb, context.parentColour) || (ownDeclaration && !sameColour(target.rgb, original ?? target.rgb))) {
+                writes.push({ element, colour: target.css });
+            }
+            if (original && Math.abs(luminance(target.rgb) - luminance(original)) > MATERIAL_LUMINANCE_SHIFT) {
+                result.material = true;
+            }
+            parentColour = target.rgb;
+        }
+        for (const child of Array.from(element.children).reverse()) {
+            stack.push({ element: child as HTMLElement, context: { background, authored, unknown, parentColour } });
+        }
+    }
+    // What each element had inline before, so the writes can be taken back (a message may carry its own inline colour).
+    const before = writes.map(({ element }) => ({ value: element.style.getPropertyValue("color"), priority: element.style.getPropertyPriority("color") }));
+    result.reapply = () => {
+        for (const { element, colour } of writes) {
+            element.style.setProperty("color", colour, "important");
+        }
+    };
+    result.revert = () => {
+        writes.forEach(({ element }, index) => {
+            if (before[index].value) {
+                element.style.setProperty("color", before[index].value, before[index].priority);
+            } else {
+                element.style.removeProperty("color");
+            }
+        });
+    };
+    result.reapply();
+    result.written = writes.length;
+    result.material ||= !result.authoredCanvas && luminance(surface.background) < LIGHT_SURFACE;
+    return result;
+}

package/apps/shared/components/mail/reading/themeSurface.ts

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import type { ResolvedTheme } from "../../../appearance/resolvedTheme.js";
+import { Rgb, Rgba, ThemeSurface, composite, formatColour, parseColour } from "./color.js";
+
+/** The palette used where the page's own tokens cannot be read (no DOM, or a stylesheet without them): the app's built-in schemes. */
+export const DEFAULT_SURFACES: Record<ResolvedTheme, ThemeSurface> = {
+    light: { background: { r: 255, g: 255, b: 255 }, text: { r: 28, g: 37, b: 38 }, link: { r: 20, g: 138, b: 128 }, dark: false },
+    dark: { background: { r: 27, g: 32, b: 34 }, text: { r: 238, g: 242, b: 243 }, link: { r: 45, g: 212, b: 191 }, dark: true },
+};
+
+/** The page's own CSS variables a message is adapted to. Read from the document, so a branding palette or a user's own Appearance colours are followed. */
+const TOKENS = {
+    surface: "--rr-color-surface",
+    page: "--rr-color-bg",
+    text: "--rr-color-text",
+    link: "--rr-color-primary-dark",
+} as const;
+
+/** The colour a CSS custom property resolves to, by asking the browser what a probe element painted with it comes to (which also
+ * resolves `var()` chains and colour functions); `undefined` when it isn't defined or isn't a colour. */
+function resolveToken(probe: HTMLElement, name: string): Rgba | undefined {
+    probe.style.color = `var(${name}, transparent)`;
+    const colour = parseColour(getComputedStyle(probe).color);
+    return colour && colour.a > 0 ? colour : undefined;
+}
+
+/**
+ * The theme a message is shown in, read from the page's own tokens: the surface behind the body composited to an opaque colour (a
+ * translucent surface over a photo would make text unreadable, so the body area is always painted with this opaque one), the text
+ * colour and the link colour. Falls back to the built-in scheme for anything the page doesn't define.
+ */
+export function readThemeSurface(theme: ResolvedTheme): ThemeSurface {
+    const fallback = DEFAULT_SURFACES[theme];
+    if (typeof document === "undefined" || !document.body) {
+        return fallback;
+    }
+    const probe = document.createElement("span");
+    probe.style.display = "none";
+    document.body.appendChild(probe);
+    try {
+        const page = resolveToken(probe, TOKENS.page);
+        const surface = resolveToken(probe, TOKENS.surface);
+        const underlay: Rgb = page ? composite(page, fallback.background) : fallback.background;
+        const text = resolveToken(probe, TOKENS.text);
+        const link = resolveToken(probe, TOKENS.link);
+        return {
+            dark: fallback.dark,
+            background: surface ? composite(surface, underlay) : underlay,
+            text: text ? composite(text, underlay) : fallback.text,
+            link: link ? composite(link, underlay) : fallback.link,
+        };
+    } finally {
+        probe.remove();
+    }
+}
+
+/** A string that changes exactly when the surface does - what a frame is keyed on. */
+export function surfaceKey(surface: ThemeSurface): string {
+    return [surface.background, surface.text, surface.link].map(formatColour).join("|") + (surface.dark ? "|dark" : "|light");
+}
+
+/**
+ * The theme surface for `theme`, kept current: re-read when the scheme changes and when the page's own colours are changed at runtime
+ * (Appearance sets `data-theme` on `<html>` and writes the user's colours into a `<style>` in the head). The identity only changes when a colour does.
+ */
+export function useThemeSurface(theme: ResolvedTheme): ThemeSurface {
+    const [surface, setSurface] = useState(() => readThemeSurface(theme));
+    useEffect(() => {
+        const update = () =>
+            setSurface((previous) => {
+                const next = readThemeSurface(theme);
+                return surfaceKey(previous) === surfaceKey(next) ? previous : next;
+            });
+        update();
+        if (typeof MutationObserver === "undefined") {
+            return;
+        }
+        const observer = new MutationObserver(update);
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ["style", "class", "data-theme"] });
+        // The Appearance provider writes the user's own colours into a `<style>` element in the head, whose text is replaced when they change.
+        observer.observe(document.head, { childList: true, subtree: true, characterData: true, attributes: true });
+        return () => observer.disconnect();
+    }, [theme]);
+    // The render that first sees a new scheme must not use the previous one's colours (the effect above corrects the state after it).
+    return surface.dark === (theme === "dark") ? surface : readThemeSurface(theme);
+}

package/apps/shared/components/mail/reading/viewOriginal.ts

@@ -0,0 +1,38 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useCallback, useState } from "react";
+
+/** Messages the reader chose to see exactly as authored rather than adapted to the theme, for the life of the tab. */
+const original = new Set<string>();
+
+/** Whether the reader asked to see `uid` as authored. */
+export function isViewedOriginal(uid: string): boolean {
+    return original.has(uid);
+}
+
+/** Forgets every choice (the tests). */
+export function clearViewedOriginal(): void {
+    original.clear();
+}
+
+/**
+ * The per-message "View original" choice: `false` (follow the theme) until the reader flips it, then remembered for the session so
+ * collapsing and expanding a message, or coming back to it, keeps the choice.
+ */
+export function useViewOriginal(uid: string): [boolean, (value: boolean) => void] {
+    const [value, setValue] = useState(() => isViewedOriginal(uid));
+    const update = useCallback(
+        (next: boolean) => {
+            if (next) {
+                original.add(uid);
+            } else {
+                original.delete(uid);
+            }
+            setValue(next);
+        },
+        [uid],
+    );
+    return [value, update];
+}