@just-web/css 0.6.1 → 0.8.0

package/esm/index.d.mts

@@ -0,0 +1,412 @@
+import { CreateTuple } from "type-plus";
+import { Properties as Properties$1 } from "csstype";
+export * from "csstype";
+
+//#region src/convertors/px_2_num.d.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
+ * ```
+ */
+declare function px2num(px: number | string | undefined): number;
+//#endregion
+//#region src/convertors/px_2_rem.d.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'
+ * ```
+ */
+declare function px2rem(px: number | string, options?: {
+  base?: number | undefined;
+  precision?: number | undefined;
+}): number;
+//#endregion
+//#region src/convertors/rem_2_px.d.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'
+ * ```
+ */
+declare function rem2px(rem: number | string, options?: {
+  base?: number | undefined;
+  precision?: number | undefined;
+}): number;
+//#endregion
+//#region src/properties/css_properties.d.ts
+/**
+ * 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.
+ */
+interface CSSProperties extends Properties$1<string | number> {
+  [k: `--${string}`]: string;
+}
+/**
+ * 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'
+ * })
+ * ```
+ */
+declare function defineCSSProperties(style: CSSProperties): any;
+//#endregion
+//#region src/properties/properties.d.ts
+/**
+ * Extends CSS properties to include custom properties.
+ * Allows for string or number values for standard properties,
+ * and string values for custom properties with '--' prefix.
+ */
+interface Properties<TLength = 0 | (string & {}), TTime = string & {}> extends Properties$1<TLength, TTime> {
+  [k: `--${string}`]: string;
+}
+/**
+ * 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'
+ * })
+ * ```
+ */
+declare function defineProperties<TLength = 0 | (string & {}), TTime = string & {}>(style: Properties<TLength, TTime>): Properties;
+//#endregion
+//#region src/properties/to_dom_style.d.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
+ * ```
+ */
+declare function toDOMStyle(style: CSSProperties | undefined): Partial<CSSStyleDeclaration> | undefined;
+//#endregion
+//#region src/props/class-name.d.ts
+/**
+ * Note that `className` could be specific to ReactJS.
+ * So this type may be misplaced in this package.
+ */
+/**
+ * Interface for component props that include a className property.
+ * The className property accepts a string value for CSS class names.
+ */
+type ClassNameProps = {
+  className?: string | undefined;
+};
+//#endregion
+//#region src/props/style.d.ts
+/**
+ * Interface for component props that include a style property.
+ */
+type StyleProps<TLength = 0 | (string & {}), TTime = string & {}> = {
+  style?: Properties<TLength, TTime> | undefined;
+};
+//#endregion
+//#region src/theme/class-name.d.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'
+ * })
+ * ```
+ */
+declare function getThemeByClassName<Themes extends Record<string, string>>(options: {
+  themes: Themes;
+  defaultTheme?: keyof Themes | undefined;
+  element?: Element | undefined;
+}): keyof Themes | undefined;
+declare function observeThemeByClassName<Themes extends Record<string, string>>(options: {
+  themes: Themes;
+  handler: (value: string | undefined) => void;
+  defaultTheme?: keyof Themes | undefined;
+  element?: Element | undefined;
+}): MutationObserver;
+//#endregion
+//#region src/theme/data-attribute.d.ts
+/**
+ * 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-')
+ * @param options.allowCustom - Whether to allow custom themes value
+ * @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'
+ * })
+ * ```
+ */
+declare function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+  attributeName: `data-${string}`;
+  defaultTheme?: keyof Themes | undefined;
+  themes: Themes;
+  element?: Element | undefined;
+}): keyof Themes | undefined;
+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.
+ *
+ * @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()
+ * ```
+ */
+declare function observeThemeByDataAttributes<Themes extends Record<string, string>>(options: {
+  attributeName: `data-${string}`;
+  themes: Themes;
+  handler: (value: string | null) => void;
+  defaultTheme?: keyof Themes | undefined;
+  element?: Element | undefined;
+}): MutationObserver;
+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;
+//#endregion
+//#region src/utils/attribute.d.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)
+ * ```
+ */
+declare function getAttribute<T extends string>(qualifiedName: T, element?: Element | undefined): string | null;
+/**
+ * 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();
+ * ```
+ */
+declare function observeAttributes<T extends string>(handlers: Record<string, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+//#endregion
+//#region src/utils/data-attribute.d.ts
+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.
+ *
+ * @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();
+ * ```
+ */
+declare function observeDataAttributes<T extends string, K extends `data-${string}`>(handlers: Record<K, (value: T | null) => void>, element?: Element | undefined): MutationObserver;
+//#endregion
+//#region src/utils/get-css-prop-values.d.ts
+/**
+ * Retrieves CSS custom property values from the specified element.
+ *
+ * @param element - The HTML element to get property values from
+ * @param props - CSS custom property names to retrieve, must be in the format `--property-name`
+ * @returns Array of property values corresponding to the requested custom properties
+ */
+declare function getCSSPropValues<Props extends Array<`--${string}`>>(element: HTMLElement, ...props: Props): CreateTuple<Props['length'], string>;
+/**
+ * Retrieves CSS custom property values from `document.body`.
+ *
+ * @param props - CSS custom property names to retrieve, must be in the format `--property-name`
+ * @returns Array of property values corresponding to the requested custom properties
+ */
+declare function getCSSPropValues<Props extends Array<`--${string}`>>(...props: Props): CreateTuple<Props['length'], string>;
+//#endregion
+//#region src/utils/prefers-color-scheme.d.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()
+ * ```
+ */
+declare function observePrefersColorScheme<T extends string>(themes: Record<T, (value: T | null) => void>): () => void;
+/**
+ * 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
+ * ```
+ */
+declare function getPrefersColorTheme<T extends string>(...themes: T[]): T | null;
+//#endregion
+export { CSSProperties, ClassNameProps, type Properties, StyleProps, defineCSSProperties, defineProperties, getAttribute, getCSSPropValues, getDataAttribute, getPrefersColorTheme, getThemeByClassName, getThemeByDataAttribute, observeAttributes, observeDataAttributes, observePrefersColorScheme, observeThemeByClassName, observeThemeByDataAttributes, px2num, px2rem, rem2px, toDOMStyle };
+//# sourceMappingURL=index.d.mts.map

package/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","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/props/class-name.ts","../src/props/style.ts","../src/theme/class-name.ts","../src/theme/data-attribute.ts","../src/utils/attribute.ts","../src/utils/data-attribute.ts","../src/utils/get-css-prop-values.ts","../src/utils/prefers-color-scheme.ts"],"sourcesContent":[],"mappings":"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"}