@spaethtech/svelte-ui 0.21.1-dev.116.7683168 → 0.21.1-dev.117.092ebb0

package/dist/components/ThemeToggle.svelte

@@ -1,11 +1,22 @@
 <script lang="ts">
   /**
    * ThemeToggle — an icon button that flips between light and dark, sibling to `ThemeSelector`.
-   * Shares the same persisted state (`svelte-ui-theme` in localStorage, applied to `<html>`), so the
-   * two stay in sync. When nothing is stored it follows the system preference; the icon reflects the
-   * effective theme (☀ light / ☾ dark), and a click sets the explicit opposite.
+   *
+   * Two ways to use it:
+   *  - **Self-managed (default)** — reads/writes `localStorage` (`svelte-ui-theme`), applies the
+   *    `<html>` class, and toggles on click. JS-only; shares state with `ThemeSelector`.
+   *  - **Form-owned (`type="submit"` / `"reset"`)** — attaches NO click handler and does NOT touch
+   *    `localStorage` or `<html>`; `type`/`name`/`value` forward to the native `<button>` so a
+   *    surrounding `<form>` owns the change. Works with JS off and before hydration.
+   *
+   * The icon is always chosen by **CSS** from the applied `<html>` theme class (`.theme-light` /
+   * `.theme-dark`, plus the system preference for "auto"), NOT from JS state — so it's correct in
+   * SSR, before hydration, and with JS off. The accessible name is a static `aria-label` (also
+   * correct in SSR); `aria-pressed` is a hydrated enhancement in self-managed mode.
    */
   import Button from "./Button.svelte";
+  import { uiI18n } from "../i18n.js";
+  const i18n = uiI18n();
   import type { Size } from "../types/sizes.js";
   import type { Variant } from "../types/variants.js";
   import type { Responsive } from "../types/responsive.js";
@@ -18,19 +29,28 @@
   let {
     size = "md",
     variant = "ghost",
+    type = "button",
     ...rest
-  }: { size?: Responsive<Size>; variant?: Variant } & Omit<HTMLButtonAttributes, "class"> =
-    $props();
+  }: {
+    size?: Responsive<Size>;
+    variant?: Variant;
+  } & Omit<HTMLButtonAttributes, "class"> = $props();
+
+  // Self-managed only when it's a plain button. A submit/reset button is form-owned: no localStorage,
+  // no <html> apply, no click toggle — the consumer's <form> handles the change (JS-off friendly).
+  const managed = $derived(type !== "submit" && type !== "reset");
 
   // The stored value ("auto" until the user picks) and the tracked system preference.
   let theme = $state<ThemeValue>("auto");
   let system = $state<"light" | "dark">("light");
 
-  // The theme actually showing — "auto" resolved against the system preference.
+  // The theme actually showing — "auto" resolved against the system preference. Used only for
+  // `aria-pressed` (the visible icon is CSS-driven); meaningful only in self-managed mode.
   const effective = $derived(theme === "auto" ? system : theme);
 
-  // Load stored theme + track the system preference (so the icon stays right in "auto" mode).
+  // Load stored theme + track the system preference — self-managed mode only.
   $effect(() => {
+    if (!managed) return;
     theme = readStoredTheme();
     system = resolveTheme("auto");
     const mq = window.matchMedia("(prefers-color-scheme: dark)");
@@ -39,8 +59,9 @@
     return () => mq.removeEventListener("change", onChange);
   });
 
-  // Apply (and persist) whenever the theme changes.
+  // Apply (and persist) whenever the theme changes — self-managed mode only.
   $effect(() => {
+    if (!managed) return;
     applyTheme(theme);
   });
 
@@ -50,17 +71,44 @@
   }
 </script>
 
-<!-- rest is fully typed on this component's own Props (below); the cast only sidesteps a TS
-     "union too complex" limit when spreading a wide attrs type into Button's ButtonProps|AnchorProps. -->
+<!-- rest is fully typed on this component's own Props (above); the cast only sidesteps a TS
+     "union too complex" limit when spreading a wide attrs type into Button's ButtonProps|AnchorProps.
+     In form-owned mode the consumer's own `onclick` (if any) is preserved; otherwise we toggle. -->
 <Button
-  {...rest as Record<string, unknown>}
+  {...(managed ? { ...rest, onclick: toggle } : rest) as Record<string, unknown>}
   {size}
   {variant}
-  onclick={toggle}
-  aria-pressed={effective === "dark"}
-  title={effective === "dark" ? "Switch to light theme" : "Switch to dark theme"}
+  {type}
+  aria-pressed={managed ? effective === "dark" : undefined}
+  aria-label={i18n.messages.toggleTheme}
+  title={i18n.messages.toggleTheme}
 >
   {#snippet icon()}
-    {#if effective === "dark"}<IconMoon />{:else}<IconSun />{/if}
+    <span class="ui-theme-toggle-sun"><IconSun /></span><span class="ui-theme-toggle-moon"
+      ><IconMoon /></span
+    >
   {/snippet}
 </Button>
+
+<style>
+  /* The visible icon tracks the APPLIED theme (the <html> class) + the system preference for "auto",
+     so it's right in SSR / before hydration / with JS off — never from JS state. Mirrors theme.css:
+     `.theme-light`/`.theme-dark` force a theme; no class → the prefers-color-scheme media query. */
+  .ui-theme-toggle-moon {
+    display: none;
+  }
+  :global(:root.theme-dark) .ui-theme-toggle-sun {
+    display: none;
+  }
+  :global(:root.theme-dark) .ui-theme-toggle-moon {
+    display: contents;
+  }
+  @media (prefers-color-scheme: dark) {
+    :global(:root:not(.theme-light)) .ui-theme-toggle-sun {
+      display: none;
+    }
+    :global(:root:not(.theme-light)) .ui-theme-toggle-moon {
+      display: contents;
+    }
+  }
+</style>

package/dist/i18n.d.ts

@@ -15,6 +15,8 @@ export type UiMessages = {
     copyToClipboard: Msg;
     done: Msg;
     noResults: Msg;
+    /** ThemeToggle accessible name (static, SSR-correct) — also its tooltip. */
+    toggleTheme: Msg;
     /** DataTable empty-state while the source is still arriving. */
     loading: Msg;
     /** DataTable empty-state when the fetch result carries a non-string error. */

package/dist/i18n.js

@@ -16,6 +16,7 @@ export const defaultUiMessages = {
     copyToClipboard: "Copy to clipboard",
     done: "Done",
     noResults: "No results",
+    toggleTheme: "Toggle light/dark theme",
     loading: "Loading…",
     loadFailed: "Failed to load",
     previous: "Previous",

package/docs/components.md

@@ -685,9 +685,27 @@ Compact icon-button sibling of `ThemeSelector` — flips light ⇄ dark (☀ /
 
 - **Location**: `src/lib/components/ThemeToggle.svelte`
 - **Axes**: `size`, `variant` (default `ghost`)
-- **Features**: shares `ThemeSelector`'s state (same `localStorage` key + `<html>` application, via
-  `src/lib/components/theme.ts`), follows the system preference until first toggled, icon reflects the
-  effective theme
+- **Self-managed (default)**: shares `ThemeSelector`'s state (same `localStorage` key + `<html>`
+  application, via `src/lib/components/theme.ts`), follows the system preference until first toggled,
+  and toggles on click.
+- **Form-owned mode (`type="submit"` / `"reset"`)**: attaches **no** click handler and does **not**
+  touch `localStorage` or `<html>`; `type`/`name`/`value` forward to the native `<button>` so a
+  surrounding `<form>` owns the change. Works with **JS off** and before hydration (a consumer's own
+  `onclick`, if passed, is preserved).
+- **SSR-correct icon**: the visible icon is chosen by **CSS** from the applied `<html>` theme class
+  (`.theme-light`/`.theme-dark`, plus `prefers-color-scheme` for "auto") — not from JS state — so
+  light/dark/system-dark users get the right icon on first paint, before hydration, and with JS off.
+- **Accessible name**: a static `aria-label` (localized `toggleTheme`, "Toggle light/dark theme") that
+  is correct in SSR; `aria-pressed` is a hydrated enhancement in self-managed mode. (Note: `Button`'s
+  `title` drives the client **tooltip** action, not an SSR attribute — use `aria-label` for the name,
+  as this does.)
+
+```svelte
+<!-- Form-owned (works with JS off): a preference <form> posts the change, ThemeToggle is just the button -->
+<form method="POST" action="/preference"><ThemeToggle type="submit" name="theme" /></form>
+<!-- Self-managed (JS): localStorage + <html>, toggles on click -->
+<ThemeToggle />
+```
 
 ## Import Pattern
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.21.1-dev.116.7683168",
+  "version": "0.21.1-dev.117.092ebb0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"