feat: synchronous mode change (#147)

Author: huntabyte

.changeset/mean-years-yell.md

@@ -0,0 +1,5 @@
+---
+"mode-watcher": minor
+---
+
+feat: expose `synchronousModeChanges` prop to opt out of performance improvements for synchronous mode changes. Defaults to `false`.

docs/package.json

@@ -15,12 +15,12 @@
 		"check:watch": "pnpm build:content && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
 	},
 	"devDependencies": {
-		"@svecodocs/kit": "^0.2.1",
+		"@svecodocs/kit": "^0.3.0",
 		"@sveltejs/adapter-cloudflare": "^4.8.0",
 		"@sveltejs/kit": "^2.20.3",
 		"@sveltejs/vite-plugin-svelte": "^5.0.3",
 		"@tailwindcss/vite": "^4.1.1",
-		"mdsx": "^0.0.6",
+		"mdsx": "^0.0.7",
 		"mode-watcher": "workspace:*",
 		"phosphor-svelte": "^3.0.1",
 		"svelte": "^5.27.0",

docs/src/content/components/mode-watcher.md

@@ -153,3 +153,11 @@ The classes to add to the root `html` element when the mode is `'light'`.
 <PropField name="disableHeadScriptInjection" type="boolean" defaultValue="false">
 	Whether to disable the injected script tag that sets the initial mode. Set this if you are manually injecting the script using a hook.
 </PropField>
+
+<PropField name="synchronousModeChanges" type="boolean" defaultValue="false">
+
+Whether to run the mode changes synchronously instead of using an animation frame. If true, will have an impact on blocking performance due to blocking the main thread.
+
+Only applicable if `disableTransitions` is set to `true`.
+
+</PropField>

packages/mode-watcher/src/lib/components/mode-watcher.svelte

@@ -8,6 +8,7 @@
 		disableTransitions,
 		lightClassNames,
 		mode,
+		synchronousModeChanges,
 		theme,
 		themeColors,
 	} from "$lib/states.svelte.js";
@@ -28,6 +29,7 @@
 		themeStorageKey: themeStorageKeyProp = "mode-watcher-theme",
 		modeStorageKey: modeStorageKeyProp = "mode-watcher-mode",
 		disableHeadScriptInjection = false,
+		synchronousModeChanges: synchronousModeChangesProp = false,
 	}: ModeWatcherProps = $props();
 
 	modeStorageKey.current = modeStorageKeyProp;
@@ -36,6 +38,11 @@
 	lightClassNames.current = lightClassNamesProp;
 	disableTransitions.current = disableTransitionsProp;
 	themeColors.current = themeColorsProp;
+	synchronousModeChanges.current = synchronousModeChangesProp;
+
+	$effect.pre(() => {
+		synchronousModeChanges.current = synchronousModeChangesProp;
+	});
 
 	$effect.pre(() => {
 		disableTransitions.current = disableTransitionsProp;

packages/mode-watcher/src/lib/states.svelte.ts

@@ -4,6 +4,7 @@ import type { ThemeColors } from "./types.js";
 import { withoutTransition } from "./without-transition.js";
 import { systemPrefersMode, userPrefersMode } from "./mode-states.svelte.js";
 import { customTheme } from "./theme-state.svelte.js";
+import { untrack } from "svelte";
 
 /**
  * Theme colors for light and dark modes.
@@ -15,6 +16,13 @@ export const themeColors = box<ThemeColors>(undefined);
  */
 export const disableTransitions = box(true);
 
+/**
+ * Whether to run the mode changes synchronously instead of using
+ * an animation frame. If true, will have an impact on blocking performance
+ * due to blocking the main thread.
+ */
+export const synchronousModeChanges = box(false);
+
 /**
  * The classnames to add to the root `html` element when the mode is dark.
  */
@@ -60,7 +68,7 @@ function createDerivedMode() {
 		}
 
 		if (disableTransitions.current) {
-			withoutTransition(update);
+			withoutTransition(update, synchronousModeChanges.current);
 		} else {
 			update();
 		}
@@ -86,7 +94,10 @@ function createDerivedTheme() {
 		}
 
 		if (disableTransitions.current) {
-			withoutTransition(update);
+			withoutTransition(
+				update,
+				untrack(() => synchronousModeChanges.current)
+			);
 		} else {
 			update();
 		}

packages/mode-watcher/src/lib/types.ts

@@ -8,14 +8,14 @@ export type ModeWatcherProps = {
 	 * Whether to automatically track operating system preferences
 	 * and update the mode accordingly.
 	 *
-	 * @defaultValue `true`
+	 * @default `true`
 	 */
 	track?: boolean;
 
 	/**
 	 * The default mode to use instead of the user's preference.
 	 *
-	 * @defaultValue `"system"`
+	 * @default `"system"`
 	 */
 	defaultMode?: Mode;
 
@@ -28,7 +28,7 @@ export type ModeWatcherProps = {
 	 * <html data-theme="your-custom-theme"></html>
 	 * ```
 	 *
-	 * @defaultValue `undefined`
+	 * @default `undefined`
 	 */
 	defaultTheme?: string;
 
@@ -45,44 +45,55 @@ export type ModeWatcherProps = {
 	/**
 	 * The classname to add to the root `html` element when the mode is dark.
 	 *
-	 * @defaultValue `["dark"]`
+	 * @default `["dark"]`
 	 */
 	darkClassNames?: string[];
 
 	/**
 	 * The classname to add to the root `html` element when the mode is light.
 	 *
-	 * @defaultValue `[]`
+	 * @default `[]`
 	 */
 	lightClassNames?: string[];
 
 	/**
 	 * Optionally provide a custom local storage key to use for storing the mode.
 	 *
-	 * @defaultValue `'mode-watcher-mode'`
+	 * @default `'mode-watcher-mode'`
 	 */
 	modeStorageKey?: string;
 
 	/**
 	 * Optionally provide a custom local storage key to use for storing the theme.
 	 *
-	 * @defaultValue `'mode-watcher-theme'`
+	 * @default `'mode-watcher-theme'`
 	 */
 	themeStorageKey?: string;
 
 	/**
 	 * An optional nonce to use for the injected script tag to allow-list mode-watcher
 	 * if you are using a Content Security Policy.
 	 *
-	 * @defaultValue `undefined`
+	 * @default `undefined`
 	 */
 	nonce?: string;
 
 	/**
 	 * Whether to disable the injected script tag that sets the initial mode.
 	 * Set this if you are manually injecting the script using a hook.
 	 *
-	 * @defaultValue `false`
+	 * @default `false`
 	 */
 	disableHeadScriptInjection?: boolean;
+
+	/**
+	 * Whether to run the mode changes synchronously instead of using
+	 * an animation frame. If true, will have an impact on blocking performance
+	 * due to blocking the main thread.
+	 *
+	 * Only applicable if `disableTransitions` is set to `true`.
+	 *
+	 * @default `false`
+	 */
+	synchronousModeChanges?: boolean;
 };

packages/mode-watcher/src/lib/without-transition.ts

@@ -30,7 +30,7 @@ function getStyleElement() {
 
 // Perform a task without any css transitions
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function withoutTransition(action: () => any) {
+export function withoutTransition(action: () => any, synchronous = false) {
 	if (typeof document === "undefined") return;
 
 	// Skip transition disabling on initial load
@@ -62,22 +62,30 @@ export function withoutTransition(action: () => any) {
 		}
 	};
 
+	function executeAction() {
+		action();
+		// defer enable to ensure action completes
+		window.requestAnimationFrame(enable);
+	}
+
 	// Use requestAnimationFrame for better performance
 	if (typeof window.requestAnimationFrame !== "undefined") {
 		disable();
-		// defer action to next frame to avoid blocking
-		window.requestAnimationFrame(() => {
-			action();
-			// defer enable to ensure action completes
-			window.requestAnimationFrame(enable);
-		});
+		if (synchronous) {
+			executeAction();
+		} else {
+			// defer action to next frame to avoid blocking
+			window.requestAnimationFrame(() => {
+				executeAction();
+			});
+		}
 		return;
 	}
 
 	// Fallback for older browsers
 	disable();
 	timeoutAction = window.setTimeout(() => {
 		action();
-		timeoutEnable = window.setTimeout(enable, 16); // ~1 frame at 60fps
+		timeoutEnable = window.setTimeout(enable, 16);
 	}, 16);
 }