@just-web/toolkits 1.0.0

package/src/class-name/just-class-name.editor.default-class-name.tsx

@@ -0,0 +1,28 @@
+import type { JustClassNameFnProps } from '@just-web/toolkits'
+import { clsx } from '@just-web/toolkits'
+
+function textTheme(renderProps?: JustClassNameFnProps) {
+	return {
+		...renderProps,
+		className: clsx(renderProps?.className, 'text-black dark:text-white')
+	}
+}
+
+function hoverTheme(renderProps?: JustClassNameFnProps) {
+	return {
+		...renderProps,
+		className: clsx(
+			renderProps?.className,
+			'rounded outline-2 hover:outline-blue-300 dark:hover:outline-blue-700'
+		)
+	}
+}
+
+export default () => {
+	const props = hoverTheme(textTheme())
+	return (
+		<button type="button" {...props}>
+			Hover me
+		</button>
+	)
+}

package/src/class-name/just-class-name.editor.default.tsx

@@ -0,0 +1,14 @@
+import type { JustClassName } from '@just-web/toolkits'
+import { clsx } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+
+const functionClassName: JustClassName<{ isSelected?: boolean | undefined }> = (renderProps) =>
+	clsx(renderProps.className, renderProps.isSelected && 'bg-blue-400')
+
+export default () => {
+	return (
+		<StoryCard appearance="output">
+			<div>Result: {functionClassName({ className: 'base', isSelected: true })}</div>
+		</StoryCard>
+	)
+}

package/src/class-name/just-class-name.editor.type-param.tsx

@@ -0,0 +1,25 @@
+import type { JustClassName } from '@just-web/toolkits'
+import { clsx } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+
+interface ButtonRenderProps {
+	isDisabled?: boolean | undefined
+	isPressed?: boolean | undefined
+}
+
+// With type param: function receives typed render props (ButtonRenderProps & { className?: string })
+const classNameWhenDisabled: JustClassName<ButtonRenderProps> = (renderProps) =>
+	clsx(renderProps.className, renderProps.isDisabled && 'opacity-50 cursor-not-allowed')
+
+const classNameWhenActive: JustClassName<ButtonRenderProps> = (renderProps) =>
+	clsx(renderProps.className, renderProps.isPressed && 'ring-2 ring-blue-500')
+
+export default () => {
+	const renderProps: ButtonRenderProps = { isDisabled: true, isPressed: true }
+	return (
+		<StoryCard appearance="output">
+			<div>without className: {classNameWhenDisabled(renderProps)}</div>
+			<div>with className: {classNameWhenActive({ ...renderProps, className: 'btn' })}</div>
+		</StoryCard>
+	)
+}

package/src/class-name/just-class-name.ts

@@ -0,0 +1,36 @@
+import type { AnyRecord } from 'type-plus'
+
+/**
+ * Props interface for components that accept a render-props-aware `className`.
+ *
+ * Use this when defining component props that support the same `className` contract as {@link JustClassName}:
+ * a static string, a resolver function that receives render props (including existing `className`), or `undefined`.
+ *
+ * @typeParam RenderProps - Record type for render props. When `className` is a function, it receives `RenderProps` merged with `{ className?: string }`.
+ */
+export interface JustClassNameProps<RenderProps extends AnyRecord = AnyRecord> {
+	className?: JustClassName<RenderProps> | undefined
+}
+
+/**
+ * A `className` type that can be static or computed from render props.
+ *
+ * - `string`: The value is appended to the existing `className` in render props.
+ * - `undefined`: Resets the `className` to `undefined`, removing existing `className`.
+ * - `function`: Process the render props and return the desired `className`.
+ *
+ * @typeParam RenderProps - Record type for render props. Resolvers receive `RenderProps` merged with `{ className?: string }`.
+ */
+export type JustClassName<RenderProps extends AnyRecord = AnyRecord> =
+	| ((renderProps: JustClassNameFnProps<RenderProps>) => string | undefined)
+	| string
+	| undefined
+
+/**
+ * The props type for `JustClassName` resolver functions.
+ *
+ * @typeParam RenderProps - Record type for render props.
+ */
+export type JustClassNameFnProps<RenderProps extends AnyRecord = AnyRecord> = RenderProps & {
+	className?: string | undefined
+}

package/src/class-name/resolve-class-name.ts

@@ -0,0 +1,12 @@
+import type { AnyRecord } from 'type-plus'
+import { clsx } from './clsx.ts'
+import type { JustClassName, JustClassNameFnProps } from './just-class-name.ts'
+
+export function resolveClassName<RenderProps extends AnyRecord = AnyRecord>(
+	renderProps: JustClassNameFnProps<RenderProps>,
+	className?: JustClassName<RenderProps>
+) {
+	return typeof className === 'function'
+		? className(renderProps)
+		: clsx(renderProps.className, className)
+}

package/src/color-scheme/get-prefers-color-scheme.ts

@@ -0,0 +1,17 @@
+/**
+ * Gets the current preferred color scheme.
+ * It can only be 'light' or 'dark'.
+ *
+ * Even if the browser preference is 'auto'/'device', it will return 'light' or 'dark'.
+ *
+ * When `matchMedia` is unavailable (e.g. SSR), returns `defaultColorScheme`.
+ *
+ * @param defaultColorScheme - Fallback when `matchMedia` is unavailable (default: `'light'`)
+ * @returns 'light' or 'dark'
+ */
+export function getPrefersColorScheme(
+	defaultColorScheme: 'light' | 'dark' = 'light'
+): 'light' | 'dark' {
+	if (typeof matchMedia === 'undefined') return defaultColorScheme
+	return matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
+}

package/src/color-scheme/observe-prefers-color-scheme.ts

@@ -0,0 +1,24 @@
+/**
+ * Observes system color scheme preference changes and calls handlers when they occur.
+ *
+ * @param handler - A function that is called when the color scheme preference changes
+ * @returns A cleanup function that removes all event listeners
+ *
+ * @example
+ * ```ts
+ * // Observe light/dark mode changes
+ * const cleanup = observePrefersColorScheme((value) => console.log('Color scheme changed to:', value))
+ *
+ * // Later, to stop observing:
+ * cleanup()
+ * ```
+ */
+export function observePrefersColorScheme(handler: (value: 'light' | 'dark') => void) {
+	const m = globalThis.matchMedia('(prefers-color-scheme: light)')
+	const listener = (event: MediaQueryListEvent) => {
+		handler(event.matches ? 'light' : 'dark')
+	}
+
+	m.addEventListener('change', listener)
+	return () => m.removeEventListener('change', listener)
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from './attributes/data-attribute.ts'
+export * from './attributes/get-attribute.ts'
+export * from './attributes/get-data-attribute.ts'
+export * from './attributes/observe-attribute.ts'
+export * from './attributes/observe-data-attribute.ts'
+export * from './children/just-children.ts'
+export * from './children/resolve-children.ts'
+export * from './class-name/class-name-props.ts'
+export * from './class-name/clsx.ts'
+export * from './class-name/just-class-name.ts'
+export * from './class-name/resolve-class-name.ts'
+export * from './color-scheme/get-prefers-color-scheme.ts'
+export * from './color-scheme/observe-prefers-color-scheme.ts'
+export * from './style/css-properties.ts'
+export * from './style/define-css-properties.ts'
+export * from './style/get-css-variable-value.ts'
+export * from './style/just-style.ts'
+export * from './style/resolve-style.ts'
+export * from './style/style-props.ts'
+export * from './style/to-dom-style.ts'
+export * from './units/get-rem-to-px-scale.ts'
+export * from './units/px-2-num.ts'
+export * from './units/px-2-rem.ts'
+export * from './units/rem-2-px.ts'
+export * from './utils/append-id.ts'

package/src/react/hooks/use-attribute.ts

@@ -0,0 +1,59 @@
+import { useCallback, useEffect, useState } from 'react'
+import { observeAttributes } from '../../attributes/observe-attribute.ts'
+
+/**
+ * React hook that returns the current value of an attribute on a target element
+ * and a setter to update it. Stays in sync when the attribute changes (e.g. from elsewhere).
+ *
+ * @param attributeName - The attribute to observe (e.g. `'class'`, `'data-theme'`).
+ * @param element - The element to observe. Defaults to `document.documentElement` when omitted.
+ * @returns Tuple of [value, setValue]. Pass null to setValue to remove the attribute.
+ *
+ * @example
+ * ```tsx
+ * const [className, setClassName] = useAttribute('class')
+ * const [theme, setTheme] = useAttribute('data-theme', myElement)
+ * setTheme('dark')
+ * setClassName(null) // removes class attribute
+ * ```
+ */
+export function useAttribute(
+	attributeName: string,
+	element: Element | undefined = typeof document !== 'undefined'
+		? document.documentElement
+		: undefined
+): [string | null, (value: string | null) => void] {
+	const [value, setValueState] = useState<string | null>(
+		() => element?.getAttribute(attributeName) ?? null
+	)
+
+	useEffect(() => {
+		if (!element) return
+
+		setValueState(element.getAttribute(attributeName))
+
+		const observer = observeAttributes(
+			{
+				[attributeName]: (next) => {
+					setValueState(next)
+				}
+			},
+			element
+		)
+		return () => observer.disconnect()
+	}, [element, attributeName])
+
+	const setValue = useCallback(
+		(next: string | null) => {
+			if (!element) return
+			if (next === null) {
+				element.removeAttribute(attributeName)
+			} else {
+				element.setAttribute(attributeName, next)
+			}
+		},
+		[element, attributeName]
+	)
+
+	return [value, setValue]
+}

package/src/react/hooks/use-prefers-color-scheme.ts

@@ -0,0 +1,42 @@
+import { useEffect, useState } from 'react'
+import { getPrefersColorScheme } from '../../color-scheme/get-prefers-color-scheme.ts'
+import { observePrefersColorScheme } from '../../color-scheme/observe-prefers-color-scheme.ts'
+
+/**
+ * React hook that returns the current system color scheme preference and re-renders when it changes.
+ *
+ * Uses `prefers-color-scheme` media query. Returns `'light'` or `'dark'`; re-renders when the user
+ * changes their OS or browser light/dark setting.
+ *
+ * For SSR, uses `defaultColorScheme` when `matchMedia` is unavailable. On client, reads the real
+ * value immediately (no flicker); `useEffect` syncs and subscribes to changes.
+ *
+ * @param defaultColorScheme - Fallback when `matchMedia` is unavailable (default: `'light'`)
+ * @returns Current system color scheme: `'light'` or `'dark'`
+ *
+ * @example
+ * ```tsx
+ * const scheme = usePrefersColorScheme()
+ * return <div>System prefers: {scheme}</div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const scheme = usePrefersColorScheme('dark')
+ * return <div>System prefers: {scheme}</div>
+ * ```
+ */
+export function usePrefersColorScheme(
+	defaultColorScheme: 'light' | 'dark' = 'light'
+): 'light' | 'dark' {
+	const [scheme, setScheme] = useState<'light' | 'dark'>(() =>
+		getPrefersColorScheme(defaultColorScheme)
+	)
+
+	useEffect(() => {
+		setScheme(getPrefersColorScheme())
+		return observePrefersColorScheme(setScheme)
+	}, [])
+
+	return scheme
+}

package/src/react/hooks/use-theme-by-class-name.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
+import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
+import { resolveThemeFromClassName } from '../../theme/class-name/resolve-theme-from-class-name.ts'
+import { themeEntry } from '../../theme/theme-entry.ts'
+import type { ThemeMap } from '../../theme/theme-map.types.ts'
+import { classNameThemeStore } from '../../theme/theme-store/class-name-theme-store/class-name-theme-store.ts'
+
+/**
+ * React hook that returns the current theme (from element class) and a setter.
+ * Subscribes to class changes on the element so the returned theme stays in sync.
+ *
+ * @param themes - Record mapping theme keys to their class name values
+ * @param options.theme - Fallback theme key when no matching class is found
+ * @param options.element - Element to read/set theme on (defaults to document.documentElement)
+ * @returns Tuple of [currentTheme, setTheme]
+ *
+ * @example
+ * ```tsx
+ * const themes = { light: 'theme-light', dark: 'theme-dark' }
+ * const [theme, setTheme] = useThemeByClassName(themes, { theme: 'light' })
+ *
+ * return (
+ *   <>
+ *     <span>Current: {theme}</span>
+ *     <button onClick={() => setTheme('dark')}>Dark</button>
+ *     <button onClick={() => setTheme('light')}>Light</button>
+ *   </>
+ * )
+ * ```
+ */
+export function useThemeByClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	options?: {
+		defaultTheme?: keyof Themes | undefined
+		element?: Element | undefined
+	}
+): [keyof Themes | undefined, (theme: keyof Themes) => void] {
+	const element =
+		options?.element ?? (typeof document !== 'undefined' ? document.documentElement : undefined)
+	const defaultTheme = options?.defaultTheme
+
+	const store = useMemo(() => classNameThemeStore(themes, { element }), [element, themes])
+
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
+		if (element) {
+			const resolved = resolveThemeFromClassName(themes, element.className)
+			return resolved ?? defaultTheme
+		}
+		return defaultTheme
+	})
+
+	useEffect(() => {
+		if (!element) return
+		const unobserve = observeThemeFromStores([store], defaultTheme, setThemeState)
+		return unobserve
+	}, [element, store, defaultTheme])
+
+	const setTheme = useCallback(
+		(themeKey: keyof Themes) => {
+			if (element) {
+				setThemeToStores([store], themeEntry(themes, themeKey))
+			}
+		},
+		[element, store, themes]
+	)
+
+	return [theme, setTheme]
+}

package/src/react/hooks/use-theme-by-data-attribute.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { getDataAttribute } from '../../attributes/get-data-attribute.ts'
+import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
+import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
+import { resolveThemeFromDataAttribute } from '../../theme/data-attribute/resolve-theme-from-data-attribute.ts'
+import { themeEntry } from '../../theme/theme-entry.ts'
+import type { ThemeMap } from '../../theme/theme-map.types.ts'
+import { dataAttributeThemeStore } from '../../theme/theme-store/data-attribute-theme-store/data-attribute-theme-store.ts'
+
+/**
+ * React hook that returns the current theme (from element data attribute) and a setter.
+ * Subscribes to data attribute changes on the element so the returned theme stays in sync.
+ *
+ * @param themes - Record mapping theme keys to their data attribute values
+ * @param options.attributeName - Data attribute name (e.g. `data-theme`)
+ * @param options.defaultTheme - Fallback theme key when no matching attribute value is found
+ * @param options.element - Element to read/set theme on (defaults to document.documentElement)
+ * @returns Tuple of [currentTheme, setTheme]
+ *
+ * @example
+ * ```tsx
+ * const themes = { light: 'theme-light', dark: 'theme-dark' }
+ * const [theme, setTheme] = useThemeByDataAttribute(themes, {
+ *   attributeName: 'data-theme',
+ *   defaultTheme: 'light'
+ * })
+ *
+ * return (
+ *   <>
+ *     <span>Current: {theme}</span>
+ *     <button onClick={() => setTheme('dark')}>Dark</button>
+ *     <button onClick={() => setTheme('light')}>Light</button>
+ *   </>
+ * )
+ * ```
+ */
+export function useThemeByDataAttribute<Themes extends ThemeMap>(
+	themes: Themes,
+	options: {
+		attributeName: `data-${string}`
+		defaultTheme?: keyof Themes | undefined
+		element?: Element | undefined
+	}
+): [keyof Themes | undefined, (theme: keyof Themes) => void] {
+	const element =
+		options.element ?? (typeof document !== 'undefined' ? document.documentElement : undefined)
+	const defaultTheme = options.defaultTheme
+	const attributeName = options.attributeName
+
+	const store = useMemo(
+		() =>
+			dataAttributeThemeStore(themes, {
+				attributeName,
+				element
+			}),
+		[element, themes, attributeName]
+	)
+
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
+		if (element) {
+			const attrValue = getDataAttribute(attributeName, element)
+			const resolved = resolveThemeFromDataAttribute(themes, attrValue)
+			return resolved ?? defaultTheme
+		}
+		return defaultTheme
+	})
+
+	useEffect(() => {
+		if (!element) return
+		const unobserve = observeThemeFromStores([store], defaultTheme, setThemeState)
+		return unobserve
+	}, [element, store, defaultTheme])
+
+	const setTheme = useCallback(
+		(themeKey: keyof Themes) => {
+			if (element) {
+				setThemeToStores([store], themeEntry(themes, themeKey))
+			}
+		},
+		[element, store, themes]
+	)
+
+	return [theme, setTheme]
+}

package/src/react/hooks/use-theme-by-local-storage.ts

@@ -0,0 +1,68 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { observeThemeFromStores } from '../../theme/_utils/observe-theme-from-stores.ts'
+import { parseStoredTheme } from '../../theme/_utils/parse-stored-theme.ts'
+import { setThemeToStores } from '../../theme/_utils/set-theme-to-stores.ts'
+import { themeEntry } from '../../theme/theme-entry.ts'
+import type { ThemeMap } from '../../theme/theme-map.types.ts'
+import { localStorageThemeStore } from '../../theme/theme-store/local-storage-theme-store/local-storage-theme-store.ts'
+
+/**
+ * React hook that returns the current theme (from localStorage) and a setter.
+ * Subscribes to storage changes so the returned theme stays in sync across tabs.
+ *
+ * @param themes - Record mapping theme keys to their values
+ * @param options.storageKey - localStorage key to persist the theme
+ * @param options.defaultTheme - Fallback theme key when no stored value is found
+ * @returns Tuple of [currentTheme, setTheme]
+ *
+ * @example
+ * ```tsx
+ * const themes = { light: 'theme-light', dark: 'theme-dark' }
+ * const [theme, setTheme] = useThemeByLocalStorage(themes, {
+ *   storageKey: 'app-theme',
+ *   defaultTheme: 'light'
+ * })
+ *
+ * return (
+ *   <>
+ *     <span>Current: {theme}</span>
+ *     <button onClick={() => setTheme('dark')}>Dark</button>
+ *     <button onClick={() => setTheme('light')}>Light</button>
+ *   </>
+ * )
+ * ```
+ */
+export function useThemeByLocalStorage<Themes extends ThemeMap>(
+	themes: Themes,
+	options: {
+		storageKey: string
+		defaultTheme?: keyof Themes | undefined
+	}
+): [keyof Themes | undefined, (theme: keyof Themes) => void] {
+	const { storageKey, defaultTheme } = options
+
+	const store = useMemo(() => localStorageThemeStore(themes, { storageKey }), [themes, storageKey])
+
+	const [theme, setThemeState] = useState<keyof Themes | undefined>(() => {
+		if (typeof window !== 'undefined' && window.localStorage) {
+			const stored = window.localStorage.getItem(storageKey)
+			const resolved = parseStoredTheme(themes, stored)
+			return resolved ?? defaultTheme
+		}
+		return defaultTheme
+	})
+
+	useEffect(() => {
+		const unobserve = observeThemeFromStores([store], defaultTheme, setThemeState)
+		return unobserve
+	}, [store, defaultTheme])
+
+	const setTheme = useCallback(
+		(themeKey: keyof Themes) => {
+			setThemeToStores([store], themeEntry(themes, themeKey))
+		},
+		[store, themes]
+	)
+
+	return [theme, setTheme]
+}

package/src/react/hooks/use-theme-stores.ts

@@ -0,0 +1,83 @@
+import { useMemo } from 'react'
+import type {
+	ComposeThemeStoreEntry,
+	ComposeThemeStoresOptions
+} from '../../theme/compose-theme-stores.ts'
+import type { ThemeMap } from '../../theme/theme-map.types.ts'
+import type { ThemeStoreFactory } from '../../theme/theme-store/theme-store-factory.types.ts'
+import { createThemeHook } from '../theme/create-theme-hook.ts'
+
+type ThemeStoresTuple<
+	Themes extends ThemeMap,
+	A extends ThemeStoreFactory<Themes> = never,
+	B extends ThemeStoreFactory<Themes> = never,
+	C extends ThemeStoreFactory<Themes> = never,
+	D extends ThemeStoreFactory<Themes> = never,
+	E extends ThemeStoreFactory<Themes> = never,
+	F extends ThemeStoreFactory<Themes> = never,
+	G extends ThemeStoreFactory<Themes> = never,
+	H extends ThemeStoreFactory<Themes> = never
+> = readonly [
+	store1: ComposeThemeStoreEntry<Themes, A>,
+	store2?: ComposeThemeStoreEntry<Themes, B>,
+	store3?: ComposeThemeStoreEntry<Themes, C>,
+	store4?: ComposeThemeStoreEntry<Themes, D>,
+	store5?: ComposeThemeStoreEntry<Themes, E>,
+	store6?: ComposeThemeStoreEntry<Themes, F>,
+	store7?: ComposeThemeStoreEntry<Themes, G>,
+	store8?: ComposeThemeStoreEntry<Themes, H>
+]
+
+/**
+ * React hook that returns the current theme and a setter for composed theme stores.
+ * Delegates to createThemeHook internally.
+ *
+ * Accepts `stores` in two forms:
+ * - **Factory (recommended):** `() => [store1, store2, ...]` — run once on mount; no memoization needed.
+ * - **Array:** `[store1, store2, ...]` — must be memoized or ref-stable; recreating the array each render breaks subscriptions.
+ *
+ * @param themes - ThemeMap mapping theme keys to their values (e.g. CSS class names)
+ * @param stores - Array or factory returning 1–8 theme stores (see ComposeThemeStoreEntry)
+ * @param options.defaultTheme - Fallback theme key when stores return empty; also used for SSR
+ * @returns Tuple of [currentTheme, setTheme]
+ *
+ * @example
+ * ```tsx
+ * // Factory form — no memoization needed
+ * const [theme, setTheme] = useThemeStores(
+ *   themes,
+ *   () => [inMemoryThemeStore(themes)],
+ *   { defaultTheme: 'light' }
+ * )
+ *
+ * // Array form — must be memoized
+ * const stores = useMemo(() => [localStorageStore], [])
+ * const [theme, setTheme] = useThemeStores(themes, stores, { defaultTheme: 'light' })
+ * setTheme('dark')
+ * ```
+ */
+export function useThemeStores<
+	Themes extends ThemeMap,
+	A extends ThemeStoreFactory<Themes> = never,
+	B extends ThemeStoreFactory<Themes> = never,
+	C extends ThemeStoreFactory<Themes> = never,
+	D extends ThemeStoreFactory<Themes> = never,
+	E extends ThemeStoreFactory<Themes> = never,
+	F extends ThemeStoreFactory<Themes> = never,
+	G extends ThemeStoreFactory<Themes> = never,
+	H extends ThemeStoreFactory<Themes> = never
+>(
+	themes: Themes,
+	stores:
+		| ThemeStoresTuple<Themes, A, B, C, D, E, F, G, H>
+		| (() => ThemeStoresTuple<Themes, A, B, C, D, E, F, G, H>),
+	options?: ComposeThemeStoresOptions<Themes>
+): [keyof Themes | undefined, (theme: keyof Themes) => void] {
+	const resolvedStores = useMemo(
+		() => (typeof stores === 'function' ? stores() : stores),
+		// Empty deps: factory runs once on mount; array form must be ref-stable (user memoizes)
+		[]
+	)
+	const useTheme = createThemeHook<Themes, A, B, C, D, E, F, G, H>(themes, resolvedStores, options)
+	return useTheme(options?.defaultTheme)
+}