@just-web/toolkits 1.0.0 → 2.1.0

package/src/theme/_utils/match-attribute-value-to-theme.ts

@@ -0,0 +1,36 @@
+import { findKey } from 'type-plus'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { resolveThemeMapValue } from './resolve-theme-map-value.ts'
+
+/**
+ * Matches an attribute value string against the theme map and returns the theme key.
+ * Pure function: no DOM access. Used by parseDataAttribute and custom parse paths.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param attrValue - Attribute value string (e.g. from getAttribute)
+ * @param options.separator - When defined, split by separator and use first token
+ * @returns Theme key if a match is found, otherwise undefined
+ */
+export function matchAttributeValueToTheme<Theme extends string>(
+	themes: ThemeMap<Theme>,
+	attrValue: string | null,
+	options?: { separator?: string | undefined } | undefined
+): Theme | undefined {
+	if (attrValue === null || attrValue === '') return undefined
+	const valueToMatch =
+		options?.separator !== undefined
+			? attrValue
+					.trim()
+					.split(options.separator)
+					.find((s) => s.trim() !== '')
+			: attrValue
+	if (valueToMatch === undefined) return undefined
+	const theme = findKey(themes, (key) => {
+		const value = themes[key]
+		if (value === undefined) return false
+		const resolved = resolveThemeMapValue(value)
+		const v = Array.isArray(resolved) ? resolved[0] : resolved
+		return v === valueToMatch
+	})
+	return theme
+}

package/src/theme/_utils/parse-stored-theme.ts

@@ -1,21 +1,61 @@
 import { tryParseJSON } from '../../_internal/utils/try-parse-json.ts'
-import type { ThemeMap } from '../theme-map.types.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap, ThemeMapValue } from '../theme-map.types.ts'
+import { isReadonlyStringArray } from './resolve-theme-map-value.ts'
+
+type Shape = 'string' | 'array' | 'object-string' | 'object-array'
+
+function getShapeAndComparable(
+	v: unknown
+): { shape: Shape; comparable: string | undefined } | null {
+	if (typeof v === 'string') return { shape: 'string', comparable: v }
+	if (Array.isArray(v)) return { shape: 'array', comparable: v[0] }
+	if (v !== null && typeof v === 'object' && 'themeValue' in v) {
+		const tv = (v as { themeValue: string | string[] }).themeValue
+		if (typeof tv === 'string') return { shape: 'object-string', comparable: tv }
+		if (Array.isArray(tv)) return { shape: 'object-array', comparable: tv[0] }
+	}
+	return null
+}
+
+function getCanonicalShapeAndComparable(v: ThemeMapValue): {
+	shape: Shape
+	comparable: string | undefined
+} {
+	if (typeof v === 'string') return { shape: 'string', comparable: v }
+	if (isReadonlyStringArray(v)) return { shape: 'array', comparable: v[0] }
+	const tv = v.themeValue
+	if (typeof tv === 'string') return { shape: 'object-string', comparable: tv }
+	return { shape: 'object-array', comparable: tv[0] }
+}
 
 /**
- * Parses stored JSON theme and validates the theme key against theme map.
+ * Parses stored JSON theme and validates against theme map with strict shape and comparable matching.
  *
  * Expects stored shape: { theme: string, value?: unknown }
  *
- * @param themes - Record of valid theme keys (optional; if omitted, any theme string is accepted)
- * @param value - Raw string from localStorage/sessionStorage
- * @returns Theme key if valid, otherwise undefined
+ * When shape matches AND comparable value (string or [0]) matches themes[theme]:
+ * returns { theme, value: stored.value }. Else returns undefined.
+ *
+ * @param themes - Record of valid theme keys and values (required for validation)
+ * @param value - Raw string from localStorage/sessionStorage/cookie (accepts null)
+ * @returns ThemeEntry when valid, otherwise undefined
  */
-export function parseStoredTheme<Theme extends string>(
-	themes: ThemeMap<Theme> | undefined,
+export function parseStoredTheme<Themes extends ThemeMap>(
+	themes: Themes | undefined,
 	value: string | null | undefined
-): Theme | undefined {
-	const parsed = tryParseJSON<{ theme: string }>(value)
+): ThemeEntry<Themes> | undefined {
+	const parsed = tryParseJSON<{ theme: string; value?: unknown }>(value ?? null)
 	if (!parsed?.theme || typeof parsed.theme !== 'string') return undefined
-	if (themes && !(parsed.theme in themes)) return undefined
-	return parsed.theme as Theme
+	if (!themes || !(parsed.theme in themes)) return undefined
+	if (parsed.value === undefined) return undefined
+
+	const storedInfo = getShapeAndComparable(parsed.value)
+	if (!storedInfo) return undefined
+
+	const canonical = getCanonicalShapeAndComparable(themes[parsed.theme] as ThemeMapValue)
+	if (storedInfo.shape !== canonical.shape) return undefined
+	if (storedInfo.comparable !== canonical.comparable) return undefined
+
+	return { theme: parsed.theme as keyof Themes, value: parsed.value as Themes[keyof Themes] }
 }

package/src/theme/_utils/resolve-theme-map-value.ts

@@ -0,0 +1,15 @@
+import type { ThemeMapValue } from '../theme-map.types.ts'
+
+export function isReadonlyStringArray(v: ThemeMapValue): v is readonly string[] {
+	return Array.isArray(v)
+}
+
+/**
+ * Resolves ThemeMapValue to its underlying string or string[] for DOM application and matching.
+ * Used when applying themes to className, data attributes, or when resolving theme from DOM.
+ */
+export function resolveThemeMapValue(v: ThemeMapValue): string | readonly string[] {
+	if (typeof v === 'string') return v
+	if (isReadonlyStringArray(v)) return v
+	return v.themeValue
+}

package/src/theme/_utils/set-theme-to-stores.ts

@@ -4,18 +4,18 @@ import type { AsyncThemeStore } from '../theme-store/async-theme-store.types.ts'
 import type { ThemeStore } from '../theme-store/theme-store.types.ts'
 
 type StoreWithWrite<Themes extends ThemeMap> = (ThemeStore<Themes> | AsyncThemeStore<Themes>) & {
-	write: (entry: ThemeEntry<Themes> | undefined) => void | Promise<void>
+	write: (entry: ThemeEntry<Themes> | null | undefined) => void | Promise<void>
 }
 
 /**
  * Writes theme entry to all stores that have a write method.
  *
  * @param stores - Array of theme stores
- * @param entry - Theme entry to write, or undefined to clear
+ * @param entry - Theme entry to write, or null/undefined to clear
  */
 export async function setThemeToStores<Themes extends ThemeMap>(
 	stores: (ThemeStore<Themes> | AsyncThemeStore<Themes>)[],
-	entry: ThemeEntry<Themes> | undefined
+	entry: ThemeEntry<Themes> | null | undefined
 ): Promise<void> {
 	const withWrite = stores.filter((s): s is StoreWithWrite<Themes> => typeof s.write === 'function')
 

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

@@ -0,0 +1,31 @@
+import { findKey } from 'type-plus'
+import { resolveThemeMapValue } from '../_utils/resolve-theme-map-value.ts'
+import { themeEntry } from '../theme-entry.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Parses a class name string into a ThemeEntry.
+ *
+ * Pure function: no DOM access. Matches class strings by checking if any theme
+ * class is included in the className (e.g. `className.includes(themeClass)`).
+ * Arrays in theme map use first value for matching.
+ *
+ * @param themes - Record mapping theme keys to class name(s)
+ * @param className - Raw class attribute value (e.g. from element.className; accepts null)
+ * @returns ThemeEntry if a match is found, otherwise undefined
+ */
+export function parseClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	className: string | null | undefined
+): ThemeEntry<Themes> | undefined {
+	const cls = className ?? ''
+	const theme = findKey(themes, (key) => {
+		const value = themes[key]
+		if (value === undefined) return false
+		const resolved = resolveThemeMapValue(value)
+		const v = Array.isArray(resolved) ? resolved[0] : resolved
+		return !!v && cls.includes(v)
+	})
+	return theme !== undefined ? themeEntry(themes, theme) : undefined
+}

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

@@ -0,0 +1,24 @@
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { parseClassName } from './parse-class-name.ts'
+
+/**
+ * Reads a theme entry from the class attribute on an element.
+ *
+ * @param themes - Record mapping theme keys to class name(s)
+ * @param options.element - Element to read from (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseClassName)
+ * @returns ThemeEntry if found, undefined otherwise. Returns undefined when element is not available (e.g. SSR).
+ */
+export function readClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	options?:
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| undefined
+): ThemeEntry<Themes> | undefined {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return undefined
+	const parse = options?.parse ?? parseClassName
+	const raw = element.className ?? undefined
+	return parse(themes, raw)
+}

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

@@ -0,0 +1,36 @@
+import { resolveThemeMapValue } from '../_utils/resolve-theme-map-value.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Stringifies a ThemeEntry for a class attribute value.
+ *
+ * Pure function: no DOM access. Removes all theme classes from existing, then
+ * adds entry's class(es). Applies all classes from entry when value is an array
+ * (unlike stringifyDataAttribute which uses first only).
+ *
+ * @param themes - Record mapping theme keys to class names (used to identify theme tokens)
+ * @param existing - Current class attribute value string (accepts null)
+ * @param entry - Theme entry to stringify, or null/undefined to clear theme (keeps non-theme classes)
+ * @returns Class attribute value string
+ */
+export function stringifyClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	existing: string | null | undefined,
+	entry: ThemeEntry<Themes> | null | undefined
+): string {
+	const allThemeClasses = Object.values(themes).flatMap((v) => {
+		const resolved = resolveThemeMapValue(v)
+		return Array.isArray(resolved) ? [...resolved] : [resolved]
+	})
+	const existingClasses = (existing ?? '')?.trim() ? (existing ?? '').trim().split(/\s+/) : []
+	const withoutThemes = existingClasses.filter((c) => !allThemeClasses.includes(c))
+	const activeClasses =
+		entry != null
+			? (() => {
+					const resolved = resolveThemeMapValue(entry.value)
+					return Array.isArray(resolved) ? [...resolved] : [resolved]
+				})()
+			: []
+	return [...withoutThemes, ...activeClasses].filter(Boolean).join(' ')
+}

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

@@ -0,0 +1,39 @@
+import { observeAttributes } from '../../attributes/observe-attribute.ts'
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { parseClassName } from './parse-class-name.ts'
+
+/**
+ * Subscribes to changes on the class attribute and invokes the handler with parsed theme entries.
+ *
+ * @param themes - Record mapping theme keys to class name(s)
+ * @param handler - Callback invoked when the class attribute changes
+ * @param options.element - Element to observe (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseClassName)
+ * @returns Unsubscribe function. Returns a no-op function when element is not available (e.g. SSR).
+ */
+export function subscribeClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	handler: (entry: ThemeEntry<Themes> | undefined) => void,
+	options?:
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| undefined
+): () => void {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return () => {}
+	const parse = options?.parse ?? parseClassName
+	let lastEmitted: keyof Themes | undefined | null = null
+	const observer = observeAttributes(
+		{
+			class: (value) => {
+				const entry = parse(themes, value ?? undefined)
+				const key = entry?.theme ?? undefined
+				if (lastEmitted === key) return
+				lastEmitted = key
+				handler(entry)
+			}
+		},
+		element
+	)
+	return () => observer.disconnect()
+}

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

@@ -0,0 +1,24 @@
+import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { stringifyClassName } from './stringify-class-name.ts'
+
+/**
+ * Writes a theme entry to the class attribute on an element.
+ *
+ * @param themes - Record mapping theme keys to class name(s)
+ * @param entry - Theme entry to write, or null/undefined to remove the theme
+ * @param options.element - Element to write to (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.stringify - Custom serializer (default: stringifyClassName)
+ */
+export function writeClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options?:
+		| { element?: Element | null | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
+		| undefined
+): void {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return
+	const stringify = options?.stringify ?? stringifyClassName
+	element.className = stringify(themes, element.className ?? undefined, entry)
+}

package/src/theme/compose-theme-stores.ts

@@ -74,7 +74,7 @@ export function composeThemeStores<
 		(s): s is StoreWithSubscribe<Themes> => typeof s.subscribe === 'function'
 	)
 
-	function subscribe(handler: (theme: ThemeEntry<Themes> | undefined | null) => void): () => void {
+	function subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void {
 		let scheduled = false
 		let lastEmitted: keyof Themes | undefined
 

package/src/theme/cookie/_cookie-utils.ts

@@ -0,0 +1,45 @@
+/**
+ * Internal cookie utilities for theme cookie storage.
+ * Cookie Store API has limited support; document.cookie is standard for theme persistence.
+ */
+
+export 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
+}
+
+export 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('; ')
+}
+
+export 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`
+}
+
+/**
+ * Parses a cookie value from a raw Cookie header string.
+ * Used for SSR when reading from request headers or framework cookie APIs.
+ */
+export 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
+}

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

@@ -0,0 +1,33 @@
+import { parseStoredTheme } from '../_utils/parse-stored-theme.ts'
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { getCookieValue } from './_cookie-utils.ts'
+
+export interface ReadCookieThemeOptions<Themes extends ThemeMap = ThemeMap> {
+	cookieName: string
+	path?: string | undefined
+	parse?: ParseStoredTheme<Themes> | undefined
+}
+
+/**
+ * Reads a theme entry from a cookie.
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param options.cookieName - Cookie name to read from
+ * @param options.path - Cookie path (default: '/')
+ * @param options.parse - Custom parser (default: parseStoredTheme)
+ * @returns ThemeEntry if found, undefined otherwise. Returns undefined when document.cookie is unavailable (e.g. SSR).
+ */
+export function readCookieTheme<Themes extends ThemeMap>(
+	themes: Themes,
+	options: ReadCookieThemeOptions<Themes>
+): ThemeEntry<Themes> | undefined {
+	const { cookieName, parse = parseStoredTheme } = options
+
+	if (typeof document === 'undefined' || document.cookie === undefined) {
+		return undefined
+	}
+
+	const stored = getCookieValue(cookieName)
+	return parse(themes, stored ?? undefined)
+}

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

@@ -0,0 +1,48 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { deleteCookie, setCookie } from './_cookie-utils.ts'
+
+export interface WriteCookieThemeOptions<_Themes extends ThemeMap = ThemeMap> {
+	cookieName: string
+	path?: string | undefined
+	maxAge?: number | undefined
+	sameSite?: 'lax' | 'strict' | 'none' | undefined
+	secure?: boolean | undefined
+}
+
+/**
+ * Writes a theme entry to a cookie.
+ *
+ * Performs cookie set/delete only. Does not notify subscribers; the store must call notify() after this.
+ *
+ * @param themes - Record mapping theme keys to values (used for type validation)
+ * @param entry - Theme entry to write, or null/undefined to remove
+ * @param options - Cookie options
+ */
+export function writeCookieTheme<Themes extends ThemeMap>(
+	_themes: Themes,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options: WriteCookieThemeOptions<Themes>
+): void {
+	const { cookieName, path = '/', maxAge, sameSite, secure } = options
+
+	if (typeof document === 'undefined' || document.cookie === undefined) {
+		return
+	}
+
+	if (entry == null) {
+		deleteCookie(cookieName, path)
+		return
+	}
+
+	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)
+}

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

@@ -0,0 +1 @@
+export const SEPARATOR_SPACE = ' '

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

@@ -0,0 +1,25 @@
+import { matchAttributeValueToTheme } from '../_utils/match-attribute-value-to-theme.ts'
+import { themeEntry } from '../theme-entry.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { SEPARATOR_SPACE } from './_constant.ts'
+
+/**
+ * Parses a data attribute value string into a ThemeEntry.
+ *
+ * Pure function: no DOM access. Uses first token when separator is defined.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param value - Raw attribute value string (e.g. from getAttribute; accepts null)
+ * @param options.separator - When defined, split by separator and use first token (default: space)
+ * @returns ThemeEntry if a match is found, otherwise undefined
+ */
+export function parseDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	value: string | null | undefined,
+	options?: { separator?: string | undefined } | undefined
+): ThemeEntry<Themes> | undefined {
+	const separator = options?.separator ?? SEPARATOR_SPACE
+	const theme = matchAttributeValueToTheme(themes, value ?? null, { separator })
+	return theme !== undefined ? themeEntry(themes, theme) : undefined
+}

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

@@ -0,0 +1,29 @@
+import { getDataAttribute } from '../../attributes/get-data-attribute.ts'
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { SEPARATOR_SPACE } from './_constant.ts'
+import { parseDataAttribute } from './parse-data-attribute.ts'
+
+/**
+ * Reads a theme entry from a data attribute on an element.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param attributeName - Data attribute name (e.g. `data-theme`)
+ * @param options.element - Element to read from (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseDataAttribute with space separator)
+ * @returns ThemeEntry if found, undefined otherwise. Returns undefined when element is not available (e.g. SSR).
+ */
+export function readDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	attributeName: `data-${string}`,
+	options?:
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| undefined
+): ThemeEntry<Themes> | undefined {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return undefined
+	const parse =
+		options?.parse ?? ((t, v) => parseDataAttribute(t, v, { separator: SEPARATOR_SPACE }))
+	const raw = getDataAttribute(attributeName, element) ?? undefined
+	return parse(themes, raw)
+}

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

@@ -0,0 +1,39 @@
+import { resolveThemeMapValue } from '../_utils/resolve-theme-map-value.ts'
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { SEPARATOR_SPACE } from './_constant.ts'
+
+/**
+ * Stringifies a ThemeEntry for a data attribute value.
+ *
+ * Pure function: no DOM access. Removes all theme values from existing, then adds entry's value(s).
+ * Aligns with stringifyClassName logic.
+ *
+ * @param themes - Record mapping theme keys to attribute values (used to identify theme tokens)
+ * @param existing - Current attribute value string (accepts null e.g. from getAttribute)
+ * @param entry - Theme entry to stringify, or null/undefined to clear theme (keeps non-theme tokens)
+ * @param options.separator - Token separator (default: space)
+ * @returns Attribute value string
+ */
+export function stringifyDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	existing: string | null | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options?: { separator?: string | undefined } | undefined
+): string {
+	const separator = options?.separator ?? SEPARATOR_SPACE
+	const allThemeValues = Object.values(themes).flatMap((v) => {
+		const resolved = resolveThemeMapValue(v)
+		return Array.isArray(resolved) ? [...resolved] : [resolved]
+	})
+	const existingTokens = (existing ?? '')?.trim() ? (existing ?? '').trim().split(separator) : []
+	const withoutThemeValues = existingTokens.filter((t) => !allThemeValues.includes(t.trim()))
+	const newTokens =
+		entry != null
+			? (() => {
+					const resolved = resolveThemeMapValue(entry.value)
+					return Array.isArray(resolved) ? [resolved[0]] : [resolved]
+				})()
+			: []
+	return [...withoutThemeValues, ...newTokens].filter(Boolean).join(separator)
+}

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

@@ -0,0 +1,39 @@
+import { observeDataAttributes } from '../../attributes/observe-data-attribute.ts'
+import type { ParseStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { SEPARATOR_SPACE } from './_constant.ts'
+import { parseDataAttribute } from './parse-data-attribute.ts'
+
+/**
+ * Subscribes to changes on a data attribute and invokes the handler with parsed theme entries.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param attributeName - Data attribute name (e.g. `data-theme`)
+ * @param handler - Callback invoked when the attribute changes
+ * @param options.element - Element to observe (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.parse - Custom parser (default: parseDataAttribute with space separator)
+ * @returns Unsubscribe function. Returns a no-op function when element is not available (e.g. SSR).
+ */
+export function subscribeDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	attributeName: `data-${string}`,
+	handler: (entry: ThemeEntry<Themes> | undefined) => void,
+	options?:
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| undefined
+): () => void {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return () => {}
+	const parse =
+		options?.parse ?? ((t, v) => parseDataAttribute(t, v, { separator: SEPARATOR_SPACE }))
+	const observer = observeDataAttributes<string, `data-${string}`>(
+		{
+			[attributeName]: (value) => {
+				const entry = parse(themes, value ?? undefined)
+				handler(entry)
+			}
+		},
+		element
+	)
+	return () => observer.disconnect()
+}

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

@@ -0,0 +1,40 @@
+import { getDataAttribute } from '../../attributes/get-data-attribute.ts'
+import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import { SEPARATOR_SPACE } from './_constant.ts'
+import { stringifyDataAttribute } from './stringify-data-attribute.ts'
+
+/**
+ * Writes a theme entry to a data attribute on an element.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param attributeName - Data attribute name (e.g. `data-theme`)
+ * @param entry - Theme entry to write, or null/undefined to remove the theme
+ * @param options.element - Element to write to (accepts null e.g. from refs). Defaults to document.documentElement.
+ * @param options.stringify - Custom serializer (default: stringifyDataAttribute with space separator)
+ */
+export function writeDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	attributeName: `data-${string}`,
+	entry: ThemeEntry<Themes> | null | undefined,
+	options?:
+		| { element?: Element | null | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
+		| undefined
+): void {
+	const element = options?.element ?? document?.documentElement
+	if (!element) return
+	const stringify =
+		options?.stringify ??
+		((t, x, e) => stringifyDataAttribute(t, x, e, { separator: SEPARATOR_SPACE }))
+	if (entry == null) {
+		element.removeAttribute(attributeName)
+		return
+	}
+	const existing = getDataAttribute(attributeName, element) ?? undefined
+	const result = stringify(themes, existing, entry)
+	if (result === '') {
+		element.removeAttribute(attributeName)
+	} else {
+		element.setAttribute(attributeName, result)
+	}
+}

package/src/theme/local-storage/read-local-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 localStorage.
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param storageKey - localStorage key to read from
+ * @param options.parse - Custom parser (default: parseStoredTheme)
+ * @returns ThemeEntry if found, undefined otherwise. Returns undefined when localStorage is unavailable (e.g. SSR).
+ */
+export function readLocalStorage<Themes extends ThemeMap>(
+	themes: Themes,
+	storageKey: string,
+	options?: { parse?: ParseStoredTheme<Themes> | undefined }
+): ThemeEntry<Themes> | undefined {
+	if (!window?.localStorage) return undefined
+	return readWebStorage(themes, storageKey, {
+		storage: window.localStorage,
+		parse: options?.parse
+	})
+}