@just-web/toolkits 1.0.0 → 2.1.0

package/src/theme/local-storage/write-local-storage.ts

@@ -0,0 +1,31 @@
+import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { writeWebStorage } from '../web-storage/write-web-storage.ts'
+
+/**
+ * Writes a theme entry to localStorage.
+ *
+ * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.
+ *
+ * @param themes - Record mapping theme keys to values (used by stringify)
+ * @param storageKey - localStorage key to write to
+ * @param entry - Theme entry to write, or null/undefined to remove
+ * @param options.stringify - Custom serializer (default: JSON.stringify)
+ * @param options.onError - Optional callback invoked when storage write throws
+ */
+export function writeLocalStorage<Themes extends ThemeMap>(
+	themes: Themes,
+	storageKey: string,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options?: {
+		stringify?: StringifyStoredTheme<Themes> | undefined
+		onError?: ((error: unknown) => void) | undefined
+	}
+): void {
+	if (!window?.localStorage) return
+	writeWebStorage(themes, storageKey, entry, {
+		storage: window.localStorage,
+		stringify: options?.stringify,
+		onError: options?.onError
+	})
+}

package/src/theme/prefers-color-scheme-theme/read-prefers-color-scheme-theme.ts

@@ -0,0 +1,30 @@
+import { getPrefersColorScheme } from '../../color-scheme/get-prefers-color-scheme.ts'
+import { themeEntry } from '../theme-entry.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+
+type PrefersColorSchemeThemes = {
+	light: string | readonly string[]
+	dark: string | readonly string[]
+}
+
+export interface ReadPrefersColorSchemeThemeOptions {
+	defaultColorScheme?: 'light' | 'dark' | undefined
+}
+
+/**
+ * Reads a theme entry from the system `prefers-color-scheme` media query.
+ *
+ * Themes must only include `light` and `dark` keys—this mirrors the system preference.
+ *
+ * @param themes - Record with `light` and `dark` keys mapping to theme values
+ * @param options.defaultColorScheme - Fallback when matchMedia is unavailable (e.g. SSR, default: 'light')
+ * @returns ThemeEntry for current system preference
+ */
+export function readPrefersColorSchemeTheme<Themes extends PrefersColorSchemeThemes>(
+	themes: Themes,
+	options?: ReadPrefersColorSchemeThemeOptions | undefined
+): ThemeEntry<Themes> {
+	const defaultColorScheme = options?.defaultColorScheme ?? 'light'
+	const scheme = getPrefersColorScheme(defaultColorScheme)
+	return themeEntry(themes, scheme)
+}

package/src/theme/prefers-color-scheme-theme/subscribe-prefers-color-scheme-theme.ts

@@ -0,0 +1,24 @@
+import { observePrefersColorScheme } from '../../color-scheme/observe-prefers-color-scheme.ts'
+import { themeEntry } from '../theme-entry.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+
+type PrefersColorSchemeThemes = {
+	light: string | readonly string[]
+	dark: string | readonly string[]
+}
+
+/**
+ * Subscribes to system `prefers-color-scheme` changes and invokes the handler with theme entries.
+ *
+ * Themes must only include `light` and `dark` keys—this mirrors the system preference.
+ *
+ * @param themes - Record with `light` and `dark` keys mapping to theme values
+ * @param handler - Callback invoked when the color scheme preference changes
+ * @returns Unsubscribe function
+ */
+export function subscribePrefersColorSchemeTheme<Themes extends PrefersColorSchemeThemes>(
+	themes: Themes,
+	handler: (entry: ThemeEntry<Themes>) => void
+): () => void {
+	return observePrefersColorScheme((scheme) => handler(themeEntry(themes, scheme)))
+}

package/src/theme/session-storage/read-session-storage.ts

@@ -0,0 +1,23 @@
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { readWebStorage } from '../web-storage/read-web-storage.ts'
+
+/**
+ * Reads a theme entry from sessionStorage.
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param storageKey - sessionStorage key to read from
+ * @param options.parse - Custom parser (default: parseStoredTheme)
+ * @returns ThemeEntry if found, undefined otherwise. Returns undefined when sessionStorage is unavailable (e.g. SSR).
+ */
+export function readSessionStorage<Themes extends ThemeMap>(
+	themes: Themes,
+	storageKey: string,
+	options?: { parse?: ParseStoredTheme<Themes> | undefined }
+): ThemeEntry<Themes> | undefined {
+	if (!window?.sessionStorage) return undefined
+	return readWebStorage(themes, storageKey, {
+		storage: window.sessionStorage,
+		parse: options?.parse
+	})
+}

package/src/theme/session-storage/write-session-storage.ts

@@ -0,0 +1,31 @@
+import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { writeWebStorage } from '../web-storage/write-web-storage.ts'
+
+/**
+ * Writes a theme entry to sessionStorage.
+ *
+ * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.
+ *
+ * @param themes - Record mapping theme keys to values (used by stringify)
+ * @param storageKey - sessionStorage key to write to
+ * @param entry - Theme entry to write, or null/undefined to remove
+ * @param options.stringify - Custom serializer (default: JSON.stringify)
+ * @param options.onError - Optional callback invoked when storage write throws
+ */
+export function writeSessionStorage<Themes extends ThemeMap>(
+	themes: Themes,
+	storageKey: string,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options?: {
+		stringify?: StringifyStoredTheme<Themes> | undefined
+		onError?: ((error: unknown) => void) | undefined
+	}
+): void {
+	if (!window?.sessionStorage) return
+	writeWebStorage(themes, storageKey, entry, {
+		storage: window.sessionStorage,
+		stringify: options?.stringify,
+		onError: options?.onError
+	})
+}

package/src/theme/theme-entry.types.ts

@@ -9,3 +9,24 @@ export interface ThemeEntry<Themes extends ThemeMap = ThemeMap> {
 	theme: keyof Themes
 	value: Themes[keyof Themes]
 }
+
+/**
+ * Function type for parsing stored string into ThemeEntry.
+ * Used as options.parse in persisting theme stores.
+ * Value accepts null (e.g. from getItem, getAttribute, cookie parsing).
+ */
+export type ParseStoredTheme<Themes extends ThemeMap> = (
+	themes: Themes,
+	value: string | null | undefined
+) => ThemeEntry<Themes> | undefined
+
+/**
+ * Function type for stringify ThemeEntry to a stored string.
+ * Used as options.stringify in persisting theme stores.
+ * Existing accepts null (e.g. from getAttribute, getItem); entry accepts null for remove/clear.
+ */
+export type StringifyStoredTheme<Themes extends ThemeMap> = (
+	themes: Themes,
+	existing: string | null | undefined,
+	entry: ThemeEntry<Themes> | null | undefined
+) => string

package/src/theme/theme-map.types.ts

@@ -1,6 +1,13 @@
+/**
+ * Polymorphic theme value: string, array, or object with themeValue.
+ * The object form allows storing extra user metadata in persistent stores (localStorage, etc.).
+ */
+export type ThemeMapValue = string | readonly string[] | { themeValue: string | readonly string[] }
+
 /**
  * Record mapping theme keys to their values.
- * Each value can be a single string or readonly string[] (e.g. multiple CSS classes).
+ * Each value can be a single string, readonly string[] (e.g. multiple CSS classes),
+ * or { themeValue: string | string[] } for polymorphic values with extra metadata.
  * Used by all ThemeStore factories via the themes option.
  */
-export type ThemeMap<Theme extends string = string> = Record<Theme, string | readonly string[]>
+export type ThemeMap<Theme extends string = string> = Record<Theme, ThemeMapValue>

package/src/theme/theme-store/async-theme-store.types.ts

@@ -18,7 +18,5 @@ export interface AsyncThemeStore<Themes extends ThemeMap = ThemeMap> {
 		| (() => ThemeEntry<Themes> | undefined | Promise<ThemeEntry<Themes> | undefined>)
 		| undefined
 	write?: ((entry: ThemeEntry<Themes> | undefined) => void | Promise<void>) | undefined
-	subscribe?:
-		| ((handler: (entry: ThemeEntry<Themes> | undefined | null) => void) => () => void)
-		| undefined
+	subscribe?: ((handler: (entry: ThemeEntry<Themes> | undefined) => void) => () => void) | undefined
 }

package/src/theme/theme-store/class-name-theme-store/class-name-theme-store.ts

@@ -1,9 +1,11 @@
 import type { Required } from 'type-plus'
-import { observeAttributes } from '../../../attributes/observe-attribute.ts'
 import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
-import { applyThemeToClassName } from '../../class-name/apply-theme-to-class-name.ts'
-import { resolveThemeFromClassName } from '../../class-name/resolve-theme-from-class-name.ts'
-import { themeEntry } from '../../theme-entry.ts'
+import { parseClassName } from '../../class-name/parse-class-name.ts'
+import { readClassName } from '../../class-name/read-class-name.ts'
+import { stringifyClassName } from '../../class-name/stringify-class-name.ts'
+import { subscribeClassName } from '../../class-name/subscribe-class-name.ts'
+import { writeClassName } from '../../class-name/write-class-name.ts'
+import type { ParseStoredTheme, StringifyStoredTheme } from '../../theme-entry.types.ts'
 import type { ThemeMap } from '../../theme-map.types.ts'
 import type { ThemeStore } from '../theme-store.types.ts'
 
@@ -11,7 +13,9 @@ import type { ThemeStore } from '../theme-store.types.ts'
  * Creates a theme store that reads and writes via element class names.
  *
  * @param themes - Record mapping theme keys to class name(s)
- * @param options.element - Element to operate on (defaults to document.documentElement)
+ * @param options.element - Element to operate on (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseClassName)
+ * @param options.stringify - Custom serializer (default: stringifyClassName)
  * @returns ThemeStore
  *
  * @example
@@ -25,38 +29,28 @@ import type { ThemeStore } from '../theme-store.types.ts'
  */
 export function classNameThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
-	options?: { element?: Element | undefined }
+	options?: {
+		element?: Element | null | undefined
+		parse?: ParseStoredTheme<Themes> | undefined
+		stringify?: StringifyStoredTheme<Themes> | undefined
+	}
 ): Required<ThemeStore<Themes>> {
 	const element = options?.element ?? document?.documentElement
 
 	if (!element) return dummyThemeStore
 
+	const parse = options?.parse ?? parseClassName
+	const stringify = options?.stringify ?? stringifyClassName
+
 	return {
 		read() {
-			const theme = resolveThemeFromClassName(themes, element.className)
-			if (theme === undefined) return undefined
-			return themeEntry(themes, theme)
+			return readClassName(themes, { element, parse })
 		},
 		write(entry) {
-			applyThemeToClassName(themes, element, entry)
+			writeClassName(themes, entry, { element, stringify })
 		},
 		subscribe(handler) {
-			let lastEmitted: keyof Themes | undefined | null = null
-			const observer = observeAttributes(
-				{
-					class: (value) => {
-						const theme = value ? resolveThemeFromClassName(themes, value) : undefined
-						const entry = theme ? themeEntry(themes, theme) : undefined
-						const key = theme ?? undefined
-
-						if (lastEmitted === key) return
-						lastEmitted = key
-						handler(entry)
-					}
-				},
-				element
-			)
-			return () => observer.disconnect()
+			return subscribeClassName(themes, handler, { element, parse })
 		}
 	}
 }

package/src/theme/theme-store/cookie-theme-store/cookie-theme-store.ts

@@ -1,48 +1,20 @@
 import type { Required } from 'type-plus'
 import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
 import { parseStoredTheme } from '../../_utils/parse-stored-theme.ts'
-import { themeEntry } from '../../theme-entry.ts'
-import type { ThemeEntry } from '../../theme-entry.types.ts'
+import { getCookieFromHeader } from '../../cookie/_cookie-utils.ts'
+import { readCookieTheme } from '../../cookie/read-cookie-theme.ts'
+import { writeCookieTheme } from '../../cookie/write-cookie-theme.ts'
+import type { ParseStoredTheme, ThemeEntry } from '../../theme-entry.types.ts'
 import type { ThemeMap } from '../../theme-map.types.ts'
 import type { ThemeStore } from '../theme-store.types.ts'
 
-export interface CookieThemeStoreOptions {
+export interface CookieThemeStoreOptions<Themes extends ThemeMap = ThemeMap> {
 	cookieName: string
 	path?: string | undefined
 	maxAge?: number | undefined
 	sameSite?: 'lax' | 'strict' | 'none' | undefined
 	secure?: boolean | undefined
-}
-
-function getCookieValue(name: string): string | null {
-	if (typeof document === 'undefined' || !document.cookie) return null
-	const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-	const value = match?.[1]
-	return value !== undefined ? decodeURIComponent(value) : null
-}
-
-function setCookie(
-	name: string,
-	value: string,
-	options: {
-		path?: string | undefined
-		maxAge?: number | undefined
-		sameSite?: 'lax' | 'strict' | 'none' | undefined
-		secure?: boolean | undefined
-	}
-) {
-	const parts = [`${name}=${encodeURIComponent(value)}`]
-	parts.push(`path=${options.path ?? '/'}`)
-	if (options.maxAge !== undefined) parts.push(`max-age=${options.maxAge}`)
-	if (options.sameSite !== undefined) parts.push(`samesite=${options.sameSite}`)
-	if (options.secure) parts.push('secure')
-	// biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API has limited support; document.cookie is standard for theme persistence
-	document.cookie = parts.join('; ')
-}
-
-function deleteCookie(name: string, path = '/') {
-	// biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API has limited support; document.cookie is standard for theme persistence
-	document.cookie = `${name}=; path=${path}; max-age=0`
+	parse?: ParseStoredTheme<Themes> | undefined
 }
 
 /**
@@ -58,6 +30,7 @@ function deleteCookie(name: string, path = '/') {
  * @param options.maxAge - Cookie max-age in seconds
  * @param options.sameSite - Cookie sameSite attribute
  * @param options.secure - Cookie secure attribute
+ * @param options.parse - Optional custom parser for stored string (default: parseStoredTheme)
  * @returns ThemeStore
  *
  * @example
@@ -71,9 +44,9 @@ function deleteCookie(name: string, path = '/') {
  */
 export function cookieThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
-	options: CookieThemeStoreOptions
+	options: CookieThemeStoreOptions<Themes>
 ): Required<ThemeStore<Themes>> {
-	const { cookieName, path = '/', maxAge, sameSite, secure } = options
+	const { cookieName, path = '/', maxAge, sameSite, secure, parse = parseStoredTheme } = options
 
 	if (document.cookie === undefined) {
 		return dummyThemeStore
@@ -83,10 +56,7 @@ export function cookieThemeStore<Themes extends ThemeMap>(
 	let lastNotifiedKey: keyof Themes | undefined = read()?.theme ?? undefined
 
 	function read() {
-		const stored = getCookieValue(cookieName)
-		const theme = parseStoredTheme(themes, stored)
-		if (theme === undefined) return undefined
-		return themeEntry(themes, theme)
+		return readCookieTheme(themes, { cookieName, path, parse })
 	}
 
 	function notify() {
@@ -101,20 +71,13 @@ export function cookieThemeStore<Themes extends ThemeMap>(
 		read,
 		write(entry) {
 			try {
-				if (entry === undefined) {
-					deleteCookie(cookieName, path)
-				} else {
-					const opts: {
-						path: string
-						maxAge?: number
-						sameSite?: 'lax' | 'strict' | 'none'
-						secure?: boolean
-					} = { path }
-					if (maxAge !== undefined) opts.maxAge = maxAge
-					if (sameSite !== undefined) opts.sameSite = sameSite
-					if (secure) opts.secure = true
-					setCookie(cookieName, JSON.stringify(entry), opts)
-				}
+				writeCookieTheme(themes, entry, {
+					cookieName,
+					path,
+					maxAge,
+					sameSite,
+					secure
+				})
 				notify()
 			} catch {
 				// Ignore quota or other errors
@@ -129,12 +92,6 @@ export function cookieThemeStore<Themes extends ThemeMap>(
 	} satisfies ThemeStore<Themes>
 }
 
-function getCookieFromHeader(cookieHeader: string, name: string): string | null {
-	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-	const value = match?.[1]
-	return value !== undefined ? decodeURIComponent(value.trim()) : null
-}
-
 /**
  * Reads the theme from cookies during SSR. Use with the request's Cookie header or
  * a framework's cookie API (e.g. Next.js cookies()).
@@ -168,7 +125,5 @@ export function getThemeFromCookie<Themes extends ThemeMap>(
 			: cookieSource
 				? getCookieFromHeader(cookieSource, cookieName)
 				: null
-	const theme = parseStoredTheme(themes, stored)
-	if (theme === undefined) return undefined
-	return themeEntry(themes, theme)
+	return parseStoredTheme(themes, stored ?? undefined)
 }

package/src/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts

@@ -1,60 +1,73 @@
-import type { Required } from 'type-plus'
-import { getDataAttribute } from '../../../attributes/get-data-attribute.ts'
-import { observeDataAttributes } from '../../../attributes/observe-data-attribute.ts'
-import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
-import { applyThemeToDataAttribute } from '../../data-attribute/apply-theme-to-data-attribute.ts'
-import { resolveThemeFromDataAttribute } from '../../data-attribute/resolve-theme-from-data-attribute.ts'
-import { themeEntry } from '../../theme-entry.ts'
+import { SEPARATOR_SPACE } from '../../data-attribute/_constant.ts'
+import { parseDataAttribute } from '../../data-attribute/parse-data-attribute.ts'
+import { readDataAttribute } from '../../data-attribute/read-data-attribute.ts'
+import { stringifyDataAttribute } from '../../data-attribute/stringify-data-attribute.ts'
+import { subscribeDataAttribute } from '../../data-attribute/subscribe-data-attribute.ts'
+import { writeDataAttribute } from '../../data-attribute/write-data-attribute.ts'
+import type { ParseStoredTheme, StringifyStoredTheme } from '../../theme-entry.types.ts'
 import type { ThemeMap } from '../../theme-map.types.ts'
 import type { ThemeStore } from '../theme-store.types.ts'
 
 /**
  * Creates a theme store that reads and writes via a data attribute.
  *
+ * read: parse(themes, getDataAttribute(element, attribute)) → ThemeEntry
+ * write: setAttribute(attribute, stringify(themes, getDataAttribute(element, attribute), entry))
+ *
+ * Supports space-separated attribute values by default. Use `parse` and `stringify` to customize
+ * (e.g. comma-separated via curried parseDataAttribute/stringifyDataAttribute).
+ *
  * @param themes - Record mapping theme keys to attribute values
  * @param options.attributeName - Data attribute name (e.g. `data-theme`)
- * @param options.element - Element to operate on (defaults to document.documentElement)
+ * @param options.element - Element to operate on (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseDataAttribute with space separator)
+ * @param options.stringify - Custom serializer (default: stringifyDataAttribute with space separator)
  * @returns ThemeStore
  *
  * @example
  * ```ts
  * const themes = { current: 'current', grayscale: 'grayscale' }
  * const store = dataAttributeThemeStore(themes, { attributeName: 'data-theme' })
- * store.read() // returns themeResult from data attribute
+ * store.read() // returns ThemeEntry from data attribute
  * store.write(themeEntry(themes, 'grayscale'))
- * store.subscribe((themeResult) => {})
+ * store.subscribe((entry) => {})
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Comma-separated
+ * const store = dataAttributeThemeStore(themes, {
+ *   attributeName: 'data-theme',
+ *   parse: (t, v) => parseDataAttribute(t, v, { separator: ',' }),
+ *   stringify: (t, x, e) => stringifyDataAttribute(t, x, e, { separator: ',' })
+ * })
  * ```
  */
 export function dataAttributeThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
-	options: { attributeName: `data-${string}`; element?: Element | undefined }
+	options: {
+		attributeName: `data-${string}`
+		element?: Element | null | undefined
+		parse?: ParseStoredTheme<Themes> | undefined
+		stringify?: StringifyStoredTheme<Themes> | undefined
+	}
 ) {
 	const element = options.element ?? document?.documentElement
-	const { attributeName } = options
-
-	if (!element) return dummyThemeStore as Required<ThemeStore<Themes>>
+	const {
+		attributeName,
+		parse = (t, v) => parseDataAttribute(t, v, { separator: SEPARATOR_SPACE }),
+		stringify = (t, x, e) => stringifyDataAttribute(t, x, e, { separator: SEPARATOR_SPACE })
+	} = options
 
 	return {
 		read() {
-			const value = getDataAttribute(attributeName, element)
-			const theme = resolveThemeFromDataAttribute(themes, value)
-			if (theme === undefined) return undefined
-			return themeEntry(themes, theme)
+			return readDataAttribute(themes, attributeName, { element, parse })
 		},
 		write(entry) {
-			applyThemeToDataAttribute(element, attributeName, entry)
+			writeDataAttribute(themes, attributeName, entry, { element, stringify })
 		},
 		subscribe(handler) {
-			const observer = observeDataAttributes<string, `data-${string}`>(
-				{
-					[attributeName]: (value) => {
-						const theme = value ? resolveThemeFromDataAttribute(themes, value) : undefined
-						handler(theme ? themeEntry(themes, theme) : undefined)
-					}
-				},
-				element
-			)
-			return () => observer.disconnect()
+			return subscribeDataAttribute(themes, attributeName, handler, { element, parse })
 		}
 	} satisfies ThemeStore<Themes>
 }

package/src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts

@@ -33,7 +33,7 @@ export function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {
 	return {
 		read,
 		write(entry) {
-			if (entry === undefined) {
+			if (entry == null) {
 				if (value === undefined || value === null) return
 				value = undefined
 				for (const fn of listeners) fn(undefined)

package/src/theme/theme-store/local-storage-theme-store/local-storage-theme-store.ts

@@ -1,7 +1,7 @@
 import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
-import { parseStoredTheme } from '../../_utils/parse-stored-theme.ts'
-import { themeEntry } from '../../theme-entry.ts'
-import type { ThemeEntry } from '../../theme-entry.types.ts'
+import { readLocalStorage } from '../../local-storage/read-local-storage.ts'
+import { writeLocalStorage } from '../../local-storage/write-local-storage.ts'
+import type { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from '../../theme-entry.types.ts'
 import type { ThemeMap } from '../../theme-map.types.ts'
 import type { ThemeStore } from '../theme-store.types.ts'
 
@@ -13,6 +13,9 @@ import type { ThemeStore } from '../theme-store.types.ts'
  *
  * @param themes - Record mapping theme keys to values (for validation)
  * @param options.storageKey - localStorage key
+ * @param options.parse - Optional custom parser for stored string (default: parseStoredTheme)
+ * @param options.stringify - Optional custom serializer (default: JSON.stringify)
+ * @param options.onError - Optional callback invoked when storage write throws
  * @returns ThemeStore
  *
  * @example
@@ -26,11 +29,16 @@ import type { ThemeStore } from '../theme-store.types.ts'
  */
 export function localStorageThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
-	options: { storageKey: string }
+	options: {
+		storageKey: string
+		parse?: ParseStoredTheme<Themes> | undefined
+		stringify?: StringifyStoredTheme<Themes> | undefined
+		onError?: ((error: unknown) => void) | undefined
+	}
 ) {
-	const { storageKey } = options
+	const { storageKey, parse, stringify, onError } = options
 
-	if (typeof window === 'undefined' || !window.localStorage) {
+	if (!window?.localStorage) {
 		return dummyThemeStore satisfies ThemeStore<Themes>
 	}
 
@@ -38,10 +46,7 @@ export function localStorageThemeStore<Themes extends ThemeMap>(
 	let lastNotifiedKey: keyof Themes | undefined = read()?.theme ?? undefined
 
 	function read() {
-		const stored = window.localStorage.getItem(storageKey)
-		const theme = parseStoredTheme(themes, stored)
-		if (theme === undefined) return undefined
-		return themeEntry(themes, theme)
+		return readLocalStorage(themes, storageKey, { parse })
 	}
 
 	function notify() {
@@ -55,16 +60,8 @@ export function localStorageThemeStore<Themes extends ThemeMap>(
 	return {
 		read,
 		write(entry) {
-			try {
-				if (entry === undefined) {
-					window.localStorage.removeItem(storageKey)
-				} else {
-					window.localStorage.setItem(storageKey, JSON.stringify(entry))
-				}
-				notify()
-			} catch {
-				// Ignore quota or other errors
-			}
+			writeLocalStorage(themes, storageKey, entry, { stringify, onError })
+			notify()
 		},
 		subscribe(handler) {
 			handlers.add(handler)

package/src/theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.ts

@@ -1,7 +1,6 @@
 import type { RequiredPick } from 'type-plus'
-import { getPrefersColorScheme } from '../../../color-scheme/get-prefers-color-scheme.ts'
-import { observePrefersColorScheme } from '../../../color-scheme/observe-prefers-color-scheme.ts'
-import { themeEntry } from '../../theme-entry.ts'
+import { readPrefersColorSchemeTheme } from '../../prefers-color-scheme-theme/read-prefers-color-scheme-theme.ts'
+import { subscribePrefersColorSchemeTheme } from '../../prefers-color-scheme-theme/subscribe-prefers-color-scheme-theme.ts'
 import type { ThemeStore } from '../theme-store.types.ts'
 
 type PrefersColorSchemeThemes = {
@@ -34,10 +33,10 @@ export function prefersColorSchemeThemeStore<Themes extends PrefersColorSchemeTh
 ): RequiredPick<ThemeStore<Themes>, 'read' | 'subscribe'> {
 	return {
 		read() {
-			return themeEntry(themes, getPrefersColorScheme())
+			return readPrefersColorSchemeTheme(themes)
 		},
 		subscribe(handler) {
-			return observePrefersColorScheme((scheme) => handler(themeEntry(themes, scheme)))
+			return subscribePrefersColorSchemeTheme(themes, handler)
 		}
 	}
 }