@just-web/css 0.6.1 → 0.8.0

package/esm/index.mjs

@@ -0,0 +1,378 @@
+import { findKey, mapKey } from "type-plus";
+
+//#region src/convertors/px_2_num.ts
+/**
+* Converts pixel values to numbers.
+*
+* @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+* @returns The numeric value
+*
+* @example
+* ```ts
+* px2num(16) // 16
+* px2num('32px') // 32
+* px2num('12.5px') // 12.5
+* px2num('0px') // 0
+* ```
+*/
+function px2num(px) {
+	return typeof px === "string" ? Number.parseFloat(px.replace(/px$/, "")) : Number(px);
+}
+
+//#endregion
+//#region src/convertors/px_2_rem.ts
+/**
+* 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'
+* ```
+*/
+function px2rem(px, options) {
+	const { base = 16, precision = 4 } = options ?? {};
+	if (typeof px === "string") {
+		px = px.replace(/px$/, "");
+		px = Number.parseFloat(px);
+	}
+	return Number((px / base).toFixed(precision));
+}
+
+//#endregion
+//#region src/convertors/rem_2_px.ts
+/**
+* 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'
+* ```
+*/
+function rem2px(rem, options) {
+	const { base = 16, precision = 4 } = options ?? {};
+	if (typeof rem === "string") {
+		rem = rem.replace(/rem$/, "");
+		rem = Number.parseFloat(rem);
+	}
+	return Number((rem * base).toFixed(precision));
+}
+
+//#endregion
+//#region src/properties/css_properties.ts
+/**
+* Defines CSS properties including custom properties.
+* This function is used to properly type CSS properties when defining styles,
+* especially when using CSS custom properties (variables).
+*
+* @deprecated Use `defineProperties` instead.
+*
+* @param style - CSS properties object that can include both standard and custom properties
+* @returns The same style object with proper typing
+*
+* @example
+* ```ts
+* defineCSSProperties({
+*   color: 'red',
+*   '--custom-color': '#ff0000'
+* })
+* ```
+*/
+function defineCSSProperties(style) {
+	return style;
+}
+
+//#endregion
+//#region src/properties/properties.ts
+/**
+* Defines CSS properties including custom properties.
+* This function is used to properly type CSS properties when defining styles,
+* especially when using CSS custom properties (variables).
+*
+* @param style - CSS properties object that can include both standard and custom properties
+* @returns The same style object with proper typing
+*
+* @example
+* ```ts
+* defineCSSProperties({
+*   color: 'red',
+*   '--custom-color': '#ff0000'
+* })
+* ```
+*/
+function defineProperties(style) {
+	return style;
+}
+
+//#endregion
+//#region src/properties/to_dom_style.ts
+/**
+* Converts React-style CSS properties to DOM style properties.
+* This function handles both standard CSS properties and custom properties,
+* ensuring proper formatting for DOM style application.
+*
+* @param style - React-style CSS properties object
+* @returns CSSStyleDeclaration compatible object for DOM style application
+*
+* @example
+* ```ts
+* const domStyle = toDOMStyle({
+*   backgroundColor: 'red',
+*   '--custom-color': '#ff0000'
+* })
+* element.style = domStyle
+* ```
+*/
+function toDOMStyle(style) {
+	if (style === void 0) return void 0;
+	const result = {};
+	for (const [key, value] of Object.entries(style)) result[key.startsWith("--") ? key : key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`)] = value;
+	return result;
+}
+
+//#endregion
+//#region src/globals.ctx.ts
+const ctx = {
+	matchMedia(query) {
+		return globalThis.matchMedia(query);
+	},
+	getDocumentElement() {
+		return globalThis.document.documentElement;
+	},
+	_reset() {
+		this.matchMedia = globalThis.matchMedia;
+		this.getDocumentElement = () => globalThis.document.documentElement;
+	}
+};
+
+//#endregion
+//#region src/utils/attribute.ts
+/**
+* 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`
+* @returns The attribute value cast to type T, or null if the attribute doesn't exist
+*
+* @example
+* ```ts
+* // Get theme from document root
+* const theme = getAttribute('data-theme')
+*
+* // Get data-testid from a specific element
+* const testId = getAttribute('data-testid', element)
+* ```
+*/
+function getAttribute(qualifiedName, element = ctx.getDocumentElement()) {
+	return element?.getAttribute(qualifiedName);
+}
+/**
+* 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.
+*
+* @example
+* ```ts
+* const observer = observeAttributes({
+*   'data-theme': (attr, value) => console.log(`Theme changed to: ${value}`),
+*   'class': (attr, value) => console.log(`class changed to: ${value}`)
+* });
+*
+* // Later, to stop observing:
+* observer.disconnect();
+* ```
+*/
+function observeAttributes(handlers, element = ctx.getDocumentElement()) {
+	const observer = new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			const attribute = mutation.attributeName;
+			const value = element.getAttribute(attribute);
+			handlers[attribute]?.(value);
+		}
+	});
+	observer.observe(element, {
+		attributes: true,
+		attributeFilter: Object.keys(handlers)
+	});
+	return observer;
+}
+
+//#endregion
+//#region src/theme/class-name.ts
+/**
+* Gets the current theme by checking element class names against a themes map.
+*
+* @param options - Configuration options
+* @param options.themes - Record mapping theme keys to their class name values
+* @param options.defaultTheme - Fallback theme key if no matching class is found
+* @param options.element - Element to check classes on (defaults to document.documentElement)
+* @returns The matching theme key or defaultTheme if no match found
+*
+* @example
+* ```ts
+* const themes = {
+*   light: 'theme-light',
+*   dark: 'theme-dark'
+* }
+*
+* // Get current theme from document.documentElement
+* const theme = getThemeByClassName({
+*   themes,
+*   defaultTheme: 'light'
+* })
+*
+* // Get theme from specific element
+* const theme = getThemeByClassName({
+*   themes,
+*   element: myElement,
+*   defaultTheme: 'light'
+* })
+* ```
+*/
+function getThemeByClassName(options) {
+	const className = (options.element ?? ctx.getDocumentElement()).className;
+	return findKey(options.themes, (theme) => className.includes(options.themes[theme])) ?? options.defaultTheme;
+}
+function observeThemeByClassName(options) {
+	return observeAttributes({ class: (value) => {
+		if (value === null) {
+			options.handler(options.defaultTheme);
+			return;
+		}
+		for (const name in options.themes) if (value.includes(options.themes[name])) {
+			options.handler(name);
+			break;
+		}
+	} }, options.element);
+}
+
+//#endregion
+//#region src/utils/data-attribute.ts
+function getDataAttribute(qualifiedName, element = ctx.getDocumentElement()) {
+	return getAttribute(qualifiedName, element);
+}
+/**
+* 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
+*
+* @example
+* ```ts
+* const observer = observeDataAttributes({
+*   handlers: {
+*     'data-theme': (value) => console.log(`Theme changed to: ${value}`),
+*     'data-mode': (value) => console.log(`Mode changed to: ${value}`)
+*   }
+* });
+*
+* // Later, to stop observing:
+* observer.disconnect();
+* ```
+*/
+function observeDataAttributes(handlers, element) {
+	return observeAttributes(handlers, element);
+}
+
+//#endregion
+//#region src/theme/data-attribute.ts
+function getThemeByDataAttribute(options) {
+	const value = getDataAttribute(options.attributeName, options.element) ?? void 0;
+	return findKey(options.themes, (theme) => options.themes[theme] === value) ?? options.defaultTheme ?? (options.allowCustom ? value : void 0);
+}
+function observeThemeByDataAttributes(options) {
+	return observeDataAttributes({ [options.attributeName]: (value) => {
+		if (value === null) {
+			options.handler(options.defaultTheme ?? null);
+			return;
+		}
+		for (const name in options.themes) if (options.themes[name] === value) {
+			options.handler(name);
+			return;
+		}
+		if (options.allowCustom) options.handler(value);
+	} }, options.element);
+}
+
+//#endregion
+//#region src/utils/get-css-prop-values.ts
+function getCSSPropValues(element, ...props) {
+	if (typeof element === "string") return getCSSPropValues(globalThis.document.body, element, ...props);
+	const style = globalThis.getComputedStyle(element);
+	return props.map((v) => style.getPropertyValue(v));
+}
+
+//#endregion
+//#region src/utils/prefers-color-scheme.ts
+/**
+* Observes system color scheme preference changes and calls handlers when they occur.
+*
+* @param themes - An object mapping theme names to handler functions that are called when that theme is activated
+* @returns A cleanup function that removes all event listeners
+*
+* @example
+* ```ts
+* // Observe light/dark mode changes
+* const cleanup = observePrefersColorScheme({
+*   light: (theme) => console.log('Light mode activated'),
+*   dark: (theme) => console.log('Dark mode activated')
+* })
+*
+* // Later, to stop observing:
+* cleanup()
+* ```
+*/
+function observePrefersColorScheme(themes) {
+	const removers = mapKey(themes, (t) => {
+		const m = ctx.matchMedia(`(prefers-color-scheme: ${t})`);
+		const listener = (event) => {
+			if (event.matches) themes[t]?.(t);
+		};
+		m.addEventListener("change", listener);
+		return () => m.removeEventListener("change", listener);
+	});
+	return () => {
+		for (const remover of removers) remover();
+	};
+}
+/**
+* Gets the current preferred color theme from the system settings.
+*
+* @param themes - A list of theme names to check against the system preference
+* @returns The first matching theme from the provided list, or null if none match
+*
+* @example
+* ```ts
+* // Check if system prefers light or dark mode
+* const theme = getPrefersColorTheme('light', 'dark')
+* // Returns 'light', 'dark', or null
+* ```
+*/
+function getPrefersColorTheme(...themes) {
+	return themes.find((theme) => ctx.matchMedia(`(prefers-color-scheme: ${theme})`).matches) ?? null;
+}
+
+//#endregion
+export { defineCSSProperties, defineProperties, getAttribute, getCSSPropValues, getDataAttribute, getPrefersColorTheme, getThemeByClassName, getThemeByDataAttribute, observeAttributes, observeDataAttributes, observePrefersColorScheme, observeThemeByClassName, observeThemeByDataAttributes, px2num, px2rem, rem2px, toDOMStyle };
+//# sourceMappingURL=index.mjs.map

package/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/convertors/px_2_num.ts","../src/convertors/px_2_rem.ts","../src/convertors/rem_2_px.ts","../src/properties/css_properties.ts","../src/properties/properties.ts","../src/properties/to_dom_style.ts","../src/globals.ctx.ts","../src/utils/attribute.ts","../src/theme/class-name.ts","../src/utils/data-attribute.ts","../src/theme/data-attribute.ts","../src/utils/get-css-prop-values.ts","../src/utils/prefers-color-scheme.ts"],"sourcesContent":["/**\n * Converts pixel values to numbers.\n *\n * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')\n * @returns The numeric value\n *\n * @example\n * ```ts\n * px2num(16) // 16\n * px2num('32px') // 32\n * px2num('12.5px') // 12.5\n * px2num('0px') // 0\n * ```\n */\nexport function px2num(px: number | string | undefined): number {\n\treturn typeof px === 'string' ? Number.parseFloat(px.replace(/px$/, '')) : Number(px)\n}\n","/**\n * Converts pixel values to rem units.\n *\n * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')\n * @param options - Optional configuration\n * @param options.base - Base pixel value to calculate rem units from. Defaults to 16\n * @param options.precision - Number of decimal places in the output. Defaults to 4\n * @returns The converted value as a string with 'rem' units\n *\n * @example\n * ```ts\n * px2rem(16) // '1.0000'\n * px2rem('32px') // '2.0000'\n * px2rem(20, { base: 20 }) // '1.0000'\n * px2rem(13, { precision: 2 }) // '0.81'\n * ```\n */\nexport function px2rem(\n\tpx: number | string,\n\toptions?: { base?: number | undefined; precision?: number | undefined },\n): number {\n\tconst { base = 16, precision = 4 } = options ?? {}\n\n\tif (typeof px === 'string') {\n\t\tpx = px.replace(/px$/, '')\n\t\tpx = Number.parseFloat(px)\n\t}\n\n\treturn Number((px / base).toFixed(precision))\n}\n","/**\n * Converts rem values to pixel units.\n *\n * @param rem - The rem value to convert. Can be a number or string (e.g. '1rem' or '1')\n * @param options - Optional configuration\n * @param options.base - Base pixel value to calculate pixels from. Defaults to 16\n * @param options.precision - Number of decimal places in the output. Defaults to 4\n * @returns The converted value as a string with 'px' units\n *\n * @example\n * ```ts\n * rem2px(1) // '16.0000'\n * rem2px('2rem') // '32.0000'\n * rem2px(1, { base: 20 }) // '20.0000'\n * rem2px(0.8125, { precision: 2 }) // '13.00'\n * ```\n */\nexport function rem2px(\n\trem: number | string,\n\toptions?: { base?: number | undefined; precision?: number | undefined },\n): number {\n\tconst { base = 16, precision = 4 } = options ?? {}\n\n\tif (typeof rem === 'string') {\n\t\trem = rem.replace(/rem$/, '')\n\t\trem = Number.parseFloat(rem)\n\t}\n\n\treturn Number((rem * base).toFixed(precision))\n}\n","import type { Properties as CSSTypeProperties } from 'csstype'\n\n/**\n * Extends CSS properties to include custom properties.\n * Allows for string or number values for standard properties,\n * and string values for custom properties with '--' prefix.\n *\n * @deprecated Use `Properties` instead.\n */\nexport interface CSSProperties extends CSSTypeProperties<string | number> {\n\t[k: `--${string}`]: string\n}\n\n/**\n * Defines CSS properties including custom properties.\n * This function is used to properly type CSS properties when defining styles,\n * especially when using CSS custom properties (variables).\n *\n * @deprecated Use `defineProperties` instead.\n *\n * @param style - CSS properties object that can include both standard and custom properties\n * @returns The same style object with proper typing\n *\n * @example\n * ```ts\n * defineCSSProperties({\n *   color: 'red',\n *   '--custom-color': '#ff0000'\n * })\n * ```\n */\nexport function defineCSSProperties(style: CSSProperties) {\n\treturn style as any\n}\n","import type { Properties as CSSTypeProperties } from 'csstype'\n\n/**\n * Extends CSS properties to include custom properties.\n * Allows for string or number values for standard properties,\n * and string values for custom properties with '--' prefix.\n */\nexport interface Properties<TLength = 0 | (string & {}), TTime = string & {}>\n\textends CSSTypeProperties<TLength, TTime> {\n\t[k: `--${string}`]: string\n}\n\n/**\n * Defines CSS properties including custom properties.\n * This function is used to properly type CSS properties when defining styles,\n * especially when using CSS custom properties (variables).\n *\n * @param style - CSS properties object that can include both standard and custom properties\n * @returns The same style object with proper typing\n *\n * @example\n * ```ts\n * defineCSSProperties({\n *   color: 'red',\n *   '--custom-color': '#ff0000'\n * })\n * ```\n */\nexport function defineProperties<TLength = 0 | (string & {}), TTime = string & {}>(style: Properties<TLength, TTime>) {\n\treturn style as Properties\n}\n","import type { CSSProperties } from './css_properties.ts'\n\n/**\n * Converts React-style CSS properties to DOM style properties.\n * This function handles both standard CSS properties and custom properties,\n * ensuring proper formatting for DOM style application.\n *\n * @param style - React-style CSS properties object\n * @returns CSSStyleDeclaration compatible object for DOM style application\n *\n * @example\n * ```ts\n * const domStyle = toDOMStyle({\n *   backgroundColor: 'red',\n *   '--custom-color': '#ff0000'\n * })\n * element.style = domStyle\n * ```\n */\nexport function toDOMStyle(style: CSSProperties | undefined): Partial<CSSStyleDeclaration> | undefined {\n\tif (style === undefined) return undefined\n\n\tconst result = {} as any\n\n\tfor (const [key, value] of Object.entries(style)) {\n\t\tresult[key.startsWith('--') ? key : key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`)] = value\n\t}\n\n\treturn result\n}\n","export const ctx = {\n\tmatchMedia(query: string) {\n\t\treturn globalThis.matchMedia(query)\n\t},\n\tgetDocumentElement() {\n\t\treturn globalThis.document.documentElement\n\t},\n\t_reset() {\n\t\tthis.matchMedia = globalThis.matchMedia\n\t\tthis.getDocumentElement = () => globalThis.document.documentElement\n\t},\n}\n","import { ctx } from '../globals.ctx.ts'\n\n/**\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>(\n\tqualifiedName: T,\n\telement: Element | undefined = ctx.getDocumentElement(),\n) {\n\treturn element?.getAttribute(qualifiedName)\n}\n\n/**\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 = ctx.getDocumentElement(),\n) {\n\tconst observer = new MutationObserver((mutations) => {\n\t\tfor (const mutation of mutations) {\n\t\t\tconst attribute = mutation.attributeName!\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","import { findKey } from 'type-plus'\nimport { ctx } from '../globals.ctx.ts'\nimport { observeAttributes } from '../utils/attribute.ts'\n\n/**\n * Gets the current theme by checking element class names against a themes map.\n *\n * @param options - Configuration options\n * @param options.themes - Record mapping theme keys to their class name values\n * @param options.defaultTheme - Fallback theme key if no matching class is found\n * @param options.element - Element to check classes on (defaults to document.documentElement)\n * @returns The matching theme key or defaultTheme if no match found\n *\n * @example\n * ```ts\n * const themes = {\n *   light: 'theme-light',\n *   dark: 'theme-dark'\n * }\n *\n * // Get current theme from document.documentElement\n * const theme = getThemeByClassName({\n *   themes,\n *   defaultTheme: 'light'\n * })\n *\n * // Get theme from specific element\n * const theme = getThemeByClassName({\n *   themes,\n *   element: myElement,\n *   defaultTheme: 'light'\n * })\n * ```\n */\nexport function getThemeByClassName<Themes extends Record<string, string>>(options: {\n\tthemes: Themes\n\tdefaultTheme?: keyof Themes | undefined\n\telement?: Element | undefined\n}): keyof Themes | undefined {\n\tconst element = options.element ?? ctx.getDocumentElement()\n\tconst className = element.className\n\tconst theme = findKey(options.themes, (theme) => className.includes(options.themes[theme]!))\n\treturn theme ?? options.defaultTheme\n}\n\nexport function observeThemeByClassName<Themes extends Record<string, string>>(options: {\n\tthemes: Themes\n\thandler: (value: string | undefined) => void\n\tdefaultTheme?: keyof Themes | undefined\n\telement?: Element | undefined\n}) {\n\treturn observeAttributes(\n\t\t{\n\t\t\tclass: (value: string | null) => {\n\t\t\t\tif (value === null) {\n\t\t\t\t\toptions.handler(options.defaultTheme as string)\n\t\t\t\t\treturn\n\t\t\t\t}\n\n\t\t\t\tfor (const name in options.themes) {\n\t\t\t\t\tif (value.includes(options.themes[name]!)) {\n\t\t\t\t\t\toptions.handler(name)\n\t\t\t\t\t\tbreak\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\toptions.element,\n\t)\n}\n","import { ctx } from '../globals.ctx.ts'\nimport { getAttribute, observeAttributes } from './attribute.ts'\n\nexport function getDataAttribute<T extends `data-${string}`>(\n\tqualifiedName: T,\n\telement: Element | undefined = ctx.getDocumentElement(),\n) {\n\treturn getAttribute(qualifiedName, element)\n}\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","import { findKey } from 'type-plus'\nimport { getDataAttribute, observeDataAttributes } from '../utils/data-attribute.ts'\n\n/**\n * Gets the theme based on a data attribute value.\n *\n * @param options - Configuration options\n * @param options.themes - Record mapping theme keys to their data attribute values\n * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme\n * @param options.attributeName - Name of the data attribute to check (must start with 'data-')\n * @param options.allowCustom - Whether to allow custom themes value\n * @returns The matching theme key, or defaultTheme if no match found\n *\n * @example\n * ```ts\n * const themes = {\n *   light: 'light',\n *   dark: 'dark',\n *   system: 'system'\n * }\n *\n * // Get theme from data-theme attribute\n * const theme = getThemeByDataAttribute({\n *   themes,\n *   defaultTheme: 'system',\n *   attributeName: 'data-theme'\n * })\n * ```\n */\nexport function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tdefaultTheme?: keyof Themes | undefined\n\tthemes: Themes\n\telement?: Element | undefined\n}): keyof Themes | undefined\nexport function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tallowCustom: true | undefined\n\tdefaultTheme?: keyof Themes | undefined\n\tthemes: Themes\n\telement?: Element | undefined\n}): string | undefined\nexport function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tallowCustom?: boolean | undefined\n\tdefaultTheme?: keyof Themes | undefined\n\tthemes: Themes\n\telement?: Element | undefined\n}): keyof Themes | undefined {\n\tconst value = getDataAttribute(options.attributeName, options.element) ?? undefined\n\tconst theme = findKey(options.themes, (theme) => options.themes[theme] === value)\n\n\treturn theme ?? options.defaultTheme ?? (options.allowCustom ? value : undefined)\n}\n\n/**\n * Observes changes to a theme data attribute and calls a handler when it changes.\n *\n * @param options - Configuration options\n * @param options.themes - Record mapping theme keys to their data attribute values\n * @param options.handler - Callback function called with the new theme value or null when removed\n * @param options.defaultTheme - Fallback theme key if attribute value doesn't match any theme\n * @param options.attributeName - Name of the data attribute to observe (must start with 'data-')\n * @returns A MutationObserver that can be disconnected to stop observing\n *\n * @example\n * ```ts\n * const themes = {\n *   light: 'light',\n *   dark: 'dark'\n * }\n *\n * // Observe data-theme attribute changes\n * const observer = observeThemeByDataAttributes({\n *   themes,\n *   handler: (theme) => console.log('Theme changed to:', theme),\n *   defaultTheme: 'light',\n *   attributeName: 'data-theme'\n * })\n *\n * // Stop observing\n * observer.disconnect()\n * ```\n */\nexport function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tthemes: Themes\n\thandler: (value: string | null) => void\n\tdefaultTheme?: keyof Themes | undefined\n\telement?: Element | undefined\n}): MutationObserver\nexport function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tthemes: Themes\n\thandler: (value: string | null) => void\n\tallowCustom: true | undefined\n\tdefaultTheme?: keyof Themes | undefined\n\telement?: Element | undefined\n}): MutationObserver\nexport function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {\n\tattributeName: `data-${string}`\n\tthemes: Themes\n\thandler: (value: string | null) => void\n\tallowCustom?: boolean | undefined\n\tdefaultTheme?: keyof Themes | undefined\n\telement?: Element | undefined\n}): MutationObserver {\n\treturn observeDataAttributes(\n\t\t{\n\t\t\t[options.attributeName]: (value: string | null) => {\n\t\t\t\tif (value === null) {\n\t\t\t\t\toptions.handler((options.defaultTheme as string) ?? null)\n\t\t\t\t\treturn\n\t\t\t\t}\n\n\t\t\t\tfor (const name in options.themes) {\n\t\t\t\t\tif (options.themes[name] === value) {\n\t\t\t\t\t\toptions.handler(name)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tif (options.allowCustom) {\n\t\t\t\t\toptions.handler(value)\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t\toptions.element,\n\t)\n}\n","import type { CreateTuple } from 'type-plus'\n\n/**\n * Retrieves CSS custom property values from the specified element.\n *\n * @param element - The HTML element to get property values from\n * @param props - CSS custom property names to retrieve, must be in the format `--property-name`\n * @returns Array of property values corresponding to the requested custom properties\n */\nexport function getCSSPropValues<Props extends Array<`--${string}`>>(\n\telement: HTMLElement,\n\t...props: Props\n): CreateTuple<Props['length'], string>\n/**\n * Retrieves CSS custom property values from `document.body`.\n *\n * @param props - CSS custom property names to retrieve, must be in the format `--property-name`\n * @returns Array of property values corresponding to the requested custom properties\n */\nexport function getCSSPropValues<Props extends Array<`--${string}`>>(\n\t...props: Props\n): CreateTuple<Props['length'], string>\nexport function getCSSPropValues<Props extends Array<`--${string}`>>(element: unknown, ...props: Props) {\n\tif (typeof element === 'string') {\n\t\treturn getCSSPropValues(globalThis.document.body, element as `--${string}`, ...props)\n\t}\n\tconst style = globalThis.getComputedStyle(element as HTMLElement)\n\treturn props.map((v) => style.getPropertyValue(v)) as any\n}\n","import { mapKey } from 'type-plus'\nimport { ctx } from '../globals.ctx.ts'\n\n/**\n * Observes system color scheme preference changes and calls handlers when they occur.\n *\n * @param themes - An object mapping theme names to handler functions that are called when that theme is activated\n * @returns A cleanup function that removes all event listeners\n *\n * @example\n * ```ts\n * // Observe light/dark mode changes\n * const cleanup = observePrefersColorScheme({\n *   light: (theme) => console.log('Light mode activated'),\n *   dark: (theme) => console.log('Dark mode activated')\n * })\n *\n * // Later, to stop observing:\n * cleanup()\n * ```\n */\nexport function observePrefersColorScheme<T extends string>(themes: Record<T, (value: T | null) => void>) {\n\tconst removers = mapKey(themes, (t) => {\n\t\tconst m = ctx.matchMedia(`(prefers-color-scheme: ${t as string})`)\n\t\tconst listener = (event: MediaQueryListEvent) => {\n\t\t\tif (event.matches) {\n\t\t\t\tthemes[t]?.(t)\n\t\t\t}\n\t\t}\n\n\t\tm.addEventListener('change', listener)\n\t\treturn () => m.removeEventListener('change', listener)\n\t})\n\n\treturn () => {\n\t\tfor (const remover of removers) {\n\t\t\tremover()\n\t\t}\n\t}\n}\n\n/**\n * Gets the current preferred color theme from the system settings.\n *\n * @param themes - A list of theme names to check against the system preference\n * @returns The first matching theme from the provided list, or null if none match\n *\n * @example\n * ```ts\n * // Check if system prefers light or dark mode\n * const theme = getPrefersColorTheme('light', 'dark')\n * // Returns 'light', 'dark', or null\n * ```\n */\nexport function getPrefersColorTheme<T extends string>(...themes: T[]) {\n\treturn themes.find((theme) => ctx.matchMedia(`(prefers-color-scheme: ${theme})`).matches) ?? null\n}\n"],"mappings":"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"}

package/package.json

@@ -1,17 +1,28 @@
 {
   "name": "@just-web/css",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "CSS types and utilities",
+  "homepage": "https://github.com/justland/just-web-foundation/tree/main/libs/css",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justland/just-web-foundation.git",
+    "directory": "libs/css"
+  },
+  "license": "MIT",
+  "author": "Unional <homawong@gmail.com>",
   "type": "module",
+  "imports": {
+    "#just-web/css": "./src/index.ts"
+  },
   "exports": {
     ".": {
-      "types": "./esm/index.d.ts",
-      "default": "./esm/index.js"
+      "types": "./esm/index.d.mts",
+      "default": "./esm/index.mjs"
     },
     "./package.json": "./package.json"
   },
-  "main": "./cjs/index.js",
-  "types": "./cjs/index.d.ts",
+  "main": "./cjs/index.cjs",
+  "types": "./cjs/index.d.cts",
   "files": [
     "cjs",
     "esm",
@@ -24,47 +35,37 @@
     "type-plus": "8.0.0-beta.7"
   },
   "devDependencies": {
-    "@repobuddy/storybook": "^0.12.0",
-    "@repobuddy/vitest": "^1.2.2",
-    "@storybook/addon-essentials": "^8.6.12",
-    "@storybook/addon-storysource": "^8.6.12",
-    "@storybook/blocks": "^8.6.12",
-    "@storybook/experimental-addon-test": "^8.6.12",
-    "@storybook/manager-api": "^8.6.12",
-    "@storybook/preview-api": "^8.6.12",
-    "@storybook/react": "^8.6.12",
-    "@storybook/react-vite": "^8.6.12",
-    "@storybook/test": "^8.6.12",
-    "@storybook/theming": "^8.6.12",
+    "@repobuddy/storybook": "^2.1.2",
+    "@repobuddy/vitest": "^2.1.1",
+    "@storybook-community/storybook-dark-mode": "^7.0.3",
+    "@storybook/addon-docs": "^10.1.10",
+    "@storybook/addon-vitest": "^10.1.10",
+    "@storybook/react-vite": "^10.1.10",
     "@tailwindcss/cli": "^4.1.6",
     "@tailwindcss/vite": "^4.1.6",
-    "@vitest/browser": "^3.1.3",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
     "dedent": "^1.6.0",
-    "ncp": "^2.0.0",
-    "playwright": "^1.52.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "rimraf": "^6.0.1",
-    "storybook": "^8.6.12",
-    "storybook-addon-code-editor": "^4.1.1",
-    "storybook-addon-tag-badges": "^1.4.0",
-    "storybook-addon-vis": "^0.19.4",
-    "storybook-dark-mode": "^4.0.2",
-    "tailwindcss": "^4.1.6",
+    "storybook": "^10.1.10",
+    "storybook-addon-code-editor": "^6.1.1",
+    "storybook-addon-tag-badges": "^3.0.4",
+    "storybook-addon-vis": "^3.1.2",
+    "tailwindcss": "^4.1.18",
+    "tsdown": "^0.18.3",
     "typescript": "^5.8.3",
-    "unbuild": "^3.5.0",
-    "vite": "^6.3.5",
-    "vitest": "^3.1.3",
-    "vitest-browser-react": "^0.1.1",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "vitest-browser-react": "^2.0.2",
     "@tools/typescript": "^0.0.1"
   },
   "scripts": {
-    "build": "run-p build:*",
+    "build": "tsdown",
     "build-doc": "storybook build -o ../../docs/css",
-    "build:cjs": "unbuild && ncp ../../tools/ts/package.cjs.json ./cjs/package.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
-    "clean": "rimraf .turbo esm *.tsbuildinfo",
+    "clean": "rimraf .turbo cjs esm *.tsbuildinfo dist",
     "cov": "vitest run --coverage",
     "inspect:css": "tailwindcss -i ./src/tailwind.css -o ./styles.css",
     "nuke": "rimraf node_modules",

package/src/convertors/px_2_num.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts pixel values to numbers.
+ *
+ * @param px - The pixel value to convert. Can be a number or string (e.g. '16px' or '16')
+ * @returns The numeric value
+ *
+ * @example
+ * ```ts
+ * px2num(16) // 16
+ * px2num('32px') // 32
+ * px2num('12.5px') // 12.5
+ * px2num('0px') // 0
+ * ```
+ */
+export function px2num(px: number | string | undefined): number {
+	return typeof px === 'string' ? Number.parseFloat(px.replace(/px$/, '')) : Number(px)
+}

package/src/index.ts

@@ -1,7 +1,11 @@
+export type * from 'csstype'
+export * from './convertors/px_2_num.ts'
 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 './properties/css_properties.ts'
+export { defineProperties } from './properties/properties.ts'
+export type { Properties } from './properties/properties.ts'
+export * from './properties/to_dom_style.ts'
 export * from './props/class-name.ts'
 export * from './props/style.ts'
 export * from './theme/class-name.ts'

package/src/{css-properties/css-properties.ts → properties/css_properties.ts}

@@ -1,11 +1,13 @@
-import type { Properties } from 'csstype'
+import type { Properties as CSSTypeProperties } from 'csstype'
 
 /**
  * Extends CSS properties to include custom properties.
  * Allows for string or number values for standard properties,
  * and string values for custom properties with '--' prefix.
+ *
+ * @deprecated Use `Properties` instead.
  */
-export interface CSSProperties extends Properties<string | number> {
+export interface CSSProperties extends CSSTypeProperties<string | number> {
 	[k: `--${string}`]: string
 }
 
@@ -14,6 +16,8 @@ export interface CSSProperties extends Properties<string | number> {
  * This function is used to properly type CSS properties when defining styles,
  * especially when using CSS custom properties (variables).
  *
+ * @deprecated Use `defineProperties` instead.
+ *
  * @param style - CSS properties object that can include both standard and custom properties
  * @returns The same style object with proper typing
  *

package/{cjs/css-properties/css-properties.d.ts → src/properties/properties.ts}

@@ -1,12 +1,15 @@
-import type { Properties } from 'csstype';
+import type { Properties as CSSTypeProperties } from 'csstype'
+
 /**
  * Extends CSS properties to include custom properties.
  * Allows for string or number values for standard properties,
  * and string values for custom properties with '--' prefix.
  */
-export interface CSSProperties extends Properties<string | number> {
-    [k: `--${string}`]: string;
+export interface Properties<TLength = 0 | (string & {}), TTime = string & {}>
+	extends CSSTypeProperties<TLength, TTime> {
+	[k: `--${string}`]: string
 }
+
 /**
  * Defines CSS properties including custom properties.
  * This function is used to properly type CSS properties when defining styles,
@@ -23,4 +26,6 @@ export interface CSSProperties extends Properties<string | number> {
  * })
  * ```
  */
-export declare function defineCSSProperties(style: CSSProperties): any;
+export function defineProperties<TLength = 0 | (string & {}), TTime = string & {}>(style: Properties<TLength, TTime>) {
+	return style as Properties
+}

package/src/{css-properties → properties}/to_dom_style.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties } from './css-properties.ts'
+import type { CSSProperties } from './css_properties.ts'
 
 /**
  * Converts React-style CSS properties to DOM style properties.

package/src/props/class-name.ts

@@ -7,6 +7,6 @@
  * Interface for component props that include a className property.
  * The className property accepts a string value for CSS class names.
  */
-export interface ClassNameProps {
+export type ClassNameProps = {
 	className?: string | undefined
 }

package/src/props/style.ts

@@ -1,8 +1,8 @@
-import type { CSSProperties } from '../css-properties/css-properties.ts'
+import type { Properties } from '../properties/properties.ts'
 
 /**
  * Interface for component props that include a style property.
  */
-export interface StyleProps {
-	style?: CSSProperties | undefined
+export type StyleProps<TLength = 0 | (string & {}), TTime = string & {}> = {
+	style?: Properties<TLength, TTime> | undefined
 }

package/cjs/convertors/px_2_rem.d.ts

@@ -1,21 +0,0 @@
-/**
- * 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;
-}): number;