@just-web/toolkits 1.0.0 → 2.0.0

package/dist/theme.d.cts

@@ -1,9 +1,27 @@
-import { ThemeMap } from "./theme/theme-map.types.cjs";
-import { ThemeEntry } from "./theme/theme-entry.types.cjs";
+import { ThemeMap, ThemeMapValue } from "./theme/theme-map.types.cjs";
+import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "./theme/theme-entry.types.cjs";
 import { AsyncThemeStore } from "./theme/theme-store/async-theme-store.types.cjs";
 import { ThemeStore } from "./theme/theme-store/theme-store.types.cjs";
 import { ThemeStoreFactory } from "./theme/theme-store/theme-store-factory.types.cjs";
 import { ComposeThemeStoreEntry, ComposeThemeStoresOptions, composeThemeStores } from "./theme/compose-theme-stores.cjs";
+import { parseClassName } from "./theme/class-name/parse-class-name.cjs";
+import { readClassName } from "./theme/class-name/read-class-name.cjs";
+import { stringifyClassName } from "./theme/class-name/stringify-class-name.cjs";
+import { subscribeClassName } from "./theme/class-name/subscribe-class-name.cjs";
+import { writeClassName } from "./theme/class-name/write-class-name.cjs";
+import { ReadCookieThemeOptions, readCookieTheme } from "./theme/cookie/read-cookie-theme.cjs";
+import { WriteCookieThemeOptions, writeCookieTheme } from "./theme/cookie/write-cookie-theme.cjs";
+import { parseDataAttribute } from "./theme/data-attribute/parse-data-attribute.cjs";
+import { readDataAttribute } from "./theme/data-attribute/read-data-attribute.cjs";
+import { stringifyDataAttribute } from "./theme/data-attribute/stringify-data-attribute.cjs";
+import { subscribeDataAttribute } from "./theme/data-attribute/subscribe-data-attribute.cjs";
+import { writeDataAttribute } from "./theme/data-attribute/write-data-attribute.cjs";
+import { readLocalStorage } from "./theme/local-storage/read-local-storage.cjs";
+import { writeLocalStorage } from "./theme/local-storage/write-local-storage.cjs";
+import { ReadPrefersColorSchemeThemeOptions, readPrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/read-prefers-color-scheme-theme.cjs";
+import { subscribePrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/subscribe-prefers-color-scheme-theme.cjs";
+import { readSessionStorage } from "./theme/session-storage/read-session-storage.cjs";
+import { writeSessionStorage } from "./theme/session-storage/write-session-storage.cjs";
 import { themeEntry } from "./theme/theme-entry.cjs";
 import { classNameThemeStore } from "./theme/theme-store/class-name-theme-store/class-name-theme-store.cjs";
 import { CookieThemeStoreOptions, cookieThemeStore, getThemeFromCookie } from "./theme/theme-store/cookie-theme-store/cookie-theme-store.cjs";
@@ -12,4 +30,6 @@ import { inMemoryThemeStore } from "./theme/theme-store/in-memory-theme-store/in
 import { localStorageThemeStore } from "./theme/theme-store/local-storage-theme-store/local-storage-theme-store.cjs";
 import { prefersColorSchemeThemeStore } from "./theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.cjs";
 import { sessionStorageThemeStore } from "./theme/theme-store/session-storage-theme-store/session-storage-theme-store.cjs";
-export { AsyncThemeStore, ComposeThemeStoreEntry, ComposeThemeStoresOptions, CookieThemeStoreOptions, ThemeEntry, ThemeMap, ThemeStore, ThemeStoreFactory, classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, prefersColorSchemeThemeStore, sessionStorageThemeStore, themeEntry };
+import { readWebStorage } from "./theme/web-storage/read-web-storage.cjs";
+import { writeWebStorage } from "./theme/web-storage/write-web-storage.cjs";
+export { AsyncThemeStore, ComposeThemeStoreEntry, ComposeThemeStoresOptions, CookieThemeStoreOptions, ParseStoredTheme, ReadCookieThemeOptions, ReadPrefersColorSchemeThemeOptions, StringifyStoredTheme, ThemeEntry, ThemeMap, ThemeMapValue, ThemeStore, ThemeStoreFactory, WriteCookieThemeOptions, classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, parseClassName, parseDataAttribute, prefersColorSchemeThemeStore, readClassName, readCookieTheme, readDataAttribute, readLocalStorage, readPrefersColorSchemeTheme, readSessionStorage, readWebStorage, sessionStorageThemeStore, stringifyClassName, stringifyDataAttribute, subscribeClassName, subscribeDataAttribute, subscribePrefersColorSchemeTheme, themeEntry, writeClassName, writeCookieTheme, writeDataAttribute, writeLocalStorage, writeSessionStorage, writeWebStorage };

package/dist/theme.d.mts

@@ -1,9 +1,27 @@
-import { ThemeMap } from "./theme/theme-map.types.mjs";
-import { ThemeEntry } from "./theme/theme-entry.types.mjs";
+import { ThemeMap, ThemeMapValue } from "./theme/theme-map.types.mjs";
+import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "./theme/theme-entry.types.mjs";
 import { AsyncThemeStore } from "./theme/theme-store/async-theme-store.types.mjs";
 import { ThemeStore } from "./theme/theme-store/theme-store.types.mjs";
 import { ThemeStoreFactory } from "./theme/theme-store/theme-store-factory.types.mjs";
 import { ComposeThemeStoreEntry, ComposeThemeStoresOptions, composeThemeStores } from "./theme/compose-theme-stores.mjs";
+import { parseClassName } from "./theme/class-name/parse-class-name.mjs";
+import { readClassName } from "./theme/class-name/read-class-name.mjs";
+import { stringifyClassName } from "./theme/class-name/stringify-class-name.mjs";
+import { subscribeClassName } from "./theme/class-name/subscribe-class-name.mjs";
+import { writeClassName } from "./theme/class-name/write-class-name.mjs";
+import { ReadCookieThemeOptions, readCookieTheme } from "./theme/cookie/read-cookie-theme.mjs";
+import { WriteCookieThemeOptions, writeCookieTheme } from "./theme/cookie/write-cookie-theme.mjs";
+import { parseDataAttribute } from "./theme/data-attribute/parse-data-attribute.mjs";
+import { readDataAttribute } from "./theme/data-attribute/read-data-attribute.mjs";
+import { stringifyDataAttribute } from "./theme/data-attribute/stringify-data-attribute.mjs";
+import { subscribeDataAttribute } from "./theme/data-attribute/subscribe-data-attribute.mjs";
+import { writeDataAttribute } from "./theme/data-attribute/write-data-attribute.mjs";
+import { readLocalStorage } from "./theme/local-storage/read-local-storage.mjs";
+import { writeLocalStorage } from "./theme/local-storage/write-local-storage.mjs";
+import { ReadPrefersColorSchemeThemeOptions, readPrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/read-prefers-color-scheme-theme.mjs";
+import { subscribePrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/subscribe-prefers-color-scheme-theme.mjs";
+import { readSessionStorage } from "./theme/session-storage/read-session-storage.mjs";
+import { writeSessionStorage } from "./theme/session-storage/write-session-storage.mjs";
 import { themeEntry } from "./theme/theme-entry.mjs";
 import { classNameThemeStore } from "./theme/theme-store/class-name-theme-store/class-name-theme-store.mjs";
 import { CookieThemeStoreOptions, cookieThemeStore, getThemeFromCookie } from "./theme/theme-store/cookie-theme-store/cookie-theme-store.mjs";
@@ -12,4 +30,6 @@ import { inMemoryThemeStore } from "./theme/theme-store/in-memory-theme-store/in
 import { localStorageThemeStore } from "./theme/theme-store/local-storage-theme-store/local-storage-theme-store.mjs";
 import { prefersColorSchemeThemeStore } from "./theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.mjs";
 import { sessionStorageThemeStore } from "./theme/theme-store/session-storage-theme-store/session-storage-theme-store.mjs";
-export { AsyncThemeStore, ComposeThemeStoreEntry, ComposeThemeStoresOptions, CookieThemeStoreOptions, ThemeEntry, ThemeMap, ThemeStore, ThemeStoreFactory, classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, prefersColorSchemeThemeStore, sessionStorageThemeStore, themeEntry };
+import { readWebStorage } from "./theme/web-storage/read-web-storage.mjs";
+import { writeWebStorage } from "./theme/web-storage/write-web-storage.mjs";
+export { AsyncThemeStore, ComposeThemeStoreEntry, ComposeThemeStoresOptions, CookieThemeStoreOptions, ParseStoredTheme, ReadCookieThemeOptions, ReadPrefersColorSchemeThemeOptions, StringifyStoredTheme, ThemeEntry, ThemeMap, ThemeMapValue, ThemeStore, ThemeStoreFactory, WriteCookieThemeOptions, classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, parseClassName, parseDataAttribute, prefersColorSchemeThemeStore, readClassName, readCookieTheme, readDataAttribute, readLocalStorage, readPrefersColorSchemeTheme, readSessionStorage, readWebStorage, sessionStorageThemeStore, stringifyClassName, stringifyDataAttribute, subscribeClassName, subscribeDataAttribute, subscribePrefersColorSchemeTheme, themeEntry, writeClassName, writeCookieTheme, writeDataAttribute, writeLocalStorage, writeSessionStorage, writeWebStorage };

package/dist/theme.mjs

@@ -1,11 +1,31 @@
 import { themeEntry } from "./theme/theme-entry.mjs";
+import { parseClassName } from "./theme/class-name/parse-class-name.mjs";
+import { readClassName } from "./theme/class-name/read-class-name.mjs";
+import { stringifyClassName } from "./theme/class-name/stringify-class-name.mjs";
+import { subscribeClassName } from "./theme/class-name/subscribe-class-name.mjs";
+import { writeClassName } from "./theme/class-name/write-class-name.mjs";
 import { classNameThemeStore } from "./theme/theme-store/class-name-theme-store/class-name-theme-store.mjs";
+import { parseDataAttribute } from "./theme/data-attribute/parse-data-attribute.mjs";
+import { readDataAttribute } from "./theme/data-attribute/read-data-attribute.mjs";
+import { stringifyDataAttribute } from "./theme/data-attribute/stringify-data-attribute.mjs";
+import { subscribeDataAttribute } from "./theme/data-attribute/subscribe-data-attribute.mjs";
+import { writeDataAttribute } from "./theme/data-attribute/write-data-attribute.mjs";
 import { dataAttributeThemeStore } from "./theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.mjs";
+import { readWebStorage } from "./theme/web-storage/read-web-storage.mjs";
+import { readLocalStorage } from "./theme/local-storage/read-local-storage.mjs";
+import { writeWebStorage } from "./theme/web-storage/write-web-storage.mjs";
+import { writeLocalStorage } from "./theme/local-storage/write-local-storage.mjs";
 import { localStorageThemeStore } from "./theme/theme-store/local-storage-theme-store/local-storage-theme-store.mjs";
 import { composeThemeStores } from "./theme/compose-theme-stores.mjs";
+import { readCookieTheme } from "./theme/cookie/read-cookie-theme.mjs";
+import { writeCookieTheme } from "./theme/cookie/write-cookie-theme.mjs";
+import { readPrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/read-prefers-color-scheme-theme.mjs";
+import { subscribePrefersColorSchemeTheme } from "./theme/prefers-color-scheme-theme/subscribe-prefers-color-scheme-theme.mjs";
+import { readSessionStorage } from "./theme/session-storage/read-session-storage.mjs";
+import { writeSessionStorage } from "./theme/session-storage/write-session-storage.mjs";
 import { cookieThemeStore, getThemeFromCookie } from "./theme/theme-store/cookie-theme-store/cookie-theme-store.mjs";
 import { inMemoryThemeStore } from "./theme/theme-store/in-memory-theme-store/in-memory-theme-store.mjs";
 import { prefersColorSchemeThemeStore } from "./theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.mjs";
 import { sessionStorageThemeStore } from "./theme/theme-store/session-storage-theme-store/session-storage-theme-store.mjs";
 
-export { classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, prefersColorSchemeThemeStore, sessionStorageThemeStore, themeEntry };
+export { classNameThemeStore, composeThemeStores, cookieThemeStore, dataAttributeThemeStore, getThemeFromCookie, inMemoryThemeStore, localStorageThemeStore, parseClassName, parseDataAttribute, prefersColorSchemeThemeStore, readClassName, readCookieTheme, readDataAttribute, readLocalStorage, readPrefersColorSchemeTheme, readSessionStorage, readWebStorage, sessionStorageThemeStore, stringifyClassName, stringifyDataAttribute, subscribeClassName, subscribeDataAttribute, subscribePrefersColorSchemeTheme, themeEntry, writeClassName, writeCookieTheme, writeDataAttribute, writeLocalStorage, writeSessionStorage, writeWebStorage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@just-web/toolkits",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Toolkits for web applications",
   "homepage": "https://github.com/justland/just-web-foundation/tree/main/libs/toolkits",
   "repository": {

package/src/react/hooks/use-theme-by-class-name.ts

@@ -1,7 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
 import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
-import { resolveThemeFromClassName } from '../../theme/class-name/resolve-theme-from-class-name.ts'
 import { themeEntry } from '../../theme/theme-entry.ts'
 import type { ThemeMap } from '../../theme/theme-map.types.ts'
 import { classNameThemeStore } from '../../theme/theme-store/class-name-theme-store/class-name-theme-store.ts'
@@ -42,13 +41,9 @@ export function useThemeByClassName<Themes extends ThemeMap>(
 
 	const store = useMemo(() => classNameThemeStore(themes, { element }), [element, themes])
 
-	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
-		if (element) {
-			const resolved = resolveThemeFromClassName(themes, element.className)
-			return resolved ?? defaultTheme
-		}
-		return defaultTheme
-	})
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(
+		() => store.read()?.theme ?? defaultTheme
+	)
 
 	useEffect(() => {
 		if (!element) return

package/src/react/hooks/use-theme-by-data-attribute.ts

@@ -1,8 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import { getDataAttribute } from '../../attributes/get-data-attribute.ts'
 import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
 import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
-import { resolveThemeFromDataAttribute } from '../../theme/data-attribute/resolve-theme-from-data-attribute.ts'
 import { themeEntry } from '../../theme/theme-entry.ts'
 import type { ThemeMap } from '../../theme/theme-map.types.ts'
 import { dataAttributeThemeStore } from '../../theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts'
@@ -56,14 +54,9 @@ export function useThemeByDataAttribute<Themes extends ThemeMap>(
 		[element, themes, attributeName]
 	)
 
-	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
-		if (element) {
-			const attrValue = getDataAttribute(attributeName, element)
-			const resolved = resolveThemeFromDataAttribute(themes, attrValue)
-			return resolved ?? defaultTheme
-		}
-		return defaultTheme
-	})
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(
+		() => store.read()?.theme ?? defaultTheme
+	)
 
 	useEffect(() => {
 		if (!element) return

package/src/react/hooks/use-theme-by-local-storage.ts

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
-import { parseStoredTheme } from '../../theme/_utils/parse-stored-theme.ts'
 import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
 import { themeEntry } from '../../theme/theme-entry.ts'
 import type { ThemeMap } from '../../theme/theme-map.types.ts'
@@ -43,14 +42,9 @@ export function useThemeByLocalStorage<Themes extends ThemeMap>(
 
 	const store = useMemo(() => localStorageThemeStore(themes, { storageKey }), [themes, storageKey])
 
-	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
-		if (typeof window !== 'undefined' && window.localStorage) {
-			const stored = window.localStorage.getItem(storageKey)
-			const resolved = parseStoredTheme(themes, stored)
-			return resolved ?? defaultTheme
-		}
-		return defaultTheme
-	})
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(
+		() => store.read()?.theme ?? defaultTheme
+	)
 
 	useEffect(() => {
 		const unobserve = observeThemeFromStores([store], defaultTheme, setThemeState)

package/src/testing/theme/theme-result-card.tsx

@@ -16,6 +16,7 @@ function formatValue(value: unknown): string {
 	if (value === null) return '(missing)'
 	if (value === '') return '(empty)'
 	if (Array.isArray(value)) return `[${value.join(', ')}]`
+	if (typeof value === 'object' && value !== null) return JSON.stringify(value)
 	return String(value)
 }
 

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
+ * @returns ThemeEntry when valid, otherwise undefined
  */
-export function parseStoredTheme<Theme extends string>(
-	themes: ThemeMap<Theme> | undefined,
-	value: string | null | undefined
-): Theme | undefined {
-	const parsed = tryParseJSON<{ theme: string }>(value)
+export function parseStoredTheme<Themes extends ThemeMap>(
+	themes: Themes | undefined,
+	value: string | undefined
+): 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/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)
+ * @returns ThemeEntry if a match is found, otherwise undefined
+ */
+export function parseClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	className: string | 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 (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 | 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
+ * @param entry - Theme entry to stringify, or undefined to clear theme (keeps non-theme classes)
+ * @returns Class attribute value string
+ */
+export function stringifyClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	existing: string | undefined,
+	entry: ThemeEntry<Themes> | 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 !== undefined
+			? (() => {
+					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 (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 | 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 undefined to remove the theme
+ * @param options.element - Element to write to (defaults to document.documentElement)
+ * @param options.stringify - Custom serializer (default: stringifyClassName)
+ */
+export function writeClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	entry: ThemeEntry<Themes> | undefined,
+	options?:
+		| { element?: Element | 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/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 undefined to remove
+ * @param options - Cookie options
+ */
+export function writeCookieTheme<Themes extends ThemeMap>(
+	_themes: Themes,
+	entry: ThemeEntry<Themes> | undefined,
+	options: WriteCookieThemeOptions<Themes>
+): void {
+	const { cookieName, path = '/', maxAge, sameSite, secure } = options
+
+	if (typeof document === 'undefined' || document.cookie === undefined) {
+		return
+	}
+
+	if (entry === undefined) {
+		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 = ' '