@just-web/css 0.1.0

package/esm/utils/prefers-color-scheme.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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()
+ * ```
+ */
+export 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
+ * ```
+ */
+export declare function getPrefersColorTheme<T extends string>(...themes: T[]): T | null;
+//# sourceMappingURL=prefers-color-scheme.d.ts.map

package/esm/utils/prefers-color-scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefers-color-scheme.d.ts","sourceRoot":"","sources":["../../src/utils/prefers-color-scheme.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,cAkBvG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,YAEpE"}

package/esm/utils/prefers-color-scheme.js

@@ -0,0 +1,54 @@
+import { mapKey } from 'type-plus';
+import { ctx } from "../globals.ctx.js";
+/**
+ * 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()
+ * ```
+ */
+export function observePrefersColorScheme(themes) {
+    const removers = mapKey(themes, (t) => {
+        const m = ctx.matchMedia(`(prefers-color-scheme: ${t})`);
+        const listener = (event) => {
+            if (event.matches) {
+                themes[t]?.(t);
+            }
+        };
+        m.addEventListener('change', listener);
+        return () => m.removeEventListener('change', listener);
+    });
+    return () => {
+        for (const remover of removers) {
+            remover();
+        }
+    };
+}
+/**
+ * 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
+ * ```
+ */
+export function getPrefersColorTheme(...themes) {
+    return themes.find((theme) => ctx.matchMedia(`(prefers-color-scheme: ${theme})`).matches) ?? null;
+}
+//# sourceMappingURL=prefers-color-scheme.js.map

package/esm/utils/prefers-color-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefers-color-scheme.js","sourceRoot":"","sources":["../../src/utils/prefers-color-scheme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CAAmB,MAA4C;IACvG,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;QACrC,MAAM,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,0BAA0B,CAAW,GAAG,CAAC,CAAA;QAClE,MAAM,QAAQ,GAAG,CAAC,KAA0B,EAAE,EAAE;YAC/C,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;YACf,CAAC;QACF,CAAC,CAAA;QAED,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QACtC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,EAAE;QACX,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAChC,OAAO,EAAE,CAAA;QACV,CAAC;IACF,CAAC,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAmB,GAAG,MAAW;IACpE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,0BAA0B,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;AAClG,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@just-web/css",
+  "version": "0.1.0",
+  "description": "",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./esm/index.d.ts",
+      "default": "./esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "esm",
+    "src",
+    "!**/*.{spec,test,unit,accept,integrate,system,stories}.*",
+    "!**/*.mdx"
+  ],
+  "dependencies": {
+    "csstype": "^3.1.3",
+    "type-plus": "8.0.0-beta.7"
+  },
+  "devDependencies": {
+    "@repobuddy/storybook": "^0.9.1",
+    "@repobuddy/vitest": "^1.2.2",
+    "@storybook/addon-essentials": "^8.6.12",
+    "@storybook/addon-storysource": "^8.6.12",
+    "@storybook/blocks": "^8.6.12",
+    "@storybook/experimental-addon-test": "^8.6.12",
+    "@storybook/manager-api": "^8.6.12",
+    "@storybook/preview-api": "^8.6.12",
+    "@storybook/react": "^8.6.12",
+    "@storybook/react-vite": "^8.6.12",
+    "@storybook/test": "^8.6.12",
+    "@storybook/theming": "^8.6.12",
+    "@tailwindcss/vite": "^4.1.6",
+    "@vitest/browser": "^3.1.3",
+    "@vitest/coverage-v8": "^3.1.3",
+    "dedent": "^1.6.0",
+    "playwright": "^1.52.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "storybook": "^8.6.12",
+    "storybook-addon-code-editor": "^4.1.1",
+    "storybook-addon-tag-badges": "^1.4.0",
+    "storybook-addon-vis": "^0.19.4",
+    "storybook-dark-mode": "^4.0.2",
+    "tailwindcss": "^4.1.6",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.3",
+    "vitest-browser-react": "^0.1.1",
+    "@tools/typescript": "^0.0.1"
+  },
+  "scripts": {
+    "build": "run-p build:*",
+    "build-doc": "storybook build -o ../../docs/css",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "clean": "rimraf .turbo esm *.tsbuildinfo",
+    "cov": "vitest run --coverage",
+    "nuke": "rimraf node_modules",
+    "sb": "storybook dev -p 6206",
+    "test": "vitest run",
+    "w": "vitest"
+  }
+}

package/readme.md

@@ -0,0 +1,15 @@
+# @just-web/css
+
+[@just-web/css][@just-web/css] provides CSS utilities and types for web applications.
+
+## Install
+
+```sh
+npm install @just-web/css
+
+yarn add @just-web/css
+
+pnpm add @just-web/css
+```
+
+[@just-web/css]: https://github.com/justland/just-web-foundation/tree/main/libs/css

package/src/class-name.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export interface ClassNameProps {
+	className?: string | undefined
+}

package/src/css-properties.ts

@@ -0,0 +1,10 @@
+import type { Properties } from 'csstype'
+
+/**
+ * Extends CSS properties to include custom properties.
+ * Allows for string or number values for standard properties,
+ * and string values for custom properties with '--' prefix.
+ */
+export interface CSSProperties extends Properties<string | number> {
+	[k: `--${string}`]: string
+}

package/src/globals.ctx.ts

@@ -0,0 +1,12 @@
+export const ctx = {
+	matchMedia(query: string) {
+		return globalThis.matchMedia(query)
+	},
+	getDocumentElement() {
+		return globalThis.document.documentElement
+	},
+	_reset() {
+		this.matchMedia = globalThis.matchMedia
+		this.getDocumentElement = () => globalThis.document.documentElement
+	},
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './class-name.ts'
+export * from './css-properties.ts'
+export * from './style.ts'
+export * from './theme/class-name.ts'
+export * from './theme/data-attribute.ts'
+export * from './utils/attribute.ts'
+export * from './utils/data-attribute.ts'
+export * from './utils/prefers-color-scheme.ts'

package/src/style.ts

@@ -0,0 +1,8 @@
+import type { CSSProperties } from './css-properties.ts'
+
+/**
+ * Interface for component props that include a style property.
+ */
+export interface StyleProps {
+	style?: CSSProperties | undefined
+}

package/src/tailwind.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/src/testing/log-panel.tsx

@@ -0,0 +1,12 @@
+export function LogPanel({ title, log }: { title: string; log: string[] }) {
+	return (
+		<div className="bg-neutral-100 p-4 rounded overflow-y-auto">
+			<h4 className="mb-2">{title}</h4>
+			{log.map((entry, i) => (
+				<pre key={i} className="font-mono">
+					{entry}
+				</pre>
+			))}
+		</div>
+	)
+}

package/src/testing/toggle-attribute-button.tsx

@@ -0,0 +1,32 @@
+import { forwardRef, useCallback } from 'react'
+
+export const ToggleAttributeButton = forwardRef<HTMLElement, { attribute: string; values?: string[] }>(
+	({ attribute, values = ['test-value'] }, ref) => {
+		const handleAttributeChange = useCallback(
+			(attr: string) => {
+				// Handle both RefObject and function ref cases
+				const target = (ref && 'current' in ref ? ref.current : null) ?? document.documentElement
+				const currentValue = target.getAttribute(attr)
+				const nextIndex = currentValue ? values.indexOf(currentValue) + 1 : 0
+				const newValue = nextIndex < values.length ? values[nextIndex]! : null
+
+				if (newValue === null) {
+					target.removeAttribute(attr)
+				} else {
+					target.setAttribute(attr, newValue)
+				}
+			},
+			[ref, values],
+		)
+
+		return (
+			<button
+				key={attribute}
+				className="bg-cyan-700 text-white px-4 py-2 rounded-md shadow-md active:bg-cyan-800"
+				onClick={() => handleAttributeChange(attribute)}
+			>
+				Toggle {attribute}
+			</button>
+		)
+	},
+)

package/src/theme/class-name.ts

@@ -0,0 +1,70 @@
+import { findKey } from 'type-plus'
+import { ctx } from '../globals.ctx.ts'
+import { observeAttributes } from '../utils/attribute.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'
+ * })
+ * ```
+ */
+export function getThemeByClassName<Themes extends Record<string, string>>(options: {
+	themes: Themes
+	defaultTheme?: keyof Themes | undefined
+	element?: Element | undefined
+}): keyof Themes | undefined {
+	const element = options.element ?? ctx.getDocumentElement()
+	const className = element.className
+	const theme = findKey(options.themes, (theme) => className.includes(options.themes[theme]!))
+	return theme ?? options.defaultTheme
+}
+
+export function observeThemeByClassName<Themes extends Record<string, string>>(options: {
+	themes: Themes
+	handler: (value: string | undefined) => void
+	defaultTheme?: keyof Themes | undefined
+	element?: Element | undefined
+}) {
+	return observeAttributes(
+		{
+			class: (value: string | null) => {
+				if (value === null) {
+					options.handler(options.defaultTheme as string)
+					return
+				}
+
+				for (const name in options.themes) {
+					if (value.includes(options.themes[name]!)) {
+						options.handler(name)
+						break
+					}
+				}
+			},
+		},
+		options.element,
+	)
+}

package/src/theme/data-attribute.ts

@@ -0,0 +1,96 @@
+import { findKey } from 'type-plus'
+import { getDataAttribute, observeDataAttributes } from '../utils/data-attribute.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-')
+ * @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'
+ * })
+ * ```
+ */
+export function getThemeByDataAttribute<Themes extends Record<string, string>>(options: {
+	themes: Themes
+	defaultTheme?: keyof Themes | undefined
+	attributeName: `data-${string}`
+	element?: Element | undefined
+}): keyof Themes | undefined {
+	const value = getDataAttribute(options.attributeName, options.element)
+
+	const theme = findKey(options.themes, (theme) => options.themes[theme] === value)
+
+	return theme ?? options.defaultTheme
+}
+
+/**
+ * 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()
+ * ```
+ */
+export 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
+}) {
+	return observeDataAttributes(
+		{
+			[options.attributeName]: (value: string | null) => {
+				if (value === null) {
+					options.handler((options.defaultTheme as string) ?? null)
+					return
+				}
+
+				for (const name in options.themes) {
+					if (options.themes[name] === value) {
+						options.handler(name)
+						break
+					}
+				}
+			},
+		},
+		options.element,
+	)
+}

package/src/utils/attribute.ts

@@ -0,0 +1,60 @@
+import { ctx } from '../globals.ctx.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)
+ * ```
+ */
+export function getAttribute<T extends string>(
+	qualifiedName: T,
+	element: Element | undefined = ctx.getDocumentElement(),
+) {
+	return element?.getAttribute(qualifiedName) as T | 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();
+ * ```
+ */
+export function observeAttributes<T extends string>(
+	handlers: Record<string, (value: T | null) => void>,
+	element: Element | undefined = ctx.getDocumentElement(),
+) {
+	const observer = new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			const attribute = mutation.attributeName!
+			const value = element.getAttribute(attribute) as T | null
+			handlers[attribute]?.(value)
+		}
+	})
+	observer.observe(element, {
+		attributes: true,
+		attributeFilter: Object.keys(handlers),
+	})
+	return observer
+}

package/src/utils/data-attribute.ts

@@ -0,0 +1,37 @@
+import { ctx } from '../globals.ctx.ts'
+import { getAttribute, observeAttributes } from './attribute.ts'
+
+export function getDataAttribute<T extends `data-${string}`>(
+	qualifiedName: T,
+	element: Element | undefined = ctx.getDocumentElement(),
+) {
+	return getAttribute(qualifiedName, element)
+}
+
+/**
+ * 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();
+ * ```
+ */
+export function observeDataAttributes<T extends string, K extends `data-${string}`>(
+	handlers: Record<K, (value: T | null) => void>,
+	element?: Element | undefined,
+) {
+	return observeAttributes(handlers, element)
+}

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

@@ -0,0 +1,57 @@
+import { mapKey } from 'type-plus'
+import { ctx } from '../globals.ctx.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()
+ * ```
+ */
+export function observePrefersColorScheme<T extends string>(themes: Record<T, (value: T | null) => void>) {
+	const removers = mapKey(themes, (t) => {
+		const m = ctx.matchMedia(`(prefers-color-scheme: ${t as string})`)
+		const listener = (event: MediaQueryListEvent) => {
+			if (event.matches) {
+				themes[t]?.(t)
+			}
+		}
+
+		m.addEventListener('change', listener)
+		return () => m.removeEventListener('change', listener)
+	})
+
+	return () => {
+		for (const remover of removers) {
+			remover()
+		}
+	}
+}
+
+/**
+ * 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
+ * ```
+ */
+export function getPrefersColorTheme<T extends string>(...themes: T[]) {
+	return themes.find((theme) => ctx.matchMedia(`(prefers-color-scheme: ${theme})`).matches) ?? null
+}