@mizen-labs/ui 0.0.0-stage → 0.1.0

package/src/styles/typography.styles.ts

@@ -0,0 +1,116 @@
+import { create } from "@stylexjs/stylex";
+import { colors } from "./colors.stylex";
+import { conditions } from "./conditions.stylex";
+import { fonts } from "./fonts.stylex";
+import {
+	fontSize,
+	fontWeight,
+	letterSpacing,
+	lineHeight,
+} from "./typography.stylex";
+
+// Trims a control label's box to its cap height so text centers optically
+// next to icons.
+export const typographyStyles = create({
+	controlLabel: {
+		minWidth: 0,
+		// eslint-disable-next-line @stylexjs/valid-styles -- StyleX 0.19 CSS metadata predates text-box; compilation and browser metrics cover it.
+		textBox: "trim-both cap alphabetic",
+	},
+	tabularNums: { fontVariantNumeric: "tabular-nums" },
+});
+
+// Type roles (design direction, "Type roles and spacing rhythm"). Each
+// role fixes size, absolute line height, weight, and tracking, and normalizes
+// x-height through fonts.sizeAdjust. Roles inherit ink so they work inside
+// filled controls; caption defaults to muted. Pair `ui` with muted ink for
+// supporting text.
+export const typeRoles = create({
+	body: {
+		fontSize: fontSize["16"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.regular,
+		letterSpacing: letterSpacing.normal,
+		lineHeight: lineHeight["24"],
+		textWrap: "pretty",
+	},
+	caption: {
+		color: colors.mutedContent,
+		fontSize: fontSize["12"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.regular,
+		letterSpacing: letterSpacing.caption,
+		lineHeight: lineHeight["16"],
+	},
+	display: {
+		fontSize: { [conditions.sm]: fontSize["40"], default: fontSize["32"] },
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.semibold,
+		letterSpacing: letterSpacing.display,
+		lineHeight: {
+			[conditions.sm]: lineHeight["44"],
+			default: lineHeight["36"],
+		},
+		textWrap: "balance",
+	},
+	heading: {
+		fontSize: fontSize["20"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.semibold,
+		letterSpacing: letterSpacing.heading,
+		lineHeight: lineHeight["28"],
+		textWrap: "balance",
+	},
+	label: {
+		fontSize: fontSize["14"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.medium,
+		letterSpacing: letterSpacing.normal,
+		lineHeight: lineHeight["20"],
+	},
+	mono: {
+		fontFamily: fonts.mono,
+		fontSize: fontSize["13"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.regular,
+		letterSpacing: letterSpacing.normal,
+		lineHeight: lineHeight["20"],
+	},
+	// Narrow screens step down so values and units stay on one line. Medium
+	// weight keeps large figures crisp rather than heavy.
+	numeric: {
+		fontSize: { [conditions.sm]: fontSize["28"], default: fontSize["20"] },
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontVariantNumeric: "tabular-nums",
+		fontWeight: fontWeight.medium,
+		letterSpacing: letterSpacing.title,
+		lineHeight: {
+			[conditions.sm]: lineHeight["32"],
+			default: lineHeight["28"],
+		},
+	},
+	subheading: {
+		fontSize: fontSize["16"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.semibold,
+		letterSpacing: letterSpacing.subheading,
+		lineHeight: lineHeight["24"],
+		textWrap: "balance",
+	},
+	title: {
+		fontSize: fontSize["28"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.semibold,
+		letterSpacing: letterSpacing.title,
+		lineHeight: lineHeight["32"],
+		textWrap: "balance",
+	},
+	ui: {
+		fontSize: fontSize["14"],
+		fontSizeAdjust: fonts.sizeAdjust,
+		fontWeight: fontWeight.regular,
+		letterSpacing: letterSpacing.normal,
+		lineHeight: lineHeight["20"],
+		textWrap: "pretty",
+	},
+});

package/src/styles/typography.stylex.ts

@@ -0,0 +1,44 @@
+import { defineConsts } from "@stylexjs/stylex";
+
+export const fontSize = defineConsts({
+	"12": "0.75rem",
+	"13": "0.8125rem",
+	"14": "0.875rem",
+	"16": "1rem",
+	"20": "1.25rem",
+	"28": "1.75rem",
+	"32": "2rem",
+	"40": "2.5rem",
+});
+
+export const fontWeight = defineConsts({
+	bold: 700,
+	medium: 500,
+	regular: 400,
+	semibold: 600,
+});
+
+// Absolute line heights keep every role on the 4px grid, independent of font
+// metrics. Keys name the pixel height at a 16px root; `none` is for single-line
+// boxes such as badges and glyph wrappers.
+export const lineHeight = defineConsts({
+	"16": "1rem",
+	"20": "1.25rem",
+	"24": "1.5rem",
+	"28": "1.75rem",
+	"32": "2rem",
+	"36": "2.25rem",
+	"44": "2.75rem",
+	none: 1,
+});
+
+// Role tracking follows one size curve in em, small enough for any family.
+export const letterSpacing = defineConsts({
+	caption: "0.01em",
+	display: "-0.025em",
+	heading: "-0.012em",
+	normal: "0",
+	subheading: "-0.006em",
+	title: "-0.02em",
+	wide: "0.02em",
+});

package/src/theme/index.ts

@@ -0,0 +1,25 @@
+import { initializeTheme as initialize } from "./initialize";
+import {
+	ThemeProvider as Provider,
+	useTheme as useThemeHook,
+} from "./theme-provider";
+import { ThemeScript as Script } from "./theme-script";
+import { isThemePreference as isPref } from "./types";
+
+export type { ThemeInitializationOptions } from "./initialize";
+
+export type {
+	ResolvedTheme,
+	ThemeContextValue,
+	ThemePreference,
+	ThemeProviderProps,
+	ThemeScriptProps,
+	ThemeStorage,
+} from "./types";
+
+export const isThemePreference = isPref;
+export const ThemeProvider = Provider;
+export const useTheme = useThemeHook;
+export const ThemeScript = Script;
+
+export const initializeTheme = initialize;

package/src/theme/initialize.ts

@@ -0,0 +1,31 @@
+import { applyRootTheme } from "./theme-root";
+import {
+	DEFAULT_STORAGE_KEY,
+	DEFAULT_THEME_PREFERENCE,
+	defaultBrowserStorage,
+	getSystemSnapshot,
+	readStorage,
+} from "./theme-storage";
+import {
+	isThemePreference,
+	type ResolvedTheme,
+	type ThemeProviderProps,
+} from "./types";
+
+export type ThemeInitializationOptions = Omit<ThemeProviderProps, "children">;
+
+/** Apply the initial client theme before createRoot renders. ThemeProvider owns later updates. */
+export function initializeTheme({
+	storageKey = DEFAULT_STORAGE_KEY,
+	defaultTheme = DEFAULT_THEME_PREFERENCE,
+	storage = defaultBrowserStorage,
+}: ThemeInitializationOptions = {}): ResolvedTheme | null {
+	if (typeof window === "undefined" || typeof document === "undefined") {
+		return null;
+	}
+	const saved = readStorage(storage, storageKey);
+	const preference = isThemePreference(saved) ? saved : defaultTheme;
+	const resolved = preference === "system" ? getSystemSnapshot() : preference;
+	applyRootTheme(resolved);
+	return resolved;
+}

package/src/theme/theme-provider.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useMemo,
+	useState,
+	useSyncExternalStore,
+} from "react";
+import { applyRootTheme } from "./theme-root";
+import {
+	createPreferenceStore,
+	DEFAULT_STORAGE_KEY,
+	DEFAULT_THEME_PREFERENCE,
+	defaultBrowserStorage,
+	getServerSystemSnapshot,
+	getSystemSnapshot,
+	subscribeSystem,
+} from "./theme-storage";
+import { getDarkThemeTokens } from "./theme-tokens";
+import { cleanThemeTransitionGuard } from "./theme-transition-guard";
+import type {
+	ResolvedTheme,
+	ThemeContextValue,
+	ThemePreference,
+	ThemeProviderProps,
+} from "./types";
+
+interface RootSnapshot {
+	readonly colorScheme: string;
+	readonly dataTheme: string | null;
+	readonly initialDarkTokens: ReadonlySet<string>;
+}
+
+interface ActiveProvider {
+	readonly id: symbol;
+	readonly theme: ResolvedTheme;
+}
+
+let activeProviders: ActiveProvider[] = [];
+let rootSnapshot: RootSnapshot | null = null;
+
+function captureRootSnapshot(): RootSnapshot {
+	const root = document.documentElement;
+	const darkTokens = getDarkThemeTokens();
+	const initialDarkTokens = new Set<string>();
+	for (const token of darkTokens) {
+		if (root.classList.contains(token)) {
+			initialDarkTokens.add(token);
+		}
+	}
+	return {
+		colorScheme: root.style.colorScheme,
+		dataTheme: root.getAttribute("data-theme"),
+		initialDarkTokens,
+	};
+}
+
+function restoreRootSnapshot(snapshot: RootSnapshot): void {
+	const root = document.documentElement;
+	if (snapshot.dataTheme === null) {
+		root.removeAttribute("data-theme");
+	} else {
+		root.setAttribute("data-theme", snapshot.dataTheme);
+	}
+	root.style.colorScheme = snapshot.colorScheme;
+	const darkTokens = getDarkThemeTokens();
+	for (const token of darkTokens) {
+		if (snapshot.initialDarkTokens.has(token)) {
+			root.classList.add(token);
+		} else {
+			root.classList.remove(token);
+		}
+	}
+}
+
+function registerOrUpdateProvider(id: symbol, theme: ResolvedTheme): void {
+	if (activeProviders.length === 0) {
+		rootSnapshot = captureRootSnapshot();
+	}
+	activeProviders = activeProviders.filter((entry) => entry.id !== id);
+	activeProviders.push({ id, theme });
+	applyRootTheme(theme);
+}
+
+function unregisterProvider(id: symbol): void {
+	activeProviders = activeProviders.filter((entry) => entry.id !== id);
+	if (activeProviders.length === 0) {
+		if (rootSnapshot !== null) {
+			restoreRootSnapshot(rootSnapshot);
+			rootSnapshot = null;
+		}
+		cleanThemeTransitionGuard();
+		return;
+	}
+	const latest = activeProviders.at(-1);
+	if (latest) {
+		applyRootTheme(latest.theme);
+	}
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({
+	children,
+	defaultTheme = DEFAULT_THEME_PREFERENCE,
+	storageKey = DEFAULT_STORAGE_KEY,
+	storage,
+}: ThemeProviderProps) {
+	const effectiveStorage = storage ?? defaultBrowserStorage;
+	const [providerId] = useState(() => Symbol("ThemeProvider"));
+
+	const store = useMemo(
+		() => createPreferenceStore(effectiveStorage, storageKey, defaultTheme),
+		[effectiveStorage, storageKey, defaultTheme]
+	);
+
+	// <html> follows the store and the system query inside their own
+	// subscriptions, so a change lands before React re-renders. Unsubscribing
+	// hands the root back to the next provider, or restores it.
+	const subscribeRoot = useCallback(
+		(onStoreChange: () => void) => {
+			const apply = () => {
+				const preference = store.getSnapshot();
+				registerOrUpdateProvider(
+					providerId,
+					preference === "system" ? getSystemSnapshot() : preference
+				);
+			};
+			const onChange = () => {
+				apply();
+				onStoreChange();
+			};
+			apply();
+			const stopStore = store.subscribe(onChange);
+			const stopSystem = subscribeSystem(onChange);
+			return () => {
+				stopStore();
+				stopSystem();
+				unregisterProvider(providerId);
+			};
+		},
+		[providerId, store]
+	);
+
+	const theme = useSyncExternalStore(
+		subscribeRoot,
+		store.getSnapshot,
+		store.getServerSnapshot
+	);
+
+	const systemTheme = useSyncExternalStore(
+		subscribeSystem,
+		getSystemSnapshot,
+		getServerSystemSnapshot
+	);
+
+	const resolvedTheme: ResolvedTheme = theme === "system" ? systemTheme : theme;
+
+	const setTheme = useCallback(
+		(next: ThemePreference) => {
+			store.setPreference(next);
+		},
+		[store]
+	);
+
+	const value = useMemo<ThemeContextValue>(
+		() => ({
+			resolvedTheme,
+			setTheme,
+			systemTheme,
+			theme,
+		}),
+		[resolvedTheme, setTheme, systemTheme, theme]
+	);
+
+	return (
+		<ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+	);
+}
+
+export function useTheme(): ThemeContextValue {
+	const context = useContext(ThemeContext);
+	if (context === null) {
+		throw new Error("useTheme must be used within a ThemeProvider");
+	}
+	return context;
+}

package/src/theme/theme-root.ts

@@ -0,0 +1,37 @@
+import { getDarkThemeTokens } from "./theme-tokens";
+import {
+	applyThemeTransitionGuard,
+	finishThemeTransitionGuard,
+} from "./theme-transition-guard";
+import type { ResolvedTheme } from "./types";
+
+export function applyRootTheme(theme: ResolvedTheme): void {
+	const root = document.documentElement;
+	const currentTheme = root.getAttribute("data-theme");
+	const isThemeChange =
+		(currentTheme === "light" && theme === "dark") ||
+		(currentTheme === "dark" && theme === "light");
+
+	if (isThemeChange) {
+		applyThemeTransitionGuard();
+	}
+
+	if (root.getAttribute("data-theme") !== theme) {
+		root.setAttribute("data-theme", theme);
+	}
+	if (root.style.colorScheme !== theme) {
+		root.style.colorScheme = theme;
+	}
+	const darkTokens = getDarkThemeTokens();
+	if (darkTokens.length > 0) {
+		if (theme === "dark") {
+			root.classList.add(...darkTokens);
+		} else {
+			root.classList.remove(...darkTokens);
+		}
+	}
+
+	if (isThemeChange) {
+		finishThemeTransitionGuard();
+	}
+}

package/src/theme/theme-script.tsx

@@ -0,0 +1,35 @@
+import type { JSX } from "react";
+import { DEFAULT_STORAGE_KEY, DEFAULT_THEME_PREFERENCE } from "./theme-storage";
+import { getDarkThemeTokens } from "./theme-tokens";
+import type { ThemePreference, ThemeScriptProps } from "./types";
+
+function safeJson(value: unknown): string {
+	return JSON.stringify(value).replace(/</gu, "\\u003c");
+}
+
+function buildThemeScript(
+	storageKey: string,
+	defaultTheme: ThemePreference,
+	darkClasses: readonly string[]
+): string {
+	const k = safeJson(storageKey);
+	const d = safeJson(defaultTheme);
+	const c = safeJson(darkClasses);
+
+	return `(function(){try{var k=${k};var d=${d};var c=${c};var p=null;try{p=localStorage.getItem(k)}catch(e){}var t=(p==="light"||p==="dark"||p==="system")?p:d;var m=window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches;var isDark=t==="dark"||(t==="system"&&m);var r=isDark?"dark":"light";var el=document.documentElement;el.setAttribute("data-theme",r);el.style.colorScheme=r;if(isDark){for(var i=0;i<c.length;i++){if(c[i])el.classList.add(c[i])}}else{for(var i=0;i<c.length;i++){if(c[i])el.classList.remove(c[i])}}}catch(e){}})()`;
+}
+
+export function ThemeScript({
+	defaultTheme = DEFAULT_THEME_PREFERENCE,
+	nonce,
+	storageKey = DEFAULT_STORAGE_KEY,
+}: ThemeScriptProps): JSX.Element {
+	const darkClasses = getDarkThemeTokens();
+	const scriptCode = buildThemeScript(storageKey, defaultTheme, darkClasses);
+
+	return (
+		<script nonce={nonce} suppressHydrationWarning>
+			{scriptCode}
+		</script>
+	);
+}