@just-web/toolkits 1.0.0

package/src/react/theme/create-theme-hook.ts

@@ -0,0 +1,197 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import type { Required } from 'type-plus'
+import {
+	type ComposeThemeStoreEntry,
+	type ComposeThemeStoresOptions,
+	composeThemeStores
+} from '../../theme/compose-theme-stores.ts'
+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 { ThemeStoreFactory } from '../../theme/theme-store/theme-store-factory.types.ts'
+
+/**
+ * Creates a React hook for theme selection that reads from and writes to composed theme stores.
+ *
+ * The returned hook subscribes to store changes via `useSyncExternalStore`, supports SSR
+ * (uses `defaultTheme` for server snapshot), and returns a `[theme, setTheme]` tuple.
+ * Channels are cached per store configuration and default theme for efficient reuse.
+ *
+ * @param themes - ThemeMap mapping theme keys to their values (e.g. CSS class names)
+ * @param stores - Array of 1–8 theme stores or factory configs (see ComposeThemeStoreEntry)
+ * @param options.defaultTheme - Fallback theme key when stores return empty; also used for SSR
+ * @returns A `useTheme` hook that returns `[currentTheme, setTheme]` tuple
+ *
+ * @example
+ * ```ts
+ * const useTheme = createThemeHook(themes, [localStorageStore], { defaultTheme: 'light' })
+ * const [theme, setTheme] = useTheme()
+ * setTheme('dark')
+ * ```
+ */
+export function createThemeHook<
+	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>
+): (
+	overrideDefaultTheme?: keyof Themes | undefined
+) => [keyof Themes | undefined, (theme: keyof Themes) => void] {
+	const { defaultTheme } = options ?? {}
+	return function useTheme(overrideDefaultTheme?: keyof Themes | undefined) {
+		const effectiveDefault = overrideDefaultTheme ?? defaultTheme
+		const channel = getOrCreateChannel<Themes, A, B, C, D, E, F, G, H>(themes, stores, {
+			defaultTheme: effectiveDefault
+		})
+
+		const theme = useSyncExternalStore<keyof Themes | undefined>(
+			channel.subscribe,
+			channel.getSnapshot,
+			channel.getServerSnapshot
+		)
+
+		const setTheme = useCallback(
+			async (newTheme: keyof Themes) => {
+				await channel.setTheme(newTheme)
+			},
+			[channel]
+		)
+
+		return [theme, setTheme]
+	}
+}
+
+/**
+ * Creates a subscription channel bridging a composed theme store to React's useSyncExternalStore.
+ * Manages listeners, initial async read from store, and delegates setTheme to store.write.
+ *
+ * @internal
+ */
+function createSharedChannel<Themes extends ThemeMap>(
+	themes: Themes,
+	composedStore: Required<AsyncThemeStore<Themes>>,
+	defaultTheme: keyof Themes | undefined
+) {
+	let lastTheme: keyof Themes | undefined = defaultTheme
+	const listeners = new Set<(theme: keyof Themes | undefined) => void>()
+
+	const notify = (theme: keyof Themes | undefined) => {
+		lastTheme = theme
+		for (const fn of listeners) {
+			fn(theme)
+		}
+	}
+
+	const handleStoreUpdate = (entry: ThemeEntry<Themes> | undefined | null) => {
+		notify(entry?.theme ?? defaultTheme)
+	}
+
+	// Initial read to populate lastTheme (compose store subscribe has no initial notify)
+	void Promise.resolve(composedStore.read()).then(
+		(entry: ThemeEntry<Themes> | undefined | null) => {
+			notify(entry?.theme ?? defaultTheme)
+		}
+	)
+
+	let unobserve: () => void = composedStore.subscribe(handleStoreUpdate)
+	let isSubscribedToStore = true
+
+	const subscribe = (listener: (theme: keyof Themes | undefined) => void) => {
+		if (!isSubscribedToStore) {
+			unobserve = composedStore.subscribe(handleStoreUpdate)
+			isSubscribedToStore = true
+		}
+		listeners.add(listener)
+		listener(lastTheme)
+		return () => {
+			listeners.delete(listener)
+			if (listeners.size === 0) {
+				unobserve()
+				isSubscribedToStore = false
+			}
+		}
+	}
+
+	const getSnapshot = (): keyof Themes | undefined => lastTheme
+	const getServerSnapshot = (): keyof Themes | undefined => defaultTheme
+
+	return {
+		subscribe,
+		getSnapshot,
+		getServerSnapshot,
+		setTheme: (theme: keyof Themes) => composedStore.write(themeEntry(themes, theme))
+	}
+}
+
+const channelsByStores = new WeakMap<
+	object,
+	Map<string | undefined, ReturnType<typeof createSharedChannel<any>>>
+>()
+
+/**
+ * Returns a cached shared channel for the given themes, stores, and defaultTheme.
+ * Channels are keyed by stores (WeakMap) and defaultTheme to avoid duplicate subscriptions.
+ *
+ * @internal
+ */
+function getOrCreateChannel<
+	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
+) {
+	const { defaultTheme } = options ?? {}
+	const storesKey = stores as unknown as object
+	let byDefault = channelsByStores.get(storesKey) as Map<
+		keyof Themes | undefined,
+		ReturnType<typeof createSharedChannel<Themes>>
+	>
+	if (!byDefault) {
+		byDefault = new Map<keyof Themes | undefined, ReturnType<typeof createSharedChannel<Themes>>>()
+		channelsByStores.set(storesKey, byDefault as any)
+	}
+	let channel = byDefault.get(defaultTheme) as ReturnType<typeof createSharedChannel<Themes>>
+	if (!channel) {
+		const composedStore = composeThemeStores(themes, stores, { defaultTheme })
+		channel = createSharedChannel<Themes>(themes, composedStore, defaultTheme)
+		byDefault.set(defaultTheme, channel)
+	}
+	return channel
+}

package/src/react.ts

@@ -0,0 +1,7 @@
+export * from './react/hooks/use-attribute.ts'
+export * from './react/hooks/use-prefers-color-scheme.ts'
+export * from './react/hooks/use-theme-by-class-name.ts'
+export * from './react/hooks/use-theme-by-data-attribute.ts'
+export * from './react/hooks/use-theme-by-local-storage.ts'
+export * from './react/hooks/use-theme-stores.ts'
+export * from './react/theme/create-theme-hook.ts'

package/src/style/css-properties.ts

@@ -0,0 +1,20 @@
+import type { Properties } from 'csstype'
+
+declare module 'csstype' {
+	interface Properties<TLength = (string & {}) | 0, TTime = string & {}> extends CustomProperties {}
+}
+
+/** Custom CSS properties (variables) with `--` prefix. */
+interface CustomProperties {
+	[k: `--${string}`]: string
+}
+
+/**
+ * Widens CSS properties to support custom properties.
+ * Allows for string or number values for standard properties,
+ * and string values for custom properties with '--' prefix.
+ * Defined as a union so plain Properties (e.g. from React) are assignable.
+ */
+export interface CSSProperties<TLength = string | number, TTime = string & {}>
+	extends Properties<TLength, TTime>,
+		CustomProperties {}

package/src/style/define-css-properties.ts

@@ -0,0 +1,23 @@
+import type { CSSProperties } from './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).
+ *
+ * @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'
+ * })
+ * ```
+ */
+export function defineCSSProperties<TLength = 0 | (string & {}), TTime = string & {}>(
+	style: CSSProperties<TLength, TTime>
+) {
+	return style as CSSProperties
+}

package/src/style/get-css-variable-value.ts

@@ -0,0 +1,32 @@
+import type { CreateTuple } from 'type-plus'
+
+/**
+ * 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
+ */
+export function getCSSVariableValue<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
+ */
+export function getCSSVariableValue<Props extends Array<`--${string}`>>(
+	...props: Props
+): CreateTuple<Props['length'], string>
+export function getCSSVariableValue<Props extends Array<`--${string}`>>(
+	element: unknown,
+	...props: Props
+) {
+	if (typeof element === 'string') {
+		return getCSSVariableValue(globalThis.document.body, element as `--${string}`, ...props)
+	}
+	const style = globalThis.getComputedStyle(element as HTMLElement)
+	return props.map((v) => style.getPropertyValue(v)) as any
+}

package/src/style/just-style-props.editor.default.tsx

@@ -0,0 +1,17 @@
+import type { JustStyleProps } from '@just-web/toolkits'
+import { resolveStyle } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+import type { PropsWithChildren } from 'react'
+
+function Badge({ style, ...rest }: PropsWithChildren<JustStyleProps>) {
+	const props = { style: { padding: '0.25rem 0.5rem', backgroundColor: 'rgb(96 165 250)' } }
+	return <div {...rest} style={resolveStyle(props, style)} />
+}
+
+export default () => (
+	<StoryCard appearance="output">
+		<Badge style={{ fontWeight: 'bold' }}>Override</Badge>
+		<Badge style={(renderProps) => ({ ...renderProps.style, fontWeight: 'lighter' })}>Amend</Badge>
+		<Badge style={() => undefined}>Unstyled</Badge>
+	</StoryCard>
+)

package/src/style/just-style-resolver-state.editor.default.tsx

@@ -0,0 +1,22 @@
+import type { JustStyleFnProps } from '@just-web/toolkits'
+
+function boxTheme(renderProps?: JustStyleFnProps) {
+	return {
+		...renderProps,
+		style: {
+			...renderProps?.style,
+			padding: '0.5rem',
+			border: '1px solid rgb(203 213 225)',
+			borderRadius: '0.25rem'
+		}
+	}
+}
+
+export default () => {
+	const props = boxTheme()
+	return (
+		<button type="button" {...props}>
+			Hello World
+		</button>
+	)
+}

package/src/style/just-style.editor.default.tsx

@@ -0,0 +1,17 @@
+import type { JustStyle } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+
+const functionStyle: JustStyle<{ isSelected?: boolean | undefined }> = (renderProps) =>
+	renderProps.isSelected
+		? { ...renderProps.style, backgroundColor: 'rgb(147 197 253)' }
+		: renderProps.style
+
+export default () => {
+	return (
+		<StoryCard appearance="output">
+			<div style={functionStyle({ style: { padding: '0.5rem' }, isSelected: true })}>
+				Result: selected (blue background)
+			</div>
+		</StoryCard>
+	)
+}

package/src/style/just-style.editor.type-param.tsx

@@ -0,0 +1,31 @@
+import type { JustStyle } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+
+interface ButtonRenderProps {
+	isDisabled?: boolean | undefined
+	isPressed?: boolean | undefined
+}
+
+const styleWhenDisabled: JustStyle<ButtonRenderProps> = (renderProps) =>
+	renderProps.isDisabled
+		? { ...renderProps.style, opacity: 0.5, cursor: 'not-allowed' }
+		: renderProps.style
+
+const styleWhenActive: JustStyle<ButtonRenderProps> = (renderProps) =>
+	renderProps.isPressed
+		? { ...renderProps.style, outline: '2px solid rgb(59 130 246)' }
+		: renderProps.style
+
+export default () => {
+	const renderProps: ButtonRenderProps = { isDisabled: true, isPressed: true }
+	return (
+		<StoryCard appearance="output">
+			<div style={styleWhenDisabled({ ...renderProps, style: { padding: '0.5rem' } })}>
+				disabled style
+			</div>
+			<div style={styleWhenActive({ ...renderProps, style: { padding: '0.5rem' } })}>
+				active style
+			</div>
+		</StoryCard>
+	)
+}

package/src/style/just-style.ts

@@ -0,0 +1,60 @@
+import type { AnyRecord } from 'type-plus'
+import type { CSSProperties } from './css-properties.ts'
+
+type DefaultLength = 0 | (string & {})
+type DefaultTime = string & {}
+
+/**
+ * Props interface for components that accept a render-props-aware `style`.
+ *
+ * Use this when defining component props that support the same `style` contract as {@link JustStyle}:
+ * a static object, a resolver function that receives render props (including existing `style`), or `undefined`.
+ *
+ * @typeParam RenderProps - Record type for render props. When `style` is a function, it receives `RenderProps` merged with `{ style?: CSSProperties }`.
+ * @typeParam TLength - CSS length type (default: `0 | (string & {})`).
+ * @typeParam TTime - CSS time type (default: `string & {}`).
+ */
+export interface JustStyleProps<
+	RenderProps extends AnyRecord = AnyRecord,
+	TLength = DefaultLength,
+	TTime = DefaultTime
+> {
+	style?: JustStyle<RenderProps, TLength, TTime> | undefined
+}
+
+/**
+ * A `style` type that can be static or computed from render props.
+ *
+ * - `CSSProperties`: The value is merged with the existing `style` in render props (override wins).
+ * - `undefined`: Uses the existing `style` from render props as-is.
+ * - `function`: Process the render props and return the desired `style`.
+ *
+ * @typeParam RenderProps - Record type for render props. Resolvers receive `RenderProps` merged with `{ style?: CSSProperties }`.
+ * @typeParam TLength - CSS length type (default: `0 | (string & {})`).
+ * @typeParam TTime - CSS time type (default: `string & {}`).
+ */
+export type JustStyle<
+	RenderProps extends AnyRecord = AnyRecord,
+	TLength = DefaultLength,
+	TTime = DefaultTime
+> =
+	| ((
+			renderProps: JustStyleFnProps<RenderProps, TLength, TTime>
+	  ) => CSSProperties<TLength, TTime> | undefined)
+	| CSSProperties<TLength, TTime>
+	| undefined
+
+/**
+ * The props type for `JustStyle` resolver functions.
+ *
+ * @typeParam RenderProps - Record type for render props.
+ * @typeParam TLength - CSS length type (default: `0 | (string & {})`).
+ * @typeParam TTime - CSS time type (default: `string & {}`).
+ */
+export type JustStyleFnProps<
+	RenderProps extends AnyRecord = AnyRecord,
+	TLength = DefaultLength,
+	TTime = DefaultTime
+> = RenderProps & {
+	style?: CSSProperties<TLength, TTime> | undefined
+}

package/src/style/resolve-style.ts

@@ -0,0 +1,23 @@
+import type { AnyRecord } from 'type-plus'
+import type { CSSProperties } from './css-properties.ts'
+import type { JustStyle, JustStyleFnProps } from './just-style.ts'
+
+type DefaultLength = 0 | (string & {})
+type DefaultTime = string & {}
+
+export function resolveStyle<
+	RenderProps extends AnyRecord = AnyRecord,
+	TLength = DefaultLength,
+	TTime = DefaultTime
+>(
+	renderProps: JustStyleFnProps<RenderProps, TLength, TTime>,
+	style?: JustStyle<RenderProps, TLength, TTime>
+): CSSProperties<TLength, TTime> | undefined {
+	if (typeof style === 'function') {
+		return style(renderProps)
+	}
+	if (style !== undefined) {
+		return { ...renderProps.style, ...style } as CSSProperties<TLength, TTime>
+	}
+	return renderProps.style
+}

package/src/style/style-props.editor.tsx

@@ -0,0 +1,13 @@
+import type { StyleProps } from '@just-web/toolkits'
+import { StoryCard } from '@repobuddy/storybook'
+import type { PropsWithChildren } from 'react'
+
+export default () => (
+	<StoryCard appearance="output">
+		<MyComponent style={{ color: 'red', fontWeight: 'bold' }}>Hello in red and bold</MyComponent>
+	</StoryCard>
+)
+
+function MyComponent({ style, children }: PropsWithChildren<StyleProps>) {
+	return <div style={style}>{children}</div>
+}

package/src/style/style-props.ts

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

package/src/style/to-dom-style.ts

@@ -0,0 +1,36 @@
+import type { CSSProperties } from './css-properties.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 DOM style properties object
+ *
+ * @example
+ * ```ts
+ * const domStyle = toDomStyle({
+ *   backgroundColor: 'red',
+ *   '--custom-color': '#ff0000'
+ * })
+ * if (domStyle && element.style) {
+ *   for (const [key, value] of Object.entries(domStyle)) {
+ *     element.style.setProperty(key, value)
+ *   }
+ * }
+ * ```
+ */
+export function toDomStyle(style: CSSProperties | undefined) {
+	if (style === undefined) return undefined
+
+	const result: Record<string, string | null> = {}
+
+	for (const [key, value] of Object.entries(style)) {
+		result[
+			key.startsWith('--') ? key : key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`)
+		] = value
+	}
+
+	return result
+}

package/src/testing/button.theme.ts

@@ -0,0 +1,21 @@
+import type { ButtonRenderProps } from 'react-aria-components'
+import { twMerge } from 'tailwind-merge'
+import type { JustClassName, JustClassNameFnProps } from '../class-name/just-class-name.ts'
+import { resolveClassName } from '../class-name/resolve-class-name.ts'
+
+export const buttonTheme = {
+	className(
+		state: JustClassNameFnProps<ButtonRenderProps>,
+		className: JustClassName<ButtonRenderProps> | undefined
+	) {
+		return twMerge(
+			resolveClassName(
+				{
+					...state,
+					className: 'bg-cyan-700 text-white px-4 py-2 rounded-md shadow-md active:bg-cyan-800'
+				},
+				className
+			)
+		)
+	}
+}

package/src/testing/button.tsx

@@ -0,0 +1,11 @@
+import { forwardRef } from 'react'
+import { Button as RacButton, type ButtonProps as RacButtonProps } from 'react-aria-components'
+import type { JustClassNameProps } from '../class-name/just-class-name.ts'
+import { buttonTheme } from './button.theme.ts'
+
+type ButtonProps = Omit<RacButtonProps, 'className'> &
+	JustClassNameProps<Omit<RacButtonProps, 'className'>>
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(({ className, ...props }, ref) => (
+	<RacButton ref={ref} className={(state) => buttonTheme.className(state, className)} {...props} />
+))

package/src/testing/log-panel.tsx

@@ -0,0 +1,14 @@
+import { StoryCard } from '@repobuddy/storybook'
+
+export function LogPanel({ title, log }: { title: string; log: string[] }) {
+	return (
+		<StoryCard appearance="output">
+			<h2 className="mb-2">{title}</h2>
+			{log.map((entry, i) => (
+				<pre key={i} className="font-mono">
+					{entry}
+				</pre>
+			))}
+		</StoryCard>
+	)
+}

package/src/testing/theme/dummy-theme-store.ts

@@ -0,0 +1,7 @@
+import type { ThemeStore } from '../../theme/theme-store/theme-store.types.ts'
+
+export const dummyThemeStore = {
+	read: () => undefined,
+	write: () => {},
+	subscribe: () => () => {}
+} satisfies ThemeStore

package/src/testing/theme/theme-result-card.tsx

@@ -0,0 +1,43 @@
+import { StoryCard } from '@repobuddy/storybook'
+import { appendId } from '../../utils/append-id.ts'
+
+type ThemeResult = {
+	theme?: unknown
+	value?: unknown
+}
+
+type ThemeResultCardProps = {
+	result: ThemeResult | null | undefined
+	title: string
+	'data-testid'?: string | undefined
+}
+
+function formatValue(value: unknown): string {
+	if (value === null) return '(missing)'
+	if (value === '') return '(empty)'
+	if (Array.isArray(value)) return `[${value.join(', ')}]`
+	return String(value)
+}
+
+export function ThemeResultCard({
+	result,
+	title,
+	'data-testid': dataTestId
+}: ThemeResultCardProps) {
+	return (
+		<StoryCard title={title} data-testid={dataTestId} appearance="output">
+			<p>
+				theme:{' '}
+				<span data-testid={appendId(dataTestId, 'theme')}>
+					{result?.theme === undefined ? '(undefined)' : String(result?.theme)}
+				</span>
+			</p>
+			<p>
+				value:{' '}
+				<span data-testid={appendId(dataTestId, 'value')}>
+					{result?.value === undefined ? '(undefined)' : formatValue(result?.value)}
+				</span>
+			</p>
+		</StoryCard>
+	)
+}