@lyeve-labs/ui-kit 0.8.2

package/dist/components/dialog/dialog-manager.svelte.js

@@ -0,0 +1,164 @@
+/**
+ * Dialog Manager - module-level Svelte 5 reactive state.
+ *
+ * Manages a stack of dialogs. Dialogs render in last-to-first order (newest on top).
+ * Each dialog returns a Promise that resolves/rejects when closed.
+ *
+ * Usage:
+ *   import { openDialog } from '@lyeve/ui-kit';
+ *   // Inside a .svelte.ts file or $effect:
+ *   const result = await openDialog({ title: 'Delete?', body: mySnippet, size: 'sm' });
+ *
+ * For confirm/cancel pattern:
+ *   import { confirm } from '@lyeve/ui-kit';
+ *   const ok = await confirm('Delete this item?', 'This action cannot be undone.');
+ *   if (ok) { /* ... *\/ }
+ */
+// ──────────────────────────────────────────────────────────
+// Module-level reactive state
+// ──────────────────────────────────────────────────────────
+let idCounter = 0;
+/** Reactive stack - topmost dialog = last element */
+let stack = $state([]);
+// ──────────────────────────────────────────────────────────
+// Body scroll lock (counter-based - handles stacked dialogs)
+// ──────────────────────────────────────────────────────────
+let bodyLockCount = 0;
+export function _lockBodyScroll() {
+    bodyLockCount++;
+    if (typeof document !== 'undefined') {
+        document.body.style.overflow = 'hidden';
+    }
+}
+export function _unlockBodyScroll() {
+    bodyLockCount--;
+    if (bodyLockCount <= 0) {
+        bodyLockCount = 0;
+        if (typeof document !== 'undefined') {
+            document.body.style.overflow = '';
+        }
+    }
+}
+/** Readonly snapshot for components */
+export function getDialogStack() {
+    return stack;
+}
+// ──────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────
+/**
+ * Open a new dialog. Returns a promise that resolves when the dialog is closed
+ * (via closeDialog with a value) or rejects if dismissed without a value.
+ *
+ * The dialog is pushed onto the stack and becomes the topmost.
+ */
+export function openDialog(options) {
+    const id = options.id ?? `dialog-${++idCounter}`;
+    return new Promise((resolve, reject) => {
+        const entry = {
+            id,
+            options: { ...options, id },
+            resolve,
+            reject,
+            depth: stack.length,
+        };
+        stack = [...stack, entry];
+        // Update depths for all entries (each re-renders because depth is in state)
+        for (let i = 0; i < stack.length; i++) {
+            stack[i].depth = i;
+        }
+    });
+}
+/**
+ * Close a dialog by id and resolve its promise with a value.
+ * If omitted, closes the topmost dialog.
+ */
+export function closeDialog(value, id) {
+    const targetId = id ?? stack[stack.length - 1]?.id;
+    if (!targetId)
+        return;
+    const idx = stack.findIndex((e) => e.id === targetId);
+    if (idx === -1)
+        return;
+    const entry = stack[idx];
+    const options = entry.options;
+    // Respect onClose guard
+    if (options.onClose) {
+        const allowed = options.onClose();
+        if (allowed === false)
+            return;
+    }
+    // Remove from stack
+    stack = stack.filter((e) => e.id !== targetId);
+    // Resolve the promise
+    entry.resolve(value);
+    // Update depths
+    for (let i = 0; i < stack.length; i++) {
+        stack[i].depth = i;
+    }
+}
+/**
+ * Dismiss (cancel) a dialog - rejects the promise.
+ * Called when user clicks backdrop or presses ESC on a non-persistent dialog.
+ */
+export function dismissDialog(id) {
+    const targetId = id ?? stack[stack.length - 1]?.id;
+    if (!targetId)
+        return;
+    const idx = stack.findIndex((e) => e.id === targetId);
+    if (idx === -1)
+        return;
+    const entry = stack[idx];
+    const options = entry.options;
+    // Persistent dialogs can only be dismissed programmatically (by id)
+    if (options.persistent && !id)
+        return;
+    // Honor onClose guard (applies regardless of persistent)
+    if (options.onClose) {
+        const allowed = options.onClose();
+        if (allowed === false)
+            return;
+    }
+    stack = stack.filter((e) => e.id !== targetId);
+    // Reject the promise - caller can .catch() or let it be
+    entry.reject(new DOMException('Dialog dismissed', 'AbortError'));
+    for (let i = 0; i < stack.length; i++) {
+        stack[i].depth = i;
+    }
+}
+/**
+ * Close all open dialogs, rejecting their promises.
+ */
+export function dismissAllDialogs() {
+    const copy = [...stack];
+    stack = [];
+    bodyLockCount = 0;
+    if (typeof document !== 'undefined') {
+        document.body.style.overflow = '';
+    }
+    for (const entry of copy) {
+        entry.reject(new DOMException('All dialogs dismissed', 'AbortError'));
+    }
+}
+/**
+ * Convenience: confirm dialog.
+ * Returns `true` if user confirmed, `false` if cancelled.
+ *
+ *   const ok = await confirm('Delete item?', 'This cannot be undone.');
+ */
+export function confirm(title, message) {
+    const id = `confirm-${++idCounter}`;
+    const promise = openDialog({ id, size: 'sm', title });
+    setDialogMeta(id, { confirmTitle: title, confirmMessage: message ?? '' });
+    return promise;
+}
+/**
+ * Set metadata on a dialog entry after it's opened.
+ * Used by convenience wrappers to pass extra data without polluting DialogOptions.
+ */
+export function setDialogMeta(id, meta) {
+    const idx = stack.findIndex((e) => e.id === id);
+    if (idx === -1)
+        return;
+    stack[idx].meta = { ...stack[idx].meta, ...meta };
+}

package/dist/components/dialog/types.d.ts

@@ -0,0 +1,33 @@
+import type { Snippet } from 'svelte';
+export type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+export interface DialogOptions<T = void> {
+    /** Unique id - auto-generated if omitted */
+    id?: string;
+    /** Dialog heading */
+    title?: string | Snippet;
+    /** Main body content */
+    body?: Snippet;
+    /** Footer content (actions). If omitted and not persistent, no footer. */
+    footer?: Snippet;
+    /** Max-width preset */
+    size?: DialogSize;
+    /** If true, backdrop click and ESC won't close the dialog */
+    persistent?: boolean;
+    /** Called when dialog is about to close. Return false to prevent. */
+    onClose?: () => boolean | void;
+    /** Resolve payload - passed to closeDialog */
+    resolve?: (value: T) => void;
+    /** Reject payload - passed to closeDialog */
+    reject?: (reason?: unknown) => void;
+}
+export interface DialogEntry<T = void> {
+    id: string;
+    options: DialogOptions<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+    /** Stack position (0 = bottom, N-1 = top) */
+    depth: number;
+    /** Arbitrary data passed by convenience functions (confirm, prompt, etc.) */
+    meta?: Record<string, unknown>;
+}
+export declare function sizeClass(size: DialogSize): string;

package/dist/components/dialog/types.js

@@ -0,0 +1,10 @@
+const SIZE_CLASSES = {
+    sm: 'max-w-sm',
+    md: 'max-w-md',
+    lg: 'max-w-lg',
+    xl: 'max-w-xl',
+    full: 'max-w-3xl',
+};
+export function sizeClass(size) {
+    return SIZE_CLASSES[size];
+}

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @lyeve/ui-kit - public API.
+ *
+ * Every component, utility, and store the library exposes is re-exported
+ * from this single entry point. Consumers should import from
+ * `'@lyeve/ui-kit'` and never reach into deep paths - the directory layout
+ * is an implementation detail.
+ */
+export { default as Card } from './components/Card.svelte';
+export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as Divider } from './components/Divider.svelte';
+export { default as Accordion } from './components/Accordion.svelte';
+export { default as AccordionItem } from './components/AccordionItem.svelte';
+export { default as Table } from './components/Table.svelte';
+export { default as Button } from './components/Button.svelte';
+export { default as ButtonGroup } from './components/ButtonGroup.svelte';
+export { default as Input } from './components/Input.svelte';
+export { default as Textarea } from './components/Textarea.svelte';
+export { default as NumberInput } from './components/NumberInput.svelte';
+export { default as SearchInput } from './components/SearchInput.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as Label } from './components/Label.svelte';
+export { default as Select } from './components/Select.svelte';
+export { default as MultiSelect } from './components/MultiSelect.svelte';
+export { default as Autocomplete } from './components/Autocomplete.svelte';
+export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as Radio } from './components/Radio.svelte';
+export { default as RadioGroup } from './components/RadioGroup.svelte';
+export { default as Toggle } from './components/Toggle.svelte';
+export { default as Breadcrumb } from './components/Breadcrumb.svelte';
+export { default as Tabs } from './components/Tabs.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
+export { default as StepIndicator } from './components/StepIndicator.svelte';
+export { default as Dropdown } from './components/Dropdown.svelte';
+export { default as Modal } from './components/Modal.svelte';
+export { default as Drawer } from './components/Drawer.svelte';
+export { default as Tooltip } from './components/Tooltip.svelte';
+export { default as Alert } from './components/Alert.svelte';
+export { default as Banner } from './components/Banner.svelte';
+export { default as Badge } from './components/Badge.svelte';
+export { default as Tag } from './components/Tag.svelte';
+export { default as Indicator } from './components/Indicator.svelte';
+export { default as Progress } from './components/Progress.svelte';
+export { default as Spinner } from './components/Spinner.svelte';
+export { default as Skeleton } from './components/Skeleton.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as Kbd } from './components/Kbd.svelte';
+export { default as Avatar } from './components/Avatar.svelte';
+export { default as AvatarGroup } from './components/AvatarGroup.svelte';
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
+export { default as Toaster } from './components/Toaster.svelte';
+export { toast } from './stores/toast.svelte.js';
+export type { Toast, ToastTone } from './stores/toast.svelte.js';
+export { default as DialogContainer } from './components/dialog/DialogContainer.svelte';
+export { default as Dialog } from './components/dialog/Dialog.svelte';
+export { default as ConfirmDialog } from './components/dialog/ConfirmDialog.svelte';
+export { openDialog, closeDialog, dismissDialog, dismissAllDialogs, confirm, setDialogMeta, getDialogStack, } from './components/dialog/dialog-manager.svelte.js';
+export type { DialogOptions, DialogEntry, DialogSize } from './components/dialog/types.js';
+export { cn, type ClassValue } from './utils/cn.js';
+export { getTheme, setTheme, toggleTheme, themeBootScript, type Theme } from './utils/theme.js';
+export declare const VERSION = "0.8.2";

package/dist/index.js

@@ -0,0 +1,72 @@
+/**
+ * @lyeve/ui-kit - public API.
+ *
+ * Every component, utility, and store the library exposes is re-exported
+ * from this single entry point. Consumers should import from
+ * `'@lyeve/ui-kit'` and never reach into deep paths - the directory layout
+ * is an implementation detail.
+ */
+// ── Layout & structure ─────────────────────────────────────────────────────
+export { default as Card } from './components/Card.svelte';
+export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as Divider } from './components/Divider.svelte';
+export { default as Accordion } from './components/Accordion.svelte';
+export { default as AccordionItem } from './components/AccordionItem.svelte';
+export { default as Table } from './components/Table.svelte';
+// ── Forms & inputs ─────────────────────────────────────────────────────────
+export { default as Button } from './components/Button.svelte';
+export { default as ButtonGroup } from './components/ButtonGroup.svelte';
+export { default as Input } from './components/Input.svelte';
+export { default as Textarea } from './components/Textarea.svelte';
+export { default as NumberInput } from './components/NumberInput.svelte';
+export { default as SearchInput } from './components/SearchInput.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as Label } from './components/Label.svelte';
+export { default as Select } from './components/Select.svelte';
+export { default as MultiSelect } from './components/MultiSelect.svelte';
+export { default as Autocomplete } from './components/Autocomplete.svelte';
+export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as Radio } from './components/Radio.svelte';
+export { default as RadioGroup } from './components/RadioGroup.svelte';
+export { default as Toggle } from './components/Toggle.svelte';
+// ── Navigation ─────────────────────────────────────────────────────────────
+export { default as Breadcrumb } from './components/Breadcrumb.svelte';
+export { default as Tabs } from './components/Tabs.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
+export { default as StepIndicator } from './components/StepIndicator.svelte';
+export { default as Dropdown } from './components/Dropdown.svelte';
+// ── Overlays ───────────────────────────────────────────────────────────────
+export { default as Modal } from './components/Modal.svelte';
+export { default as Drawer } from './components/Drawer.svelte';
+export { default as Tooltip } from './components/Tooltip.svelte';
+// ── Feedback & status ──────────────────────────────────────────────────────
+export { default as Alert } from './components/Alert.svelte';
+export { default as Banner } from './components/Banner.svelte';
+export { default as Badge } from './components/Badge.svelte';
+export { default as Tag } from './components/Tag.svelte';
+export { default as Indicator } from './components/Indicator.svelte';
+export { default as Progress } from './components/Progress.svelte';
+export { default as Spinner } from './components/Spinner.svelte';
+export { default as Skeleton } from './components/Skeleton.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as Kbd } from './components/Kbd.svelte';
+// ── Media ──────────────────────────────────────────────────────────────────
+export { default as Avatar } from './components/Avatar.svelte';
+export { default as AvatarGroup } from './components/AvatarGroup.svelte';
+// ── Theming & toasts ───────────────────────────────────────────────────────
+export { default as ThemeToggle } from './components/ThemeToggle.svelte';
+export { default as Toaster } from './components/Toaster.svelte';
+// ── Stores ─────────────────────────────────────────────────────────────────
+export { toast } from './stores/toast.svelte.js';
+// ── Dialogs (imperative stack: openDialog / confirm) ────────────────────────
+export { default as DialogContainer } from './components/dialog/DialogContainer.svelte';
+export { default as Dialog } from './components/dialog/Dialog.svelte';
+export { default as ConfirmDialog } from './components/dialog/ConfirmDialog.svelte';
+export { openDialog, closeDialog, dismissDialog, dismissAllDialogs, confirm, setDialogMeta, getDialogStack, } from './components/dialog/dialog-manager.svelte.js';
+// ── Utilities ──────────────────────────────────────────────────────────────
+export { cn } from './utils/cn.js';
+export { getTheme, setTheme, toggleTheme, themeBootScript } from './utils/theme.js';
+// ── Version ────────────────────────────────────────────────────────────────
+export const VERSION = '0.8.2';

package/dist/stores/toast.svelte.d.ts

@@ -0,0 +1,18 @@
+export type ToastTone = 'info' | 'success' | 'warn' | 'danger';
+export interface Toast {
+    id: number;
+    tone: ToastTone;
+    message: string;
+    timeout: number;
+}
+declare class ToastStore {
+    items: Toast[];
+    push(tone: ToastTone, message: string, timeout?: number): number;
+    dismiss(id: number): void;
+    info(message: string, timeout?: number): number;
+    success(message: string, timeout?: number): number;
+    warn(message: string, timeout?: number): number;
+    error(message: string, timeout?: number): number;
+}
+export declare const toast: ToastStore;
+export {};

package/dist/stores/toast.svelte.js

@@ -0,0 +1,28 @@
+let seq = 0;
+class ToastStore {
+    items = $state([]);
+    push(tone, message, timeout = 4000) {
+        const id = ++seq;
+        this.items.push({ id, tone, message, timeout });
+        if (timeout > 0) {
+            setTimeout(() => this.dismiss(id), timeout);
+        }
+        return id;
+    }
+    dismiss(id) {
+        this.items = this.items.filter((t) => t.id !== id);
+    }
+    info(message, timeout) {
+        return this.push('info', message, timeout);
+    }
+    success(message, timeout) {
+        return this.push('success', message, timeout);
+    }
+    warn(message, timeout) {
+        return this.push('warn', message, timeout);
+    }
+    error(message, timeout) {
+        return this.push('danger', message, timeout);
+    }
+}
+export const toast = new ToastStore();

package/dist/styles/theme.css

@@ -0,0 +1,148 @@
+/*
+ * @lyeve/ui-kit - theme tokens
+ *
+ * A single CSS file imported once at the top of your app's root stylesheet.
+ * Declares two palettes - Soft Dark (default) and Soft Light - built from
+ * the LyEve brand guideline (Ink #0B1422 + Cyan #00D4FF) and exposes them
+ * as Tailwind v4 `@theme` tokens.
+ *
+ *     import '@lyeve/ui-kit/styles.css';
+ *
+ * Switching themes is a single attribute on `<html>`:
+ *     <html data-theme="light">  // light mode
+ *     <html>                      // dark mode (default)
+ */
+
+@import 'tailwindcss';
+
+/* ── Soft Dark · default palette ─────────────────────────────────────────── */
+@theme {
+  --color-ink: #0b1422;
+  --color-surface: #101a2b;
+  --color-surface-2: #162233;
+  --color-line: #1e2d40;
+  --color-fg: #e6e8ee;
+  --color-muted: #9aa1ad;
+  --color-faint: #525866;
+
+  --color-brand: #00d4ff;
+  --color-brand-light: #5fd9f4;
+  --color-brand-deep: #0099c4;
+  --color-violet: #7c6aef;
+
+  --color-success: #15803d;
+  --color-warn: #b45309;
+  --color-danger: #b91c1c;
+
+  /* ── Radius ─────────────────────────────────────────────────── */
+  --radius-xs: 4px;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-2xl: 24px;
+
+  /* ── Typography · families ───────────────────────────────────── */
+  --font-sans:
+    'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
+    'Noto Sans', sans-serif;
+  --font-mono:
+    'JetBrains Mono', ui-monospace, 'SF Mono', 'Cascadia Code', 'Fira Code', Menlo, Consolas,
+    monospace;
+
+  /* ── Typography · brand type scale (from brand guideline) ────── *
+   *  Token     Size   Line   Tracking  Weight  Use               *
+   *  Display   64px   1.05  −0.04em   700     Hero headlines     *
+   *  H1        44px   1.10  −0.025em  700     Page titles        *
+   *  H2        32px   1.15  −0.02em   600     Section headings   *
+   *  H3        22px   1.25  −0.015em  600     Card / group heads *
+   *  Body      16px   1.55   0        400     Default body copy  *
+   *  Caption   13px   1.50   0        400     Labels, metadata   *
+   *  Mono      18px   1.50   0        500     Code, eyebrows     *
+   *                                                          */
+  --font-size-display: 4rem; /* 64px */
+  --font-size-h1: 2.75rem; /* 44px */
+  --font-size-h2: 2rem; /* 32px */
+  --font-size-h3: 1.375rem; /* 22px */
+  --font-size-body: 1rem; /* 16px */
+  --font-size-caption: 0.8125rem; /* 13px */
+  --font-size-mono: 1.125rem; /* 18px */
+
+  --leading-display: 1.05;
+  --leading-h1: 1.1;
+  --leading-h2: 1.15;
+  --leading-h3: 1.25;
+  --leading-body: 1.55;
+  --leading-caption: 1.5;
+  --leading-mono: 1.5;
+
+  --tracking-display: -0.04em;
+  --tracking-h1: -0.025em;
+  --tracking-h2: -0.02em;
+  --tracking-h3: -0.015em;
+
+  /* ── Spacing grid · 4px base (semantic shortcuts) ────────────── *
+   *  Tailwind's default 0.25rem (4px) grid is unchanged.          *
+   *  These tokens add named slots for common component spacing.   */
+  --spacing-page-x: 1.5rem; /* 24px - page horizontal gutter     */
+  --spacing-page-y: 2rem; /* 32px - page vertical gutter       */
+  --spacing-card: 1.5rem; /* 24px - card inner padding         */
+  --spacing-card-sm: 1rem; /* 16px - compact card padding       */
+  --spacing-section: 3rem; /* 48px - section gap                */
+  --spacing-input-x: 0.75rem; /* 12px - input horizontal padding   */
+  --spacing-input-y: 0.5rem; /* 8px  - input vertical padding     */
+  --spacing-stack: 1rem; /* 16px - default vertical stack gap */
+  --spacing-inline: 0.5rem; /* 8px  - default inline gap         */
+}
+
+/* ── Soft Light · activated by html[data-theme="light"] ──────────────────── */
+html[data-theme='light'] {
+  --color-ink: #f6f7f9;
+  --color-surface: #ffffff;
+  --color-surface-2: #e6e8ee;
+  --color-line: #d6d9e0;
+  --color-fg: #111827;
+  --color-muted: #525866;
+  --color-faint: #9aa1ad;
+
+  --color-brand: #007ea6;
+  --color-brand-light: #00b4dd;
+  --color-brand-deep: #006a8a;
+  --color-violet: #6b5cdf;
+
+  --color-success: #15803d;
+  --color-warn: #b45309;
+  --color-danger: #b91c1c;
+}
+
+@layer base {
+  html {
+    background-color: var(--color-ink);
+    color-scheme: dark;
+  }
+
+  html[data-theme='light'] {
+    color-scheme: light;
+  }
+
+  body {
+    background-color: var(--color-ink);
+    color: var(--color-fg);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  ::selection {
+    background-color: color-mix(in srgb, var(--color-brand) 30%, transparent);
+  }
+
+  :focus-visible {
+    outline: 2px solid color-mix(in srgb, var(--color-brand) 60%, transparent);
+    outline-offset: 2px;
+  }
+
+  :focus:not(:focus-visible) {
+    outline: none;
+  }
+}

package/dist/utils/cn.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Join an arbitrary list of class-name expressions into a single string.
+ *
+ * Falsy entries (`undefined`, `null`, `false`, `0`, `''`) are dropped so you
+ * can write conditionals inline without sprinkling `&&` and ternaries:
+ *
+ *     cn('btn', isPrimary && 'btn-primary', { 'is-disabled': disabled })
+ *
+ * Object entries are treated as `{ className: boolean }` maps, matching the
+ * behaviour of `clsx` so existing muscle memory carries over.
+ */
+export type ClassValue = string | number | null | false | undefined | Record<string, boolean | null | undefined> | ClassValue[];
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/utils/cn.js

@@ -0,0 +1,24 @@
+export function cn(...inputs) {
+    const out = [];
+    for (const value of inputs) {
+        if (!value)
+            continue;
+        if (typeof value === 'string' || typeof value === 'number') {
+            out.push(String(value));
+            continue;
+        }
+        if (Array.isArray(value)) {
+            const nested = cn(...value);
+            if (nested)
+                out.push(nested);
+            continue;
+        }
+        if (typeof value === 'object') {
+            for (const key in value) {
+                if (value[key])
+                    out.push(key);
+            }
+        }
+    }
+    return out.join(' ');
+}

package/dist/utils/theme.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Theme utilities - small, framework-agnostic helpers for managing the
+ * `data-theme` attribute on `<html>` and persisting the user's choice.
+ *
+ * The `<ThemeToggle />` component uses these under the hood; you can also
+ * call them directly when you need to set the theme from a layout, route
+ * loader, or an inline `<script>` that runs before paint.
+ */
+export type Theme = 'dark' | 'light';
+/**
+ * Inline-script payload that should run *before* the first paint to avoid
+ * the flash-of-wrong-theme. Drop the returned string into a `<script>` tag
+ * in the `<head>` of your app shell.
+ *
+ * Picks the theme in this order:
+ *   1. `localStorage["lyeve-theme"]` if set
+ *   2. The user's OS preference (`prefers-color-scheme`)
+ *   3. Dark (the default brand palette)
+ */
+export declare function themeBootScript(): string;
+/** Read the current theme. SSR-safe; returns `'dark'` on the server. */
+export declare function getTheme(): Theme;
+/** Apply a theme and persist the choice to `localStorage`. */
+export declare function setTheme(theme: Theme): void;
+/** Flip between dark and light. Returns the new theme. */
+export declare function toggleTheme(): Theme;

package/dist/utils/theme.js

@@ -0,0 +1,55 @@
+/**
+ * Theme utilities - small, framework-agnostic helpers for managing the
+ * `data-theme` attribute on `<html>` and persisting the user's choice.
+ *
+ * The `<ThemeToggle />` component uses these under the hood; you can also
+ * call them directly when you need to set the theme from a layout, route
+ * loader, or an inline `<script>` that runs before paint.
+ */
+const STORAGE_KEY = 'lyeve-theme';
+/**
+ * Inline-script payload that should run *before* the first paint to avoid
+ * the flash-of-wrong-theme. Drop the returned string into a `<script>` tag
+ * in the `<head>` of your app shell.
+ *
+ * Picks the theme in this order:
+ *   1. `localStorage["lyeve-theme"]` if set
+ *   2. The user's OS preference (`prefers-color-scheme`)
+ *   3. Dark (the default brand palette)
+ */
+export function themeBootScript() {
+    return `(function () {
+    try {
+      var stored = localStorage.getItem('${STORAGE_KEY}');
+      var prefersLight = window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches;
+      var theme = stored === 'light' || stored === 'dark' ? stored : (prefersLight ? 'light' : 'dark');
+      document.documentElement.setAttribute('data-theme', theme);
+    } catch (_) {
+      document.documentElement.setAttribute('data-theme', 'dark');
+    }
+  })();`;
+}
+/** Read the current theme. SSR-safe; returns `'dark'` on the server. */
+export function getTheme() {
+    if (typeof document === 'undefined')
+        return 'dark';
+    return document.documentElement.getAttribute('data-theme') === 'light' ? 'light' : 'dark';
+}
+/** Apply a theme and persist the choice to `localStorage`. */
+export function setTheme(theme) {
+    if (typeof document === 'undefined')
+        return;
+    document.documentElement.setAttribute('data-theme', theme);
+    try {
+        localStorage.setItem(STORAGE_KEY, theme);
+    }
+    catch {
+        // Storage may be disabled (private mode, quota); fall through silently.
+    }
+}
+/** Flip between dark and light. Returns the new theme. */
+export function toggleTheme() {
+    const next = getTheme() === 'dark' ? 'light' : 'dark';
+    setTheme(next);
+    return next;
+}