@just-web/toolkits 1.0.0

package/src/theme/theme-store/cookie-theme-store/cookie-theme-store.ts

@@ -0,0 +1,174 @@
+import type { Required } from 'type-plus'
+import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
+import { parseStoredTheme } from '../../_utils/parse-stored-theme.ts'
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeEntry } from '../../theme-entry.types.ts'
+import type { ThemeMap } from '../../theme-map.types.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+export interface CookieThemeStoreOptions {
+	cookieName: string
+	path?: string | undefined
+	maxAge?: number | undefined
+	sameSite?: 'lax' | 'strict' | 'none' | undefined
+	secure?: boolean | undefined
+}
+
+function getCookieValue(name: string): string | null {
+	if (typeof document === 'undefined' || !document.cookie) return null
+	const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+	const value = match?.[1]
+	return value !== undefined ? decodeURIComponent(value) : null
+}
+
+function setCookie(
+	name: string,
+	value: string,
+	options: {
+		path?: string | undefined
+		maxAge?: number | undefined
+		sameSite?: 'lax' | 'strict' | 'none' | undefined
+		secure?: boolean | undefined
+	}
+) {
+	const parts = [`${name}=${encodeURIComponent(value)}`]
+	parts.push(`path=${options.path ?? '/'}`)
+	if (options.maxAge !== undefined) parts.push(`max-age=${options.maxAge}`)
+	if (options.sameSite !== undefined) parts.push(`samesite=${options.sameSite}`)
+	if (options.secure) parts.push('secure')
+	// biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API has limited support; document.cookie is standard for theme persistence
+	document.cookie = parts.join('; ')
+}
+
+function deleteCookie(name: string, path = '/') {
+	// biome-ignore lint/suspicious/noDocumentCookie: Cookie Store API has limited support; document.cookie is standard for theme persistence
+	document.cookie = `${name}=; path=${path}; max-age=0`
+}
+
+/**
+ * Creates a theme store backed by cookies.
+ *
+ * Persists across sessions. Cookies are sent with every request, so the server can
+ * read the theme during SSR to avoid flash of wrong theme. Cross-tab sync is not
+ * supported (cookies have no StorageEvent).
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param options.cookieName - Cookie name for theme storage
+ * @param options.path - Cookie path (default: '/')
+ * @param options.maxAge - Cookie max-age in seconds
+ * @param options.sameSite - Cookie sameSite attribute
+ * @param options.secure - Cookie secure attribute
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' }
+ * const store = cookieThemeStore(themes, { cookieName: 'theme' })
+ * store.read()
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function cookieThemeStore<Themes extends ThemeMap>(
+	themes: Themes,
+	options: CookieThemeStoreOptions
+): Required<ThemeStore<Themes>> {
+	const { cookieName, path = '/', maxAge, sameSite, secure } = options
+
+	if (document.cookie === undefined) {
+		return dummyThemeStore
+	}
+
+	const handlers = new Set<(theme: ThemeEntry<Themes> | undefined) => void>()
+	let lastNotifiedKey: keyof Themes | undefined = read()?.theme ?? undefined
+
+	function read() {
+		const stored = getCookieValue(cookieName)
+		const theme = parseStoredTheme(themes, stored)
+		if (theme === undefined) return undefined
+		return themeEntry(themes, theme)
+	}
+
+	function notify() {
+		const result = read()
+		const key = result?.theme ?? undefined
+		if (key === lastNotifiedKey) return
+		lastNotifiedKey = key
+		for (const h of handlers) h(result)
+	}
+
+	return {
+		read,
+		write(entry) {
+			try {
+				if (entry === undefined) {
+					deleteCookie(cookieName, path)
+				} else {
+					const opts: {
+						path: string
+						maxAge?: number
+						sameSite?: 'lax' | 'strict' | 'none'
+						secure?: boolean
+					} = { path }
+					if (maxAge !== undefined) opts.maxAge = maxAge
+					if (sameSite !== undefined) opts.sameSite = sameSite
+					if (secure) opts.secure = true
+					setCookie(cookieName, JSON.stringify(entry), opts)
+				}
+				notify()
+			} catch {
+				// Ignore quota or other errors
+			}
+		},
+		subscribe(handler) {
+			handlers.add(handler)
+			return () => {
+				handlers.delete(handler)
+			}
+		}
+	} satisfies ThemeStore<Themes>
+}
+
+function getCookieFromHeader(cookieHeader: string, name: string): string | null {
+	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
+	const value = match?.[1]
+	return value !== undefined ? decodeURIComponent(value.trim()) : null
+}
+
+/**
+ * Reads the theme from cookies during SSR. Use with the request's Cookie header or
+ * a framework's cookie API (e.g. Next.js cookies()).
+ *
+ * @param cookieSource - Raw Cookie header string, or a getter (name) => value for framework APIs
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param options - Optional cookie name (default: 'theme')
+ * @returns ThemeEntry if valid cookie found, otherwise undefined
+ *
+ * @example
+ * ```ts
+ * // With raw Cookie header (Express, Remix, etc.)
+ * const theme = getThemeFromCookie(request.headers.get('Cookie') ?? '', themes)
+ *
+ * // With Next.js cookies()
+ * const theme = getThemeFromCookie(
+ *   (name) => cookies().get(name)?.value ?? undefined,
+ *   themes
+ * )
+ * ```
+ */
+export function getThemeFromCookie<Themes extends ThemeMap>(
+	cookieSource: string | null | undefined | ((name: string) => string | null | undefined),
+	themes: Themes,
+	options: { cookieName?: string | undefined } = {}
+): ThemeEntry<Themes> | undefined {
+	const cookieName = options.cookieName ?? 'theme'
+	const stored =
+		typeof cookieSource === 'function'
+			? (cookieSource(cookieName) ?? null)
+			: cookieSource
+				? getCookieFromHeader(cookieSource, cookieName)
+				: null
+	const theme = parseStoredTheme(themes, stored)
+	if (theme === undefined) return undefined
+	return themeEntry(themes, theme)
+}

package/src/theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts

@@ -0,0 +1,60 @@
+import type { Required } from 'type-plus'
+import { getDataAttribute } from '../../../attributes/get-data-attribute.ts'
+import { observeDataAttributes } from '../../../attributes/observe-data-attribute.ts'
+import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
+import { applyThemeToDataAttribute } from '../../data-attribute/apply-theme-to-data-attribute.ts'
+import { resolveThemeFromDataAttribute } from '../../data-attribute/resolve-theme-from-data-attribute.ts'
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeMap } from '../../theme-map.types.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+/**
+ * Creates a theme store that reads and writes via a data attribute.
+ *
+ * @param themes - Record mapping theme keys to attribute values
+ * @param options.attributeName - Data attribute name (e.g. `data-theme`)
+ * @param options.element - Element to operate on (defaults to document.documentElement)
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'current', grayscale: 'grayscale' }
+ * const store = dataAttributeThemeStore(themes, { attributeName: 'data-theme' })
+ * store.read() // returns themeResult from data attribute
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function dataAttributeThemeStore<Themes extends ThemeMap>(
+	themes: Themes,
+	options: { attributeName: `data-${string}`; element?: Element | undefined }
+) {
+	const element = options.element ?? document?.documentElement
+	const { attributeName } = options
+
+	if (!element) return dummyThemeStore as Required<ThemeStore<Themes>>
+
+	return {
+		read() {
+			const value = getDataAttribute(attributeName, element)
+			const theme = resolveThemeFromDataAttribute(themes, value)
+			if (theme === undefined) return undefined
+			return themeEntry(themes, theme)
+		},
+		write(entry) {
+			applyThemeToDataAttribute(element, attributeName, entry)
+		},
+		subscribe(handler) {
+			const observer = observeDataAttributes<string, `data-${string}`>(
+				{
+					[attributeName]: (value) => {
+						const theme = value ? resolveThemeFromDataAttribute(themes, value) : undefined
+						handler(theme ? themeEntry(themes, theme) : undefined)
+					}
+				},
+				element
+			)
+			return () => observer.disconnect()
+		}
+	} satisfies ThemeStore<Themes>
+}

package/src/theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts

@@ -0,0 +1,54 @@
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeEntry } from '../../theme-entry.types.ts'
+import type { ThemeMap } from '../../theme-map.types.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+/**
+ * In-memory theme store. Transient state; no persistence.
+ *
+ * Bakes themes at creation. Validates theme keys on write; read/write use theme keys
+ * and build ThemeEntry from the themes map, consistent with other stores.
+ *
+ * @param themes - Record mapping theme keys to values (for validation and entry construction)
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' } as const
+ * const store = inMemoryThemeStore(themes)
+ * store.read() // undefined when empty
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function inMemoryThemeStore<Themes extends ThemeMap>(themes: Themes) {
+	let value: keyof Themes | undefined | null
+	const listeners = new Set<(v: ThemeEntry<Themes> | undefined) => void>()
+
+	function read(): ThemeEntry<Themes> | undefined {
+		if (value === undefined || value === null) return undefined
+		return themeEntry(themes, value)
+	}
+
+	return {
+		read,
+		write(entry) {
+			if (entry === undefined) {
+				if (value === undefined || value === null) return
+				value = undefined
+				for (const fn of listeners) fn(undefined)
+				return
+			}
+			if (!(entry.theme in themes)) return
+			if (value === entry.theme) return
+			value = entry.theme
+			for (const fn of listeners) fn(themeEntry(themes, entry.theme))
+		},
+		subscribe(handler) {
+			listeners.add(handler)
+			return () => {
+				listeners.delete(handler)
+			}
+		}
+	} satisfies ThemeStore<Themes>
+}

package/src/theme/theme-store/local-storage-theme-store/local-storage-theme-store.ts

@@ -0,0 +1,83 @@
+import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
+import { parseStoredTheme } from '../../_utils/parse-stored-theme.ts'
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeEntry } from '../../theme-entry.types.ts'
+import type { ThemeMap } from '../../theme-map.types.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+/**
+ * Creates a theme store backed by localStorage.
+ *
+ * Persists across sessions; cross-tab sync via StorageEvent.
+ * Same-tab writes trigger manual notify (StorageEvent does not fire for same tab).
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param options.storageKey - localStorage key
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' }
+ * const store = localStorageThemeStore(themes, { storageKey: 'theme' })
+ * store.read() // returns themeResult from localStorage
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function localStorageThemeStore<Themes extends ThemeMap>(
+	themes: Themes,
+	options: { storageKey: string }
+) {
+	const { storageKey } = options
+
+	if (typeof window === 'undefined' || !window.localStorage) {
+		return dummyThemeStore satisfies ThemeStore<Themes>
+	}
+
+	const handlers = new Set<(theme: ThemeEntry<Themes> | undefined) => void>()
+	let lastNotifiedKey: keyof Themes | undefined = read()?.theme ?? undefined
+
+	function read() {
+		const stored = window.localStorage.getItem(storageKey)
+		const theme = parseStoredTheme(themes, stored)
+		if (theme === undefined) return undefined
+		return themeEntry(themes, theme)
+	}
+
+	function notify() {
+		const result = read()
+		const key = result?.theme ?? undefined
+		if (key === lastNotifiedKey) return
+		lastNotifiedKey = key
+		for (const h of handlers) h(result)
+	}
+
+	return {
+		read,
+		write(entry) {
+			try {
+				if (entry === undefined) {
+					window.localStorage.removeItem(storageKey)
+				} else {
+					window.localStorage.setItem(storageKey, JSON.stringify(entry))
+				}
+				notify()
+			} catch {
+				// Ignore quota or other errors
+			}
+		},
+		subscribe(handler) {
+			handlers.add(handler)
+
+			const onStorage = (e: StorageEvent) => {
+				if (e.key === storageKey && e.storageArea === window.localStorage) notify()
+			}
+			window.addEventListener('storage', onStorage)
+
+			return () => {
+				handlers.delete(handler)
+				window.removeEventListener('storage', onStorage)
+			}
+		}
+	} satisfies ThemeStore<Themes>
+}

package/src/theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.ts

@@ -0,0 +1,43 @@
+import type { RequiredPick } from 'type-plus'
+import { getPrefersColorScheme } from '../../../color-scheme/get-prefers-color-scheme.ts'
+import { observePrefersColorScheme } from '../../../color-scheme/observe-prefers-color-scheme.ts'
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+type PrefersColorSchemeThemes = {
+	light: string | readonly string[]
+	dark: string | readonly string[]
+}
+
+/**
+ * Creates a read-only theme store that reads from `prefers-color-scheme`.
+ *
+ * **Color-scheme specific:** Themes must only include `light` and `dark` keys—this store
+ * mirrors the system preference which is always one of these.
+ *
+ * Returns `ThemeEntry` for `light` or `dark` based on system preference.
+ * No write method—the value is controlled by the system.
+ *
+ * @param themes - Record with `light` and `dark` keys mapping to theme values
+ * @returns ThemeStore with read and subscribe only
+ *
+ * @example
+ * ```ts
+ * const themes = { light: 'theme-light', dark: 'theme-dark' }
+ * const store = prefersColorSchemeThemeStore(themes)
+ * store.read() // ThemeEntry for current system preference
+ * store.subscribe((entry) => {})
+ * ```
+ */
+export function prefersColorSchemeThemeStore<Themes extends PrefersColorSchemeThemes>(
+	themes: Themes
+): RequiredPick<ThemeStore<Themes>, 'read' | 'subscribe'> {
+	return {
+		read() {
+			return themeEntry(themes, getPrefersColorScheme())
+		},
+		subscribe(handler) {
+			return observePrefersColorScheme((scheme) => handler(themeEntry(themes, scheme)))
+		}
+	}
+}

package/src/theme/theme-store/session-storage-theme-store/session-storage-theme-store.ts

@@ -0,0 +1,83 @@
+import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
+import { parseStoredTheme } from '../../_utils/parse-stored-theme.ts'
+import { themeEntry } from '../../theme-entry.ts'
+import type { ThemeEntry } from '../../theme-entry.types.ts'
+import type { ThemeMap } from '../../theme-map.types.ts'
+import type { ThemeStore } from '../theme-store.types.ts'
+
+/**
+ * Creates a theme store backed by sessionStorage.
+ *
+ * Persists per tab; cross-tab sync via StorageEvent when available.
+ * Same-tab writes trigger manual notify (StorageEvent does not fire for same tab).
+ *
+ * @param themes - Record mapping theme keys to values (for validation)
+ * @param options.storageKey - sessionStorage key
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' }
+ * const store = sessionStorageThemeStore(themes, { storageKey: 'theme' })
+ * store.read() // returns themeResult from sessionStorage
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function sessionStorageThemeStore<Themes extends ThemeMap>(
+	themes: Themes,
+	options: { storageKey: string }
+) {
+	const { storageKey } = options
+
+	if (typeof window === 'undefined' || !window.sessionStorage) {
+		return dummyThemeStore satisfies ThemeStore<Themes>
+	}
+
+	const handlers = new Set<(theme: ThemeEntry<Themes> | undefined) => void>()
+	let lastNotifiedKey: keyof Themes | undefined = read()?.theme ?? undefined
+
+	function read() {
+		const stored = window.sessionStorage.getItem(storageKey)
+		const theme = parseStoredTheme(themes, stored)
+		if (theme === undefined) return undefined
+		return themeEntry(themes, theme)
+	}
+
+	function notify() {
+		const result = read()
+		const key = result?.theme ?? undefined
+		if (key === lastNotifiedKey) return
+		lastNotifiedKey = key
+		for (const h of handlers) h(result)
+	}
+
+	return {
+		read,
+		write(entry) {
+			try {
+				if (entry === undefined) {
+					window.sessionStorage.removeItem(storageKey)
+				} else {
+					window.sessionStorage.setItem(storageKey, JSON.stringify(entry))
+				}
+				notify()
+			} catch {
+				// Ignore quota or other errors
+			}
+		},
+		subscribe(handler) {
+			handlers.add(handler)
+
+			const onStorage = (e: StorageEvent) => {
+				if (e.key === storageKey && e.storageArea === window.sessionStorage) notify()
+			}
+			window.addEventListener('storage', onStorage)
+
+			return () => {
+				handlers.delete(handler)
+				window.removeEventListener('storage', onStorage)
+			}
+		}
+	} satisfies ThemeStore<Themes>
+}

package/src/theme/theme-store/theme-store-factory.types.ts

@@ -0,0 +1,9 @@
+import type { ThemeMap } from '../theme-map.types.ts'
+import type { AsyncThemeStore } from './async-theme-store.types.ts'
+import type { ThemeStore } from './theme-store.types.ts'
+
+/** Factory signature for theme stores. */
+export type ThemeStoreFactory<Themes extends ThemeMap> = (
+	themes: Themes,
+	...args: any[]
+) => ThemeStore<Themes> | AsyncThemeStore<Themes>

package/src/theme/theme-store/theme-store.types.ts

@@ -0,0 +1,30 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Interface for theme stores with optional read, write, and subscribe methods.
+ * Data flow participation is inferred from which methods exist:
+ *
+ * - **read** – Participates in waterfall read for `getThemeFromStores`
+ * - **write** – Receives writes from `setThemeToStores`
+ * - **subscribe** – GObserved for external changes via `observeThemeFromStores`
+ *
+ * All methods are optional.
+ * Built-in implementations:
+ * - `classNameThemeStore`
+ * - `cookieThemeStore`
+ * - `dataAttributeThemeStore`
+ * - `inMemoryThemeStore`
+ * - `localStorageThemeStore`
+ * - `prefersColorSchemeThemeStore`
+ * - `sessionStorageThemeStore`
+ *
+ * @typeParam Themes - Map of theme keys to their value types (string or readonly string[])
+ */
+export interface ThemeStore<Themes extends ThemeMap = ThemeMap> {
+	read?: (() => ThemeEntry<Themes> | undefined) | undefined
+	write?: ((entry: ThemeEntry<Themes> | undefined) => void) | undefined
+	subscribe?:
+		| ((handler: (theme: ThemeEntry<Themes> | undefined | null) => void) => () => void)
+		| undefined
+}

package/src/theme.ts

@@ -0,0 +1,14 @@
+export * from './theme/compose-theme-stores.ts'
+export * from './theme/theme-entry.ts'
+export type * from './theme/theme-entry.types.ts'
+export type * from './theme/theme-map.types.ts'
+export type * from './theme/theme-store/async-theme-store.types.ts'
+export * from './theme/theme-store/class-name-theme-store/class-name-theme-store.ts'
+export * from './theme/theme-store/cookie-theme-store/cookie-theme-store.ts'
+export * from './theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts'
+export * from './theme/theme-store/in-memory-theme-store/in-memory-theme-store.ts'
+export * from './theme/theme-store/local-storage-theme-store/local-storage-theme-store.ts'
+export * from './theme/theme-store/prefers-color-scheme-theme-store/prefers-color-scheme-theme-store.ts'
+export * from './theme/theme-store/session-storage-theme-store/session-storage-theme-store.ts'
+export type * from './theme/theme-store/theme-store.types.ts'
+export type * from './theme/theme-store/theme-store-factory.types.ts'

package/src/units/get-rem-to-px-scale.ts

@@ -0,0 +1,27 @@
+const DEFAULT_REM_TO_PX_SCALE = 16
+
+/**
+ * Returns the current document's rem-to-px scale (the pixel value of 1rem).
+ *
+ * Reads the computed font size of the root element (`html`), which is the value
+ * the browser uses to resolve rem units. In non-browser environments (e.g. SSR,
+ * Node), returns {@link DEFAULT_REM_TO_PX_SCALE} as a fallback.
+ *
+ * @returns The number of pixels that 1rem equals in the current document,
+ * or {@link DEFAULT_REM_TO_PX_SCALE} when not in a browser.
+ *
+ * @example
+ * ```ts
+ * getRemToPxScale() // e.g. 16 (or 20 if user increased default font size)
+ * rem2px(1, { base: getRemToPxScale() }) // matches actual 1rem in the document
+ * ```
+ */
+export function getRemToPxScale(): number {
+	/* c8 ignore start */
+	if (typeof document === 'undefined' || !document.documentElement) {
+		return DEFAULT_REM_TO_PX_SCALE
+	}
+	/* c8 ignore end */
+	const rootFontSize = getComputedStyle(document.documentElement).fontSize
+	return Number.parseFloat(rootFontSize) ?? DEFAULT_REM_TO_PX_SCALE
+}

package/src/units/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/units/px-2-rem.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 }
+): number {
+	const { base = 16, precision = 4 } = options ?? {}
+
+	if (typeof px === 'string') {
+		px = px.replace(/px$/, '')
+		px = Number.parseFloat(px)
+	}
+
+	return Number((px / base).toFixed(precision))
+}

package/src/units/rem-2-px.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 }
+): number {
+	const { base = 16, precision = 4 } = options ?? {}
+
+	if (typeof rem === 'string') {
+		rem = rem.replace(/rem$/, '')
+		rem = Number.parseFloat(rem)
+	}
+
+	return Number((rem * base).toFixed(precision))
+}

package/src/utils/append-id.ts

@@ -0,0 +1,10 @@
+/**
+ * Appends a suffix to an ID if the ID is defined.
+ *
+ * @param id - The ID to append the suffix to.
+ * @param suffix - The suffix to append to the ID.
+ * @returns The ID with the suffix appended, or undefined if the ID is undefined.
+ */
+export function appendId(id: string | undefined, suffix: string): string | undefined {
+	return id ? `${id}-${suffix}` : undefined
+}