@just-web/toolkits 1.0.0

package/src/testing/theme/theme-store-demo.tsx

@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useState } from 'react'
+import { themeEntry } from '../../theme/theme-entry.ts'
+import type { ThemeEntry } from '../../theme/theme-entry.types.ts'
+import type { ThemeMap } from '../../theme/theme-map.types.ts'
+import type { AsyncThemeStore } from '../../theme/theme-store/async-theme-store.types.ts'
+import type { ThemeStore } from '../../theme/theme-store/theme-store.types.ts'
+import { appendId } from '../../utils/append-id.ts'
+import { Button } from '../button.tsx'
+import { ThemeResultCard } from './theme-result-card.tsx'
+
+type ThemeStoreDemoProps<Themes extends ThemeMap> = {
+	store: ThemeStore<Themes> | AsyncThemeStore<Themes>
+	themes: Themes
+	/** Theme keys to show as "Write X" buttons. Defaults to first 3 keys from themes. */
+	setThemeKeys?: (keyof Themes)[] | undefined
+	'data-testid'?: string | undefined
+}
+
+/**
+ * Demo component that uses theme store.read, store.write, and store.subscribe.
+ * Renders observed value, a one-time read result, and buttons to trigger read/write for showcasing behavior.
+ * All interactive elements and result areas use data-testid for testing.
+ */
+export function ThemeStoreDemo<Themes extends ThemeMap>({
+	store,
+	themes,
+	setThemeKeys,
+	'data-testid': dataTestId = 'theme-store-demo'
+}: ThemeStoreDemoProps<Themes>) {
+	const [observedResult, setObservedResult] = useState<ThemeEntry<Themes> | undefined | null>(
+		undefined
+	)
+	const [getResult, setGetResult] = useState<ThemeEntry<Themes> | undefined | null>(undefined)
+
+	const keys = (setThemeKeys ??
+		(Object.keys(themes) as (keyof Themes)[]).slice(0, 3)) as (keyof Themes)[]
+
+	useEffect(() => {
+		void Promise.resolve(store.read?.()).then((r) => setObservedResult(r ?? undefined))
+	}, [store])
+
+	useEffect(() => {
+		return store.subscribe?.(setObservedResult)
+	}, [store])
+
+	const handleGet = useCallback(async () => {
+		const result = store.read?.()
+		const resolved = await Promise.resolve(result)
+		setGetResult(resolved ?? undefined)
+	}, [store])
+
+	const handleSet = useCallback(
+		(theme: keyof Themes) => async () => {
+			const ret = store.write?.(themeEntry(themes, theme))
+			await Promise.resolve(ret)
+		},
+		[store, themes]
+	)
+
+	const observeTestId = appendId(dataTestId, 'observe')
+	const readTestId = appendId(dataTestId, 'read')
+
+	return (
+		<div className="flex flex-col gap-2" data-testid={dataTestId}>
+			<div className="flex flex-wrap gap-2">
+				<Button onClick={handleGet} data-testid={appendId(dataTestId, 'btn-read')}>
+					Read theme
+				</Button>
+				{keys.map((key) => (
+					<Button
+						key={String(key)}
+						onClick={handleSet(key)}
+						data-testid={appendId(dataTestId, `btn-write-${String(key)}`)}
+					>
+						Write {String(key)}
+					</Button>
+				))}
+			</div>
+			<ThemeResultCard title="Read (one-time)" result={getResult} data-testid={readTestId} />
+			<ThemeResultCard
+				title="Observed (subscribe)"
+				result={observedResult}
+				data-testid={observeTestId}
+			/>
+		</div>
+	)
+}

package/src/theme/_utils/get-theme-from-stores.ts

@@ -0,0 +1,34 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import type { AsyncThemeStore } from '../theme-store/async-theme-store.types.ts'
+import type { ThemeStore } from '../theme-store/theme-store.types.ts'
+
+type StoreWithRead<Themes extends ThemeMap> = (ThemeStore<Themes> | AsyncThemeStore<Themes>) & {
+	read: () => ThemeEntry<Themes> | undefined | Promise<ThemeEntry<Themes> | undefined>
+}
+
+/**
+ * Reads theme from stores using waterfall strategy.
+ *
+ * Iterates stores in order; returns first non-empty result.
+ * Only includes stores that have a `read` method.
+ *
+ * @param stores - Array of theme stores
+ * @param defaultTheme - Fallback when all stores return empty
+ * @returns Resolved theme key or defaultTheme
+ */
+export async function getThemeFromStores<Themes extends ThemeMap>(
+	stores: (ThemeStore<Themes> | AsyncThemeStore<Themes>)[],
+	defaultTheme: keyof Themes | undefined
+): Promise<keyof Themes | undefined> {
+	const withRead = stores.filter((s): s is StoreWithRead<Themes> => typeof s.read === 'function')
+
+	for (const store of withRead) {
+		const result = await Promise.resolve(store.read())
+		if (result !== undefined) {
+			return result.theme
+		}
+	}
+
+	return defaultTheme
+}

package/src/theme/_utils/observe-theme-from-stores.ts

@@ -0,0 +1,57 @@
+import type { RequiredPick } from 'type-plus'
+import type { ThemeMap } from '../theme-map.types.ts'
+import type { AsyncThemeStore } from '../theme-store/async-theme-store.types.ts'
+import type { ThemeStore } from '../theme-store/theme-store.types.ts'
+import { getThemeFromStores } from './get-theme-from-stores.ts'
+
+type StoreWithSubscribe<Themes extends ThemeMap> = RequiredPick<
+	AsyncThemeStore<Themes>,
+	'subscribe'
+>
+
+/**
+ * Subscribes to stores that have a subscribe method.
+ *
+ * When any store emits, runs coalesced handler (getThemeFromStores + callback).
+ * Skips handler if resolved theme equals last emitted (value equality).
+ *
+ * @param stores - Array of theme stores
+ * @param defaultTheme - Fallback when all stores return empty
+ * @param handler - Callback with resolved theme key
+ * @returns Unsubscribe function
+ */
+export function observeThemeFromStores<Themes extends ThemeMap>(
+	stores: (ThemeStore<Themes> | AsyncThemeStore<Themes>)[],
+	defaultTheme: keyof Themes | undefined,
+	handler: (theme: keyof Themes | undefined) => void
+): () => void {
+	const withSubscribe = stores.filter(
+		(s): s is StoreWithSubscribe<Themes> => typeof s.subscribe === 'function'
+	)
+
+	let scheduled = false
+	let lastEmitted: keyof Themes | undefined
+
+	const scheduleNotify = () => {
+		if (scheduled) return
+		scheduled = true
+		queueMicrotask(async () => {
+			scheduled = false
+			const theme = await getThemeFromStores(stores, defaultTheme)
+			if (theme === lastEmitted) return
+			lastEmitted = theme
+			handler(theme)
+		})
+	}
+
+	// Initial notify
+	scheduleNotify()
+
+	const unSubs = withSubscribe.map((s) => s.subscribe!((_result) => scheduleNotify()))
+
+	return () => {
+		for (const unSub of unSubs) {
+			unSub()
+		}
+	}
+}

package/src/theme/_utils/parse-stored-theme.ts

@@ -0,0 +1,21 @@
+import { tryParseJSON } from '../../_internal/utils/try-parse-json.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Parses stored JSON theme and validates the theme key against theme map.
+ *
+ * Expects stored shape: { theme: string, value?: unknown }
+ *
+ * @param themes - Record of valid theme keys (optional; if omitted, any theme string is accepted)
+ * @param value - Raw string from localStorage/sessionStorage
+ * @returns Theme key if valid, otherwise undefined
+ */
+export function parseStoredTheme<Theme extends string>(
+	themes: ThemeMap<Theme> | undefined,
+	value: string | null | undefined
+): Theme | undefined {
+	const parsed = tryParseJSON<{ theme: string }>(value)
+	if (!parsed?.theme || typeof parsed.theme !== 'string') return undefined
+	if (themes && !(parsed.theme in themes)) return undefined
+	return parsed.theme as Theme
+}

package/src/theme/_utils/set-theme-to-stores.ts

@@ -0,0 +1,23 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+import type { AsyncThemeStore } from '../theme-store/async-theme-store.types.ts'
+import type { ThemeStore } from '../theme-store/theme-store.types.ts'
+
+type StoreWithWrite<Themes extends ThemeMap> = (ThemeStore<Themes> | AsyncThemeStore<Themes>) & {
+	write: (entry: ThemeEntry<Themes> | undefined) => void | Promise<void>
+}
+
+/**
+ * Writes theme entry to all stores that have a write method.
+ *
+ * @param stores - Array of theme stores
+ * @param entry - Theme entry to write, or undefined to clear
+ */
+export async function setThemeToStores<Themes extends ThemeMap>(
+	stores: (ThemeStore<Themes> | AsyncThemeStore<Themes>)[],
+	entry: ThemeEntry<Themes> | undefined
+): Promise<void> {
+	const withWrite = stores.filter((s): s is StoreWithWrite<Themes> => typeof s.write === 'function')
+
+	await Promise.all(withWrite.map((store) => Promise.resolve(store.write!(entry))))
+}

package/src/theme/class-name/apply-theme-to-class-name.ts

@@ -0,0 +1,26 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Applies theme to element by updating its class attribute.
+ *
+ * Removes all theme classes from the element, then adds classes for the given entry.
+ * When entry is undefined, removes all theme classes (themeMap needed for clear path).
+ *
+ * @param element - Target element
+ * @param entry - Theme entry to apply, or undefined to clear
+ * @param themes - Record mapping theme keys to class names (used for clear case)
+ */
+export function applyThemeToClassName<Themes extends ThemeMap>(
+	themes: Themes,
+	element: Element,
+	entry: ThemeEntry<Themes> | undefined
+): void {
+	const allThemeClasses = Object.values(themes).flatMap((v) => (Array.isArray(v) ? [...v] : [v]))
+	const current = element.className.trim()
+	const currentClasses = current ? current.split(/\s+/) : []
+	const withoutThemes = currentClasses.filter((c) => !allThemeClasses.includes(c))
+	const activeClasses =
+		entry !== undefined ? (Array.isArray(entry.value) ? [...entry.value] : [entry.value]) : []
+	element.className = [...withoutThemes, ...activeClasses].filter(Boolean).join(' ')
+}

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

@@ -0,0 +1,22 @@
+import { findKey } from 'type-plus'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Resolves theme key from class name string by matching against theme map.
+ *
+ * @param className - Element class attribute value
+ * @param themes - Record mapping theme keys to class name(s); arrays use first value for matching
+ * @returns Theme key if a match is found, otherwise undefined
+ */
+export function resolveThemeFromClassName<Theme extends string>(
+	themes: ThemeMap<Theme>,
+	className: string
+): Theme | undefined {
+	const theme = findKey(themes, (key) => {
+		const value = themes[key]
+		if (value === undefined) return false
+		const v = Array.isArray(value) ? value[0] : value
+		return !!v && className.includes(v)
+	})
+	return theme as Theme | undefined
+}

package/src/theme/compose-theme-stores.ts

@@ -0,0 +1,139 @@
+import type { Required, RequiredPick } from 'type-plus'
+import { setThemeToStores } from './_utils/set-theme-to-stores.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 { AsyncThemeStore } from './theme-store/async-theme-store.types.ts'
+import type { ThemeStore } from './theme-store/theme-store.types.ts'
+import type { ThemeStoreFactory } from './theme-store/theme-store-factory.types.ts'
+
+/** Input item for one position: concrete store or factory config [factory, options?]. */
+export type ComposeThemeStoreEntry<
+	Themes extends ThemeMap,
+	F extends ThemeStoreFactory<Themes> = never
+> = ThemeStore<Themes> | AsyncThemeStore<Themes> | readonly [F] | readonly [F, Parameters<F>[1]]
+
+export type ComposeThemeStoresOptions<Themes extends ThemeMap> = {
+	defaultTheme?: keyof Themes | undefined
+}
+
+/**
+ * Composes multiple theme stores into a single store.
+ *
+ * Accepts concrete stores or store factory tuples `[factory]` or `[factory, options]`.
+ * For factory tuples, calls `factory(themes)` or `factory(themes, options)` to create stores.
+ *
+ * - **read**: Returns first non-empty `ThemeEntry` from stores (waterfall). When all empty
+ *   and `defaultTheme` is defined, returns `themeEntry(themes, defaultTheme)`.
+ * - **write**: Delegates to `setThemeToStores` (writes to all stores with write).
+ * - **subscribe**: Aggregates child store subscriptions. No initial notify—handler is only
+ *   called when a child store emits.
+ *
+ * @param themes - ThemeMap for synthesizing fallback ThemeEntry
+ * @param stores - Array of theme stores or factory configs [factory, options?]
+ * @param options.defaultTheme - Fallback theme key when all stores return empty
+ * @returns AsyncThemeStore
+ */
+export function composeThemeStores<
+	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: 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>
+	],
+	options?: ComposeThemeStoresOptions<Themes> | undefined
+): Required<AsyncThemeStore<Themes>> {
+	const { defaultTheme } = options ?? {}
+	const resolved = resolveStores(themes, stores)
+	const withRead = resolved.filter((s): s is StoreWithRead<Themes> => typeof s.read === 'function')
+
+	async function readFromStores(): Promise<ThemeEntry<Themes> | undefined> {
+		for (const store of withRead) {
+			const result = await Promise.resolve(store.read())
+			if (result !== undefined) return result
+		}
+		return defaultTheme !== undefined ? themeEntry(themes, defaultTheme) : undefined
+	}
+
+	const withSubscribe = resolved.filter(
+		(s): s is StoreWithSubscribe<Themes> => typeof s.subscribe === 'function'
+	)
+
+	function subscribe(handler: (theme: ThemeEntry<Themes> | undefined | null) => void): () => void {
+		let scheduled = false
+		let lastEmitted: keyof Themes | undefined
+
+		const scheduleNotify = () => {
+			if (scheduled) return
+			scheduled = true
+			queueMicrotask(async () => {
+				scheduled = false
+				const entry = await readFromStores()
+				const key = entry?.theme ?? undefined
+				if (key === lastEmitted) return
+				lastEmitted = key
+				handler(entry ?? undefined)
+			})
+		}
+
+		const unSubs = withSubscribe.map((s) => s.subscribe!((_result) => scheduleNotify()))
+
+		return () => {
+			for (const unSub of unSubs) {
+				unSub()
+			}
+		}
+	}
+
+	return {
+		read: readFromStores,
+		write(entry) {
+			return setThemeToStores(resolved, entry)
+		},
+		subscribe: withSubscribe.length > 0 ? subscribe : () => () => {}
+	}
+}
+
+type StoreWithRead<Themes extends ThemeMap> = RequiredPick<AsyncThemeStore<Themes>, 'read'>
+
+type StoreWithSubscribe<Themes extends ThemeMap> = RequiredPick<
+	AsyncThemeStore<Themes>,
+	'subscribe'
+>
+
+function resolveStores<Themes extends ThemeMap>(
+	themes: Themes,
+	stores: readonly [
+		store1: ComposeThemeStoreEntry<Themes, any>,
+		store2?: ComposeThemeStoreEntry<Themes, any>,
+		store3?: ComposeThemeStoreEntry<Themes, any>,
+		store4?: ComposeThemeStoreEntry<Themes, any>,
+		store5?: ComposeThemeStoreEntry<Themes, any>,
+		store6?: ComposeThemeStoreEntry<Themes, any>,
+		store7?: ComposeThemeStoreEntry<Themes, any>,
+		store8?: ComposeThemeStoreEntry<Themes, any>
+	]
+): (ThemeStore<Themes> | AsyncThemeStore<Themes>)[] {
+	return stores.map((item) => {
+		if (Array.isArray(item)) {
+			const [factory, options] = item
+			return (factory as (t: Themes, o?: unknown) => ThemeStore<Themes>)(themes, options)
+		}
+		return item as ThemeStore<Themes> | AsyncThemeStore<Themes>
+	})
+}

package/src/theme/data-attribute/apply-theme-to-data-attribute.ts

@@ -0,0 +1,27 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Applies theme to element by setting or removing a data attribute.
+ *
+ * @param element - Target element
+ * @param attributeName - Data attribute name (e.g. `data-theme`)
+ * @param entry - Theme entry to apply, or undefined to remove attribute
+ */
+export function applyThemeToDataAttribute<Themes extends ThemeMap>(
+	element: Element,
+	attributeName: `data-${string}`,
+	entry: ThemeEntry<Themes> | undefined
+): void {
+	if (entry === undefined) {
+		element.removeAttribute(attributeName)
+		return
+	}
+	const val = entry.value
+	const attributeValue = Array.isArray(val) ? val[0] : val
+	if (attributeValue !== undefined && attributeValue !== '') {
+		element.setAttribute(attributeName, attributeValue)
+	} else {
+		element.removeAttribute(attributeName)
+	}
+}

package/src/theme/data-attribute/resolve-theme-from-data-attribute.ts

@@ -0,0 +1,23 @@
+import { findKey } from 'type-plus'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Resolves theme key from data attribute value by matching against theme map.
+ *
+ * @param attrValue - Data attribute value (e.g. from getAttribute)
+ * @param themes - Record mapping theme keys to attribute values
+ * @returns Theme key if a match is found, otherwise undefined
+ */
+export function resolveThemeFromDataAttribute<Theme extends string>(
+	themes: ThemeMap<Theme>,
+	attrValue: string | null
+): Theme | undefined {
+	if (attrValue === null || attrValue === '') return undefined
+	const theme = findKey(themes, (key) => {
+		const value = themes[key]
+		if (value === undefined) return false
+		const v = Array.isArray(value) ? value[0] : value
+		return v === attrValue
+	})
+	return theme as Theme | undefined
+}

package/src/theme/theme-entry.ts

@@ -0,0 +1,10 @@
+import type { ThemeEntry } from './theme-entry.types.ts'
+import type { ThemeMap } from './theme-map.types.ts'
+
+/** Creates ThemeEntry from theme map and theme key. */
+export function themeEntry<Themes extends ThemeMap>(
+	themes: Themes,
+	theme: keyof Themes
+): ThemeEntry<Themes> {
+	return { theme, value: themes[theme] }
+}

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

@@ -0,0 +1,11 @@
+import type { ThemeMap } from './theme-map.types.ts'
+
+/**
+ * Theme entry is a pair of theme key and theme value.
+ *
+ * It is the basic value persisted by the theme stores.
+ */
+export interface ThemeEntry<Themes extends ThemeMap = ThemeMap> {
+	theme: keyof Themes
+	value: Themes[keyof Themes]
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Record mapping theme keys to their values.
+ * Each value can be a single string or readonly string[] (e.g. multiple CSS classes).
+ * Used by all ThemeStore factories via the themes option.
+ */
+export type ThemeMap<Theme extends string = string> = Record<Theme, string | readonly string[]>

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

@@ -0,0 +1,24 @@
+import type { ThemeEntry } from '../theme-entry.types.ts'
+import type { ThemeMap } from '../theme-map.types.ts'
+
+/**
+ * Async variant of `ThemeStore` where read and write may return promises.
+ * Use for remote persistence, polling, or WebSocket-based sync.
+ *
+ * Same optional methods as `ThemeStore`:
+ *
+ * - **read** – Can return `Promise<ThemeEntry | undefined>` for async sources
+ * - **write** – Can return `Promise<void>` for async persistence
+ * - **subscribe** – Same signature as sync; observes external changes
+ *
+ * @typeParam Themes - Map of theme keys to their value types (string or readonly string[])
+ */
+export interface AsyncThemeStore<Themes extends ThemeMap = ThemeMap> {
+	read?:
+		| (() => ThemeEntry<Themes> | undefined | Promise<ThemeEntry<Themes> | undefined>)
+		| undefined
+	write?: ((entry: ThemeEntry<Themes> | undefined) => void | Promise<void>) | undefined
+	subscribe?:
+		| ((handler: (entry: ThemeEntry<Themes> | undefined | null) => void) => () => void)
+		| undefined
+}

package/src/theme/theme-store/class-name-theme-store/class-name-theme-store.ts

@@ -0,0 +1,62 @@
+import type { Required } from 'type-plus'
+import { observeAttributes } from '../../../attributes/observe-attribute.ts'
+import { dummyThemeStore } from '../../../testing/theme/dummy-theme-store.ts'
+import { applyThemeToClassName } from '../../class-name/apply-theme-to-class-name.ts'
+import { resolveThemeFromClassName } from '../../class-name/resolve-theme-from-class-name.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 element class names.
+ *
+ * @param themes - Record mapping theme keys to class name(s)
+ * @param options.element - Element to operate on (defaults to document.documentElement)
+ * @returns ThemeStore
+ *
+ * @example
+ * ```ts
+ * const themes = { current: 'theme-current', grayscale: 'theme-grayscale' }
+ * const store = classNameThemeStore(themes)
+ * store.read() // returns themeResult from element.className
+ * store.write(themeEntry(themes, 'grayscale'))
+ * store.subscribe((themeResult) => {})
+ * ```
+ */
+export function classNameThemeStore<Themes extends ThemeMap>(
+	themes: Themes,
+	options?: { element?: Element | undefined }
+): Required<ThemeStore<Themes>> {
+	const element = options?.element ?? document?.documentElement
+
+	if (!element) return dummyThemeStore
+
+	return {
+		read() {
+			const theme = resolveThemeFromClassName(themes, element.className)
+			if (theme === undefined) return undefined
+			return themeEntry(themes, theme)
+		},
+		write(entry) {
+			applyThemeToClassName(themes, element, entry)
+		},
+		subscribe(handler) {
+			let lastEmitted: keyof Themes | undefined | null = null
+			const observer = observeAttributes(
+				{
+					class: (value) => {
+						const theme = value ? resolveThemeFromClassName(themes, value) : undefined
+						const entry = theme ? themeEntry(themes, theme) : undefined
+						const key = theme ?? undefined
+
+						if (lastEmitted === key) return
+						lastEmitted = key
+						handler(entry)
+					}
+				},
+				element
+			)
+			return () => observer.disconnect()
+		}
+	}
+}