@just-web/toolkits 2.0.0 → 3.0.0

package/dist/attributes/get-attribute.cjs

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

package/dist/attributes/get-attribute.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-attribute.cjs","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":["/**\n * Gets the value of an attribute from an element.\n *\n * @param qualifiedName - The name of the attribute to get\n * @param element - The element to get the attribute from. Defaults to `document.documentElement`\n * @returns The attribute value cast to type T, or null if the attribute doesn't exist\n *\n * @example\n * ```ts\n * // Get theme from document root\n * const theme = getAttribute('data-theme')\n *\n * // Get data-testid from a specific element\n * const testId = getAttribute('data-testid', element)\n * ```\n */\nexport function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined) {\n\telement = element ?? globalThis.document.documentElement\n\treturn element.getAttribute(qualifiedName)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,SAAgB,aAA+B,eAAkB,SAA+B;AAC/F,WAAU,WAAW,WAAW,SAAS;AACzC,QAAO,QAAQ,aAAa,cAAc"}
+{"version":3,"file":"get-attribute.cjs","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":["/**\n * Gets the value of an attribute from an element.\n *\n * @param qualifiedName - The name of the attribute to get\n * @param element - The element to get the attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns The attribute value cast to type T, or null if the attribute doesn't exist\n *\n * @example\n * ```ts\n * // Get theme from document root\n * const theme = getAttribute('data-theme')\n *\n * // Get data-testid from a specific element\n * const testId = getAttribute('data-testid', element)\n * ```\n */\nexport function getAttribute<T extends string>(\n\tqualifiedName: T,\n\telement?: Element | null | undefined\n) {\n\telement = element ?? globalThis.document.documentElement\n\treturn element.getAttribute(qualifiedName)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,SAAgB,aACf,eACA,SACC;AACD,WAAU,WAAW,WAAW,SAAS;AACzC,QAAO,QAAQ,aAAa,cAAc"}

package/dist/attributes/get-attribute.d.cts

@@ -3,7 +3,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
@@ -15,7 +15,7 @@
  * const testId = getAttribute('data-testid', element)
  * ```
  */
-declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): string | null;
+declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | null | undefined): string | null;
 //#endregion
 export { getAttribute };
 //# sourceMappingURL=get-attribute.d.cts.map

package/dist/attributes/get-attribute.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"get-attribute.d.cts","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;;;;iBAAgB,8CAA8C,aAAa"}
+{"version":3,"file":"get-attribute.d.cts","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;;;;iBAAgB,8CACA,aACL"}

package/dist/attributes/get-attribute.d.mts

@@ -3,7 +3,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
@@ -15,7 +15,7 @@
  * const testId = getAttribute('data-testid', element)
  * ```
  */
-declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): string | null;
+declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | null | undefined): string | null;
 //#endregion
 export { getAttribute };
 //# sourceMappingURL=get-attribute.d.mts.map

package/dist/attributes/get-attribute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"get-attribute.d.mts","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;;;;iBAAgB,8CAA8C,aAAa"}
+{"version":3,"file":"get-attribute.d.mts","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;;;;iBAAgB,8CACA,aACL"}

package/dist/attributes/get-attribute.mjs

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

package/dist/attributes/get-attribute.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-attribute.mjs","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":["/**\n * Gets the value of an attribute from an element.\n *\n * @param qualifiedName - The name of the attribute to get\n * @param element - The element to get the attribute from. Defaults to `document.documentElement`\n * @returns The attribute value cast to type T, or null if the attribute doesn't exist\n *\n * @example\n * ```ts\n * // Get theme from document root\n * const theme = getAttribute('data-theme')\n *\n * // Get data-testid from a specific element\n * const testId = getAttribute('data-testid', element)\n * ```\n */\nexport function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined) {\n\telement = element ?? globalThis.document.documentElement\n\treturn element.getAttribute(qualifiedName)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,SAAgB,aAA+B,eAAkB,SAA+B;AAC/F,WAAU,WAAW,WAAW,SAAS;AACzC,QAAO,QAAQ,aAAa,cAAc"}
+{"version":3,"file":"get-attribute.mjs","names":[],"sources":["../../src/attributes/get-attribute.ts"],"sourcesContent":["/**\n * Gets the value of an attribute from an element.\n *\n * @param qualifiedName - The name of the attribute to get\n * @param element - The element to get the attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns The attribute value cast to type T, or null if the attribute doesn't exist\n *\n * @example\n * ```ts\n * // Get theme from document root\n * const theme = getAttribute('data-theme')\n *\n * // Get data-testid from a specific element\n * const testId = getAttribute('data-testid', element)\n * ```\n */\nexport function getAttribute<T extends string>(\n\tqualifiedName: T,\n\telement?: Element | null | undefined\n) {\n\telement = element ?? globalThis.document.documentElement\n\treturn element.getAttribute(qualifiedName)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,SAAgB,aACf,eACA,SACC;AACD,WAAU,WAAW,WAAW,SAAS;AACzC,QAAO,QAAQ,aAAa,cAAc"}

package/dist/attributes/get-data-attribute.cjs

@@ -5,7 +5,7 @@ const require_get_attribute = require('./get-attribute.cjs');
 * 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

package/dist/attributes/get-data-attribute.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-data-attribute.cjs","names":["getAttribute"],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":["import type { DataAttribute } from './data-attribute.ts'\nimport { getAttribute } from './get-attribute.ts'\n\n/**\n * Gets the value of a data attribute from an element.\n *\n * @param qualifiedName - The name of the data attribute to get\n * @param element - The element to get the data attribute from. Defaults to `document.documentElement`\n * @returns The data attribute value, or null if the attribute doesn't exist\n *\n * @example\n */\nexport function getDataAttribute(qualifiedName: DataAttribute, element?: Element | undefined) {\n\treturn getAttribute(qualifiedName, element)\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,iBAAiB,eAA8B,SAA+B;AAC7F,QAAOA,mCAAa,eAAe,QAAQ"}
+{"version":3,"file":"get-data-attribute.cjs","names":["getAttribute"],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":["import type { DataAttribute } from './data-attribute.ts'\nimport { getAttribute } from './get-attribute.ts'\n\n/**\n * Gets the value of a data attribute from an element.\n *\n * @param qualifiedName - The name of the data attribute to get\n * @param element - The element to get the data attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns The data attribute value, or null if the attribute doesn't exist\n *\n * @example\n */\nexport function getDataAttribute(\n\tqualifiedName: DataAttribute,\n\telement?: Element | null | undefined\n) {\n\treturn getAttribute(qualifiedName, element)\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,iBACf,eACA,SACC;AACD,QAAOA,mCAAa,eAAe,QAAQ"}

package/dist/attributes/get-data-attribute.d.cts

@@ -6,12 +6,12 @@ import { DataAttribute } from "./data-attribute.cjs";
  * 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
  */
-declare function getDataAttribute(qualifiedName: DataAttribute, element?: Element | undefined): string | null;
+declare function getDataAttribute(qualifiedName: DataAttribute, element?: Element | null | undefined): string | null;
 //#endregion
 export { getDataAttribute };
 //# sourceMappingURL=get-data-attribute.d.cts.map

package/dist/attributes/get-data-attribute.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"get-data-attribute.d.cts","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,gBAAA,gBAAgC,yBAAyB"}
+{"version":3,"file":"get-data-attribute.d.cts","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,gBAAA,gBACA,yBACL"}

package/dist/attributes/get-data-attribute.d.mts

@@ -6,12 +6,12 @@ import { DataAttribute } from "./data-attribute.mjs";
  * 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
  */
-declare function getDataAttribute(qualifiedName: DataAttribute, element?: Element | undefined): string | null;
+declare function getDataAttribute(qualifiedName: DataAttribute, element?: Element | null | undefined): string | null;
 //#endregion
 export { getDataAttribute };
 //# sourceMappingURL=get-data-attribute.d.mts.map

package/dist/attributes/get-data-attribute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"get-data-attribute.d.mts","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,gBAAA,gBAAgC,yBAAyB"}
+{"version":3,"file":"get-data-attribute.d.mts","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;iBAAgB,gBAAA,gBACA,yBACL"}

package/dist/attributes/get-data-attribute.mjs

@@ -5,7 +5,7 @@ import { getAttribute } from "./get-attribute.mjs";
 * 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

package/dist/attributes/get-data-attribute.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-data-attribute.mjs","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":["import type { DataAttribute } from './data-attribute.ts'\nimport { getAttribute } from './get-attribute.ts'\n\n/**\n * Gets the value of a data attribute from an element.\n *\n * @param qualifiedName - The name of the data attribute to get\n * @param element - The element to get the data attribute from. Defaults to `document.documentElement`\n * @returns The data attribute value, or null if the attribute doesn't exist\n *\n * @example\n */\nexport function getDataAttribute(qualifiedName: DataAttribute, element?: Element | undefined) {\n\treturn getAttribute(qualifiedName, element)\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,iBAAiB,eAA8B,SAA+B;AAC7F,QAAO,aAAa,eAAe,QAAQ"}
+{"version":3,"file":"get-data-attribute.mjs","names":[],"sources":["../../src/attributes/get-data-attribute.ts"],"sourcesContent":["import type { DataAttribute } from './data-attribute.ts'\nimport { getAttribute } from './get-attribute.ts'\n\n/**\n * Gets the value of a data attribute from an element.\n *\n * @param qualifiedName - The name of the data attribute to get\n * @param element - The element to get the data attribute from (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns The data attribute value, or null if the attribute doesn't exist\n *\n * @example\n */\nexport function getDataAttribute(\n\tqualifiedName: DataAttribute,\n\telement?: Element | null | undefined\n) {\n\treturn getAttribute(qualifiedName, element)\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,iBACf,eACA,SACC;AACD,QAAO,aAAa,eAAe,QAAQ"}

package/dist/attributes/observe-attribute.cjs

@@ -4,22 +4,25 @@
 * 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();
 * ```
 */
 function observeAttributes(handlers, element) {
-	element = element ?? globalThis.document.documentElement;
+	/* 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;
@@ -32,7 +35,7 @@ function observeAttributes(handlers, element) {
 		attributes: true,
 		attributeFilter: Object.keys(handlers)
 	});
-	return observer;
+	return () => observer.disconnect();
 }
 
 //#endregion

package/dist/attributes/observe-attribute.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"observe-attribute.cjs","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":["/**\n * Observes attributes changes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping attribute names to handler functions.\n * @param element - The element to observe. Defaults to `document.documentElement`.\n * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer.\n *\n * @example\n * ```ts\n * const observer = observeAttributes({\n *   'data-theme': (attr, value) => console.log(`Theme changed to: ${value}`),\n *   'class': (attr, value) => console.log(`class changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * observer.disconnect();\n * ```\n */\nexport function observeAttributes<T extends string>(\n\thandlers: Record<string, (value: T | null) => void>,\n\telement?: Element | undefined\n) {\n\telement = element ?? globalThis.document.documentElement\n\tconst observer = new MutationObserver((mutations) => {\n\t\tfor (const mutation of mutations) {\n\t\t\tconst attribute = mutation.attributeName\n\t\t\tif (!attribute) continue\n\t\t\tconst value = element.getAttribute(attribute) as T | null\n\t\t\thandlers[attribute]?.(value)\n\t\t}\n\t})\n\tobserver.observe(element, {\n\t\tattributes: true,\n\t\tattributeFilter: Object.keys(handlers)\n\t})\n\treturn observer\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBACf,UACA,SACC;AACD,WAAU,WAAW,WAAW,SAAS;CACzC,MAAM,WAAW,IAAI,kBAAkB,cAAc;AACpD,OAAK,MAAM,YAAY,WAAW;GACjC,MAAM,YAAY,SAAS;AAC3B,OAAI,CAAC,UAAW;GAChB,MAAM,QAAQ,QAAQ,aAAa,UAAU;AAC7C,YAAS,aAAa,MAAM;;GAE5B;AACF,UAAS,QAAQ,SAAS;EACzB,YAAY;EACZ,iBAAiB,OAAO,KAAK,SAAS;EACtC,CAAC;AACF,QAAO"}
+{"version":3,"file":"observe-attribute.cjs","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":["/**\n * Observes attributes changes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping attribute names to handler functions.\n * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`.\n * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.\n *\n * @example\n * ```ts\n * const unsubscribe = observeAttributes({\n *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *   'class': (value) => console.log(`class changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * unsubscribe();\n * ```\n */\nexport function observeAttributes<T extends string>(\n\thandlers: Record<string, (value: T | null) => void>,\n\telement?: Element | null | undefined\n): () => void {\n\t/* c8 ignore start */\n\tif (typeof document === 'undefined') {\n\t\treturn () => {}\n\t}\n\t/* c8 ignore end */\n\telement = element ?? document.documentElement\n\tconst observer = new MutationObserver((mutations) => {\n\t\tfor (const mutation of mutations) {\n\t\t\tconst attribute = mutation.attributeName\n\t\t\tif (!attribute) continue\n\t\t\tconst value = element.getAttribute(attribute) as T | null\n\t\t\thandlers[attribute]?.(value)\n\t\t}\n\t})\n\tobserver.observe(element, {\n\t\tattributes: true,\n\t\tattributeFilter: Object.keys(handlers)\n\t})\n\treturn () => observer.disconnect()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBACf,UACA,SACa;;AAEb,KAAI,OAAO,aAAa,YACvB,cAAa;;AAGd,WAAU,WAAW,SAAS;CAC9B,MAAM,WAAW,IAAI,kBAAkB,cAAc;AACpD,OAAK,MAAM,YAAY,WAAW;GACjC,MAAM,YAAY,SAAS;AAC3B,OAAI,CAAC,UAAW;GAChB,MAAM,QAAQ,QAAQ,aAAa,UAAU;AAC7C,YAAS,aAAa,MAAM;;GAE5B;AACF,UAAS,QAAQ,SAAS;EACzB,YAAY;EACZ,iBAAiB,OAAO,KAAK,SAAS;EACtC,CAAC;AACF,cAAa,SAAS,YAAY"}

package/dist/attributes/observe-attribute.d.cts

@@ -3,21 +3,21 @@
  * 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();
  * ```
  */
-declare function observeAttributes<T extends string>(handlers: Record<string, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+declare function observeAttributes<T extends string>(handlers: Record<string, (value: T | null) => void>, element?: Element | null | undefined): () => void;
 //#endregion
 export { observeAttributes };
 //# sourceMappingURL=observe-attribute.d.cts.map

package/dist/attributes/observe-attribute.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-attribute.d.cts","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":[],"mappings":";;AAkBA;;;;;;;;;;;;;;;;;iBAAgB,8CACL,uBAAuB,8BACvB,sBAAmB"}
+{"version":3,"file":"observe-attribute.d.cts","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":[],"mappings":";;AAkBA;;;;;;;;;;;;;;;;;iBAAgB,8CACL,uBAAuB,8BACvB"}

package/dist/attributes/observe-attribute.d.mts

@@ -3,21 +3,21 @@
  * 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();
  * ```
  */
-declare function observeAttributes<T extends string>(handlers: Record<string, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+declare function observeAttributes<T extends string>(handlers: Record<string, (value: T | null) => void>, element?: Element | null | undefined): () => void;
 //#endregion
 export { observeAttributes };
 //# sourceMappingURL=observe-attribute.d.mts.map

package/dist/attributes/observe-attribute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-attribute.d.mts","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":[],"mappings":";;AAkBA;;;;;;;;;;;;;;;;;iBAAgB,8CACL,uBAAuB,8BACvB,sBAAmB"}
+{"version":3,"file":"observe-attribute.d.mts","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":[],"mappings":";;AAkBA;;;;;;;;;;;;;;;;;iBAAgB,8CACL,uBAAuB,8BACvB"}

package/dist/attributes/observe-attribute.mjs

@@ -3,22 +3,25 @@
 * 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();
 * ```
 */
 function observeAttributes(handlers, element) {
-	element = element ?? globalThis.document.documentElement;
+	/* 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;
@@ -31,7 +34,7 @@ function observeAttributes(handlers, element) {
 		attributes: true,
 		attributeFilter: Object.keys(handlers)
 	});
-	return observer;
+	return () => observer.disconnect();
 }
 
 //#endregion

package/dist/attributes/observe-attribute.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"observe-attribute.mjs","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":["/**\n * Observes attributes changes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping attribute names to handler functions.\n * @param element - The element to observe. Defaults to `document.documentElement`.\n * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer.\n *\n * @example\n * ```ts\n * const observer = observeAttributes({\n *   'data-theme': (attr, value) => console.log(`Theme changed to: ${value}`),\n *   'class': (attr, value) => console.log(`class changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * observer.disconnect();\n * ```\n */\nexport function observeAttributes<T extends string>(\n\thandlers: Record<string, (value: T | null) => void>,\n\telement?: Element | undefined\n) {\n\telement = element ?? globalThis.document.documentElement\n\tconst observer = new MutationObserver((mutations) => {\n\t\tfor (const mutation of mutations) {\n\t\t\tconst attribute = mutation.attributeName\n\t\t\tif (!attribute) continue\n\t\t\tconst value = element.getAttribute(attribute) as T | null\n\t\t\thandlers[attribute]?.(value)\n\t\t}\n\t})\n\tobserver.observe(element, {\n\t\tattributes: true,\n\t\tattributeFilter: Object.keys(handlers)\n\t})\n\treturn observer\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBACf,UACA,SACC;AACD,WAAU,WAAW,WAAW,SAAS;CACzC,MAAM,WAAW,IAAI,kBAAkB,cAAc;AACpD,OAAK,MAAM,YAAY,WAAW;GACjC,MAAM,YAAY,SAAS;AAC3B,OAAI,CAAC,UAAW;GAChB,MAAM,QAAQ,QAAQ,aAAa,UAAU;AAC7C,YAAS,aAAa,MAAM;;GAE5B;AACF,UAAS,QAAQ,SAAS;EACzB,YAAY;EACZ,iBAAiB,OAAO,KAAK,SAAS;EACtC,CAAC;AACF,QAAO"}
+{"version":3,"file":"observe-attribute.mjs","names":[],"sources":["../../src/attributes/observe-attribute.ts"],"sourcesContent":["/**\n * Observes attributes changes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping attribute names to handler functions.\n * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`.\n * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.\n *\n * @example\n * ```ts\n * const unsubscribe = observeAttributes({\n *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *   'class': (value) => console.log(`class changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * unsubscribe();\n * ```\n */\nexport function observeAttributes<T extends string>(\n\thandlers: Record<string, (value: T | null) => void>,\n\telement?: Element | null | undefined\n): () => void {\n\t/* c8 ignore start */\n\tif (typeof document === 'undefined') {\n\t\treturn () => {}\n\t}\n\t/* c8 ignore end */\n\telement = element ?? document.documentElement\n\tconst observer = new MutationObserver((mutations) => {\n\t\tfor (const mutation of mutations) {\n\t\t\tconst attribute = mutation.attributeName\n\t\t\tif (!attribute) continue\n\t\t\tconst value = element.getAttribute(attribute) as T | null\n\t\t\thandlers[attribute]?.(value)\n\t\t}\n\t})\n\tobserver.observe(element, {\n\t\tattributes: true,\n\t\tattributeFilter: Object.keys(handlers)\n\t})\n\treturn () => observer.disconnect()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAkBA,SAAgB,kBACf,UACA,SACa;;AAEb,KAAI,OAAO,aAAa,YACvB,cAAa;;AAGd,WAAU,WAAW,SAAS;CAC9B,MAAM,WAAW,IAAI,kBAAkB,cAAc;AACpD,OAAK,MAAM,YAAY,WAAW;GACjC,MAAM,YAAY,SAAS;AAC3B,OAAI,CAAC,UAAW;GAChB,MAAM,QAAQ,QAAQ,aAAa,UAAU;AAC7C,YAAS,aAAa,MAAM;;GAE5B;AACF,UAAS,QAAQ,SAAS;EACzB,YAAY;EACZ,iBAAiB,OAAO,KAAK,SAAS;EACtC,CAAC;AACF,cAAa,SAAS,YAAY"}

package/dist/attributes/observe-data-attribute.cjs

@@ -4,22 +4,19 @@ const require_observe_attribute = require('./observe-attribute.cjs');
 /**
 * 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();
 * ```
 */
 function observeDataAttributes(handlers, element) {

package/dist/attributes/observe-data-attribute.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"observe-data-attribute.cjs","names":["observeAttributes"],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":["import { observeAttributes } from './observe-attribute.ts'\n\n/**\n * Observes changes to `data-*` attributes on an element and calls corresponding handlers.\n *\n * @param options - Configuration options\n * @param options.handlers - An object mapping `data-*` attribute names to handler functions.\n * @param options.element - The element to observe. Defaults to `document.documentElement`\n * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer\n *\n * @example\n * ```ts\n * const observer = observeDataAttributes({\n *   handlers: {\n *     'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *     'data-mode': (value) => console.log(`Mode changed to: ${value}`)\n *   }\n * });\n *\n * // Later, to stop observing:\n * observer.disconnect();\n * ```\n */\nexport function observeDataAttributes<T extends string, K extends `data-${string}`>(\n\thandlers: Record<K, (value: T | null) => void>,\n\telement?: Element | undefined\n) {\n\treturn observeAttributes(handlers, element)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,sBACf,UACA,SACC;AACD,QAAOA,4CAAkB,UAAU,QAAQ"}
+{"version":3,"file":"observe-data-attribute.cjs","names":["observeAttributes"],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":["import { observeAttributes } from './observe-attribute.ts'\n\n/**\n * Observes changes to `data-*` attributes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping `data-*` attribute names to handler functions.\n * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.\n *\n * @example\n * ```ts\n * const unsubscribe = observeDataAttributes({\n *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *   'data-mode': (value) => console.log(`Mode changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * unsubscribe();\n * ```\n */\nexport function observeDataAttributes<T extends string, K extends `data-${string}`>(\n\thandlers: Record<K, (value: T | null) => void>,\n\telement?: Element | null | undefined\n) {\n\treturn observeAttributes(handlers, element)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,sBACf,UACA,SACC;AACD,QAAOA,4CAAkB,UAAU,QAAQ"}

package/dist/attributes/observe-data-attribute.d.cts

@@ -2,25 +2,22 @@
 /**
  * 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();
  * ```
  */
-declare function observeDataAttributes<T extends string, K extends `data-${string}`>(handlers: Record<K, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+declare function observeDataAttributes<T extends string, K extends `data-${string}`>(handlers: Record<K, (value: T | null) => void>, element?: Element | null | undefined): () => void;
 //#endregion
 export { observeDataAttributes };
 //# sourceMappingURL=observe-data-attribute.d.cts.map

package/dist/attributes/observe-data-attribute.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-data-attribute.d.cts","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":[],"mappings":";;AAuBA;;;;;;;;;;;;;;;;;;;;iBAAgB,8EACL,OAAO,WAAW,8BAClB,sBAAmB"}
+{"version":3,"file":"observe-data-attribute.d.cts","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":[],"mappings":";;AAoBA;;;;;;;;;;;;;;;;;iBAAgB,8EACL,OAAO,WAAW,8BAClB"}

package/dist/attributes/observe-data-attribute.d.mts

@@ -2,25 +2,22 @@
 /**
  * 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();
  * ```
  */
-declare function observeDataAttributes<T extends string, K extends `data-${string}`>(handlers: Record<K, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+declare function observeDataAttributes<T extends string, K extends `data-${string}`>(handlers: Record<K, (value: T | null) => void>, element?: Element | null | undefined): () => void;
 //#endregion
 export { observeDataAttributes };
 //# sourceMappingURL=observe-data-attribute.d.mts.map

package/dist/attributes/observe-data-attribute.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"observe-data-attribute.d.mts","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":[],"mappings":";;AAuBA;;;;;;;;;;;;;;;;;;;;iBAAgB,8EACL,OAAO,WAAW,8BAClB,sBAAmB"}
+{"version":3,"file":"observe-data-attribute.d.mts","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":[],"mappings":";;AAoBA;;;;;;;;;;;;;;;;;iBAAgB,8EACL,OAAO,WAAW,8BAClB"}

package/dist/attributes/observe-data-attribute.mjs

@@ -4,22 +4,19 @@ import { observeAttributes } from "./observe-attribute.mjs";
 /**
 * 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();
 * ```
 */
 function observeDataAttributes(handlers, element) {

package/dist/attributes/observe-data-attribute.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"observe-data-attribute.mjs","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":["import { observeAttributes } from './observe-attribute.ts'\n\n/**\n * Observes changes to `data-*` attributes on an element and calls corresponding handlers.\n *\n * @param options - Configuration options\n * @param options.handlers - An object mapping `data-*` attribute names to handler functions.\n * @param options.element - The element to observe. Defaults to `document.documentElement`\n * @returns {MutationObserver} The observer instance, which can be used to disconnect the observer\n *\n * @example\n * ```ts\n * const observer = observeDataAttributes({\n *   handlers: {\n *     'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *     'data-mode': (value) => console.log(`Mode changed to: ${value}`)\n *   }\n * });\n *\n * // Later, to stop observing:\n * observer.disconnect();\n * ```\n */\nexport function observeDataAttributes<T extends string, K extends `data-${string}`>(\n\thandlers: Record<K, (value: T | null) => void>,\n\telement?: Element | undefined\n) {\n\treturn observeAttributes(handlers, element)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,sBACf,UACA,SACC;AACD,QAAO,kBAAkB,UAAU,QAAQ"}
+{"version":3,"file":"observe-data-attribute.mjs","names":[],"sources":["../../src/attributes/observe-data-attribute.ts"],"sourcesContent":["import { observeAttributes } from './observe-attribute.ts'\n\n/**\n * Observes changes to `data-*` attributes on an element and calls corresponding handlers.\n *\n * @param handlers - An object mapping `data-*` attribute names to handler functions.\n * @param element - The element to observe (accepts null e.g. from refs). Defaults to `document.documentElement`\n * @returns An unsubscribe function to stop observing. Returns a no-op function in SSR environments.\n *\n * @example\n * ```ts\n * const unsubscribe = observeDataAttributes({\n *   'data-theme': (value) => console.log(`Theme changed to: ${value}`),\n *   'data-mode': (value) => console.log(`Mode changed to: ${value}`)\n * });\n *\n * // Later, to stop observing:\n * unsubscribe();\n * ```\n */\nexport function observeDataAttributes<T extends string, K extends `data-${string}`>(\n\thandlers: Record<K, (value: T | null) => void>,\n\telement?: Element | null | undefined\n) {\n\treturn observeAttributes(handlers, element)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,sBACf,UACA,SACC;AACD,QAAO,kBAAkB,UAAU,QAAQ"}

package/dist/color-scheme/color-scheme.types.d.cts

@@ -0,0 +1,11 @@
+//#region src/color-scheme/color-scheme.types.d.ts
+/**
+ * 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.
+ */
+type ColorScheme = 'light' | 'dark';
+//#endregion
+export { ColorScheme };
+//# sourceMappingURL=color-scheme.types.d.cts.map

package/dist/color-scheme/color-scheme.types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-scheme.types.d.cts","names":[],"sources":["../../src/color-scheme/color-scheme.types.ts"],"sourcesContent":[],"mappings":";;AAMA;;;;;KAAY,WAAA"}

package/dist/color-scheme/color-scheme.types.d.mts

@@ -0,0 +1,11 @@
+//#region src/color-scheme/color-scheme.types.d.ts
+/**
+ * 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.
+ */
+type ColorScheme = 'light' | 'dark';
+//#endregion
+export { ColorScheme };
+//# sourceMappingURL=color-scheme.types.d.mts.map

package/dist/color-scheme/color-scheme.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-scheme.types.d.mts","names":[],"sources":["../../src/color-scheme/color-scheme.types.ts"],"sourcesContent":[],"mappings":";;AAMA;;;;;KAAY,WAAA"}

package/dist/color-scheme/get-prefers-color-scheme.cjs

@@ -4,7 +4,9 @@
 * 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`.
 *

package/dist/color-scheme/get-prefers-color-scheme.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-prefers-color-scheme.cjs","names":[],"sources":["../../src/color-scheme/get-prefers-color-scheme.ts"],"sourcesContent":["/**\n * Gets the current preferred color scheme.\n * It can only be 'light' or 'dark'.\n *\n * Even if the browser preference is 'auto'/'device', it will return 'light' or 'dark'.\n *\n * When `matchMedia` is unavailable (e.g. SSR), returns `defaultColorScheme`.\n *\n * @param defaultColorScheme - Fallback when `matchMedia` is unavailable (default: `'light'`)\n * @returns 'light' or 'dark'\n */\nexport function getPrefersColorScheme(\n\tdefaultColorScheme: 'light' | 'dark' = 'light'\n): 'light' | 'dark' {\n\tif (typeof matchMedia === 'undefined') return defaultColorScheme\n\treturn matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'\n}\n"],"mappings":";;;;;;;;;;;;;AAWA,SAAgB,sBACf,qBAAuC,SACpB;AACnB,KAAI,OAAO,eAAe,YAAa,QAAO;AAC9C,QAAO,WAAW,gCAAgC,CAAC,UAAU,UAAU"}
+{"version":3,"file":"get-prefers-color-scheme.cjs","names":[],"sources":["../../src/color-scheme/get-prefers-color-scheme.ts"],"sourcesContent":["import type { ColorScheme } from './color-scheme.types.ts'\n\n/**\n * Gets the current preferred color scheme.\n * It can only be 'light' or 'dark'.\n *\n * Per {@link https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme Media Queries Level 5},\n * the `prefers-color-scheme` media feature has only two valid values. Even if the browser\n * preference is 'auto'/'device', it will return 'light' or 'dark'.\n *\n * When `matchMedia` is unavailable (e.g. SSR), returns `defaultColorScheme`.\n *\n * @param defaultColorScheme - Fallback when `matchMedia` is unavailable (default: `'light'`)\n * @returns 'light' or 'dark'\n */\nexport function getPrefersColorScheme(defaultColorScheme: ColorScheme = 'light'): ColorScheme {\n\tif (typeof matchMedia === 'undefined') return defaultColorScheme\n\treturn matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,sBAAsB,qBAAkC,SAAsB;AAC7F,KAAI,OAAO,eAAe,YAAa,QAAO;AAC9C,QAAO,WAAW,gCAAgC,CAAC,UAAU,UAAU"}

package/dist/color-scheme/get-prefers-color-scheme.d.cts

@@ -1,16 +1,21 @@
+import { ColorScheme } from "./color-scheme.types.cjs";
+
 //#region src/color-scheme/get-prefers-color-scheme.d.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'
  */
-declare function getPrefersColorScheme(defaultColorScheme?: 'light' | 'dark'): 'light' | 'dark';
+declare function getPrefersColorScheme(defaultColorScheme?: ColorScheme): ColorScheme;
 //#endregion
 export { getPrefersColorScheme };
 //# sourceMappingURL=get-prefers-color-scheme.d.cts.map

package/dist/color-scheme/get-prefers-color-scheme.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"get-prefers-color-scheme.d.cts","names":[],"sources":["../../src/color-scheme/get-prefers-color-scheme.ts"],"sourcesContent":[],"mappings":";;AAWA;;;;;;;;;;iBAAgB,qBAAA"}
+{"version":3,"file":"get-prefers-color-scheme.d.cts","names":[],"sources":["../../src/color-scheme/get-prefers-color-scheme.ts"],"sourcesContent":[],"mappings":";;;;;;AAeA;;;;;;;;;;;iBAAgB,qBAAA,sBAA0C,cAAwB"}