@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/theme/theme-storage.ts

@@ -0,0 +1,256 @@
+import type { ResolvedTheme, ThemePreference, ThemeStorage } from "./types";
+import { isThemePreference } from "./types";
+
+export const DEFAULT_THEME_PREFERENCE: ThemePreference = "system";
+export const DEFAULT_STORAGE_KEY = "mizen-theme";
+const DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+
+export function readStorage(storage: ThemeStorage, key: string): string | null {
+	try {
+		return storage.getItem(key);
+	} catch (error) {
+		if (error instanceof DOMException) {
+			return null;
+		}
+		throw error;
+	}
+}
+
+function writeStorage(storage: ThemeStorage, key: string, value: string): void {
+	try {
+		storage.setItem(key, value);
+	} catch (error) {
+		if (error instanceof DOMException) {
+			return;
+		}
+		throw error;
+	}
+}
+
+export const defaultBrowserStorage: ThemeStorage = {
+	getItem(key: string): string | null {
+		if (typeof window === "undefined") {
+			return null;
+		}
+		try {
+			return window.localStorage.getItem(key);
+		} catch (error) {
+			if (error instanceof DOMException) {
+				return null;
+			}
+			throw error;
+		}
+	},
+	setItem(key: string, value: string): void {
+		if (typeof window === "undefined") {
+			return;
+		}
+		try {
+			window.localStorage.setItem(key, value);
+		} catch (error) {
+			if (error instanceof DOMException) {
+				return;
+			}
+			throw error;
+		}
+	},
+};
+
+export interface PreferenceStore {
+	readonly getServerSnapshot: () => ThemePreference;
+	readonly getSnapshot: () => ThemePreference;
+	readonly setPreference: (next: ThemePreference) => void;
+	readonly subscribe: (onStoreChange: () => void) => () => void;
+}
+
+interface CustomEventPayload {
+	readonly preference: ThemePreference;
+	readonly sourceId: symbol;
+	readonly storage: unknown;
+}
+
+const sharedPreferenceStore = new WeakMap<
+	ThemeStorage,
+	Map<string, ThemePreference>
+>();
+
+function getSharedPreference(
+	storage: ThemeStorage,
+	key: string
+): ThemePreference | undefined {
+	if (typeof window === "undefined") {
+		return undefined;
+	}
+	return sharedPreferenceStore.get(storage)?.get(key);
+}
+
+function setSharedPreference(
+	storage: ThemeStorage,
+	key: string,
+	preference: ThemePreference
+): void {
+	if (typeof window === "undefined") {
+		return;
+	}
+	let keyMap = sharedPreferenceStore.get(storage);
+	if (!keyMap) {
+		keyMap = new Map();
+		sharedPreferenceStore.set(storage, keyMap);
+	}
+	keyMap.set(key, preference);
+}
+
+function isCustomPayload(value: unknown): value is CustomEventPayload {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	const preference = Reflect.get(value, "preference");
+	const sourceId = Reflect.get(value, "sourceId");
+	return (
+		isThemePreference(preference) &&
+		typeof sourceId === "symbol" &&
+		Reflect.has(value, "storage")
+	);
+}
+
+function resolveCurrentPreference(
+	storage: ThemeStorage,
+	storageKey: string,
+	defaultTheme: ThemePreference
+): ThemePreference {
+	const shared = getSharedPreference(storage, storageKey);
+	if (shared !== undefined) {
+		return shared;
+	}
+	const raw = readStorage(storage, storageKey);
+	if (isThemePreference(raw)) {
+		return raw;
+	}
+	return defaultTheme;
+}
+
+export function createPreferenceStore(
+	storage: ThemeStorage,
+	storageKey: string,
+	defaultTheme: ThemePreference
+): PreferenceStore {
+	const listeners = new Set<() => void>();
+	const eventName = `mizen-theme:${storageKey}`;
+	const storeId = Symbol("storeId");
+
+	let memoryPreference: ThemePreference = resolveCurrentPreference(
+		storage,
+		storageKey,
+		defaultTheme
+	);
+
+	const notify = () => {
+		for (const listener of listeners) {
+			listener();
+		}
+	};
+
+	const subscribe = (onStoreChange: () => void): (() => void) => {
+		listeners.add(onStoreChange);
+
+		const handleStorage = (event: StorageEvent) => {
+			if (
+				storage !== defaultBrowserStorage ||
+				(event.storageArea !== null &&
+					event.storageArea !== window.localStorage) ||
+				(event.key !== storageKey && event.key !== null)
+			) {
+				return;
+			}
+			const next = isThemePreference(event.newValue)
+				? event.newValue
+				: defaultTheme;
+			setSharedPreference(storage, storageKey, next);
+			memoryPreference = next;
+			onStoreChange();
+		};
+
+		const handleCustomEvent = (event: Event) => {
+			const { detail } = event as CustomEvent<unknown>;
+			if (
+				isCustomPayload(detail) &&
+				detail.sourceId !== storeId &&
+				detail.storage === storage
+			) {
+				setSharedPreference(storage, storageKey, detail.preference);
+				memoryPreference = detail.preference;
+				onStoreChange();
+			}
+		};
+
+		if (typeof window !== "undefined") {
+			window.addEventListener("storage", handleStorage);
+			window.addEventListener(eventName, handleCustomEvent);
+		}
+
+		const latest = resolveCurrentPreference(storage, storageKey, defaultTheme);
+		if (memoryPreference !== latest) {
+			memoryPreference = latest;
+			onStoreChange();
+		}
+
+		return () => {
+			listeners.delete(onStoreChange);
+			if (typeof window !== "undefined") {
+				window.removeEventListener("storage", handleStorage);
+				window.removeEventListener(eventName, handleCustomEvent);
+			}
+		};
+	};
+
+	const getSnapshot = (): ThemePreference => memoryPreference;
+
+	const getServerSnapshot = (): ThemePreference => defaultTheme;
+
+	const setPreference = (next: ThemePreference): void => {
+		memoryPreference = next;
+		setSharedPreference(storage, storageKey, next);
+		writeStorage(storage, storageKey, next);
+		notify();
+		if (typeof window !== "undefined") {
+			window.dispatchEvent(
+				new CustomEvent(eventName, {
+					detail: { preference: next, sourceId: storeId, storage },
+				})
+			);
+		}
+	};
+
+	return {
+		getServerSnapshot,
+		getSnapshot,
+		setPreference,
+		subscribe,
+	};
+}
+
+export function subscribeSystem(callback: () => void): () => void {
+	if (
+		typeof window === "undefined" ||
+		typeof window.matchMedia === "undefined"
+	) {
+		return () => undefined;
+	}
+	const media = window.matchMedia(DARK_MEDIA_QUERY);
+	media.addEventListener("change", callback);
+	return () => media.removeEventListener("change", callback);
+}
+
+export function getSystemSnapshot(): ResolvedTheme {
+	if (
+		typeof window === "undefined" ||
+		typeof window.matchMedia === "undefined"
+	) {
+		return "light";
+	}
+	return window.matchMedia(DARK_MEDIA_QUERY).matches ? "dark" : "light";
+}
+
+export function getServerSystemSnapshot(): ResolvedTheme {
+	return "light";
+}

package/src/theme/theme-tokens.ts

@@ -0,0 +1,11 @@
+import { props } from "@stylexjs/stylex";
+import { darkTheme } from "../styles/themes";
+
+const WHITESPACE_REGEX = /\s+/u;
+
+export function getDarkThemeTokens(): readonly string[] {
+	const result = props(darkTheme);
+	const className =
+		typeof result.className === "string" ? result.className : "";
+	return className.split(WHITESPACE_REGEX).filter(Boolean);
+}

package/src/theme/theme-transition-guard.ts

@@ -0,0 +1,102 @@
+export const THEME_GUARD_STYLE_ID = "mizen-theme-transition-guard";
+
+export const THEME_GUARD_CSS =
+	":root, *, *::before, *::after { transition-property: opacity, transform, translate, scale, rotate !important; }";
+
+let cleanupFrameId: number | null = null;
+let currentGuardElement: HTMLStyleElement | null = null;
+
+function cancelPendingCleanup(): void {
+	if (cleanupFrameId !== null && typeof cancelAnimationFrame === "function") {
+		cancelAnimationFrame(cleanupFrameId);
+		cleanupFrameId = null;
+	}
+}
+
+function removeGuardElement(): void {
+	if (currentGuardElement !== null) {
+		currentGuardElement.remove();
+		currentGuardElement = null;
+		return;
+	}
+	if (typeof document !== "undefined") {
+		const existing = document.querySelector(`#${THEME_GUARD_STYLE_ID}`);
+		if (existing !== null) {
+			existing.remove();
+		}
+	}
+}
+
+function getExistingNonce(): string | null {
+	if (typeof document === "undefined") {
+		return null;
+	}
+	const script = document.querySelector<HTMLScriptElement>("script[nonce]");
+	if (script === null) {
+		return null;
+	}
+	return script.nonce || script.getAttribute("nonce");
+}
+
+function forceStyleCalculation(): void {
+	if (typeof document === "undefined" || !document.documentElement) {
+		return;
+	}
+	const _forced = document.documentElement.offsetHeight;
+}
+
+export function applyThemeTransitionGuard(): void {
+	if (typeof document === "undefined" || !document.head) {
+		return;
+	}
+
+	cancelPendingCleanup();
+
+	let style = currentGuardElement;
+	if (style === null) {
+		const existing = document.querySelector(`#${THEME_GUARD_STYLE_ID}`);
+		if (existing instanceof HTMLStyleElement) {
+			style = existing;
+		}
+	}
+
+	if (style === null) {
+		style = document.createElement("style");
+		style.id = THEME_GUARD_STYLE_ID;
+		const nonce = getExistingNonce();
+		if (nonce !== null && nonce.length > 0) {
+			style.setAttribute("nonce", nonce);
+		}
+		style.textContent = THEME_GUARD_CSS;
+		document.head.appendChild(style);
+	}
+
+	currentGuardElement = style;
+	forceStyleCalculation();
+}
+
+export function finishThemeTransitionGuard(): void {
+	forceStyleCalculation();
+
+	cancelPendingCleanup();
+
+	if (
+		typeof window === "undefined" ||
+		typeof requestAnimationFrame !== "function"
+	) {
+		removeGuardElement();
+		return;
+	}
+
+	cleanupFrameId = requestAnimationFrame(() => {
+		cleanupFrameId = requestAnimationFrame(() => {
+			removeGuardElement();
+			cleanupFrameId = null;
+		});
+	});
+}
+
+export function cleanThemeTransitionGuard(): void {
+	cancelPendingCleanup();
+	removeGuardElement();
+}

package/src/theme/types.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+export interface ThemeStorage {
+	readonly getItem: (key: string) => string | null;
+	readonly setItem: (key: string, value: string) => void;
+}
+
+export interface ThemeContextValue {
+	readonly resolvedTheme: ResolvedTheme;
+	readonly setTheme: (theme: ThemePreference) => void;
+	readonly systemTheme: ResolvedTheme;
+	readonly theme: ThemePreference;
+}
+
+export interface ThemeProviderProps {
+	readonly children?: ReactNode;
+	readonly defaultTheme?: ThemePreference;
+	readonly storage?: ThemeStorage;
+	readonly storageKey?: string;
+}
+
+export interface ThemeScriptProps {
+	readonly defaultTheme?: ThemePreference;
+	readonly nonce?: string;
+	readonly storageKey?: string;
+}
+
+export function isThemePreference(value: unknown): value is ThemePreference {
+	return value === "light" || value === "dark" || value === "system";
+}

package/src/use-copy-to-clipboard.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+
+/** `copied` until the timeout passes; `failed` until the next attempt. */
+export type CopyStatus = "copied" | "failed" | "idle";
+
+export interface UseCopyToClipboardOptions {
+	/** Called with the text after a copy succeeds. */
+	onCopy?: (text: string) => void;
+	/** Milliseconds before `copied` returns to `idle`. 0 keeps it. */
+	timeout?: number;
+}
+
+/**
+ * Copies text to the clipboard and reports how it went, so a button can show
+ * a check and a status region can announce the result. Pass a promise to
+ * copy text that is still loading.
+ */
+export function useCopyToClipboard({
+	onCopy,
+	timeout = 2000,
+}: UseCopyToClipboardOptions = {}) {
+	const [status, setStatus] = useState<CopyStatus>("idle");
+	// Only the latest attempt reports, and a new one cancels the reset.
+	const latest = useRef(0);
+	const reset = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+	const copy = useCallback(
+		async (value: string | Promise<string>) => {
+			latest.current += 1;
+			const attempt = latest.current;
+			clearTimeout(reset.current);
+			let text: string | undefined;
+			try {
+				text = await value;
+				await navigator.clipboard.writeText(text);
+			} catch {
+				text = undefined;
+			}
+			if (attempt !== latest.current) {
+				return text !== undefined;
+			}
+			if (text === undefined) {
+				setStatus("failed");
+				return false;
+			}
+			setStatus("copied");
+			onCopy?.(text);
+			if (timeout > 0) {
+				reset.current = setTimeout(() => setStatus("idle"), timeout);
+			}
+			return true;
+		},
+		[onCopy, timeout]
+	);
+	return { copy, status };
+}

package/src/use-elapsed.ts

@@ -0,0 +1,40 @@
+import { useCallback, useRef, useState } from "react";
+
+// Measures how long work took from the DOM, never during render: the element
+// shown while working marks the start when it mounts, and the one shown once
+// settled marks the end when it replaces it.
+export function useElapsed() {
+	const start = useRef<number | undefined>(undefined);
+	const [seconds, setSeconds] = useState<number>();
+	const markStart = useCallback((node: HTMLElement | null) => {
+		if (node && start.current === undefined) {
+			start.current = performance.now();
+		}
+	}, []);
+	const markEnd = useCallback((node: HTMLElement | null) => {
+		if (node && start.current !== undefined) {
+			const elapsed = (performance.now() - start.current) / 1000;
+			start.current = undefined;
+			setSeconds(elapsed);
+		}
+	}, []);
+	return { markEnd, markStart, seconds };
+}
+
+/** Whole seconds: "7s", or "1m 35s" past a minute. */
+export function formatSeconds(seconds: number) {
+	const total = Math.max(1, Math.round(seconds));
+	const minutes = Math.floor(total / 60);
+	const rest = total % 60;
+	if (minutes === 0) {
+		return `${rest}s`;
+	}
+	return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+}
+
+/** Tenths under ten seconds, for quick work such as tool calls: "0.4s". */
+export function formatShortSeconds(seconds: number) {
+	return seconds < 10
+		? `${Math.max(0.1, Math.round(seconds * 10) / 10)}s`
+		: formatSeconds(seconds);
+}