@just-web/toolkits 2.0.0 → 3.0.0

package/src/react/hooks/use-attribute.ts

@@ -6,47 +6,46 @@ import { observeAttributes } from '../../attributes/observe-attribute.ts'
  * and a setter to update it. Stays in sync when the attribute changes (e.g. from elsewhere).
  *
  * @param attributeName - The attribute to observe (e.g. `'class'`, `'data-theme'`).
- * @param element - The element to observe. Defaults to `document.documentElement` when omitted.
- * @returns Tuple of [value, setValue]. Pass null to setValue to remove the attribute.
+ * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement` when omitted.
+ * @returns Tuple of [value, setValue]. Pass null or undefined to setValue to remove the attribute.
  *
  * @example
  * ```tsx
  * const [className, setClassName] = useAttribute('class')
  * const [theme, setTheme] = useAttribute('data-theme', myElement)
  * setTheme('dark')
- * setClassName(null) // removes class attribute
+ * setClassName(undefined) // removes class attribute
  * ```
  */
 export function useAttribute(
 	attributeName: string,
-	element: Element | undefined = typeof document !== 'undefined'
+	element: Element | null | undefined = typeof document !== 'undefined'
 		? document.documentElement
 		: undefined
-): [string | null, (value: string | null) => void] {
-	const [value, setValueState] = useState<string | null>(
-		() => element?.getAttribute(attributeName) ?? null
+): [string | undefined, (value: string | null | undefined) => void] {
+	const [value, setValueState] = useState<string | undefined>(
+		() => element?.getAttribute(attributeName) ?? undefined
 	)
 
 	useEffect(() => {
 		if (!element) return
 
-		setValueState(element.getAttribute(attributeName))
+		setValueState(element.getAttribute(attributeName) ?? undefined)
 
-		const observer = observeAttributes(
+		return observeAttributes(
 			{
 				[attributeName]: (next) => {
-					setValueState(next)
+					setValueState(next ?? undefined)
 				}
 			},
 			element
 		)
-		return () => observer.disconnect()
 	}, [element, attributeName])
 
 	const setValue = useCallback(
-		(next: string | null) => {
+		(next: string | null | undefined) => {
 			if (!element) return
-			if (next === null) {
+			if (next == null) {
 				element.removeAttribute(attributeName)
 			} else {
 				element.setAttribute(attributeName, next)

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

@@ -11,7 +11,7 @@ import { classNameThemeStore } from '../../theme/theme-store/class-name-theme-st
  *
  * @param themes - Record mapping theme keys to their class name values
  * @param options.theme - Fallback theme key when no matching class is found
- * @param options.element - Element to read/set theme on (defaults to document.documentElement)
+ * @param options.element - Element to read/set theme on (accepts null e.g. from refs). Defaults to document.documentElement.
  * @returns Tuple of [currentTheme, setTheme]
  *
  * @example
@@ -32,7 +32,7 @@ export function useThemeByClassName<Themes extends ThemeMap>(
 	themes: Themes,
 	options?: {
 		defaultTheme?: keyof Themes | undefined
-		element?: Element | undefined
+		element?: Element | null | undefined
 	}
 ): [keyof Themes | undefined, (theme: keyof Themes) => void] {
 	const element =

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

@@ -12,7 +12,7 @@ import { dataAttributeThemeStore } from '../../theme/theme-store/data-attribute-
  * @param themes - Record mapping theme keys to their data attribute values
  * @param options.attributeName - Data attribute name (e.g. `data-theme`)
  * @param options.defaultTheme - Fallback theme key when no matching attribute value is found
- * @param options.element - Element to read/set theme on (defaults to document.documentElement)
+ * @param options.element - Element to read/set theme on (accepts null e.g. from refs). Defaults to document.documentElement.
  * @returns Tuple of [currentTheme, setTheme]
  *
  * @example
@@ -37,7 +37,7 @@ export function useThemeByDataAttribute<Themes extends ThemeMap>(
 	options: {
 		attributeName: `data-${string}`
 		defaultTheme?: keyof Themes | undefined
-		element?: Element | undefined
+		element?: Element | null | undefined
 	}
 ): [keyof Themes | undefined, (theme: keyof Themes) => void] {
 	const element =

package/src/react/theme/create-theme-hook.ts

@@ -101,16 +101,14 @@ function createSharedChannel<Themes extends ThemeMap>(
 		}
 	}
 
-	const handleStoreUpdate = (entry: ThemeEntry<Themes> | undefined | null) => {
+	const handleStoreUpdate = (entry: ThemeEntry<Themes> | undefined) => {
 		notify(entry?.theme ?? defaultTheme)
 	}
 
 	// Initial read to populate lastTheme (compose store subscribe has no initial notify)
-	void Promise.resolve(composedStore.read()).then(
-		(entry: ThemeEntry<Themes> | undefined | null) => {
-			notify(entry?.theme ?? defaultTheme)
-		}
-	)
+	void Promise.resolve(composedStore.read()).then((entry: ThemeEntry<Themes> | undefined) => {
+		notify(entry?.theme ?? defaultTheme)
+	})
 
 	let unobserve: () => void = composedStore.subscribe(handleStoreUpdate)
 	let isSubscribedToStore = true

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

@@ -38,12 +38,12 @@ function getCanonicalShapeAndComparable(v: ThemeMapValue): {
  * 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
+ * @param value - Raw string from localStorage/sessionStorage/cookie (accepts null)
  * @returns ThemeEntry when valid, otherwise undefined
  */
 export function parseStoredTheme<Themes extends ThemeMap>(
 	themes: Themes | undefined,
-	value: string | undefined
+	value: string | null | undefined
 ): ThemeEntry<Themes> | undefined {
 	const parsed = tryParseJSON<{ theme: string; value?: unknown }>(value ?? null)
 	if (!parsed?.theme || typeof parsed.theme !== 'string') return undefined

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

@@ -12,12 +12,12 @@ import type { ThemeMap } from '../theme-map.types.ts'
  * 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)
+ * @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 | undefined
+	className: string | null | undefined
 ): ThemeEntry<Themes> | undefined {
 	const cls = className ?? ''
 	const theme = findKey(themes, (key) => {

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

@@ -6,14 +6,14 @@ 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.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 | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
 		| undefined
 ): ThemeEntry<Themes> | undefined {
 	const element = options?.element ?? document?.documentElement

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

@@ -10,23 +10,23 @@ import type { ThemeMap } from '../theme-map.types.ts'
  * (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)
+ * @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 | undefined,
-	entry: ThemeEntry<Themes> | undefined
+	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 existingClasses = (existing ?? '')?.trim() ? (existing ?? '').trim().split(/\s+/) : []
 	const withoutThemes = existingClasses.filter((c) => !allThemeClasses.includes(c))
 	const activeClasses =
-		entry !== undefined
+		entry != null
 			? (() => {
 					const resolved = resolveThemeMapValue(entry.value)
 					return Array.isArray(resolved) ? [...resolved] : [resolved]

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

@@ -8,7 +8,7 @@ import { parseClassName } from './parse-class-name.ts'
  *
  * @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.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).
  */
@@ -16,14 +16,14 @@ export function subscribeClassName<Themes extends ThemeMap>(
 	themes: Themes,
 	handler: (entry: ThemeEntry<Themes> | undefined) => void,
 	options?:
-		| { element?: Element | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| { 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(
+	return observeAttributes(
 		{
 			class: (value) => {
 				const entry = parse(themes, value ?? undefined)
@@ -35,5 +35,4 @@ export function subscribeClassName<Themes extends ThemeMap>(
 		},
 		element
 	)
-	return () => observer.disconnect()
 }

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

@@ -6,15 +6,15 @@ 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 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> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options?:
-		| { element?: Element | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
+		| { element?: Element | null | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
 		| undefined
 ): void {
 	const element = options?.element ?? document?.documentElement

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/write-cookie-theme.ts

@@ -16,12 +16,12 @@ export interface WriteCookieThemeOptions<_Themes extends ThemeMap = ThemeMap> {
  * 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 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> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options: WriteCookieThemeOptions<Themes>
 ): void {
 	const { cookieName, path = '/', maxAge, sameSite, secure } = options
@@ -30,7 +30,7 @@ export function writeCookieTheme<Themes extends ThemeMap>(
 		return
 	}
 
-	if (entry === undefined) {
+	if (entry == null) {
 		deleteCookie(cookieName, path)
 		return
 	}

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

@@ -10,13 +10,13 @@ import { SEPARATOR_SPACE } from './_constant.ts'
  * 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)
+ * @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 | undefined,
+	value: string | null | undefined,
 	options?: { separator?: string | undefined } | undefined
 ): ThemeEntry<Themes> | undefined {
 	const separator = options?.separator ?? SEPARATOR_SPACE

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

@@ -9,7 +9,7 @@ import { parseDataAttribute } from './parse-data-attribute.ts'
  *
  * @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 (defaults to document.documentElement)
+ * @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).
  */
@@ -17,7 +17,7 @@ export function readDataAttribute<Themes extends ThemeMap>(
 	themes: Themes,
 	attributeName: `data-${string}`,
 	options?:
-		| { element?: Element | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| { element?: Element | null | undefined; parse?: ParseStoredTheme<Themes> | undefined }
 		| undefined
 ): ThemeEntry<Themes> | undefined {
 	const element = options?.element ?? document?.documentElement

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

@@ -10,15 +10,15 @@ import { SEPARATOR_SPACE } from './_constant.ts'
  * Aligns with stringifyClassName logic.
  *
  * @param themes - Record mapping theme keys to attribute values (used to identify theme tokens)
- * @param existing - Current attribute value string
- * @param entry - Theme entry to stringify, or undefined to clear theme (keeps non-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 | undefined,
-	entry: ThemeEntry<Themes> | undefined,
+	existing: string | null | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options?: { separator?: string | undefined } | undefined
 ): string {
 	const separator = options?.separator ?? SEPARATOR_SPACE
@@ -26,10 +26,10 @@ export function stringifyDataAttribute<Themes extends ThemeMap>(
 		const resolved = resolveThemeMapValue(v)
 		return Array.isArray(resolved) ? [...resolved] : [resolved]
 	})
-	const existingTokens = existing?.trim() ? existing.trim().split(separator) : []
+	const existingTokens = (existing ?? '')?.trim() ? (existing ?? '').trim().split(separator) : []
 	const withoutThemeValues = existingTokens.filter((t) => !allThemeValues.includes(t.trim()))
 	const newTokens =
-		entry !== undefined
+		entry != null
 			? (() => {
 					const resolved = resolveThemeMapValue(entry.value)
 					return Array.isArray(resolved) ? [resolved[0]] : [resolved]

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

@@ -10,7 +10,7 @@ import { parseDataAttribute } from './parse-data-attribute.ts'
  * @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 (defaults to document.documentElement)
+ * @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).
  */
@@ -19,14 +19,14 @@ export function subscribeDataAttribute<Themes extends ThemeMap>(
 	attributeName: `data-${string}`,
 	handler: (entry: ThemeEntry<Themes> | undefined) => void,
 	options?:
-		| { element?: Element | undefined; parse?: ParseStoredTheme<Themes> | undefined }
+		| { 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}`>(
+	return observeDataAttributes<string, `data-${string}`>(
 		{
 			[attributeName]: (value) => {
 				const entry = parse(themes, value ?? undefined)
@@ -35,5 +35,4 @@ export function subscribeDataAttribute<Themes extends ThemeMap>(
 		},
 		element
 	)
-	return () => observer.disconnect()
 }

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

@@ -9,16 +9,16 @@ import { stringifyDataAttribute } from './stringify-data-attribute.ts'
  *
  * @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 undefined to remove the theme
- * @param options.element - Element to write to (defaults to document.documentElement)
+ * @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> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options?:
-		| { element?: Element | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
+		| { element?: Element | null | undefined; stringify?: StringifyStoredTheme<Themes> | undefined }
 		| undefined
 ): void {
 	const element = options?.element ?? document?.documentElement
@@ -26,7 +26,7 @@ export function writeDataAttribute<Themes extends ThemeMap>(
 	const stringify =
 		options?.stringify ??
 		((t, x, e) => stringifyDataAttribute(t, x, e, { separator: SEPARATOR_SPACE }))
-	if (entry === undefined) {
+	if (entry == null) {
 		element.removeAttribute(attributeName)
 		return
 	}

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

@@ -9,14 +9,14 @@ import { writeWebStorage } from '../web-storage/write-web-storage.ts'
  *
  * @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 undefined to remove
+ * @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> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options?: {
 		stringify?: StringifyStoredTheme<Themes> | undefined
 		onError?: ((error: unknown) => void) | undefined

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

@@ -9,14 +9,14 @@ import { writeWebStorage } from '../web-storage/write-web-storage.ts'
  *
  * @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 undefined to remove
+ * @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> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options?: {
 		stringify?: StringifyStoredTheme<Themes> | undefined
 		onError?: ((error: unknown) => void) | undefined

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

@@ -13,18 +13,20 @@ export interface ThemeEntry<Themes extends ThemeMap = ThemeMap> {
 /**
  * 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 | undefined
+	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 | undefined,
-	entry: ThemeEntry<Themes> | undefined
+	existing: string | null | undefined,
+	entry: ThemeEntry<Themes> | null | undefined
 ) => string

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

@@ -13,7 +13,7 @@ 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
@@ -30,7 +30,7 @@ import type { ThemeStore } from '../theme-store.types.ts'
 export function classNameThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
 	options?: {
-		element?: Element | undefined
+		element?: Element | null | undefined
 		parse?: ParseStoredTheme<Themes> | undefined
 		stringify?: StringifyStoredTheme<Themes> | undefined
 	}

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

@@ -19,7 +19,7 @@ import type { ThemeStore } from '../theme-store.types.ts'
  *
  * @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
@@ -47,7 +47,7 @@ export function dataAttributeThemeStore<Themes extends ThemeMap>(
 	themes: Themes,
 	options: {
 		attributeName: `data-${string}`
-		element?: Element | undefined
+		element?: Element | null | undefined
 		parse?: ParseStoredTheme<Themes> | undefined
 		stringify?: StringifyStoredTheme<Themes> | undefined
 	}

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/theme-store.types.ts

@@ -24,7 +24,5 @@ import type { ThemeMap } from '../theme-map.types.ts'
 export interface ThemeStore<Themes extends ThemeMap = ThemeMap> {
 	read?: (() => ThemeEntry<Themes> | undefined) | undefined
 	write?: ((entry: ThemeEntry<Themes> | undefined) => void) | undefined
-	subscribe?:
-		| ((handler: (theme: ThemeEntry<Themes> | undefined | null) => void) => () => void)
-		| undefined
+	subscribe?: ((handler: (theme: ThemeEntry<Themes> | undefined) => void) => () => void) | undefined
 }

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

@@ -4,9 +4,9 @@ import type { ThemeMap } from '../theme-map.types.ts'
 function defaultStringify<Themes extends ThemeMap>(
 	_themes: Themes,
 	_existing: string | undefined,
-	entry: ThemeEntry<Themes> | undefined
+	entry: ThemeEntry<Themes> | null | undefined
 ): string {
-	return entry === undefined ? '' : JSON.stringify(entry)
+	return entry == null ? '' : JSON.stringify(entry)
 }
 
 /**
@@ -16,7 +16,7 @@ function defaultStringify<Themes extends ThemeMap>(
  *
  * @param themes - Record mapping theme keys to values (used by stringify)
  * @param storageKey - Storage key to write to
- * @param entry - Theme entry to write, or undefined to remove
+ * @param entry - Theme entry to write, or null/undefined to remove
  * @param options.storage - Storage object (localStorage or sessionStorage)
  * @param options.stringify - Custom serializer (default: JSON.stringify)
  * @param options.onError - Optional callback invoked when setItem/removeItem throws
@@ -24,7 +24,7 @@ function defaultStringify<Themes extends ThemeMap>(
 export function writeWebStorage<Themes extends ThemeMap>(
 	themes: Themes,
 	storageKey: string,
-	entry: ThemeEntry<Themes> | undefined,
+	entry: ThemeEntry<Themes> | null | undefined,
 	options: {
 		storage: Storage
 		stringify?: StringifyStoredTheme<Themes> | undefined
@@ -33,7 +33,7 @@ export function writeWebStorage<Themes extends ThemeMap>(
 ): void {
 	const { storage, stringify = defaultStringify, onError } = options
 	try {
-		if (entry === undefined) {
+		if (entry == null) {
 			storage.removeItem(storageKey)
 		} else {
 			const existing = storage.getItem(storageKey) ?? undefined

package/src/utils/append-id.ts

@@ -1,10 +1,10 @@
 /**
  * Appends a suffix to an ID if the ID is defined.
  *
- * @param id - The ID to append the suffix to.
+ * @param id - The ID to append the suffix to (accepts null e.g. from getAttribute).
  * @param suffix - The suffix to append to the ID.
- * @returns The ID with the suffix appended, or undefined if the ID is undefined.
+ * @returns The ID with the suffix appended, or undefined if the ID is null/undefined.
  */
-export function appendId(id: string | undefined, suffix: string): string | undefined {
+export function appendId(id: string | null | undefined, suffix: string): string | undefined {
 	return id ? `${id}-${suffix}` : undefined
 }