@spaethtech/svelte-ui 0.4.1-dev.13.042fac9 → 0.4.1-dev.16.e97ba4d

package/.claude/skills/svelte-ui/SKILL.md

@@ -101,13 +101,15 @@ examples):
 - **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
   (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`).
-- **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` accept any CSS value)
-  · `ConfirmDialog` (title + message + Confirm/Cancel, built on Dialog) · `Popup` `Menu` ·
-  `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
+- **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` take any CSS value;
+  `onShow(ctx)`/`onHide(ctx)` control focus — set `ctx.autoFocus` to a selector/element/`false`,
+  `ctx.restoreFocus` likewise) · `ConfirmDialog` (title + message + Confirm/Cancel, built on Dialog)
+  · `Popup` `Menu` · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
 - **Navigation:** `TabStrip` `SideBarMenu`
 - **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast`
 - **Layout:** `Card` `CardHeader` `CardBody` `CardFooter`
-- **Display / theme:** `NotesEditor` `ThemeSelector`
+- **Display / theme:** `NotesEditor` · `ThemeSelector` (Auto/Light/Dark Select) · `ThemeToggle`
+  (compact ☀/☾ icon button, same persisted state)
 - **Types / utils:** `Variant` `Size` `TabDefinition` (types), `responsiveClasses` / `resolveScalar`,
   `BREAKPOINT_PX`.
 

package/dist/components/ConfirmDialog.svelte

@@ -4,7 +4,7 @@
   import CardHeader from "./CardHeader.svelte";
   import CardFooter from "./CardFooter.svelte";
   import Button from "./Button.svelte";
-  import type { Snippet } from "svelte";
+  import type { ComponentProps, Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import type { Responsive } from "../types/responsive.js";
 
@@ -32,6 +32,9 @@
     /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
     width?: string;
     height?: string;
+    /** Forwarded to the Dialog shell — open/close hooks with the `autoFocus`/`restoreFocus` knobs. */
+    onShow?: ComponentProps<typeof Dialog>["onShow"];
+    onHide?: ComponentProps<typeof Dialog>["onHide"];
     /** Custom body between header and footer (replaces `message`). */
     children?: Snippet;
   }
@@ -51,6 +54,8 @@
     dismissible = true,
     width,
     height,
+    onShow,
+    onHide,
     children,
   }: Props = $props();
 
@@ -69,6 +74,8 @@
   {dismissible}
   {width}
   {height}
+  {onShow}
+  {onHide}
   onClose={onCancel}
   aria-label={title}
 >

package/dist/components/ConfirmDialog.svelte.d.ts

@@ -1,4 +1,5 @@
-import type { Snippet } from "svelte";
+import Dialog from "./Dialog.svelte";
+import type { ComponentProps, Snippet } from "svelte";
 import type { Size } from "../types/sizes.js";
 import type { Responsive } from "../types/responsive.js";
 /**
@@ -25,6 +26,9 @@ interface Props {
     /** Forwarded to the Dialog shell — any CSS value (default: content-sized, capped at 32rem). */
     width?: string;
     height?: string;
+    /** Forwarded to the Dialog shell — open/close hooks with the `autoFocus`/`restoreFocus` knobs. */
+    onShow?: ComponentProps<typeof Dialog>["onShow"];
+    onHide?: ComponentProps<typeof Dialog>["onHide"];
     /** Custom body between header and footer (replaces `message`). */
     children?: Snippet;
 }

package/dist/components/Dialog.svelte

@@ -11,7 +11,27 @@
    *
    * `width` / `height` accept any CSS length: `"80%"`, `"80vw"`, `"60vh"`, `"400px"`, … (both default
    * to content size, capped to the viewport minus a 1rem inset so the panel never runs off-screen).
+   *
+   * `onShow` / `onHide` fire on open / close. Each hands you a mutable focus knob preset to the
+   * default, so a handler that ignores it keeps built-in behavior:
+   *   onShow(ctx):  ctx.autoFocus is the default focusable selector — set a selector/element to focus
+   *                 something specific, or `false` to skip (focus stays on the panel).
+   *   onHide(ctx):  ctx.restoreFocus is the element focused before open — set `false` to skip
+   *                 restoration, or another element to focus on close.
    */
+  interface DialogShowContext {
+    /** The panel element (already mounted). */
+    panel: HTMLElement;
+    /** What to focus on open — preset to the default focusable selector. Set a CSS selector or an
+     *  element to focus something specific, or `false` to skip autofocus (focus stays on the panel). */
+    autoFocus: string | HTMLElement | false;
+  }
+  interface DialogHideContext {
+    /** Where focus returns on close — preset to the element focused before the dialog opened. Set
+     *  `false` to skip restoration, or another element to focus instead. */
+    restoreFocus: HTMLElement | null | false;
+  }
+
   interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
@@ -23,6 +43,12 @@
     dismissible?: boolean;
     /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
     onClose?: () => void;
+    /** Fires on open (after mount). `ctx.autoFocus` (default = the focusable selector) controls what
+     *  gets focused; mutate it to retarget or set `false` to skip. */
+    onShow?: (ctx: DialogShowContext) => void;
+    /** Fires on close. `ctx.restoreFocus` (default = the pre-open element) controls focus return;
+     *  mutate it to retarget or set `false` to skip. */
+    onHide?: (ctx: DialogHideContext) => void;
     /** Extra classes on the panel wrapper. */
     class?: string;
     children?: Snippet;
@@ -34,6 +60,8 @@
     height,
     dismissible = true,
     onClose,
+    onShow,
+    onHide,
     class: cls = "",
     children,
     ...rest
@@ -66,16 +94,27 @@
     };
   });
 
-  // Focus management: on open, remember what was focused and move focus into the panel; on close,
-  // restore it. (Tab-wrapping is handled in onKeydown.)
+  // Focus management. On open: remember what was focused, fire `onShow`, then focus per
+  // `ctx.autoFocus` (default = first focusable). On close: fire `onHide`, then restore per
+  // `ctx.restoreFocus` (default = the pre-open element). (Tab-wrapping is handled in onKeydown.)
   $effect(() => {
     if (!isOpen) return;
     previouslyFocused = document.activeElement as HTMLElement | null;
     queueMicrotask(() => {
-      const first = panelEl?.querySelector<HTMLElement>(FOCUSABLE);
-      (first ?? panelEl)?.focus();
+      if (!panelEl) return;
+      const ctx: DialogShowContext = { panel: panelEl, autoFocus: FOCUSABLE };
+      onShow?.(ctx);
+      let target: HTMLElement | null;
+      if (ctx.autoFocus === false) target = panelEl;
+      else if (ctx.autoFocus instanceof HTMLElement) target = ctx.autoFocus;
+      else target = panelEl.querySelector<HTMLElement>(ctx.autoFocus) ?? panelEl;
+      target?.focus();
     });
-    return () => previouslyFocused?.focus?.();
+    return () => {
+      const ctx: DialogHideContext = { restoreFocus: previouslyFocused };
+      onHide?.(ctx);
+      if (ctx.restoreFocus) ctx.restoreFocus.focus?.();
+    };
   });
 
   const panelStyle = $derived(

package/dist/components/Dialog.svelte.d.ts

@@ -9,7 +9,26 @@ import type { HTMLAttributes } from "svelte/elements";
  *
  * `width` / `height` accept any CSS length: `"80%"`, `"80vw"`, `"60vh"`, `"400px"`, … (both default
  * to content size, capped to the viewport minus a 1rem inset so the panel never runs off-screen).
+ *
+ * `onShow` / `onHide` fire on open / close. Each hands you a mutable focus knob preset to the
+ * default, so a handler that ignores it keeps built-in behavior:
+ *   onShow(ctx):  ctx.autoFocus is the default focusable selector — set a selector/element to focus
+ *                 something specific, or `false` to skip (focus stays on the panel).
+ *   onHide(ctx):  ctx.restoreFocus is the element focused before open — set `false` to skip
+ *                 restoration, or another element to focus on close.
  */
+interface DialogShowContext {
+    /** The panel element (already mounted). */
+    panel: HTMLElement;
+    /** What to focus on open — preset to the default focusable selector. Set a CSS selector or an
+     *  element to focus something specific, or `false` to skip autofocus (focus stays on the panel). */
+    autoFocus: string | HTMLElement | false;
+}
+interface DialogHideContext {
+    /** Where focus returns on close — preset to the element focused before the dialog opened. Set
+     *  `false` to skip restoration, or another element to focus instead. */
+    restoreFocus: HTMLElement | null | false;
+}
 interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     /** Whether the dialog is shown (bindable). */
     isOpen: boolean;
@@ -21,6 +40,12 @@ interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
     dismissible?: boolean;
     /** Called when dismissed via backdrop / Escape (isOpen is also set false). */
     onClose?: () => void;
+    /** Fires on open (after mount). `ctx.autoFocus` (default = the focusable selector) controls what
+     *  gets focused; mutate it to retarget or set `false` to skip. */
+    onShow?: (ctx: DialogShowContext) => void;
+    /** Fires on close. `ctx.restoreFocus` (default = the pre-open element) controls focus return;
+     *  mutate it to retarget or set `false` to skip. */
+    onHide?: (ctx: DialogHideContext) => void;
     /** Extra classes on the panel wrapper. */
     class?: string;
     children?: Snippet;

package/dist/components/ThemeSelector.svelte

@@ -3,6 +3,7 @@
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import type { Variant } from "../types/variants.js";
+  import { applyTheme, readStoredTheme, type ThemeValue } from "./theme.js";
 
   // Shared axes, forwarded to the underlying Select (and the label text tracks size).
   let { size = "md", variant }: { size?: Responsive<Size>; variant?: Variant } = $props();
@@ -15,54 +16,18 @@
     { label: "Dark", value: "dark" },
   ];
 
-  const themeClasses = {
-    light: "theme-light",
-    dark: "theme-dark",
-  };
-
+  // Shared theme state (localStorage-backed, applied to <html>) — see ./theme.ts. Kept as a plain
+  // string for the Select `bind:value`; the values are constrained to the options above.
   let selectedTheme = $state("auto");
 
-  // Load saved theme on mount
+  // Load the saved theme on mount (defaults to "auto" when nothing is stored).
   $effect(() => {
-    if (typeof window !== "undefined") {
-      const savedTheme = localStorage.getItem("svelte-ui-theme");
-      if (savedTheme && options.some((opt) => opt.value === savedTheme)) {
-        selectedTheme = savedTheme;
-      }
-    }
+    selectedTheme = readStoredTheme();
   });
 
-  // Apply theme to <html> (documentElement) — NOT <body>.
-  // The theme tokens (incl. --ui-color-hover/active) are defined at :root, and app.html's pre-hydration
-  // script forces the class onto <html>. If we applied it to <body> instead, <html> would stay on the
-  // system @media(prefers-color-scheme) path, so tokens that reference other tokens (--ui-color-hover =
-  // color-mix(var(--ui-color-text)…)) would resolve against the WRONG theme at :root and inherit down
-  // stale (e.g. a white hover-tint on a light page → invisible hover). Keep the class on :root.
-  function applyTheme(themeValue: string) {
-    const body = document.body;
-    const html = document.documentElement;
-
-    // Remove all existing theme classes from both body and html (clear any stray body class too)
-    Object.values(themeClasses).forEach((className) => {
-      body.classList.remove(className);
-      html.classList.remove(className);
-    });
-
-    // Add the selected theme class to <html>
-    const themeClass = themeClasses[themeValue as keyof typeof themeClasses];
-    if (themeClass) {
-      html.classList.add(themeClass);
-    }
-
-    // Save theme to localStorage
-    if (typeof window !== "undefined") {
-      localStorage.setItem("svelte-ui-theme", themeValue);
-    }
-  }
-
-  // Apply theme when selection changes
+  // Apply (and persist) whenever the selection changes.
   $effect(() => {
-    applyTheme(selectedTheme);
+    applyTheme(selectedTheme as ThemeValue);
   });
 </script>
 

package/dist/components/ThemeToggle.svelte

@@ -0,0 +1,57 @@
+<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.
+   */
+  import Button from "./Button.svelte";
+  import type { Size } from "../types/sizes.js";
+  import type { Variant } from "../types/variants.js";
+  import type { Responsive } from "../types/responsive.js";
+  import { applyTheme, readStoredTheme, resolveTheme, type ThemeValue } from "./theme.js";
+  import IconSun from "~icons/mdi/weather-sunny";
+  import IconMoon from "~icons/mdi/weather-night";
+
+  // Shared axes, forwarded to the underlying Button. Icon-only, so it defaults to the chromeless ghost.
+  let { size = "md", variant = "ghost" }: { size?: Responsive<Size>; variant?: Variant } = $props();
+
+  // 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.
+  const effective = $derived(theme === "auto" ? system : theme);
+
+  // Load stored theme + track the system preference (so the icon stays right in "auto" mode).
+  $effect(() => {
+    theme = readStoredTheme();
+    system = resolveTheme("auto");
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = (e: MediaQueryListEvent) => (system = e.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  });
+
+  // Apply (and persist) whenever the theme changes.
+  $effect(() => {
+    applyTheme(theme);
+  });
+
+  // Flip to the explicit opposite of whatever is currently in effect.
+  function toggle() {
+    theme = effective === "dark" ? "light" : "dark";
+  }
+</script>
+
+<Button
+  {size}
+  {variant}
+  onclick={toggle}
+  aria-pressed={effective === "dark"}
+  title={effective === "dark" ? "Switch to light theme" : "Switch to dark theme"}
+>
+  {#snippet icon()}
+    {#if effective === "dark"}<IconMoon />{:else}<IconSun />{/if}
+  {/snippet}
+</Button>

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

@@ -0,0 +1,10 @@
+import type { Size } from "../types/sizes.js";
+import type { Variant } from "../types/variants.js";
+import type { Responsive } from "../types/responsive.js";
+type $$ComponentProps = {
+    size?: Responsive<Size>;
+    variant?: Variant;
+};
+declare const ThemeToggle: import("svelte").Component<$$ComponentProps, {}, "">;
+type ThemeToggle = ReturnType<typeof ThemeToggle>;
+export default ThemeToggle;

package/dist/components/theme.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared theme state — single source for the persisted theme, used by `ThemeSelector` and
+ * `ThemeToggle` so the localStorage key, the `<html>` class application, and system detection can't
+ * drift between them.
+ */
+export declare const THEME_STORAGE_KEY = "svelte-ui-theme";
+export type ThemeValue = "auto" | "light" | "dark";
+/** The saved theme, or `"auto"` when nothing valid is stored (or on the server). */
+export declare function readStoredTheme(): ThemeValue;
+/** The OS/browser preference, used to resolve `"auto"` to a concrete light/dark. */
+export declare function systemTheme(): "light" | "dark";
+/** The concrete theme in effect — `"auto"` resolved against the system preference. */
+export declare function resolveTheme(value: ThemeValue): "light" | "dark";
+/**
+ * Apply a theme to `<html>` (documentElement) — NOT `<body>` — and persist it.
+ * The tokens (incl. --ui-color-hover/active, which color-mix from other tokens) are defined at
+ * `:root`; app.html's pre-hydration script forces the class onto `<html>`. Applying it to `<body>`
+ * instead would leave `<html>` on the system `@media(prefers-color-scheme)` path, so token-references
+ * would resolve against the WRONG theme at `:root` and inherit down stale (e.g. a white hover-tint on
+ * a light page → invisible hover). Keep the class on `:root`. `"auto"` clears both classes so the
+ * `@media` path takes over.
+ */
+export declare function applyTheme(value: ThemeValue): void;

package/dist/components/theme.js

@@ -0,0 +1,49 @@
+/**
+ * Shared theme state — single source for the persisted theme, used by `ThemeSelector` and
+ * `ThemeToggle` so the localStorage key, the `<html>` class application, and system detection can't
+ * drift between them.
+ */
+export const THEME_STORAGE_KEY = "svelte-ui-theme";
+const THEME_CLASSES = {
+    light: "theme-light",
+    dark: "theme-dark",
+};
+/** The saved theme, or `"auto"` when nothing valid is stored (or on the server). */
+export function readStoredTheme() {
+    if (typeof window === "undefined")
+        return "auto";
+    const v = localStorage.getItem(THEME_STORAGE_KEY);
+    return v === "light" || v === "dark" || v === "auto" ? v : "auto";
+}
+/** The OS/browser preference, used to resolve `"auto"` to a concrete light/dark. */
+export function systemTheme() {
+    if (typeof window === "undefined")
+        return "light";
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+/** The concrete theme in effect — `"auto"` resolved against the system preference. */
+export function resolveTheme(value) {
+    return value === "auto" ? systemTheme() : value;
+}
+/**
+ * Apply a theme to `<html>` (documentElement) — NOT `<body>` — and persist it.
+ * The tokens (incl. --ui-color-hover/active, which color-mix from other tokens) are defined at
+ * `:root`; app.html's pre-hydration script forces the class onto `<html>`. Applying it to `<body>`
+ * instead would leave `<html>` on the system `@media(prefers-color-scheme)` path, so token-references
+ * would resolve against the WRONG theme at `:root` and inherit down stale (e.g. a white hover-tint on
+ * a light page → invisible hover). Keep the class on `:root`. `"auto"` clears both classes so the
+ * `@media` path takes over.
+ */
+export function applyTheme(value) {
+    if (typeof document === "undefined")
+        return;
+    const { body, documentElement: html } = document;
+    Object.values(THEME_CLASSES).forEach((className) => {
+        body.classList.remove(className);
+        html.classList.remove(className);
+    });
+    if (value === "light" || value === "dark")
+        html.classList.add(THEME_CLASSES[value]);
+    if (typeof window !== "undefined")
+        localStorage.setItem(THEME_STORAGE_KEY, value);
+}

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export { default as TimeSpinner } from "./components/TimeSpinner.svelte";
 export { default as TimePicker } from "./components/TimePicker.svelte";
 export { default as TimeRangeInput } from "./components/TimeRangeInput.svelte";
 export { default as ThemeSelector } from "./components/ThemeSelector.svelte";
+export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";
 export { default as Checkbox } from "./components/Checkbox.svelte";

package/dist/index.js

@@ -32,6 +32,7 @@ export { default as TimePicker } from "./components/TimePicker.svelte";
 export { default as TimeRangeInput } from "./components/TimeRangeInput.svelte";
 // Theme Components
 export { default as ThemeSelector } from "./components/ThemeSelector.svelte";
+export { default as ThemeToggle } from "./components/ThemeToggle.svelte";
 // Utility Components
 export { default as Popup } from "./components/Popup.svelte";
 export { default as Menu } from "./components/Menu.svelte";

package/docs/components.md

@@ -148,8 +148,13 @@ dialog.
 - **Location**: `src/lib/components/Dialog.svelte`
 - **Props**: `isOpen` (bindable), `width` (any CSS value — `'80%'`, `'80vw'`, `'400px'`; default
   auto, capped at `min(32rem, …)`), `height` (any CSS value; default auto), `dismissible` (default
-  `true`), `onClose`, `class`, `children` (snippet). Extra attributes (e.g. `aria-label`) spread onto
-  the panel.
+  `true`), `onClose`, `onShow`, `onHide`, `class`, `children` (snippet). Extra attributes (e.g.
+  `aria-label`) spread onto the panel.
+- **Focus control**: `onShow(ctx)` fires on open — `ctx.autoFocus` is preset to the default focusable
+  selector; set it to a **CSS selector / element** to focus something specific, or **`false`** to
+  skip (focus stays on the panel). `onHide(ctx)` mirrors it with `ctx.restoreFocus` (preset to the
+  pre-open element; set `false` to skip restoring focus, or another element). A handler that ignores
+  the knob keeps the built-in behavior.
 - **Features**: portals to `<body>`, background scroll-lock (scrollbar-width compensated), backdrop
   + Escape dismiss, **focus trap** (initial focus in, Tab wraps, focus restored on close),
   `role="dialog"` + `aria-modal`.
@@ -162,7 +167,8 @@ shell.
 - **Location**: `src/lib/components/ConfirmDialog.svelte`
 - **Props**: `isOpen` (bindable), `title`, `message`, `confirmText`, `cancelText`, `onConfirm`,
   `onCancel`, `variant` (`'normal' | 'danger'`), `size`, `showConfirm`, `showCancel`, `dismissible`,
-  `width`/`height` (forwarded to the shell), `children` (snippet — replaces `message` as the body).
+  `width`/`height`/`onShow`/`onHide` (forwarded to the shell), `children` (snippet — replaces
+  `message` as the body).
 
 ### Popup
 
@@ -225,9 +231,20 @@ Status indicator / label.
 Theme switcher (Auto / Light / Dark), built on `Select`.
 
 - **Location**: `src/lib/components/ThemeSelector.svelte`
-- **Features**: applies `.theme-light` / `.theme-dark` to `<html>`/`<body>`, `auto` follows the
+- **Axes**: `size`, `variant` (forwarded to the Select)
+- **Features**: applies `.theme-light` / `.theme-dark` to `<html>`, `auto` follows the
   system preference, persists to `localStorage` (`svelte-ui-theme`)
 
+### ThemeToggle
+
+Compact icon-button sibling of `ThemeSelector` — flips light ⇄ dark (☀ / ☾), built on `Button`.
+
+- **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
+
 ## Import Pattern
 
 ```typescript

package/docs/usage.md

@@ -273,6 +273,21 @@ with `width` / `height` (any CSS value).
 </Dialog>
 ```
 
+**Controlling focus.** The shell focuses the first focusable element on open and restores focus on
+close. Override via `onShow` / `onHide` — each hands you a mutable knob (default preserved if you
+ignore it):
+
+```svelte
+<Dialog
+  bind:isOpen={open}
+  onShow={(ctx) => (ctx.autoFocus = "[data-focus-me]")}
+  onHide={(ctx) => (ctx.restoreFocus = false)}
+>
+  <!-- ctx.autoFocus: CSS selector | element | false (skip). Default = first focusable. -->
+  <!-- ctx.restoreFocus: element | false (skip). Default = the element focused before open.  -->
+</Dialog>
+```
+
 ### Badge
 
 ```svelte
@@ -439,12 +454,16 @@ See the live demo for the full DataTable + Query walkthrough — http://localhos
 </style>
 ```
 
-### Theme Selector
+### Theme Selector / Toggle
 
 ```svelte
 <script>
-  import { ThemeSelector } from "@spaethtech/svelte-ui";
+  import { ThemeSelector, ThemeToggle } from "@spaethtech/svelte-ui";
 </script>
 
+<!-- Full Auto/Light/Dark dropdown -->
 <ThemeSelector />
+
+<!-- Compact ☀/☾ icon toggle (light ⇄ dark) — same persisted state, follows system until toggled -->
+<ThemeToggle />
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.4.1-dev.13.042fac9",
+  "version": "0.4.1-dev.16.e97ba4d",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"