zabi-components 7.0.2 → 8.1.0

package/dist/atoms/Textarea.svelte

@@ -1,9 +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 } 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;
@@ -17,13 +36,20 @@
         rows?: 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;
         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 = '',
@@ -36,53 +62,52 @@
         size = 'md',
         variant = 'default',
         message = '',
+        hint = '',
+        error = '',
         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 }));
+
     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';
     });
 
+    // 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-lg transition-all duration-200 placeholder:text-description text-body focus:outline-none focus-visible:outline-none disabled:opacity-50 disabled:cursor-not-allowed resize-y px-4 py-2.5 text-base 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 resize-y px-3 py-2 text-sm max-sm:text-base leading-6';
 
-        return `${baseClasses} ${variantClass()} ${className}`.trim();
+        return cn(`${baseClasses} ${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-1.5 text-sm text-error';
-        } else if (variant === 'success') {
-            return 'mt-1 flex items-center gap-1.5 text-sm text-success';
-        } else if (variant === 'warning') {
-            return 'mt-1 flex items-center gap-1.5 text-sm text-warning';
-        }
-        return 'mt-1 flex items-center gap-1.5 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;
@@ -105,10 +130,10 @@
             {rows}
             class={textareaClasses()}
             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={fieldDescribedBy(textareaId, status, describedBy)}
             {...restProps}
         ></textarea>
         {#if loading}
@@ -117,23 +142,10 @@
                 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}
+    <FieldMessages fieldId={textareaId} {status} {hint} gap="mt-1" />
 </div>

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

@@ -1,5 +1,10 @@
+import type { HTMLTextareaAttributes } from 'svelte/elements';
 import type { SemanticVariant, SizeVariant } from '../types/variants.js';
-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;
@@ -13,9 +18,16 @@ interface Props {
     rows?: 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;
     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,85 +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";
-    
-    function safeLocalStorage(): Storage | undefined {
-        return typeof window !== "undefined" ? localStorage : undefined;
-    }
-
-    function safeDocument(): Document | undefined {
-        return typeof window !== "undefined" ? document : undefined;
-    }
+    import { cn } from "../util/cn.js";
+    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");
-        }
-        
-        if (onclick) {
-            (onclick as (event: Event) => void)(event);
-        }
+        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") {
@@ -89,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
             };
         }
@@ -97,20 +263,20 @@
 
     const variantClass = $derived(() => {
         if (variant === "ghost") {
-            return "bg-transparent hover:bg-base-100 active:bg-base-200 border-0";
+            return "bg-transparent hover:bg-surface-hover active:bg-surface-active border-0";
         } else if (variant === "outline") {
-            return "bg-base-50 hover:bg-base-100 active:bg-base-200 border border-border";
+            return "bg-action-secondary hover:bg-action-secondary-hover active:bg-action-secondary-active border border-border";
         } else {
-            return "bg-base-50 hover:bg-base-100 active:bg-base-200 border-0";
+            return "bg-action-secondary hover:bg-action-secondary-hover active:bg-action-secondary-active border-0";
         }
     });
 
     const buttonClasses = $derived(() => {
         const sizeStyles = sizeClass();
-        return `
+        return cn(`
             ${sizeStyles.button}
             ${variantClass()}
-            rounded-lg
+            rounded-control
             flex
             items-center
             justify-center
@@ -122,23 +288,26 @@
             disabled:opacity-50
             disabled:cursor-not-allowed
             disabled:active:scale-100
-            disabled:hover:bg-base-50
+            disabled:hover:bg-action-disabled
             ${FOCUS_BRAND_CLASS}
-        `.trim().replace(/\s+/g, " ");
+        `).replace(/\s+/g, " ");
     });
 </script>
 
 {#if mounted}
     <button
         onclick={toggleTheme}
-        class={buttonClasses()}
-        aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
-        aria-pressed={isDark}
+        class="{buttonClasses()} {className}"
+        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" />
@@ -146,12 +315,25 @@
     </button>
 {:else}
     <button
-        class="w-10 h-10 bg-base-50 rounded-lg flex items-center justify-center text-label cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
-        aria-label="Theme toggle"
+        class="{sizeClass().button} {variantClass()} rounded-control flex items-center justify-center text-label cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+        aria-label={text.beforeMount}
         type="button"
         {disabled}
         {...restProps}
     >
-        <Sun size={20} 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}

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

@@ -1,9 +1,34 @@
-interface Props {
+import type { HTMLButtonAttributes } from "svelte/elements";
+import { type ThemeMode, type ThemeToggleLabels } from "../util/theme-mode.js";
+/** 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;
-}
-declare const ThemeToggle: import("svelte").Component<Props, {}, "">;
+};
+declare const ThemeToggle: import("svelte").Component<Props, {}, "mode">;
 type ThemeToggle = ReturnType<typeof ThemeToggle>;
 export default ThemeToggle;