@just-web/toolkits 2.0.0 → 2.1.0

package/dist/theme/web-storage/write-web-storage.cjs

@@ -1,7 +1,7 @@
 
 //#region src/theme/web-storage/write-web-storage.ts
 function defaultStringify(_themes, _existing, entry) {
-	return entry === void 0 ? "" : JSON.stringify(entry);
+	return entry == null ? "" : JSON.stringify(entry);
 }
 /**
 * Writes a theme entry to a web storage (localStorage or sessionStorage).
@@ -10,7 +10,7 @@ function defaultStringify(_themes, _existing, entry) {
 *
 * @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
@@ -18,7 +18,7 @@ function defaultStringify(_themes, _existing, entry) {
 function writeWebStorage(themes, storageKey, entry, options) {
 	const { storage, stringify = defaultStringify, onError } = options;
 	try {
-		if (entry === void 0) storage.removeItem(storageKey);
+		if (entry == null) storage.removeItem(storageKey);
 		else {
 			const value = stringify(themes, storage.getItem(storageKey) ?? void 0, entry);
 			storage.setItem(storageKey, value);

package/dist/theme/web-storage/write-web-storage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"write-web-storage.cjs","names":[],"sources":["../../../src/theme/web-storage/write-web-storage.ts"],"sourcesContent":["import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'\nimport type { ThemeMap } from '../theme-map.types.ts'\n\nfunction defaultStringify<Themes extends ThemeMap>(\n\t_themes: Themes,\n\t_existing: string | undefined,\n\tentry: ThemeEntry<Themes> | undefined\n): string {\n\treturn entry === undefined ? '' : JSON.stringify(entry)\n}\n\n/**\n * Writes a theme entry to a web storage (localStorage or sessionStorage).\n *\n * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.\n *\n * @param themes - Record mapping theme keys to values (used by stringify)\n * @param storageKey - Storage key to write to\n * @param entry - Theme entry to write, or undefined to remove\n * @param options.storage - Storage object (localStorage or sessionStorage)\n * @param options.stringify - Custom serializer (default: JSON.stringify)\n * @param options.onError - Optional callback invoked when setItem/removeItem throws\n */\nexport function writeWebStorage<Themes extends ThemeMap>(\n\tthemes: Themes,\n\tstorageKey: string,\n\tentry: ThemeEntry<Themes> | undefined,\n\toptions: {\n\t\tstorage: Storage\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t\tonError?: ((error: unknown) => void) | undefined\n\t}\n): void {\n\tconst { storage, stringify = defaultStringify, onError } = options\n\ttry {\n\t\tif (entry === undefined) {\n\t\t\tstorage.removeItem(storageKey)\n\t\t} else {\n\t\t\tconst existing = storage.getItem(storageKey) ?? undefined\n\t\t\tconst value = stringify(themes, existing, entry)\n\t\t\tstorage.setItem(storageKey, value)\n\t\t}\n\t} catch (error) {\n\t\tonError?.(error)\n\t}\n}\n"],"mappings":";;AAGA,SAAS,iBACR,SACA,WACA,OACS;AACT,QAAO,UAAU,SAAY,KAAK,KAAK,UAAU,MAAM;;;;;;;;;;;;;;AAexD,SAAgB,gBACf,QACA,YACA,OACA,SAKO;CACP,MAAM,EAAE,SAAS,YAAY,kBAAkB,YAAY;AAC3D,KAAI;AACH,MAAI,UAAU,OACb,SAAQ,WAAW,WAAW;OACxB;GAEN,MAAM,QAAQ,UAAU,QADP,QAAQ,QAAQ,WAAW,IAAI,QACN,MAAM;AAChD,WAAQ,QAAQ,YAAY,MAAM;;UAE3B,OAAO;AACf,YAAU,MAAM"}
+{"version":3,"file":"write-web-storage.cjs","names":[],"sources":["../../../src/theme/web-storage/write-web-storage.ts"],"sourcesContent":["import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'\nimport type { ThemeMap } from '../theme-map.types.ts'\n\nfunction defaultStringify<Themes extends ThemeMap>(\n\t_themes: Themes,\n\t_existing: string | undefined,\n\tentry: ThemeEntry<Themes> | null | undefined\n): string {\n\treturn entry == null ? '' : JSON.stringify(entry)\n}\n\n/**\n * Writes a theme entry to a web storage (localStorage or sessionStorage).\n *\n * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.\n *\n * @param themes - Record mapping theme keys to values (used by stringify)\n * @param storageKey - Storage key to write to\n * @param entry - Theme entry to write, or null/undefined to remove\n * @param options.storage - Storage object (localStorage or sessionStorage)\n * @param options.stringify - Custom serializer (default: JSON.stringify)\n * @param options.onError - Optional callback invoked when setItem/removeItem throws\n */\nexport function writeWebStorage<Themes extends ThemeMap>(\n\tthemes: Themes,\n\tstorageKey: string,\n\tentry: ThemeEntry<Themes> | null | undefined,\n\toptions: {\n\t\tstorage: Storage\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t\tonError?: ((error: unknown) => void) | undefined\n\t}\n): void {\n\tconst { storage, stringify = defaultStringify, onError } = options\n\ttry {\n\t\tif (entry == null) {\n\t\t\tstorage.removeItem(storageKey)\n\t\t} else {\n\t\t\tconst existing = storage.getItem(storageKey) ?? undefined\n\t\t\tconst value = stringify(themes, existing, entry)\n\t\t\tstorage.setItem(storageKey, value)\n\t\t}\n\t} catch (error) {\n\t\tonError?.(error)\n\t}\n}\n"],"mappings":";;AAGA,SAAS,iBACR,SACA,WACA,OACS;AACT,QAAO,SAAS,OAAO,KAAK,KAAK,UAAU,MAAM;;;;;;;;;;;;;;AAelD,SAAgB,gBACf,QACA,YACA,OACA,SAKO;CACP,MAAM,EAAE,SAAS,YAAY,kBAAkB,YAAY;AAC3D,KAAI;AACH,MAAI,SAAS,KACZ,SAAQ,WAAW,WAAW;OACxB;GAEN,MAAM,QAAQ,UAAU,QADP,QAAQ,QAAQ,WAAW,IAAI,QACN,MAAM;AAChD,WAAQ,QAAQ,YAAY,MAAM;;UAE3B,OAAO;AACf,YAAU,MAAM"}

package/dist/theme/web-storage/write-web-storage.d.cts

@@ -10,12 +10,12 @@ import { StringifyStoredTheme, ThemeEntry } from "../theme-entry.types.cjs";
  *
  * @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
  */
-declare function writeWebStorage<Themes extends ThemeMap>(themes: Themes, storageKey: string, entry: ThemeEntry<Themes> | undefined, options: {
+declare function writeWebStorage<Themes extends ThemeMap>(themes: Themes, storageKey: string, entry: ThemeEntry<Themes> | null | undefined, options: {
   storage: Storage;
   stringify?: StringifyStoredTheme<Themes> | undefined;
   onError?: ((error: unknown) => void) | undefined;

package/dist/theme/web-storage/write-web-storage.d.mts

@@ -10,12 +10,12 @@ import { StringifyStoredTheme, ThemeEntry } from "../theme-entry.types.mjs";
  *
  * @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
  */
-declare function writeWebStorage<Themes extends ThemeMap>(themes: Themes, storageKey: string, entry: ThemeEntry<Themes> | undefined, options: {
+declare function writeWebStorage<Themes extends ThemeMap>(themes: Themes, storageKey: string, entry: ThemeEntry<Themes> | null | undefined, options: {
   storage: Storage;
   stringify?: StringifyStoredTheme<Themes> | undefined;
   onError?: ((error: unknown) => void) | undefined;

package/dist/theme/web-storage/write-web-storage.mjs

@@ -1,6 +1,6 @@
 //#region src/theme/web-storage/write-web-storage.ts
 function defaultStringify(_themes, _existing, entry) {
-	return entry === void 0 ? "" : JSON.stringify(entry);
+	return entry == null ? "" : JSON.stringify(entry);
 }
 /**
 * Writes a theme entry to a web storage (localStorage or sessionStorage).
@@ -9,7 +9,7 @@ function defaultStringify(_themes, _existing, entry) {
 *
 * @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
@@ -17,7 +17,7 @@ function defaultStringify(_themes, _existing, entry) {
 function writeWebStorage(themes, storageKey, entry, options) {
 	const { storage, stringify = defaultStringify, onError } = options;
 	try {
-		if (entry === void 0) storage.removeItem(storageKey);
+		if (entry == null) storage.removeItem(storageKey);
 		else {
 			const value = stringify(themes, storage.getItem(storageKey) ?? void 0, entry);
 			storage.setItem(storageKey, value);

package/dist/theme/web-storage/write-web-storage.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"write-web-storage.mjs","names":[],"sources":["../../../src/theme/web-storage/write-web-storage.ts"],"sourcesContent":["import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'\nimport type { ThemeMap } from '../theme-map.types.ts'\n\nfunction defaultStringify<Themes extends ThemeMap>(\n\t_themes: Themes,\n\t_existing: string | undefined,\n\tentry: ThemeEntry<Themes> | undefined\n): string {\n\treturn entry === undefined ? '' : JSON.stringify(entry)\n}\n\n/**\n * Writes a theme entry to a web storage (localStorage or sessionStorage).\n *\n * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.\n *\n * @param themes - Record mapping theme keys to values (used by stringify)\n * @param storageKey - Storage key to write to\n * @param entry - Theme entry to write, or undefined to remove\n * @param options.storage - Storage object (localStorage or sessionStorage)\n * @param options.stringify - Custom serializer (default: JSON.stringify)\n * @param options.onError - Optional callback invoked when setItem/removeItem throws\n */\nexport function writeWebStorage<Themes extends ThemeMap>(\n\tthemes: Themes,\n\tstorageKey: string,\n\tentry: ThemeEntry<Themes> | undefined,\n\toptions: {\n\t\tstorage: Storage\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t\tonError?: ((error: unknown) => void) | undefined\n\t}\n): void {\n\tconst { storage, stringify = defaultStringify, onError } = options\n\ttry {\n\t\tif (entry === undefined) {\n\t\t\tstorage.removeItem(storageKey)\n\t\t} else {\n\t\t\tconst existing = storage.getItem(storageKey) ?? undefined\n\t\t\tconst value = stringify(themes, existing, entry)\n\t\t\tstorage.setItem(storageKey, value)\n\t\t}\n\t} catch (error) {\n\t\tonError?.(error)\n\t}\n}\n"],"mappings":";AAGA,SAAS,iBACR,SACA,WACA,OACS;AACT,QAAO,UAAU,SAAY,KAAK,KAAK,UAAU,MAAM;;;;;;;;;;;;;;AAexD,SAAgB,gBACf,QACA,YACA,OACA,SAKO;CACP,MAAM,EAAE,SAAS,YAAY,kBAAkB,YAAY;AAC3D,KAAI;AACH,MAAI,UAAU,OACb,SAAQ,WAAW,WAAW;OACxB;GAEN,MAAM,QAAQ,UAAU,QADP,QAAQ,QAAQ,WAAW,IAAI,QACN,MAAM;AAChD,WAAQ,QAAQ,YAAY,MAAM;;UAE3B,OAAO;AACf,YAAU,MAAM"}
+{"version":3,"file":"write-web-storage.mjs","names":[],"sources":["../../../src/theme/web-storage/write-web-storage.ts"],"sourcesContent":["import type { StringifyStoredTheme, ThemeEntry } from '../theme-entry.types.ts'\nimport type { ThemeMap } from '../theme-map.types.ts'\n\nfunction defaultStringify<Themes extends ThemeMap>(\n\t_themes: Themes,\n\t_existing: string | undefined,\n\tentry: ThemeEntry<Themes> | null | undefined\n): string {\n\treturn entry == null ? '' : JSON.stringify(entry)\n}\n\n/**\n * Writes a theme entry to a web storage (localStorage or sessionStorage).\n *\n * Performs setItem/removeItem only. Does not notify subscribers; the store must call notify() after this.\n *\n * @param themes - Record mapping theme keys to values (used by stringify)\n * @param storageKey - Storage key to write to\n * @param entry - Theme entry to write, or null/undefined to remove\n * @param options.storage - Storage object (localStorage or sessionStorage)\n * @param options.stringify - Custom serializer (default: JSON.stringify)\n * @param options.onError - Optional callback invoked when setItem/removeItem throws\n */\nexport function writeWebStorage<Themes extends ThemeMap>(\n\tthemes: Themes,\n\tstorageKey: string,\n\tentry: ThemeEntry<Themes> | null | undefined,\n\toptions: {\n\t\tstorage: Storage\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t\tonError?: ((error: unknown) => void) | undefined\n\t}\n): void {\n\tconst { storage, stringify = defaultStringify, onError } = options\n\ttry {\n\t\tif (entry == null) {\n\t\t\tstorage.removeItem(storageKey)\n\t\t} else {\n\t\t\tconst existing = storage.getItem(storageKey) ?? undefined\n\t\t\tconst value = stringify(themes, existing, entry)\n\t\t\tstorage.setItem(storageKey, value)\n\t\t}\n\t} catch (error) {\n\t\tonError?.(error)\n\t}\n}\n"],"mappings":";AAGA,SAAS,iBACR,SACA,WACA,OACS;AACT,QAAO,SAAS,OAAO,KAAK,KAAK,UAAU,MAAM;;;;;;;;;;;;;;AAelD,SAAgB,gBACf,QACA,YACA,OACA,SAKO;CACP,MAAM,EAAE,SAAS,YAAY,kBAAkB,YAAY;AAC3D,KAAI;AACH,MAAI,SAAS,KACZ,SAAQ,WAAW,WAAW;OACxB;GAEN,MAAM,QAAQ,UAAU,QADP,QAAQ,QAAQ,WAAW,IAAI,QACN,MAAM;AAChD,WAAQ,QAAQ,YAAY,MAAM;;UAE3B,OAAO;AACf,YAAU,MAAM"}

package/dist/utils/append-id.cjs

@@ -3,9 +3,9 @@
 /**
 * 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.
 */
 function appendId(id, suffix) {
 	return id ? `${id}-${suffix}` : void 0;

package/dist/utils/append-id.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"append-id.cjs","names":[],"sources":["../../src/utils/append-id.ts"],"sourcesContent":["/**\n * Appends a suffix to an ID if the ID is defined.\n *\n * @param id - The ID to append the suffix to.\n * @param suffix - The suffix to append to the ID.\n * @returns The ID with the suffix appended, or undefined if the ID is undefined.\n */\nexport function appendId(id: string | undefined, suffix: string): string | undefined {\n\treturn id ? `${id}-${suffix}` : undefined\n}\n"],"mappings":";;;;;;;;;AAOA,SAAgB,SAAS,IAAwB,QAAoC;AACpF,QAAO,KAAK,GAAG,GAAG,GAAG,WAAW"}
+{"version":3,"file":"append-id.cjs","names":[],"sources":["../../src/utils/append-id.ts"],"sourcesContent":["/**\n * Appends a suffix to an ID if the ID is defined.\n *\n * @param id - The ID to append the suffix to (accepts null e.g. from getAttribute).\n * @param suffix - The suffix to append to the ID.\n * @returns The ID with the suffix appended, or undefined if the ID is null/undefined.\n */\nexport function appendId(id: string | null | undefined, suffix: string): string | undefined {\n\treturn id ? `${id}-${suffix}` : undefined\n}\n"],"mappings":";;;;;;;;;AAOA,SAAgB,SAAS,IAA+B,QAAoC;AAC3F,QAAO,KAAK,GAAG,GAAG,GAAG,WAAW"}

package/dist/utils/append-id.d.cts

@@ -2,11 +2,11 @@
 /**
  * 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.
  */
-declare function appendId(id: string | undefined, suffix: string): string | undefined;
+declare function appendId(id: string | null | undefined, suffix: string): string | undefined;
 //#endregion
 export { appendId };
 //# sourceMappingURL=append-id.d.cts.map

package/dist/utils/append-id.d.mts

@@ -2,11 +2,11 @@
 /**
  * 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.
  */
-declare function appendId(id: string | undefined, suffix: string): string | undefined;
+declare function appendId(id: string | null | undefined, suffix: string): string | undefined;
 //#endregion
 export { appendId };
 //# sourceMappingURL=append-id.d.mts.map

package/dist/utils/append-id.mjs

@@ -2,9 +2,9 @@
 /**
 * 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.
 */
 function appendId(id, suffix) {
 	return id ? `${id}-${suffix}` : void 0;

package/dist/utils/append-id.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"append-id.mjs","names":[],"sources":["../../src/utils/append-id.ts"],"sourcesContent":["/**\n * Appends a suffix to an ID if the ID is defined.\n *\n * @param id - The ID to append the suffix to.\n * @param suffix - The suffix to append to the ID.\n * @returns The ID with the suffix appended, or undefined if the ID is undefined.\n */\nexport function appendId(id: string | undefined, suffix: string): string | undefined {\n\treturn id ? `${id}-${suffix}` : undefined\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,SAAS,IAAwB,QAAoC;AACpF,QAAO,KAAK,GAAG,GAAG,GAAG,WAAW"}
+{"version":3,"file":"append-id.mjs","names":[],"sources":["../../src/utils/append-id.ts"],"sourcesContent":["/**\n * Appends a suffix to an ID if the ID is defined.\n *\n * @param id - The ID to append the suffix to (accepts null e.g. from getAttribute).\n * @param suffix - The suffix to append to the ID.\n * @returns The ID with the suffix appended, or undefined if the ID is null/undefined.\n */\nexport function appendId(id: string | null | undefined, suffix: string): string | undefined {\n\treturn id ? `${id}-${suffix}` : undefined\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,SAAS,IAA+B,QAAoC;AAC3F,QAAO,KAAK,GAAG,GAAG,GAAG,WAAW"}

package/package.json

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

package/src/attributes/get-attribute.ts

@@ -2,7 +2,7 @@
  * Gets the value of an attribute from an element.
  *
  * @param qualifiedName - The name of the attribute to get
- * @param element - The element to get the attribute from. Defaults to `document.documentElement`
+ * @param element - The element to get the attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`
  * @returns The attribute value cast to type T, or null if the attribute doesn't exist
  *
  * @example
@@ -14,7 +14,10 @@
  * const testId = getAttribute('data-testid', element)
  * ```
  */
-export function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined) {
+export function getAttribute<T extends string>(
+	qualifiedName: T,
+	element?: Element | null | undefined
+) {
 	element = element ?? globalThis.document.documentElement
 	return element.getAttribute(qualifiedName)
 }

package/src/attributes/get-data-attribute.ts

@@ -5,11 +5,14 @@ import { getAttribute } from './get-attribute.ts'
  * Gets the value of a data attribute from an element.
  *
  * @param qualifiedName - The name of the data attribute to get
- * @param element - The element to get the data attribute from. Defaults to `document.documentElement`
+ * @param element - The element to get the data attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`
  * @returns The data attribute value, or null if the attribute doesn't exist
  *
  * @example
  */
-export function getDataAttribute(qualifiedName: DataAttribute, element?: Element | undefined) {
+export function getDataAttribute(
+	qualifiedName: DataAttribute,
+	element?: Element | null | undefined
+) {
 	return getAttribute(qualifiedName, element)
 }

package/src/attributes/observe-attribute.ts

@@ -2,7 +2,7 @@
  * Observes attributes changes on an element and calls corresponding handlers.
  *
  * @param handlers - An object mapping attribute names to handler functions.
- * @param element - The element to observe. Defaults to `document.documentElement`.
+ * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`.
  * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer.
  *
  * @example
@@ -18,7 +18,7 @@
  */
 export function observeAttributes<T extends string>(
 	handlers: Record<string, (value: T | null) => void>,
-	element?: Element | undefined
+	element?: Element | null | undefined
 ) {
 	element = element ?? globalThis.document.documentElement
 	const observer = new MutationObserver((mutations) => {

package/src/attributes/observe-data-attribute.ts

@@ -5,7 +5,7 @@ import { observeAttributes } from './observe-attribute.ts'
  *
  * @param options - Configuration options
  * @param options.handlers - An object mapping `data-*` attribute names to handler functions.
- * @param options.element - The element to observe. Defaults to `document.documentElement`
+ * @param options.element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`
  * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer
  *
  * @example
@@ -23,7 +23,7 @@ import { observeAttributes } from './observe-attribute.ts'
  */
 export function observeDataAttributes<T extends string, K extends `data-${string}`>(
 	handlers: Record<K, (value: T | null) => void>,
-	element?: Element | undefined
+	element?: Element | null | undefined
 ) {
 	return observeAttributes(handlers, element)
 }

package/src/color-scheme/color-scheme.types.ts

@@ -0,0 +1,7 @@
+/**
+ * The color scheme of the system.
+ *
+ * Per {@link https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme Media Queries Level 5 § prefers-color-scheme},
+ * these are the only valid values exposed by the `prefers-color-scheme` media feature.
+ */
+export type ColorScheme = 'light' | 'dark'

package/src/color-scheme/get-prefers-color-scheme.ts

@@ -1,17 +1,19 @@
+import type { ColorScheme } from './color-scheme.types.ts'
+
 /**
  * Gets the current preferred color scheme.
  * It can only be 'light' or 'dark'.
  *
- * Even if the browser preference is 'auto'/'device', it will return 'light' or 'dark'.
+ * Per {@link https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme Media Queries Level 5},
+ * the `prefers-color-scheme` media feature has only two valid values. Even if the browser
+ * preference is 'auto'/'device', it will return 'light' or 'dark'.
  *
  * When `matchMedia` is unavailable (e.g. SSR), returns `defaultColorScheme`.
  *
  * @param defaultColorScheme - Fallback when `matchMedia` is unavailable (default: `'light'`)
  * @returns 'light' or 'dark'
  */
-export function getPrefersColorScheme(
-	defaultColorScheme: 'light' | 'dark' = 'light'
-): 'light' | 'dark' {
+export function getPrefersColorScheme(defaultColorScheme: ColorScheme = 'light'): ColorScheme {
 	if (typeof matchMedia === 'undefined') return defaultColorScheme
 	return matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
 }

package/src/color-scheme/observe-prefers-color-scheme.ts

@@ -1,3 +1,5 @@
+import type { ColorScheme } from './color-scheme.types.ts'
+
 /**
  * Observes system color scheme preference changes and calls handlers when they occur.
  *
@@ -13,7 +15,7 @@
  * cleanup()
  * ```
  */
-export function observePrefersColorScheme(handler: (value: 'light' | 'dark') => void) {
+export function observePrefersColorScheme(handler: (value: ColorScheme) => void) {
 	const m = globalThis.matchMedia('(prefers-color-scheme: light)')
 	const listener = (event: MediaQueryListEvent) => {
 		handler(event.matches ? 'light' : 'dark')

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './class-name/class-name-props.ts'
 export * from './class-name/clsx.ts'
 export * from './class-name/just-class-name.ts'
 export * from './class-name/resolve-class-name.ts'
+export * from './color-scheme/color-scheme.types.ts'
 export * from './color-scheme/get-prefers-color-scheme.ts'
 export * from './color-scheme/observe-prefers-color-scheme.ts'
 export * from './style/css-properties.ts'

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

@@ -6,36 +6,36 @@ 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(
 			{
 				[attributeName]: (next) => {
-					setValueState(next)
+					setValueState(next ?? undefined)
 				}
 			},
 			element
@@ -44,9 +44,9 @@ export function useAttribute(
 	}, [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,7 +16,7 @@ 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

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
 	}