@just-web/toolkits 2.0.0 → 3.0.0

package/dist/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.d.cts

@@ -14,7 +14,7 @@ import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "../../theme-
  *
  * @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
@@ -40,13 +40,13 @@ import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "../../theme-
  */
 declare 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;
 }): {
   read(): ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { dataAttributeThemeStore };

package/dist/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.d.mts

@@ -14,7 +14,7 @@ import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "../../theme-
  *
  * @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
@@ -40,13 +40,13 @@ import { ParseStoredTheme, StringifyStoredTheme, ThemeEntry } from "../../theme-
  */
 declare 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;
 }): {
   read(): ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { dataAttributeThemeStore };

package/dist/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.mjs

@@ -17,7 +17,7 @@ import { writeDataAttribute } from "../../data-attribute/write-data-attribute.mj
 *
 * @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

package/dist/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"data-attribute-theme-store.mjs","names":[],"sources":["../../../../src/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts"],"sourcesContent":["import { SEPARATOR_SPACE } from '../../data-attribute/_constant.ts'\nimport { parseDataAttribute } from '../../data-attribute/parse-data-attribute.ts'\nimport { readDataAttribute } from '../../data-attribute/read-data-attribute.ts'\nimport { stringifyDataAttribute } from '../../data-attribute/stringify-data-attribute.ts'\nimport { subscribeDataAttribute } from '../../data-attribute/subscribe-data-attribute.ts'\nimport { writeDataAttribute } from '../../data-attribute/write-data-attribute.ts'\nimport type { ParseStoredTheme, StringifyStoredTheme } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * Creates a theme store that reads and writes via a data attribute.\n *\n * read: parse(themes, getDataAttribute(element, attribute)) → ThemeEntry\n * write: setAttribute(attribute, stringify(themes, getDataAttribute(element, attribute), entry))\n *\n * Supports space-separated attribute values by default. Use `parse` and `stringify` to customize\n * (e.g. comma-separated via curried parseDataAttribute/stringifyDataAttribute).\n *\n * @param themes - Record mapping theme keys to attribute values\n * @param options.attributeName - Data attribute name (e.g. `data-theme`)\n * @param options.element - Element to operate on (defaults to document.documentElement)\n * @param options.parse - Custom parser (default: parseDataAttribute with space separator)\n * @param options.stringify - Custom serializer (default: stringifyDataAttribute with space separator)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'current', grayscale: 'grayscale' }\n * const store = dataAttributeThemeStore(themes, { attributeName: 'data-theme' })\n * store.read() // returns ThemeEntry from data attribute\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((entry) => {})\n * ```\n *\n * @example\n * ```ts\n * // Comma-separated\n * const store = dataAttributeThemeStore(themes, {\n *   attributeName: 'data-theme',\n *   parse: (t, v) => parseDataAttribute(t, v, { separator: ',' }),\n *   stringify: (t, x, e) => stringifyDataAttribute(t, x, e, { separator: ',' })\n * })\n * ```\n */\nexport function dataAttributeThemeStore<Themes extends ThemeMap>(\n\tthemes: Themes,\n\toptions: {\n\t\tattributeName: `data-${string}`\n\t\telement?: Element | undefined\n\t\tparse?: ParseStoredTheme<Themes> | undefined\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t}\n) {\n\tconst element = options.element ?? document?.documentElement\n\tconst {\n\t\tattributeName,\n\t\tparse = (t, v) => parseDataAttribute(t, v, { separator: SEPARATOR_SPACE }),\n\t\tstringify = (t, x, e) => stringifyDataAttribute(t, x, e, { separator: SEPARATOR_SPACE })\n\t} = options\n\n\treturn {\n\t\tread() {\n\t\t\treturn readDataAttribute(themes, attributeName, { element, parse })\n\t\t},\n\t\twrite(entry) {\n\t\t\twriteDataAttribute(themes, attributeName, entry, { element, stringify })\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\treturn subscribeDataAttribute(themes, attributeName, handler, { element, parse })\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,wBACf,QACA,SAMC;CACD,MAAM,UAAU,QAAQ,WAAW,UAAU;CAC7C,MAAM,EACL,eACA,SAAS,GAAG,MAAM,mBAAmB,GAAG,GAAG,EAAE,WAAW,iBAAiB,CAAC,EAC1E,aAAa,GAAG,GAAG,MAAM,uBAAuB,GAAG,GAAG,GAAG,EAAE,WAAW,iBAAiB,CAAC,KACrF;AAEJ,QAAO;EACN,OAAO;AACN,UAAO,kBAAkB,QAAQ,eAAe;IAAE;IAAS;IAAO,CAAC;;EAEpE,MAAM,OAAO;AACZ,sBAAmB,QAAQ,eAAe,OAAO;IAAE;IAAS;IAAW,CAAC;;EAEzE,UAAU,SAAS;AAClB,UAAO,uBAAuB,QAAQ,eAAe,SAAS;IAAE;IAAS;IAAO,CAAC;;EAElF"}
+{"version":3,"file":"data-attribute-theme-store.mjs","names":[],"sources":["../../../../src/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts"],"sourcesContent":["import { SEPARATOR_SPACE } from '../../data-attribute/_constant.ts'\nimport { parseDataAttribute } from '../../data-attribute/parse-data-attribute.ts'\nimport { readDataAttribute } from '../../data-attribute/read-data-attribute.ts'\nimport { stringifyDataAttribute } from '../../data-attribute/stringify-data-attribute.ts'\nimport { subscribeDataAttribute } from '../../data-attribute/subscribe-data-attribute.ts'\nimport { writeDataAttribute } from '../../data-attribute/write-data-attribute.ts'\nimport type { ParseStoredTheme, StringifyStoredTheme } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * Creates a theme store that reads and writes via a data attribute.\n *\n * read: parse(themes, getDataAttribute(element, attribute)) → ThemeEntry\n * write: setAttribute(attribute, stringify(themes, getDataAttribute(element, attribute), entry))\n *\n * Supports space-separated attribute values by default. Use `parse` and `stringify` to customize\n * (e.g. comma-separated via curried parseDataAttribute/stringifyDataAttribute).\n *\n * @param themes - Record mapping theme keys to attribute values\n * @param options.attributeName - Data attribute name (e.g. `data-theme`)\n * @param options.element - Element to operate on (accepts null e.g. from refs). Defaults to document.documentElement.\n * @param options.parse - Custom parser (default: parseDataAttribute with space separator)\n * @param options.stringify - Custom serializer (default: stringifyDataAttribute with space separator)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'current', grayscale: 'grayscale' }\n * const store = dataAttributeThemeStore(themes, { attributeName: 'data-theme' })\n * store.read() // returns ThemeEntry from data attribute\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((entry) => {})\n * ```\n *\n * @example\n * ```ts\n * // Comma-separated\n * const store = dataAttributeThemeStore(themes, {\n *   attributeName: 'data-theme',\n *   parse: (t, v) => parseDataAttribute(t, v, { separator: ',' }),\n *   stringify: (t, x, e) => stringifyDataAttribute(t, x, e, { separator: ',' })\n * })\n * ```\n */\nexport function dataAttributeThemeStore<Themes extends ThemeMap>(\n\tthemes: Themes,\n\toptions: {\n\t\tattributeName: `data-${string}`\n\t\telement?: Element | null | undefined\n\t\tparse?: ParseStoredTheme<Themes> | undefined\n\t\tstringify?: StringifyStoredTheme<Themes> | undefined\n\t}\n) {\n\tconst element = options.element ?? document?.documentElement\n\tconst {\n\t\tattributeName,\n\t\tparse = (t, v) => parseDataAttribute(t, v, { separator: SEPARATOR_SPACE }),\n\t\tstringify = (t, x, e) => stringifyDataAttribute(t, x, e, { separator: SEPARATOR_SPACE })\n\t} = options\n\n\treturn {\n\t\tread() {\n\t\t\treturn readDataAttribute(themes, attributeName, { element, parse })\n\t\t},\n\t\twrite(entry) {\n\t\t\twriteDataAttribute(themes, attributeName, entry, { element, stringify })\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\treturn subscribeDataAttribute(themes, attributeName, handler, { element, parse })\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,wBACf,QACA,SAMC;CACD,MAAM,UAAU,QAAQ,WAAW,UAAU;CAC7C,MAAM,EACL,eACA,SAAS,GAAG,MAAM,mBAAmB,GAAG,GAAG,EAAE,WAAW,iBAAiB,CAAC,EAC1E,aAAa,GAAG,GAAG,MAAM,uBAAuB,GAAG,GAAG,GAAG,EAAE,WAAW,iBAAiB,CAAC,KACrF;AAEJ,QAAO;EACN,OAAO;AACN,UAAO,kBAAkB,QAAQ,eAAe;IAAE;IAAS;IAAO,CAAC;;EAEpE,MAAM,OAAO;AACZ,sBAAmB,QAAQ,eAAe,OAAO;IAAE;IAAS;IAAW,CAAC;;EAEzE,UAAU,SAAS;AAClB,UAAO,uBAAuB,QAAQ,eAAe,SAAS;IAAE;IAAS;IAAO,CAAC;;EAElF"}

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.cjs

@@ -29,7 +29,7 @@ function inMemoryThemeStore(themes) {
 	return {
 		read,
 		write(entry) {
-			if (entry === void 0) {
+			if (entry == null) {
 				if (value === void 0 || value === null) return;
 				value = void 0;
 				for (const fn of listeners) fn(void 0);

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-theme-store.cjs","names":["value: keyof Themes | undefined | null","themeEntry"],"sources":["../../../../src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts"],"sourcesContent":["import { themeEntry } from '../../theme-entry.ts'\nimport type { ThemeEntry } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * In-memory theme store. Transient state; no persistence.\n *\n * Bakes themes at creation. Validates theme keys on write; read/write use theme keys\n * and build ThemeEntry from the themes map, consistent with other stores.\n *\n * @param themes - Record mapping theme keys to values (for validation and entry construction)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' } as const\n * const store = inMemoryThemeStore(themes)\n * store.read() // undefined when empty\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((themeResult) => {})\n * ```\n */\nexport function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {\n\tlet value: keyof Themes | undefined | null\n\tconst listeners = new Set<(v: ThemeEntry<Themes> | undefined) => void>()\n\n\tfunction read(): ThemeEntry<Themes> | undefined {\n\t\tif (value === undefined || value === null) return undefined\n\t\treturn themeEntry(themes, value)\n\t}\n\n\treturn {\n\t\tread,\n\t\twrite(entry) {\n\t\t\tif (entry === undefined) {\n\t\t\t\tif (value === undefined || value === null) return\n\t\t\t\tvalue = undefined\n\t\t\t\tfor (const fn of listeners) fn(undefined)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (!(entry.theme in themes)) return\n\t\t\tif (value === entry.theme) return\n\t\t\tvalue = entry.theme\n\t\t\tfor (const fn of listeners) fn(themeEntry(themes, entry.theme))\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\tlisteners.add(handler)\n\t\t\treturn () => {\n\t\t\t\tlisteners.delete(handler)\n\t\t\t}\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBAA4C,QAAgB;CAC3E,IAAIA;CACJ,MAAM,4BAAY,IAAI,KAAkD;CAExE,SAAS,OAAuC;AAC/C,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,SAAOC,+BAAW,QAAQ,MAAM;;AAGjC,QAAO;EACN;EACA,MAAM,OAAO;AACZ,OAAI,UAAU,QAAW;AACxB,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,YAAQ;AACR,SAAK,MAAM,MAAM,UAAW,IAAG,OAAU;AACzC;;AAED,OAAI,EAAE,MAAM,SAAS,QAAS;AAC9B,OAAI,UAAU,MAAM,MAAO;AAC3B,WAAQ,MAAM;AACd,QAAK,MAAM,MAAM,UAAW,IAAGA,+BAAW,QAAQ,MAAM,MAAM,CAAC;;EAEhE,UAAU,SAAS;AAClB,aAAU,IAAI,QAAQ;AACtB,gBAAa;AACZ,cAAU,OAAO,QAAQ;;;EAG3B"}
+{"version":3,"file":"in-memory-theme-store.cjs","names":["value: keyof Themes | undefined | null","themeEntry"],"sources":["../../../../src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts"],"sourcesContent":["import { themeEntry } from '../../theme-entry.ts'\nimport type { ThemeEntry } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * In-memory theme store. Transient state; no persistence.\n *\n * Bakes themes at creation. Validates theme keys on write; read/write use theme keys\n * and build ThemeEntry from the themes map, consistent with other stores.\n *\n * @param themes - Record mapping theme keys to values (for validation and entry construction)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' } as const\n * const store = inMemoryThemeStore(themes)\n * store.read() // undefined when empty\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((themeResult) => {})\n * ```\n */\nexport function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {\n\tlet value: keyof Themes | undefined | null\n\tconst listeners = new Set<(v: ThemeEntry<Themes> | undefined) => void>()\n\n\tfunction read(): ThemeEntry<Themes> | undefined {\n\t\tif (value === undefined || value === null) return undefined\n\t\treturn themeEntry(themes, value)\n\t}\n\n\treturn {\n\t\tread,\n\t\twrite(entry) {\n\t\t\tif (entry == null) {\n\t\t\t\tif (value === undefined || value === null) return\n\t\t\t\tvalue = undefined\n\t\t\t\tfor (const fn of listeners) fn(undefined)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (!(entry.theme in themes)) return\n\t\t\tif (value === entry.theme) return\n\t\t\tvalue = entry.theme\n\t\t\tfor (const fn of listeners) fn(themeEntry(themes, entry.theme))\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\tlisteners.add(handler)\n\t\t\treturn () => {\n\t\t\t\tlisteners.delete(handler)\n\t\t\t}\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBAA4C,QAAgB;CAC3E,IAAIA;CACJ,MAAM,4BAAY,IAAI,KAAkD;CAExE,SAAS,OAAuC;AAC/C,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,SAAOC,+BAAW,QAAQ,MAAM;;AAGjC,QAAO;EACN;EACA,MAAM,OAAO;AACZ,OAAI,SAAS,MAAM;AAClB,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,YAAQ;AACR,SAAK,MAAM,MAAM,UAAW,IAAG,OAAU;AACzC;;AAED,OAAI,EAAE,MAAM,SAAS,QAAS;AAC9B,OAAI,UAAU,MAAM,MAAO;AAC3B,WAAQ,MAAM;AACd,QAAK,MAAM,MAAM,UAAW,IAAGA,+BAAW,QAAQ,MAAM,MAAM,CAAC;;EAEhE,UAAU,SAAS;AAClB,aAAU,IAAI,QAAQ;AACtB,gBAAa;AACZ,cAAU,OAAO,QAAQ;;;EAG3B"}

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.d.cts

@@ -24,7 +24,7 @@ import { ThemeEntry } from "../../theme-entry.types.cjs";
 declare function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { inMemoryThemeStore };

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.d.mts

@@ -24,7 +24,7 @@ import { ThemeEntry } from "../../theme-entry.types.mjs";
 declare function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { inMemoryThemeStore };

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.mjs

@@ -29,7 +29,7 @@ function inMemoryThemeStore(themes) {
 	return {
 		read,
 		write(entry) {
-			if (entry === void 0) {
+			if (entry == null) {
 				if (value === void 0 || value === null) return;
 				value = void 0;
 				for (const fn of listeners) fn(void 0);

package/dist/theme/theme-store/in-memory-theme-store/in-memory-theme-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory-theme-store.mjs","names":["value: keyof Themes | undefined | null"],"sources":["../../../../src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts"],"sourcesContent":["import { themeEntry } from '../../theme-entry.ts'\nimport type { ThemeEntry } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * In-memory theme store. Transient state; no persistence.\n *\n * Bakes themes at creation. Validates theme keys on write; read/write use theme keys\n * and build ThemeEntry from the themes map, consistent with other stores.\n *\n * @param themes - Record mapping theme keys to values (for validation and entry construction)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' } as const\n * const store = inMemoryThemeStore(themes)\n * store.read() // undefined when empty\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((themeResult) => {})\n * ```\n */\nexport function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {\n\tlet value: keyof Themes | undefined | null\n\tconst listeners = new Set<(v: ThemeEntry<Themes> | undefined) => void>()\n\n\tfunction read(): ThemeEntry<Themes> | undefined {\n\t\tif (value === undefined || value === null) return undefined\n\t\treturn themeEntry(themes, value)\n\t}\n\n\treturn {\n\t\tread,\n\t\twrite(entry) {\n\t\t\tif (entry === undefined) {\n\t\t\t\tif (value === undefined || value === null) return\n\t\t\t\tvalue = undefined\n\t\t\t\tfor (const fn of listeners) fn(undefined)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (!(entry.theme in themes)) return\n\t\t\tif (value === entry.theme) return\n\t\t\tvalue = entry.theme\n\t\t\tfor (const fn of listeners) fn(themeEntry(themes, entry.theme))\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\tlisteners.add(handler)\n\t\t\treturn () => {\n\t\t\t\tlisteners.delete(handler)\n\t\t\t}\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBAA4C,QAAgB;CAC3E,IAAIA;CACJ,MAAM,4BAAY,IAAI,KAAkD;CAExE,SAAS,OAAuC;AAC/C,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,SAAO,WAAW,QAAQ,MAAM;;AAGjC,QAAO;EACN;EACA,MAAM,OAAO;AACZ,OAAI,UAAU,QAAW;AACxB,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,YAAQ;AACR,SAAK,MAAM,MAAM,UAAW,IAAG,OAAU;AACzC;;AAED,OAAI,EAAE,MAAM,SAAS,QAAS;AAC9B,OAAI,UAAU,MAAM,MAAO;AAC3B,WAAQ,MAAM;AACd,QAAK,MAAM,MAAM,UAAW,IAAG,WAAW,QAAQ,MAAM,MAAM,CAAC;;EAEhE,UAAU,SAAS;AAClB,aAAU,IAAI,QAAQ;AACtB,gBAAa;AACZ,cAAU,OAAO,QAAQ;;;EAG3B"}
+{"version":3,"file":"in-memory-theme-store.mjs","names":["value: keyof Themes | undefined | null"],"sources":["../../../../src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts"],"sourcesContent":["import { themeEntry } from '../../theme-entry.ts'\nimport type { ThemeEntry } from '../../theme-entry.types.ts'\nimport type { ThemeMap } from '../../theme-map.types.ts'\nimport type { ThemeStore } from '../theme-store.types.ts'\n\n/**\n * In-memory theme store. Transient state; no persistence.\n *\n * Bakes themes at creation. Validates theme keys on write; read/write use theme keys\n * and build ThemeEntry from the themes map, consistent with other stores.\n *\n * @param themes - Record mapping theme keys to values (for validation and entry construction)\n * @returns ThemeStore\n *\n * @example\n * ```ts\n * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' } as const\n * const store = inMemoryThemeStore(themes)\n * store.read() // undefined when empty\n * store.write(themeEntry(themes, 'grayscale'))\n * store.subscribe((themeResult) => {})\n * ```\n */\nexport function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {\n\tlet value: keyof Themes | undefined | null\n\tconst listeners = new Set<(v: ThemeEntry<Themes> | undefined) => void>()\n\n\tfunction read(): ThemeEntry<Themes> | undefined {\n\t\tif (value === undefined || value === null) return undefined\n\t\treturn themeEntry(themes, value)\n\t}\n\n\treturn {\n\t\tread,\n\t\twrite(entry) {\n\t\t\tif (entry == null) {\n\t\t\t\tif (value === undefined || value === null) return\n\t\t\t\tvalue = undefined\n\t\t\t\tfor (const fn of listeners) fn(undefined)\n\t\t\t\treturn\n\t\t\t}\n\t\t\tif (!(entry.theme in themes)) return\n\t\t\tif (value === entry.theme) return\n\t\t\tvalue = entry.theme\n\t\t\tfor (const fn of listeners) fn(themeEntry(themes, entry.theme))\n\t\t},\n\t\tsubscribe(handler) {\n\t\t\tlisteners.add(handler)\n\t\t\treturn () => {\n\t\t\t\tlisteners.delete(handler)\n\t\t\t}\n\t\t}\n\t} satisfies ThemeStore<Themes>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBAA4C,QAAgB;CAC3E,IAAIA;CACJ,MAAM,4BAAY,IAAI,KAAkD;CAExE,SAAS,OAAuC;AAC/C,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,SAAO,WAAW,QAAQ,MAAM;;AAGjC,QAAO;EACN;EACA,MAAM,OAAO;AACZ,OAAI,SAAS,MAAM;AAClB,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,YAAQ;AACR,SAAK,MAAM,MAAM,UAAW,IAAG,OAAU;AACzC;;AAED,OAAI,EAAE,MAAM,SAAS,QAAS;AAC9B,OAAI,UAAU,MAAM,MAAO;AAC3B,WAAQ,MAAM;AACd,QAAK,MAAM,MAAM,UAAW,IAAG,WAAW,QAAQ,MAAM,MAAM,CAAC;;EAEhE,UAAU,SAAS;AAClB,aAAU,IAAI,QAAQ;AACtB,gBAAa;AACZ,cAAU,OAAO,QAAQ;;;EAG3B"}

package/dist/theme/theme-store/local-storage-theme-store/local-storage-theme-store.d.cts

@@ -33,7 +33,7 @@ declare function localStorageThemeStore<Themes extends ThemeMap>(themes: Themes,
 }): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { localStorageThemeStore };

package/dist/theme/theme-store/local-storage-theme-store/local-storage-theme-store.d.mts

@@ -33,7 +33,7 @@ declare function localStorageThemeStore<Themes extends ThemeMap>(themes: Themes,
 }): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { localStorageThemeStore };

package/dist/theme/theme-store/session-storage-theme-store/session-storage-theme-store.d.cts

@@ -33,7 +33,7 @@ declare function sessionStorageThemeStore<Themes extends ThemeMap>(themes: Theme
 }): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { sessionStorageThemeStore };

package/dist/theme/theme-store/session-storage-theme-store/session-storage-theme-store.d.mts

@@ -33,7 +33,7 @@ declare function sessionStorageThemeStore<Themes extends ThemeMap>(themes: Theme
 }): {
   read: () => ThemeEntry<Themes> | undefined;
   write(entry: ThemeEntry<Themes> | undefined): void;
-  subscribe(handler: (theme: ThemeEntry<Themes> | null | undefined) => void): () => void;
+  subscribe(handler: (theme: ThemeEntry<Themes> | undefined) => void): () => void;
 };
 //#endregion
 export { sessionStorageThemeStore };

package/dist/theme/theme-store/theme-store.types.d.cts

@@ -26,7 +26,7 @@ import { ThemeEntry } from "../theme-entry.types.cjs";
 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;
 }
 //#endregion
 export { ThemeStore };

package/dist/theme/theme-store/theme-store.types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-store.types.d.cts","names":[],"sources":["../../../src/theme/theme-store/theme-store.types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAuBA;;;;;;;;;;;;;;;;;;UAAiB,0BAA0B,WAAW;gBACvC,WAAW;mBACR,WAAW;iCAEN,WAAW"}
+{"version":3,"file":"theme-store.types.d.cts","names":[],"sources":["../../../src/theme/theme-store/theme-store.types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAuBA;;;;;;;;;;;;;;;;;;UAAiB,0BAA0B,WAAW;gBACvC,WAAW;mBACR,WAAW;iCACG,WAAW"}

package/dist/theme/theme-store/theme-store.types.d.mts

@@ -26,7 +26,7 @@ import { ThemeEntry } from "../theme-entry.types.mjs";
 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;
 }
 //#endregion
 export { ThemeStore };

package/dist/theme/theme-store/theme-store.types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-store.types.d.mts","names":[],"sources":["../../../src/theme/theme-store/theme-store.types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAuBA;;;;;;;;;;;;;;;;;;UAAiB,0BAA0B,WAAW;gBACvC,WAAW;mBACR,WAAW;iCAEN,WAAW"}
+{"version":3,"file":"theme-store.types.d.mts","names":[],"sources":["../../../src/theme/theme-store/theme-store.types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAuBA;;;;;;;;;;;;;;;;;;UAAiB,0BAA0B,WAAW;gBACvC,WAAW;mBACR,WAAW;iCACG,WAAW"}

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": "3.0.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,25 +2,30 @@
  * 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`.
- * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer.
+ * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`.
+ * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.
  *
  * @example
  * ```ts
- * const observer = observeAttributes({
- *   'data-theme': (attr, value) => console.log(`Theme changed to: ${value}`),
- *   'class': (attr, value) => console.log(`class changed to: ${value}`)
+ * const unsubscribe = observeAttributes({
+ *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),
+ *   'class': (value) => console.log(`class changed to: ${value}`)
  * });
  *
  * // Later, to stop observing:
- * observer.disconnect();
+ * unsubscribe();
  * ```
  */
 export function observeAttributes<T extends string>(
 	handlers: Record<string, (value: T | null) => void>,
-	element?: Element | undefined
-) {
-	element = element ?? globalThis.document.documentElement
+	element?: Element | null | undefined
+): () => void {
+	/* c8 ignore start */
+	if (typeof document === 'undefined') {
+		return () => {}
+	}
+	/* c8 ignore end */
+	element = element ?? document.documentElement
 	const observer = new MutationObserver((mutations) => {
 		for (const mutation of mutations) {
 			const attribute = mutation.attributeName
@@ -33,5 +38,5 @@ export function observeAttributes<T extends string>(
 		attributes: true,
 		attributeFilter: Object.keys(handlers)
 	})
-	return observer
+	return () => observer.disconnect()
 }

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

@@ -3,27 +3,24 @@ import { observeAttributes } from './observe-attribute.ts'
 /**
  * Observes changes to `data-*` attributes on an element and calls corresponding handlers.
  *
- * @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`
- * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer
+ * @param handlers - An object mapping `data-*` attribute names to handler functions.
+ * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`
+ * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.
  *
  * @example
  * ```ts
- * const observer = observeDataAttributes({
- *   handlers: {
- *     'data-theme': (value) => console.log(`Theme changed to: ${value}`),
- *     'data-mode': (value) => console.log(`Mode changed to: ${value}`)
- *   }
+ * const unsubscribe = observeDataAttributes({
+ *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),
+ *   'data-mode': (value) => console.log(`Mode changed to: ${value}`)
  * });
  *
  * // Later, to stop observing:
- * observer.disconnect();
+ * unsubscribe();
  * ```
  */
 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'