zabi-components 8.0.0 → 9.0.0

package/dist/atoms/Textarea.svelte

@@ -1,10 +1,28 @@
 <script lang="ts">
-    import { CheckCircle, AlertTriangle, AlertCircle } from '@lucide/svelte';
+    import type { HTMLTextareaAttributes } from 'svelte/elements';
     import type { SemanticVariant, SizeVariant } from '../types/variants.js';
     import { generateId } from "../util/ssr-safe.js";
     import { cn } from "../util/cn.js";
+    import { fieldDescribedBy, fieldMessageState, type TextareaCount } from "../util/field.js";
+    import FieldMessages from "./FieldMessages.svelte";
 
-    interface Props {
+    /**
+     * Other attributes (`autocomplete`, `inputmode`, `maxlength`,
+     * `enterkeyhint`, `data-*`, `onchange`, ...) land on the `<textarea>`.
+     */
+    type Props = Omit<
+        HTMLTextareaAttributes,
+        | 'class'
+        | 'value'
+        | 'id'
+        | 'name'
+        | 'placeholder'
+        | 'required'
+        | 'disabled'
+        | 'rows'
+        | 'oninput'
+        | 'aria-describedby'
+    > & {
         id?: string;
         value?: string;
         name?: string;
@@ -16,15 +34,42 @@
         disabled?: boolean;
         loading?: boolean;
         rows?: number;
+        /**
+         * The resize grip. `auto` (default): the browser's vertical grip with a mouse or
+         * trackpad, none on a touch screen, where dragging it scrolls the page. `vertical`
+         * shows it everywhere, `none` never. With `autogrow` there is no grip.
+         */
+        resize?: 'auto' | 'none' | 'vertical';
+        /** The field grows with its content, from `rows` up to `maxRows`, and scrolls after that. */
+        autogrow?: boolean;
+        /** The tallest an `autogrow` field gets, in rows. Without it the field has no limit. */
+        maxRows?: number;
         size?: SizeVariant;
         variant?: SemanticVariant;
+        /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
         message?: string;
+        /** Help text under the field, read out with it. */
+        hint?: string;
+        /** An error under the field. It marks the field invalid and is announced; it wins over `variant` and `message`. */
+        error?: string;
+        /**
+         * A character count under the field, at the end of the line the hint is on. It needs
+         * `maxlength`; without one nothing is shown. It is part of the field's description
+         * (`aria-describedby`) and is not a live region, so it is not read out at every key.
+         */
+        count?: boolean;
+        /** The count is shown from this many characters on. `0` (default): always. */
+        countFrom?: number;
+        /** The words of the count, for the page's language. Default: "12 / 2000". */
+        countText?: (count: TextareaCount) => string;
         oninput?: (event: Event) => void;
-    }
+        /** Ids of other elements that describe the field. The hint and the message are added after them. */
+        "aria-describedby"?: string | null;
+    };
 
     let {
         id: idProp,
-        value = $bindable(''),
+        value = $bindable<Exclude<Props["value"], undefined>>(),
         name = '',
         class: className = '',
         label = '',
@@ -34,56 +79,113 @@
         disabled = false,
         loading = false,
         rows = 4,
+        resize = 'auto',
+        autogrow = false,
+        maxRows,
         size = 'md',
         variant = 'default',
         message = '',
+        hint = '',
+        error = '',
+        count = false,
+        countFrom = 0,
+        countText,
         oninput,
+        'aria-describedby': describedBy,
         ...restProps
     }: Props = $props();
 
+    // No fallback on a bindable prop: Svelte refuses `bind:…={undefined}` on
+    // one that has a fallback (`props_invalid_value`), and a page that throws
+    // while it hydrates never becomes interactive. The default is applied
+    // here instead: at once, for the server and the first render, and again
+    // whenever a parent hands back `undefined`.
+    const applyDefaults = () => {
+        if (value === undefined) value = '';
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
     const fallbackId = generateId('textarea');
     const textareaId = $derived(idProp ?? fallbackId);
     const isDisabled = $derived(disabled || loading);
 
+    const status = $derived(fieldMessageState({ variant, message, hint, error }));
+
+    // The count: only with a `maxlength`, and only once `countFrom` is reached.
+    // The length is the one `maxlength` counts (UTF-16 units).
+    const countMax = $derived(Number(restProps.maxlength));
+    const countLength = $derived((value ?? '').length);
+    const showCount = $derived(
+        count && Number.isFinite(countMax) && countMax > 0 && countLength >= countFrom,
+    );
+    const countLabel = $derived.by(() => {
+        if (!showCount) return '';
+        const state = { length: countLength, max: countMax, remaining: Math.max(0, countMax - countLength) };
+        return countText ? countText(state) : `${state.length} / ${state.max}`;
+    });
+    const countId = $derived(`${textareaId}-count`);
+    // The caller's ids, the hint and the message, then the count.
+    const fieldDescription = $derived(
+        [fieldDescribedBy(textareaId, status, describedBy), showCount ? countId : '']
+            .filter(Boolean)
+            .join(' ') || undefined,
+    );
+
     const variantClass = $derived(() => {
-        return variant === 'success'
+        return status.variant === 'success'
             ? 'border-success focus-visible:border-success'
-            : variant === 'warning'
+            : status.variant === 'warning'
               ? 'border-warning focus-visible:border-warning'
-              : variant === 'error'
+              : status.variant === 'error'
                 ? 'border-error focus-visible:border-error'
-                : 'border-input-border';
+                : 'border-input-border enabled:hover:border-input-border-hover';
+    });
+
+    const resizeClass = $derived(
+        autogrow || resize === 'none'
+            ? 'resize-none'
+            : resize === 'vertical'
+              ? 'resize-y'
+              : 'resize-y pointer-coarse:resize-none',
+    );
+
+    // Autogrow: `field-sizing: content` where the browser has it, held between
+    // `rows` and `maxRows` lines (`leading-6`, plus `py-2` and the two borders,
+    // since the box is border-box). Elsewhere the height is measured from the
+    // content after each change; the same two limits clamp it.
+    const linesHeight = (lines: number) => `calc(${lines * 1.5 + 1}rem + 2px)`;
+    const minHeight = $derived(autogrow ? linesHeight(Math.max(1, rows)) : undefined);
+    const maxHeight = $derived(
+        autogrow && maxRows !== undefined ? linesHeight(Math.max(rows, maxRows)) : undefined,
+    );
+
+    let element: HTMLTextAreaElement | undefined = $state();
+
+    $effect(() => {
+        void value;
+        if (!autogrow || !element) return;
+        if (typeof CSS !== 'undefined' && CSS.supports?.('field-sizing', 'content')) return;
+        const field = element;
+        field.style.height = 'auto';
+        field.style.height = `${field.scrollHeight + field.offsetHeight - field.clientHeight}px`;
+        return () => {
+            field.style.height = '';
+        };
     });
 
+    // 16px below `sm`: iOS Safari zooms the page when a focused field is smaller.
     const textareaClasses = $derived(() => {
         const baseClasses =
-            'focus-ring w-full border bg-input hover:bg-input-hover focus-visible:bg-input-focus disabled:bg-input-disabled rounded-control transition-colors duration-150 placeholder:text-input-placeholder text-body focus:outline-none focus-visible:outline-none disabled:text-action-disabled-text disabled:cursor-not-allowed resize-y px-3 py-2 text-sm leading-6';
+            'focus-ring w-full border bg-input hover:bg-input-hover focus-visible:bg-input-focus disabled:bg-input-disabled rounded-control transition-colors duration-150 placeholder:text-input-placeholder text-body focus:outline-none focus-visible:outline-none disabled:text-action-disabled-text disabled:cursor-not-allowed px-3 py-2 text-sm max-sm:text-base leading-6';
 
-        return cn(`${baseClasses} ${variantClass()} ${className}`);
+        return cn(`${baseClasses} ${resizeClass} ${variantClass()} ${className}`);
     });
 
     const labelClasses = $derived(
         () => 'mb-1 block text-sm font-medium text-label',
     );
 
-    const messageClasses = $derived(() => {
-        if (variant === 'error') {
-            return 'mt-1 flex items-center gap-2 text-sm text-error';
-        } else if (variant === 'success') {
-            return 'mt-1 flex items-center gap-2 text-sm text-success';
-        } else if (variant === 'warning') {
-            return 'mt-1 flex items-center gap-2 text-sm text-warning';
-        }
-        return 'mt-1 flex items-center gap-2 text-sm text-description';
-    });
-
-    const getIcon = $derived(() => {
-        if (variant === 'error') return AlertCircle;
-        if (variant === 'success') return CheckCircle;
-        if (variant === 'warning') return AlertTriangle;
-        return null;
-    });
-
     function handleInput(event: Event) {
         const target = event.target as HTMLTextAreaElement;
         value = target.value;
@@ -97,6 +199,7 @@
     {/if}
     <div class="relative">
         <textarea
+            bind:this={element}
             id={textareaId}
             {name}
             bind:value
@@ -105,11 +208,15 @@
             disabled={isDisabled}
             {rows}
             class={textareaClasses()}
+            style:field-sizing={autogrow ? 'content' : undefined}
+            style:min-height={minHeight}
+            style:max-height={maxHeight}
+            style:overflow-y={maxHeight ? 'auto' : undefined}
             oninput={handleInput}
-            aria-invalid={variant === 'error' ? 'true' : undefined}
+            aria-invalid={status.variant === 'error' ? 'true' : undefined}
             aria-required={required ? 'true' : undefined}
             aria-busy={loading ? 'true' : undefined}
-            aria-describedby={message ? `${textareaId}-message` : undefined}
+            aria-describedby={fieldDescription}
             {...restProps}
         ></textarea>
         {#if loading}
@@ -118,23 +225,22 @@
                 aria-hidden="true"
             >
                 <span
-                    class="inline-block size-5 shrink-0 animate-spin rounded-full border-2 border-current border-t-transparent opacity-70"
+                    class="inline-block size-5 shrink-0 animate-spin rounded-full border-2 border-current border-t-transparent opacity-70 motion-reduce:animate-pulse"
                 ></span>
             </span>
         {/if}
     </div>
-    {#if message && variant !== 'default'}
-        <p
-            id={`${textareaId}-message`}
-            class={messageClasses()}
-            role={variant === 'error' ? 'alert' : 'status'}
-            aria-live={variant === 'error' ? 'assertive' : 'polite'}
-        >
-            {#if getIcon()}
-                {@const Icon = getIcon()}
-                <Icon size={14} class="shrink-0" />
-            {/if}
-            <span>{message}</span>
-        </p>
+    {#if showCount}
+        <!-- The count ends the line the hint starts. Not a live region: it is read with the field. -->
+        <div class="flex items-start gap-3">
+            <div class="min-w-0 flex-1">
+                <FieldMessages fieldId={textareaId} {status} {hint} gap="mt-1" />
+            </div>
+            <p id={countId} class="mt-1 shrink-0 text-sm text-description tabular-nums" data-textarea-count>
+                {countLabel}
+            </p>
+        </div>
+    {:else}
+        <FieldMessages fieldId={textareaId} {status} {hint} gap="mt-1" />
     {/if}
 </div>

package/dist/atoms/Textarea.svelte.d.ts

@@ -1,5 +1,11 @@
+import type { HTMLTextareaAttributes } from 'svelte/elements';
 import type { SemanticVariant, SizeVariant } from '../types/variants.js';
-interface Props {
+import { type TextareaCount } from "../util/field.js";
+/**
+ * Other attributes (`autocomplete`, `inputmode`, `maxlength`,
+ * `enterkeyhint`, `data-*`, `onchange`, ...) land on the `<textarea>`.
+ */
+type Props = Omit<HTMLTextareaAttributes, 'class' | 'value' | 'id' | 'name' | 'placeholder' | 'required' | 'disabled' | 'rows' | 'oninput' | 'aria-describedby'> & {
     id?: string;
     value?: string;
     name?: string;
@@ -11,11 +17,38 @@ interface Props {
     disabled?: boolean;
     loading?: boolean;
     rows?: number;
+    /**
+     * The resize grip. `auto` (default): the browser's vertical grip with a mouse or
+     * trackpad, none on a touch screen, where dragging it scrolls the page. `vertical`
+     * shows it everywhere, `none` never. With `autogrow` there is no grip.
+     */
+    resize?: 'auto' | 'none' | 'vertical';
+    /** The field grows with its content, from `rows` up to `maxRows`, and scrolls after that. */
+    autogrow?: boolean;
+    /** The tallest an `autogrow` field gets, in rows. Without it the field has no limit. */
+    maxRows?: number;
     size?: SizeVariant;
     variant?: SemanticVariant;
+    /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
     message?: string;
+    /** Help text under the field, read out with it. */
+    hint?: string;
+    /** An error under the field. It marks the field invalid and is announced; it wins over `variant` and `message`. */
+    error?: string;
+    /**
+     * A character count under the field, at the end of the line the hint is on. It needs
+     * `maxlength`; without one nothing is shown. It is part of the field's description
+     * (`aria-describedby`) and is not a live region, so it is not read out at every key.
+     */
+    count?: boolean;
+    /** The count is shown from this many characters on. `0` (default): always. */
+    countFrom?: number;
+    /** The words of the count, for the page's language. Default: "12 / 2000". */
+    countText?: (count: TextareaCount) => string;
     oninput?: (event: Event) => void;
-}
+    /** Ids of other elements that describe the field. The hint and the message are added after them. */
+    "aria-describedby"?: string | null;
+};
 declare const Textarea: import("svelte").Component<Props, {}, "value">;
 type Textarea = ReturnType<typeof Textarea>;
 export default Textarea;

package/dist/atoms/ThemeToggle.svelte

@@ -1,88 +1,251 @@
 <script lang="ts">
-    import { onMount } from "svelte";
-    import { Sun, Moon } from "@lucide/svelte";
+    import { mergeStrings } from "../util/ready-made-strings.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
+    import { onMount, untrack } from "svelte";
+    import type { HTMLButtonAttributes } from "svelte/elements";
+    import Sun from "@lucide/svelte/icons/sun";
+    import Moon from "@lucide/svelte/icons/moon";
+    import Monitor from "@lucide/svelte/icons/monitor";
     import { FOCUS_BRAND_CLASS } from "../util/focus-utils.js";
     import { cn } from "../util/cn.js";
-    
-    function safeLocalStorage(): Storage | undefined {
-        return typeof window !== "undefined" ? localStorage : undefined;
-    }
-
-    function safeDocument(): Document | undefined {
-        return typeof window !== "undefined" ? document : undefined;
-    }
+    import {
+        DEFAULT_THEME_STORAGE_KEY,
+        THEME_MODES,
+        getStoredThemeMode,
+        getThemeMode,
+        isThemeDark,
+        isThemeMode,
+        setThemeMode,
+        storeThemeMode,
+        type ThemeMode,
+        type ThemeToggleLabels,
+    } from "../util/theme-mode.js";
 
-    interface Props {
+    /** Other attributes (`data-*`, `aria-*`, `id`, ...) land on the `<button>`. */
+    type Props = Omit<
+        HTMLButtonAttributes,
+        "class" | "disabled" | "type" | "onclick" | "children"
+    > & {
         /** Extra classes for the host element. */
         class?: string;
         size?: "sm" | "md" | "lg";
         variant?: "default" | "ghost" | "outline";
         disabled?: boolean;
+        /**
+         * `"two"` (the default) flips light and dark. `"three"` steps through
+         * system, light and dark, and always writes `data-theme` on `<html>`.
+         */
+        modes?: "two" | "three";
+        /**
+         * The page's mode: `"auto"` (follow the system), `"light"` or `"dark"`.
+         * Bindable. It is read from `<html>` when the button mounts and follows
+         * the page from then on; assigning it switches the page.
+         */
+        mode?: ThemeMode;
+        /** Called with the new mode when a press changes it. */
+        onmodechange?: (mode: ThemeMode) => void;
+        /**
+         * The `localStorage` key the choice is kept under and restored from when
+         * the button mounts. `null` keeps nothing.
+         */
+        storageKey?: string | null;
+        /** Replaces the texts of the accessible name, for another language. */
+        labels?: Partial<ThemeToggleLabels>;
         onclick?: (event: Event) => void;
-    }
+    };
 
     let {
         class: className = "",
         size = "md",
         variant = "default",
         disabled = false,
+        modes = "two",
+        mode = $bindable(),
+        onmodechange,
+        storageKey = DEFAULT_THEME_STORAGE_KEY,
+        labels,
         onclick,
         ...restProps
     }: Props = $props();
 
+    const DEFAULT_LABELS: ThemeToggleLabels = {
+        auto: "system",
+        light: "light",
+        dark: "dark",
+        describe: (current, next) => `Theme: ${current}. Switch to ${next}`,
+        darkMode: "Dark mode",
+        beforeMount: "Theme toggle",
+    };
+    /** The app-wide words for this component, from a `ZabiStringsProvider` above it, if there is one. */
+    const provided = zabiStringsFor("themeToggle");
+    const text = $derived(mergeStrings(DEFAULT_LABELS, provided(), labels));
+
+    /** Whether the page is dark right now, whichever way it is switched. */
     let isDark = $state(false);
+    /** The page's mode as last read from `<html>`. */
+    let pageMode = $state<ThemeMode>("light");
     let mounted = $state(false);
 
+    const SYSTEM_DARK = "(prefers-color-scheme: dark)";
+
+    /** A page that carries `data-theme` on `<html>` is switched through it; any other page through the class. */
+    function usesAttribute(root: HTMLElement): boolean {
+        return root.hasAttribute("data-theme");
+    }
+
+    /** Reads the page into the button. The only place `mode` is set from the page. */
+    function readPage() {
+        isDark = isThemeDark();
+        pageMode = getThemeMode();
+        mode = pageMode;
+    }
+
+    /**
+     * Puts the page in `next`. With three modes that is always `data-theme`.
+     * With two, "auto" can only be said with the attribute, and light or dark
+     * go to whichever mechanism the page uses, as they always have.
+     */
+    function applyMode(next: ThemeMode) {
+        if (modes === "three" || next === "auto") {
+            setThemeMode(next, { storageKey });
+        } else {
+            isDark = next === "dark";
+            updateTheme();
+            storeThemeMode(next, storageKey);
+        }
+        readPage();
+    }
+
     onMount(() => {
         mounted = true;
-        const doc = safeDocument();
-        if (doc) {
-            isDark = doc.documentElement.classList.contains("dark");
+        if (typeof document === "undefined") return;
+        const root = document.documentElement;
+
+        clearInlineScheme(root);
+
+        // The choice made last time, unless a script in <head> has applied it
+        // already (`themeInitScript`) or the app passed a mode of its own.
+        const asked = isThemeMode(mode) ? mode : getStoredThemeMode(storageKey);
+        if (asked && asked !== getThemeMode() && (modes === "three" || asked !== "auto" || usesAttribute(root))) {
+            applyMode(asked);
+        } else {
+            readPage();
         }
 
-        if (!window.matchMedia) return;
+        // The page can be switched by something else (another control bound to
+        // the same helpers, the app's own script): the icon and the name follow.
+        const observer = typeof MutationObserver === "undefined" ? undefined : new MutationObserver(readPage);
+        observer?.observe(root, { attributes: true, attributeFilter: ["class", "data-theme"] });
 
-        const media = window.matchMedia("(prefers-color-scheme: dark)");
+        const media = window.matchMedia?.(SYSTEM_DARK);
         const handleSystemChange = (event: MediaQueryListEvent) => {
-            const storage = safeLocalStorage();
-            if (storage && storage.getItem("theme")) return;
+            if (modes === "three" || usesAttribute(root)) {
+                // `data-theme="auto"` follows the system in the stylesheet, and
+                // "light" or "dark" is a choice: either way only the reading changes.
+                readPage();
+                return;
+            }
+            if (getStoredThemeMode(storageKey)) return;
             isDark = event.matches;
             updateTheme();
+            readPage();
+        };
+        media?.addEventListener("change", handleSystemChange);
+
+        return () => {
+            observer?.disconnect();
+            media?.removeEventListener("change", handleSystemChange);
         };
+    });
 
-        media.addEventListener("change", handleSystemChange);
-        return () => media.removeEventListener("change", handleSystemChange);
+    // `mode` assigned from outside (a bound value, the app's own control).
+    $effect(() => {
+        const wanted = mode;
+        if (!mounted || !isThemeMode(wanted)) return;
+        untrack(() => {
+            if (wanted !== pageMode) applyMode(wanted);
+        });
     });
 
+    /** What a press leads to. */
+    const nextMode = $derived<ThemeMode>(
+        modes === "three"
+            ? THEME_MODES[(THEME_MODES.indexOf(pageMode) + 1) % THEME_MODES.length]
+            : isDark
+              ? "light"
+              : "dark",
+    );
+
+    /**
+     * Two modes: a switch with one name, "Dark mode", and `aria-pressed` for its
+     * state. The name used to flip as well ("Switch to dark mode", then "Switch
+     * to light mode, pressed"), and "pressed" on "Switch to light mode" says
+     * two things at once. Three modes are steps, not on and off, so there the
+     * name carries the state and there is no `aria-pressed`.
+     */
+    const accessibleName = $derived(modes === "three" ? text.describe(text[pageMode], text[nextMode]) : text.darkMode);
+
     function toggleTheme(event: Event) {
         if (disabled) return;
-        isDark = !isDark;
-        updateTheme();
-        const storage = safeLocalStorage();
-        if (mounted && storage) {
-            storage.setItem("theme", isDark ? "dark" : "light");
-        }
-
+        applyMode(nextMode);
+        onmodechange?.(pageMode);
         onclick?.(event);
     }
 
+    /** Two modes, light or dark: the attribute where the page has it, the class otherwise. */
     function updateTheme() {
-        const doc = safeDocument();
-        if (mounted && doc) {
-            if (isDark) {
-                doc.documentElement.classList.add("dark");
-                doc.documentElement.style.colorScheme = "dark";
-            } else {
-                doc.documentElement.classList.remove("dark");
-                doc.documentElement.style.colorScheme = "light";
-            }
+        if (!mounted || typeof document === "undefined") return;
+        const root = document.documentElement;
+        if (usesAttribute(root)) {
+            // An explicit choice, also when the page was on "auto". The theme
+            // sets `color-scheme` for each value, so no inline style is written.
+            root.setAttribute("data-theme", isDark ? "dark" : "light");
+            // A leftover class would keep the page dark under data-theme="light".
+            if (!isDark) root.classList.remove("dark");
+            return;
         }
+        // The class only. The theme sets `color-scheme` for it (dark under
+        // `.dark`, light on the root otherwise), so no inline value is written:
+        // one left behind would outrank the stylesheet, and the next time the
+        // app added or removed the class itself the tokens would change and
+        // the native controls would not.
+        root.classList.toggle("dark", isDark);
+        clearInlineScheme(root);
+    }
+
+    /**
+     * Removes an inline `color-scheme` of "light" or "dark" from `<html>`: what
+     * this button wrote before the theme set the scheme itself, and what a
+     * start-up script copied from the old docs writes. Any other inline value
+     * is the app's own and is left alone.
+     */
+    function clearInlineScheme(root: HTMLElement) {
+        const inline = root.style.colorScheme;
+        if (inline === "light" || inline === "dark") root.style.removeProperty("color-scheme");
     }
 
+    /**
+     * Before mount every icon is rendered and CSS shows one, by the selectors
+     * the theme itself is switched with. Written out in full, because Tailwind
+     * only generates a class it can read in the source.
+     *
+     * Two modes: sun on a light page, moon on a dark one (the class,
+     * `data-theme="dark"`, or `data-theme="auto"` on a dark system).
+     * Three modes show the mode, not the result: the monitor for
+     * `data-theme="auto"` whatever the system is.
+     */
+    const SUN_BEFORE_MOUNT =
+        "[.dark_&]:hidden [[data-theme=dark]_&]:hidden [@media(prefers-color-scheme:dark)]:[[data-theme=auto]_&]:hidden";
+    const MOON_BEFORE_MOUNT =
+        "hidden [.dark_&]:block [[data-theme=dark]_&]:block [@media(prefers-color-scheme:dark)]:[[data-theme=auto]_&]:block";
+    const SUN_BEFORE_MOUNT_THREE = "[.dark_&]:hidden [[data-theme=dark]_&]:hidden [[data-theme=auto]_&]:hidden";
+    const MOON_BEFORE_MOUNT_THREE = "hidden [.dark_&]:block [[data-theme=dark]_&]:block";
+    const SYSTEM_BEFORE_MOUNT_THREE = "hidden [[data-theme=auto]_&]:block";
+
     const sizeClass = $derived(() => {
         if (size === "sm") {
             return {
-                button: "w-8 h-8",
+                button: "w-8 h-8 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
                 icon: 16
             };
         } else if (size === "lg") {
@@ -92,7 +255,7 @@
             };
         } else {
             return {
-                button: "w-10 h-10",
+                button: "w-10 h-10 pointer-coarse:min-h-11 pointer-coarse:min-w-11",
                 icon: 20
             };
         }
@@ -135,13 +298,16 @@
     <button
         onclick={toggleTheme}
         class="{buttonClasses()} {className}"
-        aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
-        aria-pressed={isDark}
+        aria-label={accessibleName}
+        aria-pressed={modes === "three" ? undefined : isDark}
+        data-theme-mode={modes === "three" ? pageMode : undefined}
         type="button"
         {disabled}
         {...restProps}
     >
-        {#if isDark}
+        {#if modes === "three" && pageMode === "auto"}
+            <Monitor size={sizeClass().icon} class="text-label" />
+        {:else if modes === "three" ? pageMode === "dark" : isDark}
             <Moon size={sizeClass().icon} class="text-label" />
         {:else}
             <Sun size={sizeClass().icon} class="text-label" />
@@ -150,11 +316,24 @@
 {:else}
     <button
         class="{sizeClass().button} {variantClass()} rounded-control flex items-center justify-center text-label cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
-        aria-label="Theme toggle"
+        aria-label={text.beforeMount}
         type="button"
         {disabled}
         {...restProps}
     >
-        <Sun size={sizeClass().icon} class="text-label" />
+        <!-- Before mount there is no state to read: the server cannot know the
+        theme, and hydration has not run yet. Every icon is in the markup and
+        the stylesheet picks one, so a dark page never shows the Sun first:
+        by the `dark` class, by `data-theme="dark"`, or by `data-theme="auto"`
+        (the moon on a dark system with two modes, the monitor with three).
+        The icon matches the mounted button. -->
+        {#if modes === "three"}
+            <Sun size={sizeClass().icon} class="text-label {SUN_BEFORE_MOUNT_THREE}" />
+            <Moon size={sizeClass().icon} class="text-label {MOON_BEFORE_MOUNT_THREE}" />
+            <Monitor size={sizeClass().icon} class="text-label {SYSTEM_BEFORE_MOUNT_THREE}" />
+        {:else}
+            <Sun size={sizeClass().icon} class="text-label {SUN_BEFORE_MOUNT}" />
+            <Moon size={sizeClass().icon} class="text-label {MOON_BEFORE_MOUNT}" />
+        {/if}
     </button>
 {/if}