@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/components/ui/mode-switcher/ModeSwitcher.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">import { onMount } from "svelte";
+import { setMode } from "mode-watcher";
+import { capturePreferenceStorage } from "../../../preferences/capture-preference-storage.js";
+import { buttonVariants } from "../button/index.js";
+import { Icon } from "../../icon";
+import { cn } from "../../../utils.js";
+import { applySharedMode, persistSharedMode, persistSharedModePreference } from "./shared-mode-sync";
+let { class: className, host, cookieDomain, onpersist, ...restProps } = $props();
+// The legacy page entry point mirrors into the runtime's preference storage once resolved.
+const resolveStorage = capturePreferenceStorage();
+let storage = $state();
+onMount(() => {
+	void resolveStorage().then((resolved) => {
+		storage = resolved;
+	});
+});
+function toggleTheme(event) {
+	// The button's own document is the one to theme.
+	const ownerDocument = event.currentTarget.ownerDocument;
+	const root = ownerDocument.documentElement;
+	const prefersDark = host ? host.prefersDark() : ownerDocument.defaultView?.matchMedia("(prefers-color-scheme: dark)").matches ?? false;
+	const isDark = root.dataset.mode === "dark" || root.classList.contains("dark") || !root.dataset.mode && prefersDark;
+	const nextMode = isDark ? "light" : "dark";
+	const outcome = host ? persistSharedMode(host, nextMode, { cookieDomain }) : persistSharedModePreference(nextMode, { storage });
+	onpersist?.(outcome);
+	setMode(nextMode);
+	applySharedMode(root, nextMode, prefersDark);
+}
+</script>
+
+<button
+	type="button"
+	data-slot="button"
+	class={cn(buttonVariants({ variant: 'outline', size: 'icon' }), className)}
+	onclick={toggleTheme}
+	{...restProps}
+>
+	<Icon
+		icon="lucide:sun"
+		class="h-[1.2rem] w-[1.2rem] scale-100 rotate-0 transition-all dark:scale-0 dark:-rotate-90"
+	/>
+	<Icon
+		icon="lucide:moon"
+		class="absolute h-[1.2rem] w-[1.2rem] scale-0 rotate-90 transition-all dark:scale-100 dark:rotate-0"
+	/>
+	<span class="sr-only">Toggle theme</span>
+</button>

package/dist/lib/components/ui/mode-switcher/ModeSwitcher.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type ButtonProps } from '../button/index.js';
+import type { Result } from '../../../types/errors.ts';
+import { type SharedMode, type SharedModeHost } from './shared-mode-sync';
+type $$ComponentProps = ButtonProps & {
+    /** The page facts to persist through; without one, the current page (legacy). */
+    host?: SharedModeHost;
+    /** With `host`: the cookie's sharing domain. Omitted, the cookie is host-only. */
+    cookieDomain?: string;
+    /** Told how persisting went, including blocked storage. */
+    onpersist?: (outcome: Result<SharedMode>) => void;
+};
+declare const ModeSwitcher: import("svelte").Component<$$ComponentProps, {}, "">;
+type ModeSwitcher = ReturnType<typeof ModeSwitcher>;
+export default ModeSwitcher;

package/dist/lib/components/ui/mode-switcher/SharedModeWatcher.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">import { onMount, untrack } from "svelte";
+import { capturePreferenceStorage } from "../../../preferences/capture-preference-storage.js";
+import { BROWSER } from "esm-env";
+import { ModeWatcher, setMode } from "mode-watcher";
+import { applySharedMode, createSharedModeBootstrapScript, parseSharedMode, syncSharedMode, syncSharedModePreference, applySharedModePreference } from "./shared-mode-sync";
+let { track = true, defaultMode = "system", cookieName = undefined, cookieDomain = undefined, modeStorageKey = undefined, maxAge = undefined, themeColors = undefined, disableTransitions = true, darkClassNames = ["dark"], lightClassNames = [], defaultTheme = "", nonce = "", themeStorageKey = "mode-watcher-theme", disableHeadScriptInjection = false, synchronousModeChanges = false, host = undefined, onsync = undefined } = $props();
+// Seed storage before ModeWatcher mounts, including when CSP disables the
+// inline bootstrap. Host-local storage must not undo the server preference.
+untrack(() => {
+	if (!BROWSER) return;
+	// The watcher themes the page it renders into; it has no element of its own.
+	const root = document.documentElement;
+	const ssrMode = parseSharedMode(root.dataset.themeMode ?? root.dataset.mode) ?? undefined;
+	const options = {
+		cookieName,
+		cookieDomain,
+		modeStorageKey,
+		maxAge,
+		ssrMode
+	};
+	if (host) {
+		const outcome = syncSharedMode(host, options);
+		onsync?.(outcome);
+		if (outcome.mode) {
+			setMode(outcome.mode);
+			applySharedMode(root, outcome.mode, host.prefersDark(), {
+				darkClassNames,
+				lightClassNames
+			});
+		}
+		return;
+	}
+	const initialMode = syncSharedModePreference(options);
+	if (initialMode) {
+		setMode(initialMode);
+		applySharedModePreference(initialMode, {
+			darkClassNames,
+			lightClassNames
+		});
+	}
+});
+// The runtime's preference storage arrives after mount; settle the mode against it then.
+const resolveStorage = capturePreferenceStorage();
+onMount(() => {
+	if (host) return;
+	void resolveStorage().then((storage) => {
+		if (!storage) return;
+		const root = document.documentElement;
+		const ssrMode = parseSharedMode(root.dataset.themeMode ?? root.dataset.mode) ?? undefined;
+		const settled = syncSharedModePreference({
+			cookieName,
+			cookieDomain,
+			modeStorageKey,
+			maxAge,
+			ssrMode,
+			storage
+		});
+		if (settled) {
+			setMode(settled);
+			applySharedModePreference(settled, {
+				darkClassNames,
+				lightClassNames
+			});
+		}
+	});
+});
+const bootstrapScript = $derived(createSharedModeBootstrapScript({
+	cookieName,
+	cookieDomain,
+	modeStorageKey,
+	maxAge,
+	darkClassNames,
+	lightClassNames
+}));
+// The bootstrap is rendered as a real <script> element (never raw HTML), so no
+// lint suppression is needed. `this` is an expression, and the JSON-escaped
+// body is set through the DOM `text` property — a property every Element has,
+// which the HTML attribute typings for <script> do not list.
+const scriptTag = "script";
+const scriptProps = $derived({
+	nonce,
+	text: bootstrapScript
+});
+</script>
+
+<svelte:head>
+	{#if !disableHeadScriptInjection}
+		<!-- The bootstrap body comes from createSharedModeBootstrapScript, which
+		     JSON-escapes every value; Svelte sets it as the element's text. -->
+		<svelte:element this={scriptTag} {...scriptProps} />
+	{/if}
+</svelte:head>
+
+<ModeWatcher
+	{track}
+	{defaultMode}
+	{themeColors}
+	{disableTransitions}
+	{darkClassNames}
+	{lightClassNames}
+	{defaultTheme}
+	{nonce}
+	{themeStorageKey}
+	disableHeadScriptInjection={true}
+	{synchronousModeChanges}
+	{modeStorageKey}
+/>

package/dist/lib/components/ui/mode-switcher/SharedModeWatcher.svelte.d.ts

@@ -0,0 +1,32 @@
+import { type SystemModeValue } from 'mode-watcher';
+import { type SharedModeHost, type SharedModeSync } from './shared-mode-sync';
+type $$ComponentProps = {
+    track?: boolean;
+    defaultMode?: SystemModeValue | 'system';
+    cookieName?: string;
+    cookieDomain?: string;
+    modeStorageKey?: string;
+    maxAge?: number;
+    themeColors?: {
+        dark: string;
+        light: string;
+    };
+    disableTransitions?: boolean;
+    darkClassNames?: string[];
+    lightClassNames?: string[];
+    defaultTheme?: string;
+    nonce?: string;
+    themeStorageKey?: string;
+    disableHeadScriptInjection?: boolean;
+    synchronousModeChanges?: boolean;
+    /**
+     * The page facts to sync through. Without one the current page is used
+     * and the sharing domain is derived from its host (legacy).
+     */
+    host?: SharedModeHost;
+    /** Told what syncing found, including blocked storage, when `host` is given. */
+    onsync?: (outcome: SharedModeSync) => void;
+};
+declare const SharedModeWatcher: import("svelte").Component<$$ComponentProps, {}, "">;
+type SharedModeWatcher = ReturnType<typeof SharedModeWatcher>;
+export default SharedModeWatcher;

package/dist/lib/components/ui/mode-switcher/index.d.ts

@@ -0,0 +1,5 @@
+export { default as ModeSwitcher } from './ModeSwitcher.svelte';
+export { default as SharedModeWatcher } from './SharedModeWatcher.svelte';
+export { ModeStore } from './mode-store.svelte';
+export { currentModeStore } from '../../../preferences/preference-stores.ts';
+export { createSharedModeBootstrapScript, deriveSharedCookieDomain, MODE_STORAGE_KEY, persistSharedModePreference, readSharedModeCookie, SHARED_MODE_COOKIE_NAME, SHARED_MODE_MAX_AGE, syncSharedModePreference } from './shared-mode-sync';

package/dist/lib/components/ui/mode-switcher/index.js

@@ -0,0 +1,5 @@
+export { default as ModeSwitcher } from './ModeSwitcher.svelte';
+export { default as SharedModeWatcher } from './SharedModeWatcher.svelte';
+export { ModeStore } from './mode-store.svelte';
+export { currentModeStore } from "../../../preferences/preference-stores.js";
+export { createSharedModeBootstrapScript, deriveSharedCookieDomain, MODE_STORAGE_KEY, persistSharedModePreference, readSharedModeCookie, SHARED_MODE_COOKIE_NAME, SHARED_MODE_MAX_AGE, syncSharedModePreference } from './shared-mode-sync';

package/dist/lib/components/ui/mode-switcher/mode-store.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Result } from '../../../types/errors.ts';
+import type { PreferenceStorage } from '../../../preferences/preference-storage.ts';
+import { type SharedMode } from './shared-mode-sync';
+export declare class ModeStore {
+    mode: "light" | "dark" | "system";
+    private initialized;
+    private storage;
+    private readonly stopFollowingChanges;
+    constructor();
+    /** Settle the mode against the cookie (and storage, once attached). */
+    init(): void;
+    /**
+     * Bind the runtime's preference storage (a switcher resolves it from its
+     * runtime) and settle the mode again: the cookie mode is mirrored into
+     * storage, or a stored mode is shared back to the cookie.
+     */
+    attachStorage(storage: PreferenceStorage): void;
+    /** Stop following `vibes:theme-mode-changed` events; the store keeps its mode. */
+    dispose(): void;
+    toggleMode: () => Result<SharedMode>;
+    /** Apply `nextMode`; answers how persisting went (blocked storage, or no page on the server). */
+    setMode: (nextMode: SharedMode) => Result<SharedMode>;
+}

package/dist/lib/components/ui/mode-switcher/mode-store.svelte.js

@@ -0,0 +1,56 @@
+import { BROWSER } from 'esm-env';
+import { setMode, mode } from 'mode-watcher';
+import { applySharedModePreference, persistSharedModePreference, subscribeThemeModeChanges, syncSharedModePreference } from './shared-mode-sync';
+export class ModeStore {
+    mode = $derived(mode.current ?? 'system');
+    initialized = false;
+    storage;
+    stopFollowingChanges = () => { };
+    constructor() {
+        // Settling the mode reads the page, so it happens on the browser only,
+        // from `init()` or `attachStorage()` — never at construction, which would
+        // be a hydration mismatch.
+        if (BROWSER) {
+            this.stopFollowingChanges = subscribeThemeModeChanges(globalThis.window, (nextMode) => this.setMode(nextMode));
+            this.init();
+        }
+    }
+    /** Settle the mode against the cookie (and storage, once attached). */
+    init() {
+        if (!this.initialized && BROWSER) {
+            this.initialized = true;
+            const savedMode = syncSharedModePreference({ storage: this.storage });
+            if (savedMode) {
+                setMode(savedMode);
+            }
+        }
+    }
+    /**
+     * Bind the runtime's preference storage (a switcher resolves it from its
+     * runtime) and settle the mode again: the cookie mode is mirrored into
+     * storage, or a stored mode is shared back to the cookie.
+     */
+    attachStorage(storage) {
+        this.storage = storage;
+        if (!BROWSER)
+            return;
+        const savedMode = syncSharedModePreference({ storage });
+        if (savedMode)
+            setMode(savedMode);
+    }
+    /** Stop following `vibes:theme-mode-changed` events; the store keeps its mode. */
+    dispose() {
+        this.stopFollowingChanges();
+    }
+    toggleMode = () => {
+        const nextMode = mode.current === 'dark' ? 'light' : 'dark';
+        return this.setMode(nextMode);
+    };
+    /** Apply `nextMode`; answers how persisting went (blocked storage, or no page on the server). */
+    setMode = (nextMode) => {
+        const persisted = persistSharedModePreference(nextMode, { storage: this.storage });
+        applySharedModePreference(nextMode);
+        setMode(nextMode);
+        return persisted;
+    };
+}

package/dist/lib/components/ui/mode-switcher/shared-mode-sync.d.ts

@@ -0,0 +1,124 @@
+import { type ApiError, type Result } from '../../../types/errors.ts';
+export declare const SHARED_MODE_COOKIE_NAME = "vibes-mode";
+export declare const MODE_STORAGE_KEY = "mode-watcher-mode";
+export declare const SHARED_MODE_MAX_AGE: number;
+declare const SHARED_MODE_VALUES: readonly ["light", "dark", "system"];
+export type SharedMode = (typeof SHARED_MODE_VALUES)[number];
+/** The shared mode a stored or transmitted string names, or `null` for anything else. */
+export declare function parseSharedMode(value: string | null | undefined): SharedMode | null;
+/** The event other surfaces dispatch on `window` to change the shared mode. */
+export declare const THEME_MODE_CHANGED_EVENT = "vibes:theme-mode-changed";
+/**
+ * Follow theme-mode change events on `target`. Any script can dispatch the
+ * event, so its `detail` is parsed: only a shared mode reaches `onMode`.
+ * Answers the unsubscribe.
+ */
+export declare function subscribeThemeModeChanges(target: EventTarget, onMode: (mode: SharedMode) => void): () => void;
+/**
+ * The legacy shared cookie domain for a page host: the host minus its first
+ * label, never above the registered domain (`example.co.uk` stays
+ * `.example.co.uk`, `vibes.dev` stays `.vibes.dev`). `null` for local and IP
+ * hosts. Hosts that know their sharing domain pass `cookieDomain` instead.
+ */
+export declare function deriveSharedCookieDomain(hostname: string): string | null;
+export declare function readSharedModeCookie(cookieString: string, cookieName?: string): SharedMode | null;
+/** Storage shaped like the runtime browser host's (`RuntimeBrowserHost.storage`). */
+export interface SharedModeStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * The page facts shared mode needs, supplied by the host. `storage` is the
+ * runtime browser host's storage. The runtime has no cookie or colour-scheme
+ * kind, so the host adapts those itself.
+ */
+export interface SharedModeHost {
+    readonly storage: SharedModeStorage;
+    /** The page's cookie text, as `document.cookie` reads it. */
+    readCookies(): string;
+    /** Set one serialised cookie, as assigning `document.cookie` does. */
+    writeCookie(serialized: string): void;
+    /** Whether the system colour scheme is dark, for `system` mode. */
+    prefersDark(): boolean;
+}
+export interface SharedModeHostOptions {
+    cookieName?: string;
+    modeStorageKey?: string;
+    maxAge?: number;
+    /** The cookie's `Domain`, such as `.vibes.dev`. Omitted, the cookie is host-only. */
+    cookieDomain?: string;
+}
+/** Storage access was denied. Fixed text: no host error text is carried. */
+export declare const SHARED_MODE_STORAGE_BLOCKED: ApiError;
+/** The configured cookie domain is not a domain name. */
+export declare const SHARED_MODE_COOKIE_DOMAIN_INVALID: ApiError;
+/** No browser page is present (server rendering), so nothing was persisted. */
+export declare const SHARED_MODE_HOST_UNAVAILABLE: ApiError;
+/** The stored mode, `null` when none (or no valid one) is stored, or a blocked refusal. */
+export declare function readStoredSharedMode(storage: SharedModeStorage, key: string): Result<SharedMode | null>;
+export declare function writeStoredSharedMode(storage: SharedModeStorage, key: string, mode: SharedMode): Result<SharedMode>;
+/** The serialised shared cookie for `mode`, or a refusal for an invalid domain. */
+export declare function serializeSharedModeCookie(mode: SharedMode, options?: SharedModeHostOptions): Result<string>;
+/**
+ * Persist `mode` through the host: the shared cookie, then the storage
+ * mirror. A blocked mirror is reported; the cookie still carries the mode.
+ */
+export declare function persistSharedMode(host: SharedModeHost, mode: SharedMode, options?: SharedModeHostOptions): Result<SharedMode>;
+/** What syncing found: the mode to apply (or none) and what storage did. */
+export interface SharedModeSync {
+    readonly mode: SharedMode | null;
+    /** `mirrored`: the cookie mode was copied to storage; `found`: storage held the mode. */
+    readonly storage: 'found' | 'missing' | 'mirrored' | 'blocked';
+}
+/**
+ * Settle the mode before the watcher mounts. The shared cookie (or the
+ * server-resolved mode) wins and is mirrored to storage; otherwise a stored
+ * mode is shared back to the cookie. Blocked storage is reported apart from a
+ * missing preference.
+ */
+export declare function syncSharedMode(host: SharedModeHost, options?: SharedModeHostOptions & {
+    ssrMode?: SharedMode;
+}): SharedModeSync;
+export interface SharedModeClassNames {
+    darkClassNames?: readonly string[];
+    lightClassNames?: readonly string[];
+}
+/** Apply `mode` to a document root: class sets, `data-mode` and `color-scheme`. */
+export declare function applySharedMode(root: HTMLElement, mode: SharedMode, prefersDark: boolean, options?: SharedModeClassNames): void;
+/** Legacy entry point: persist on the current page, deriving the sharing domain. */
+export declare function persistSharedModePreference(mode: SharedMode, options?: {
+    cookieName?: string;
+    cookieDomain?: string;
+    modeStorageKey?: string;
+    maxAge?: number;
+    /** The runtime's preference storage; omitted, only the cookie persists. */
+    storage?: SharedModeStorage;
+}): Result<SharedMode>;
+/** Legacy entry point: apply on the current page's root. */
+export declare function applySharedModePreference(mode: SharedMode, options?: {
+    darkClassNames?: string[];
+    lightClassNames?: string[];
+}): void;
+/** Legacy entry point: sync on the current page, deriving the sharing domain. */
+export declare function syncSharedModePreference(options?: {
+    ssrMode?: SharedMode;
+    cookieName?: string;
+    modeStorageKey?: string;
+    cookieDomain?: string;
+    maxAge?: number;
+    /** The runtime's preference storage; omitted, only the cookie is read. */
+    storage?: SharedModeStorage;
+}): SharedMode | null;
+/** The bootstrap `<script>` element, with an optional CSP nonce quoted and escaped. */
+export declare function createSharedModeBootstrapTag(script: string, nonce?: string): string;
+export declare function createSharedModeBootstrapScript(options?: {
+    cookieName?: string;
+    cookieDomain?: string;
+    modeStorageKey?: string;
+    maxAge?: number;
+    /** Classes set while dark; the same default as `applySharedModePreference`. */
+    darkClassNames?: readonly string[];
+    /** Classes set while light. */
+    lightClassNames?: readonly string[];
+}): string;
+export {};