@just-web/css 0.4.0 → 0.6.0

package/cjs/convertors/px_2_rem.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Converts pixel values to rem units.
+ *
+ * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate rem units from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'rem' units
+ *
+ * @example
+ * ```ts
+ * px2rem(16) // '1.0000'
+ * px2rem('32px') // '2.0000'
+ * px2rem(20, { base: 20 }) // '1.0000'
+ * px2rem(13, { precision: 2 }) // '0.81'
+ * ```
+ */
+export declare function px2rem(px: number | string, options?: {
+    base?: number | undefined;
+    precision?: number | undefined;
+}): string;

package/cjs/convertors/px_2_rem.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.px2rem = px2rem;
+function px2rem(px, options) {
+  const {
+    base = 16,
+    precision = 4
+  } = options ?? {};
+  if (typeof px === "string") {
+    px = px.replace(/px$/, "");
+    px = Number.parseFloat(px);
+  }
+  return (px / base).toFixed(precision);
+}

package/cjs/convertors/rem_2_px.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Converts rem values to pixel units.
+ *
+ * @param rem - The rem value to convert. Can be a number or string (e.g. '1rem' or '1')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate pixels from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'px' units
+ *
+ * @example
+ * ```ts
+ * rem2px(1) // '16.0000'
+ * rem2px('2rem') // '32.0000'
+ * rem2px(1, { base: 20 }) // '20.0000'
+ * rem2px(0.8125, { precision: 2 }) // '13.00'
+ * ```
+ */
+export declare function rem2px(rem: number | string, options?: {
+    base?: number | undefined;
+    precision?: number | undefined;
+}): string;

package/cjs/convertors/rem_2_px.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.rem2px = rem2px;
+function rem2px(rem, options) {
+  const {
+    base = 16,
+    precision = 4
+  } = options ?? {};
+  if (typeof rem === "string") {
+    rem = rem.replace(/rem$/, "");
+    rem = Number.parseFloat(rem);
+  }
+  return (rem * base).toFixed(precision);
+}

package/cjs/index.d.ts

@@ -1,3 +1,5 @@
+export * from './convertors/px_2_rem.ts';
+export * from './convertors/rem_2_px.ts';
 export * from './css-properties/css-properties.ts';
 export * from './css-properties/to_dom_style.ts';
 export * from './props/class-name.ts';

package/cjs/index.js

@@ -3,6 +3,28 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+var _px_2_rem = require("./convertors/px_2_rem.ts");
+Object.keys(_px_2_rem).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _px_2_rem[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _px_2_rem[key];
+    }
+  });
+});
+var _rem_2_px = require("./convertors/rem_2_px.ts");
+Object.keys(_rem_2_px).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _rem_2_px[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _rem_2_px[key];
+    }
+  });
+});
 var _cssProperties = require("./css-properties/css-properties.ts");
 Object.keys(_cssProperties).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/cjs/tailwind.css

@@ -1 +1 @@
-@import "tailwindcss";
+@import "tailwindcss";@custom-variant dark (&:where(.dark, .dark *));

package/cjs/testing/log-panel.js

@@ -9,7 +9,7 @@ function LogPanel({
   log
 }) {
   return /* @__PURE__ */React.createElement("div", {
-    className: "bg-neutral-100 p-4 rounded overflow-y-auto"
+    className: "bg-neutral-100 dark:bg-neutral-900 p-4 rounded overflow-y-auto"
   }, /* @__PURE__ */React.createElement("h4", {
     className: "mb-2"
   }, title), log.map((entry, i) => /* @__PURE__ */React.createElement("pre", {

package/cjs/theme/data-attribute.d.ts

@@ -5,6 +5,7 @@
  * @param options.themes - Record mapping theme keys to their data attribute values
  * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme
  * @param options.attributeName - Name of the data attribute to check (must start with 'data-')
+ * @param options.allowCustom - Whether to allow custom themes value
  * @returns The matching theme key, or defaultTheme if no match found
  *
  * @example
@@ -24,11 +25,18 @@
  * ```
  */
 export declare function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
-    themes: Themes;
-    defaultTheme?: keyof Themes | undefined;
     attributeName: `data-${string}`;
+    defaultTheme?: keyof Themes | undefined;
+    themes: Themes;
     element?: Element | undefined;
 }): keyof Themes | undefined;
+export declare function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+    attributeName: `data-${string}`;
+    allowCustom: true | undefined;
+    defaultTheme?: keyof Themes | undefined;
+    themes: Themes;
+    element?: Element | undefined;
+}): string | undefined;
 /**
  * Observes changes to a theme data attribute and calls a handler when it changes.
  *
@@ -65,3 +73,11 @@ export declare function observeThemeByDataAttributes<Themes extends Record<strin
     defaultTheme?: keyof Themes | undefined;
     element?: Element | undefined;
 }): MutationObserver;
+export declare function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {
+    attributeName: `data-${string}`;
+    themes: Themes;
+    handler: (value: string | null) => void;
+    allowCustom: true | undefined;
+    defaultTheme?: keyof Themes | undefined;
+    element?: Element | undefined;
+}): MutationObserver;

package/cjs/theme/data-attribute.js

@@ -8,9 +8,9 @@ exports.observeThemeByDataAttributes = observeThemeByDataAttributes;
 var _typePlus = require("type-plus");
 var _dataAttribute = require("../utils/data-attribute.ts");
 function getThemeByDataAttribute(options) {
-  const value = (0, _dataAttribute.getDataAttribute)(options.attributeName, options.element);
+  const value = (0, _dataAttribute.getDataAttribute)(options.attributeName, options.element) ?? void 0;
   const theme = (0, _typePlus.findKey)(options.themes, theme2 => options.themes[theme2] === value);
-  return theme ?? options.defaultTheme;
+  return theme ?? options.defaultTheme ?? (options.allowCustom ? value : void 0);
 }
 function observeThemeByDataAttributes(options) {
   return (0, _dataAttribute.observeDataAttributes)({
@@ -22,9 +22,12 @@ function observeThemeByDataAttributes(options) {
       for (const name in options.themes) {
         if (options.themes[name] === value) {
           options.handler(name);
-          break;
+          return;
         }
       }
+      if (options.allowCustom) {
+        options.handler(value);
+      }
     }
   }, options.element);
 }

package/cjs/utils/attribute.d.ts

@@ -14,7 +14,7 @@
  * const testId = getAttribute('data-testid', element)
  * ```
  */
-export declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): T | null;
+export declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): string | null;
 /**
  * Observes attributes changes on an element and calls corresponding handlers.
  *

package/cjs/utils/data-attribute.d.ts

@@ -1,4 +1,4 @@
-export declare function getDataAttribute<T extends `data-${string}`>(qualifiedName: T, element?: Element | undefined): T | null;
+export declare function getDataAttribute<T extends `data-${string}`>(qualifiedName: T, element?: Element | undefined): string | null;
 /**
  * Observes changes to `data-*` attributes on an element and calls corresponding handlers.
  *

package/esm/convertors/px_2_rem.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Converts pixel values to rem units.
+ *
+ * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate rem units from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'rem' units
+ *
+ * @example
+ * ```ts
+ * px2rem(16) // '1.0000'
+ * px2rem('32px') // '2.0000'
+ * px2rem(20, { base: 20 }) // '1.0000'
+ * px2rem(13, { precision: 2 }) // '0.81'
+ * ```
+ */
+export declare function px2rem(px: number | string, options?: {
+    base?: number | undefined;
+    precision?: number | undefined;
+}): string;
+//# sourceMappingURL=px_2_rem.d.ts.map

package/esm/convertors/px_2_rem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"px_2_rem.d.ts","sourceRoot":"","sources":["../../src/convertors/px_2_rem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,UASlH"}

package/esm/convertors/px_2_rem.js

@@ -0,0 +1,26 @@
+/**
+ * Converts pixel values to rem units.
+ *
+ * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate rem units from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'rem' units
+ *
+ * @example
+ * ```ts
+ * px2rem(16) // '1.0000'
+ * px2rem('32px') // '2.0000'
+ * px2rem(20, { base: 20 }) // '1.0000'
+ * px2rem(13, { precision: 2 }) // '0.81'
+ * ```
+ */
+export function px2rem(px, options) {
+    const { base = 16, precision = 4 } = options ?? {};
+    if (typeof px === 'string') {
+        px = px.replace(/px$/, '');
+        px = Number.parseFloat(px);
+    }
+    return (px / base).toFixed(precision);
+}
+//# sourceMappingURL=px_2_rem.js.map

package/esm/convertors/px_2_rem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"px_2_rem.js","sourceRoot":"","sources":["../../src/convertors/px_2_rem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,MAAM,CAAC,EAAmB,EAAE,OAAuE;IAClH,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,GAAG,CAAC,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAElD,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC5B,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAC1B,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IAC3B,CAAC;IAED,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACtC,CAAC"}

package/esm/convertors/rem_2_px.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Converts rem values to pixel units.
+ *
+ * @param rem - The rem value to convert. Can be a number or string (e.g. '1rem' or '1')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate pixels from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'px' units
+ *
+ * @example
+ * ```ts
+ * rem2px(1) // '16.0000'
+ * rem2px('2rem') // '32.0000'
+ * rem2px(1, { base: 20 }) // '20.0000'
+ * rem2px(0.8125, { precision: 2 }) // '13.00'
+ * ```
+ */
+export declare function rem2px(rem: number | string, options?: {
+    base?: number | undefined;
+    precision?: number | undefined;
+}): string;
+//# sourceMappingURL=rem_2_px.d.ts.map

package/esm/convertors/rem_2_px.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rem_2_px.d.ts","sourceRoot":"","sources":["../../src/convertors/rem_2_px.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,UASnH"}

package/esm/convertors/rem_2_px.js

@@ -0,0 +1,26 @@
+/**
+ * Converts rem values to pixel units.
+ *
+ * @param rem - The rem value to convert. Can be a number or string (e.g. '1rem' or '1')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate pixels from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'px' units
+ *
+ * @example
+ * ```ts
+ * rem2px(1) // '16.0000'
+ * rem2px('2rem') // '32.0000'
+ * rem2px(1, { base: 20 }) // '20.0000'
+ * rem2px(0.8125, { precision: 2 }) // '13.00'
+ * ```
+ */
+export function rem2px(rem, options) {
+    const { base = 16, precision = 4 } = options ?? {};
+    if (typeof rem === 'string') {
+        rem = rem.replace(/rem$/, '');
+        rem = Number.parseFloat(rem);
+    }
+    return (rem * base).toFixed(precision);
+}
+//# sourceMappingURL=rem_2_px.js.map

package/esm/convertors/rem_2_px.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rem_2_px.js","sourceRoot":"","sources":["../../src/convertors/rem_2_px.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,MAAM,CAAC,GAAoB,EAAE,OAAuE;IACnH,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,GAAG,CAAC,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAElD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QAC7B,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACvC,CAAC"}

package/esm/index.d.ts

@@ -1,3 +1,5 @@
+export * from './convertors/px_2_rem.ts';
+export * from './convertors/rem_2_px.ts';
 export * from './css-properties/css-properties.ts';
 export * from './css-properties/to_dom_style.ts';
 export * from './props/class-name.ts';

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAA;AAClD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,iCAAiC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oCAAoC,CAAA;AAClD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,iCAAiC,CAAA"}

package/esm/index.js

@@ -1,3 +1,5 @@
+export * from "./convertors/px_2_rem.js";
+export * from "./convertors/rem_2_px.js";
 export * from "./css-properties/css-properties.js";
 export * from "./css-properties/to_dom_style.js";
 export * from "./props/class-name.js";

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAA;AAClD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,iCAAiC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oCAAoC,CAAA;AAClD,cAAc,kCAAkC,CAAA;AAChD,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,uBAAuB,CAAA;AACrC,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,iCAAiC,CAAA"}

package/esm/testing/log-panel.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export function LogPanel({ title, log }) {
-    return (_jsxs("div", { className: "bg-neutral-100 p-4 rounded overflow-y-auto", children: [_jsx("h4", { className: "mb-2", children: title }), log.map((entry, i) => (_jsx("pre", { className: "font-mono", children: entry }, i)))] }));
+    return (_jsxs("div", { className: "bg-neutral-100 dark:bg-neutral-900 p-4 rounded overflow-y-auto", children: [_jsx("h4", { className: "mb-2", children: title }), log.map((entry, i) => (_jsx("pre", { className: "font-mono", children: entry }, i)))] }));
 }
 //# sourceMappingURL=log-panel.js.map

package/esm/testing/log-panel.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-panel.js","sourceRoot":"","sources":["../../src/testing/log-panel.tsx"],"names":[],"mappings":";AAAA,MAAM,UAAU,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,EAAoC;IACxE,OAAO,CACN,eAAK,SAAS,EAAC,4CAA4C,aAC1D,aAAI,SAAS,EAAC,MAAM,YAAE,KAAK,GAAM,EAChC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CACtB,cAAa,SAAS,EAAC,WAAW,YAChC,KAAK,IADG,CAAC,CAEL,CACN,CAAC,IACG,CACN,CAAA;AACF,CAAC"}
+{"version":3,"file":"log-panel.js","sourceRoot":"","sources":["../../src/testing/log-panel.tsx"],"names":[],"mappings":";AAAA,MAAM,UAAU,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,EAAoC;IACxE,OAAO,CACN,eAAK,SAAS,EAAC,gEAAgE,aAC9E,aAAI,SAAS,EAAC,MAAM,YAAE,KAAK,GAAM,EAChC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CACtB,cAAa,SAAS,EAAC,WAAW,YAChC,KAAK,IADG,CAAC,CAEL,CACN,CAAC,IACG,CACN,CAAA;AACF,CAAC"}

package/esm/theme/data-attribute.d.ts

@@ -5,6 +5,7 @@
  * @param options.themes - Record mapping theme keys to their data attribute values
  * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme
  * @param options.attributeName - Name of the data attribute to check (must start with 'data-')
+ * @param options.allowCustom - Whether to allow custom themes value
  * @returns The matching theme key, or defaultTheme if no match found
  *
  * @example
@@ -24,11 +25,18 @@
  * ```
  */
 export declare function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
-    themes: Themes;
-    defaultTheme?: keyof Themes | undefined;
     attributeName: `data-${string}`;
+    defaultTheme?: keyof Themes | undefined;
+    themes: Themes;
     element?: Element | undefined;
 }): keyof Themes | undefined;
+export declare function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+    attributeName: `data-${string}`;
+    allowCustom: true | undefined;
+    defaultTheme?: keyof Themes | undefined;
+    themes: Themes;
+    element?: Element | undefined;
+}): string | undefined;
 /**
  * Observes changes to a theme data attribute and calls a handler when it changes.
  *
@@ -65,4 +73,12 @@ export declare function observeThemeByDataAttributes<Themes extends Record<strin
     defaultTheme?: keyof Themes | undefined;
     element?: Element | undefined;
 }): MutationObserver;
+export declare function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {
+    attributeName: `data-${string}`;
+    themes: Themes;
+    handler: (value: string | null) => void;
+    allowCustom: true | undefined;
+    defaultTheme?: keyof Themes | undefined;
+    element?: Element | undefined;
+}): MutationObserver;
 //# sourceMappingURL=data-attribute.d.ts.map

package/esm/theme/data-attribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-attribute.d.ts","sourceRoot":"","sources":["../../src/theme/data-attribute.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IACvF,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,GAAG,MAAM,MAAM,GAAG,SAAS,CAM3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAC5F,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,oBAmBA"}
+{"version":3,"file":"data-attribute.d.ts","sourceRoot":"","sources":["../../src/theme/data-attribute.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IACvF,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,GAAG,MAAM,MAAM,GAAG,SAAS,CAAA;AAC5B,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IACvF,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,WAAW,EAAE,IAAI,GAAG,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,GAAG,MAAM,GAAG,SAAS,CAAA;AActB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAC5F,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,GAAG,gBAAgB,CAAA;AACpB,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;IAC5F,aAAa,EAAE,QAAQ,MAAM,EAAE,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IACvC,WAAW,EAAE,IAAI,GAAG,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,GAAG,gBAAgB,CAAA"}

package/esm/theme/data-attribute.js

@@ -1,64 +1,10 @@
 import { findKey } from 'type-plus';
 import { getDataAttribute, observeDataAttributes } from "../utils/data-attribute.js";
-/**
- * Gets the theme based on a data attribute value.
- *
- * @param options - Configuration options
- * @param options.themes - Record mapping theme keys to their data attribute values
- * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme
- * @param options.attributeName - Name of the data attribute to check (must start with 'data-')
- * @returns The matching theme key, or defaultTheme if no match found
- *
- * @example
- * ```ts
- * const themes = {
- *   light: 'light',
- *   dark: 'dark',
- *   system: 'system'
- * }
- *
- * // Get theme from data-theme attribute
- * const theme = getThemeByDataAttribute({
- *   themes,
- *   defaultTheme: 'system',
- *   attributeName: 'data-theme'
- * })
- * ```
- */
 export function getThemeByDataAttribute(options) {
-    const value = getDataAttribute(options.attributeName, options.element);
+    const value = getDataAttribute(options.attributeName, options.element) ?? undefined;
     const theme = findKey(options.themes, (theme) => options.themes[theme] === value);
-    return theme ?? options.defaultTheme;
+    return theme ?? options.defaultTheme ?? (options.allowCustom ? value : undefined);
 }
-/**
- * Observes changes to a theme data attribute and calls a handler when it changes.
- *
- * @param options - Configuration options
- * @param options.themes - Record mapping theme keys to their data attribute values
- * @param options.handler - Callback function called with the new theme value or null when removed
- * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme
- * @param options.attributeName - Name of the data attribute to observe (must start with 'data-')
- * @returns A MutationObserver that can be disconnected to stop observing
- *
- * @example
- * ```ts
- * const themes = {
- *   light: 'light',
- *   dark: 'dark'
- * }
- *
- * // Observe data-theme attribute changes
- * const observer = observeThemeByDataAttributes({
- *   themes,
- *   handler: (theme) => console.log('Theme changed to:', theme),
- *   defaultTheme: 'light',
- *   attributeName: 'data-theme'
- * })
- *
- * // Stop observing
- * observer.disconnect()
- * ```
- */
 export function observeThemeByDataAttributes(options) {
     return observeDataAttributes({
         [options.attributeName]: (value) => {
@@ -69,9 +15,12 @@ export function observeThemeByDataAttributes(options) {
             for (const name in options.themes) {
                 if (options.themes[name] === value) {
                     options.handler(name);
-                    break;
+                    return;
                 }
             }
+            if (options.allowCustom) {
+                options.handler(value);
+            }
         },
     }, options.element);
 }

package/esm/theme/data-attribute.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-attribute.js","sourceRoot":"","sources":["../../src/theme/data-attribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,uBAAuB,CAAwC,OAK9E;IACA,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtE,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,CAAA;IAEjF,OAAO,KAAK,IAAI,OAAO,CAAC,YAAY,CAAA;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,4BAA4B,CAAwC,OAMnF;IACA,OAAO,qBAAqB,CAC3B;QACC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,KAAoB,EAAE,EAAE;YACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,CAAC,OAAO,CAAE,OAAO,CAAC,YAAuB,IAAI,IAAI,CAAC,CAAA;gBACzD,OAAM;YACP,CAAC;YAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnC,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;oBACpC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;oBACrB,MAAK;gBACN,CAAC;YACF,CAAC;QACF,CAAC;KACD,EACD,OAAO,CAAC,OAAO,CACf,CAAA;AACF,CAAC"}
+{"version":3,"file":"data-attribute.js","sourceRoot":"","sources":["../../src/theme/data-attribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AAyCpF,MAAM,UAAU,uBAAuB,CAAwC,OAM9E;IACA,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,SAAS,CAAA;IACnF,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,CAAA;IAEjF,OAAO,KAAK,IAAI,OAAO,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAClF,CAAC;AA8CD,MAAM,UAAU,4BAA4B,CAAwC,OAOnF;IACA,OAAO,qBAAqB,CAC3B;QACC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,KAAoB,EAAE,EAAE;YACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,CAAC,OAAO,CAAE,OAAO,CAAC,YAAuB,IAAI,IAAI,CAAC,CAAA;gBACzD,OAAM;YACP,CAAC;YAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnC,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;oBACpC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;oBACrB,OAAM;gBACP,CAAC;YACF,CAAC;YAED,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBACzB,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACvB,CAAC;QACF,CAAC;KACD,EACD,OAAO,CAAC,OAAO,CACf,CAAA;AACF,CAAC"}

package/esm/utils/attribute.d.ts

@@ -14,7 +14,7 @@
  * const testId = getAttribute('data-testid', element)
  * ```
  */
-export declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): T | null;
+export declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): string | null;
 /**
  * Observes attributes changes on an element and calls corresponding handlers.
  *

package/esm/utils/attribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../../src/utils/attribute.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC5C,aAAa,EAAE,CAAC,EAChB,OAAO,GAAE,OAAO,GAAG,SAAoC,GAER,CAAC,GAAG,IAAI,CACvD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,EACnD,OAAO,GAAE,OAAO,GAAG,SAAoC,oBAcvD"}
+{"version":3,"file":"attribute.d.ts","sourceRoot":"","sources":["../../src/utils/attribute.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC5C,aAAa,EAAE,CAAC,EAChB,OAAO,GAAE,OAAO,GAAG,SAAoC,iBAGvD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,EACnD,OAAO,GAAE,OAAO,GAAG,SAAoC,oBAcvD"}

package/esm/utils/attribute.js.map

@@ -1 +1 @@
-{"version":3,"file":"attribute.js","sourceRoot":"","sources":["../../src/utils/attribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAC3B,aAAgB,EAChB,UAA+B,GAAG,CAAC,kBAAkB,EAAE;IAEvD,OAAO,OAAO,EAAE,YAAY,CAAC,aAAa,CAAa,CAAA;AACxD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAChC,QAAmD,EACnD,UAA+B,GAAG,CAAC,kBAAkB,EAAE;IAEvD,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;QACnD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAc,CAAA;YACzC,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAa,CAAA;YACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;QAC7B,CAAC;IACF,CAAC,CAAC,CAAA;IACF,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE;QACzB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;KACtC,CAAC,CAAA;IACF,OAAO,QAAQ,CAAA;AAChB,CAAC"}
+{"version":3,"file":"attribute.js","sourceRoot":"","sources":["../../src/utils/attribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAC3B,aAAgB,EAChB,UAA+B,GAAG,CAAC,kBAAkB,EAAE;IAEvD,OAAO,OAAO,EAAE,YAAY,CAAC,aAAa,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAChC,QAAmD,EACnD,UAA+B,GAAG,CAAC,kBAAkB,EAAE;IAEvD,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,CAAC,SAAS,EAAE,EAAE;QACnD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAc,CAAA;YACzC,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,CAAa,CAAA;YACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;QAC7B,CAAC;IACF,CAAC,CAAC,CAAA;IACF,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE;QACzB,UAAU,EAAE,IAAI;QAChB,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;KACtC,CAAC,CAAA;IACF,OAAO,QAAQ,CAAA;AAChB,CAAC"}

package/esm/utils/data-attribute.d.ts

@@ -1,4 +1,4 @@
-export declare function getDataAttribute<T extends `data-${string}`>(qualifiedName: T, element?: Element | undefined): T | null;
+export declare function getDataAttribute<T extends `data-${string}`>(qualifiedName: T, element?: Element | undefined): string | null;
 /**
  * Observes changes to `data-*` attributes on an element and calls corresponding handlers.
  *

package/esm/utils/data-attribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-attribute.d.ts","sourceRoot":"","sources":["../../src/utils/data-attribute.ts"],"names":[],"mappings":"AAGA,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,MAAM,EAAE,EAC1D,aAAa,EAAE,CAAC,EAChB,OAAO,GAAE,OAAO,GAAG,SAAoC,YAGvD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,MAAM,EAAE,EACjF,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,EAC9C,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,oBAG7B"}
+{"version":3,"file":"data-attribute.d.ts","sourceRoot":"","sources":["../../src/utils/data-attribute.ts"],"names":[],"mappings":"AAGA,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,MAAM,EAAE,EAC1D,aAAa,EAAE,CAAC,EAChB,OAAO,GAAE,OAAO,GAAG,SAAoC,iBAGvD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,MAAM,EAAE,EACjF,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,EAC9C,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,oBAG7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@just-web/css",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CSS types and utilities",
   "type": "module",
   "exports": {
@@ -24,7 +24,7 @@
     "type-plus": "8.0.0-beta.7"
   },
   "devDependencies": {
-    "@repobuddy/storybook": "^0.9.4",
+    "@repobuddy/storybook": "^0.12.0",
     "@repobuddy/vitest": "^1.2.2",
     "@storybook/addon-essentials": "^8.6.12",
     "@storybook/addon-storysource": "^8.6.12",

package/src/convertors/px_2_rem.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts pixel values to rem units.
+ *
+ * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate rem units from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'rem' units
+ *
+ * @example
+ * ```ts
+ * px2rem(16) // '1.0000'
+ * px2rem('32px') // '2.0000'
+ * px2rem(20, { base: 20 }) // '1.0000'
+ * px2rem(13, { precision: 2 }) // '0.81'
+ * ```
+ */
+export function px2rem(px: number | string, options?: { base?: number | undefined; precision?: number | undefined }) {
+	const { base = 16, precision = 4 } = options ?? {}
+
+	if (typeof px === 'string') {
+		px = px.replace(/px$/, '')
+		px = Number.parseFloat(px)
+	}
+
+	return (px / base).toFixed(precision)
+}

package/src/convertors/rem_2_px.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts rem values to pixel units.
+ *
+ * @param rem - The rem value to convert. Can be a number or string (e.g. '1rem' or '1')
+ * @param options - Optional configuration
+ * @param options.base - Base pixel value to calculate pixels from. Defaults to 16
+ * @param options.precision - Number of decimal places in the output. Defaults to 4
+ * @returns The converted value as a string with 'px' units
+ *
+ * @example
+ * ```ts
+ * rem2px(1) // '16.0000'
+ * rem2px('2rem') // '32.0000'
+ * rem2px(1, { base: 20 }) // '20.0000'
+ * rem2px(0.8125, { precision: 2 }) // '13.00'
+ * ```
+ */
+export function rem2px(rem: number | string, options?: { base?: number | undefined; precision?: number | undefined }) {
+	const { base = 16, precision = 4 } = options ?? {}
+
+	if (typeof rem === 'string') {
+		rem = rem.replace(/rem$/, '')
+		rem = Number.parseFloat(rem)
+	}
+
+	return (rem * base).toFixed(precision)
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from './convertors/px_2_rem.ts'
+export * from './convertors/rem_2_px.ts'
 export * from './css-properties/css-properties.ts'
 export * from './css-properties/to_dom_style.ts'
 export * from './props/class-name.ts'

package/src/tailwind.css

@@ -1 +1,3 @@
-@import "tailwindcss";
+@import "tailwindcss";
+
+@custom-variant dark (&:where(.dark, .dark *));

package/src/testing/log-panel.tsx

@@ -1,6 +1,6 @@
 export function LogPanel({ title, log }: { title: string; log: string[] }) {
 	return (
-		<div className="bg-neutral-100 p-4 rounded overflow-y-auto">
+		<div className="bg-neutral-100 dark:bg-neutral-900 p-4 rounded overflow-y-auto">
 			<h4 className="mb-2">{title}</h4>
 			{log.map((entry, i) => (
 				<pre key={i} className="font-mono">

package/src/theme/data-attribute.ts

@@ -8,6 +8,7 @@ import { getDataAttribute, observeDataAttributes } from '../utils/data-attribute
  * @param options.themes - Record mapping theme keys to their data attribute values
  * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme
  * @param options.attributeName - Name of the data attribute to check (must start with 'data-')
+ * @param options.allowCustom - Whether to allow custom themes value
  * @returns The matching theme key, or defaultTheme if no match found
  *
  * @example
@@ -27,16 +28,29 @@ import { getDataAttribute, observeDataAttributes } from '../utils/data-attribute
  * ```
  */
 export function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+	attributeName: `data-${string}`
+	defaultTheme?: keyof Themes | undefined
 	themes: Themes
+	element?: Element | undefined
+}): keyof Themes | undefined
+export function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+	attributeName: `data-${string}`
+	allowCustom: true | undefined
 	defaultTheme?: keyof Themes | undefined
+	themes: Themes
+	element?: Element | undefined
+}): string | undefined
+export function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
 	attributeName: `data-${string}`
+	allowCustom?: boolean | undefined
+	defaultTheme?: keyof Themes | undefined
+	themes: Themes
 	element?: Element | undefined
 }): keyof Themes | undefined {
-	const value = getDataAttribute(options.attributeName, options.element)
-
+	const value = getDataAttribute(options.attributeName, options.element) ?? undefined
 	const theme = findKey(options.themes, (theme) => options.themes[theme] === value)
 
-	return theme ?? options.defaultTheme
+	return theme ?? options.defaultTheme ?? (options.allowCustom ? value : undefined)
 }
 
 /**
@@ -74,7 +88,23 @@ export function observeThemeByDataAttributes<Themes extends Record<string, strin
 	handler: (value: string | null) => void
 	defaultTheme?: keyof Themes | undefined
 	element?: Element | undefined
-}) {
+}): MutationObserver
+export function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {
+	attributeName: `data-${string}`
+	themes: Themes
+	handler: (value: string | null) => void
+	allowCustom: true | undefined
+	defaultTheme?: keyof Themes | undefined
+	element?: Element | undefined
+}): MutationObserver
+export function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {
+	attributeName: `data-${string}`
+	themes: Themes
+	handler: (value: string | null) => void
+	allowCustom?: boolean | undefined
+	defaultTheme?: keyof Themes | undefined
+	element?: Element | undefined
+}): MutationObserver {
 	return observeDataAttributes(
 		{
 			[options.attributeName]: (value: string | null) => {
@@ -86,9 +116,13 @@ export function observeThemeByDataAttributes<Themes extends Record<string, strin
 				for (const name in options.themes) {
 					if (options.themes[name] === value) {
 						options.handler(name)
-						break
+						return
 					}
 				}
+
+				if (options.allowCustom) {
+					options.handler(value)
+				}
 			},
 		},
 		options.element,

package/src/utils/attribute.ts

@@ -20,7 +20,7 @@ export function getAttribute<T extends string>(
 	qualifiedName: T,
 	element: Element | undefined = ctx.getDocumentElement(),
 ) {
-	return element?.getAttribute(qualifiedName) as T | null
+	return element?.getAttribute(qualifiedName)
 }
 
 /**