@just-web/toolkits 2.0.0 → 2.1.0

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,7 +19,7 @@ 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

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
 }