@badnpm/ui 0.0.0-stage → 0.0.0

package/dist/cjs/providers/theme-provider.cjs

@@ -0,0 +1,181 @@
+"use client";
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var useHydrated = require('../hooks/use-hydrated.cjs');
+
+const COLOR_SCHEME_QUERY = '(prefers-color-scheme: dark)';
+const ThemeProviderContext = react.createContext(undefined);
+// 校验存储值，同时将类型收窄为合法的主题选项。
+function isTheme(value) {
+    return value === 'dark' || value === 'light' || value === 'system';
+}
+// 优先读取已保存的主题；值无效或存储不可用时使用默认主题。
+function readTheme(storageKey, fallback) {
+    try {
+        const value = localStorage.getItem(storageKey);
+        return isTheme(value) ? value : fallback;
+    }
+    catch {
+        // 存储不可用时回退到默认主题，不影响组件初始化。
+        return fallback;
+    }
+}
+// 持久化用户选择，存储失败时仍允许更新页面主题。
+function persistTheme(storageKey, theme) {
+    try {
+        localStorage.setItem(storageKey, theme);
+    }
+    catch {
+        // 忽略存储异常，主题仍可在当前页面内切换。
+    }
+}
+// 将用户选择解析为实际配色；system 每次读取当前系统偏好。
+function resolveTheme(theme) {
+    if (theme !== 'system') {
+        return theme;
+    }
+    return window.matchMedia(COLOR_SCHEME_QUERY).matches ? 'dark' : 'light';
+}
+// 更新根元素的主题类名，并返回清理临时样式及动画帧的函数。
+function applyTheme(theme, disableTransitionOnChange) {
+    const root = document.documentElement;
+    const resolvedTheme = resolveTheme(theme);
+    // 主题已生效且没有冲突类名时，跳过重复的 DOM 操作。
+    if (root.classList.contains(resolvedTheme) && !root.classList.contains(resolvedTheme === 'dark' ? 'light' : 'dark')) {
+        return () => { };
+    }
+    const style = disableTransitionOnChange ? document.createElement('style') : null;
+    if (style) {
+        style.textContent = '*,*::before,*::after{transition:none!important}';
+        document.head.appendChild(style);
+        // 强制浏览器计算样式，确保禁用过渡的规则先于主题切换生效。
+        window.getComputedStyle(root).getPropertyValue('transition-property');
+    }
+    root.classList.remove('light', 'dark');
+    root.classList.add(resolvedTheme);
+    if (!style) {
+        return () => { };
+    }
+    // 在禁用过渡期间计算新主题样式，再通过两次动画帧延迟移除规则。
+    window.getComputedStyle(root).getPropertyValue('color');
+    let frame = requestAnimationFrame(() => {
+        frame = requestAnimationFrame(() => style.remove());
+    });
+    // 重新应用主题或卸载时，取消待执行的帧并移除临时样式。
+    return () => {
+        cancelAnimationFrame(frame);
+        style.remove();
+    };
+}
+// 判断事件是否来自可编辑区域，避免主题快捷键干扰输入。
+function isEditableTarget(target) {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    if (target.isContentEditable) {
+        return true;
+    }
+    return target.closest('input, textarea, select') !== null;
+}
+// 统一管理主题状态、页面样式及系统和跨标签页同步。
+function ThemeProvider({ children, defaultTheme = 'system', storageKey = 'bad-ui:theme', disableTransitionOnChange = true, keyboardShortcut, }) {
+    const hydrated = useHydrated.useHydrated();
+    const [storedTheme, setThemeState] = react.useState(() => readTheme(storageKey, defaultTheme));
+    // 水合首帧与服务端一致，完成后才使用浏览器保存的主题。
+    const theme = hydrated ? storedTheme : defaultTheme;
+    // 所有主动切换共用此入口，统一更新存储和 React 状态。
+    const setTheme = react.useCallback((nextTheme) => {
+        persistTheme(storageKey, nextTheme);
+        setThemeState(nextTheme);
+    }, [storageKey]);
+    // 按需解析系统配色，按钮和快捷键共用同一切换逻辑。
+    const toggleTheme = react.useCallback(() => {
+        setTheme(resolveTheme(theme) === 'dark' ? 'light' : 'dark');
+    }, [theme, setTheme]);
+    // 水合完成后应用主题；服务端与水合首帧不访问系统配色或修改根元素。
+    react.useLayoutEffect(() => {
+        if (!hydrated)
+            return;
+        let cleanup = applyTheme(theme, disableTransitionOnChange);
+        const mediaQuery = window.matchMedia(COLOR_SCHEME_QUERY);
+        const handleChange = () => {
+            cleanup();
+            cleanup = applyTheme(theme, disableTransitionOnChange);
+        };
+        // 仅跟随系统时订阅配色变化；显式选择深浅色后不再跟随。
+        if (theme === 'system') {
+            mediaQuery.addEventListener('change', handleChange);
+        }
+        return () => {
+            mediaQuery.removeEventListener('change', handleChange);
+            cleanup();
+        };
+    }, [theme, disableTransitionOnChange, hydrated]);
+    react.useEffect(() => {
+        if (!hydrated || !keyboardShortcut)
+            return;
+        const shortcutKey = keyboardShortcut.toLowerCase();
+        // 忽略已处理事件、输入法组合和长按重复。
+        const handleKeyDown = (event) => {
+            if (event.defaultPrevented || event.isComposing || event.repeat) {
+                return;
+            }
+            if (event.metaKey || event.ctrlKey || event.altKey) {
+                return;
+            }
+            if (isEditableTarget(event.target)) {
+                return;
+            }
+            if (event.key.toLowerCase() !== shortcutKey) {
+                return;
+            }
+            toggleTheme();
+        };
+        window.addEventListener('keydown', handleKeyDown);
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [toggleTheme, hydrated, keyboardShortcut]);
+    react.useEffect(() => {
+        // storage 事件用于接收同源其他标签页的主题变更。
+        const handleStorageChange = (event) => {
+            if (event.storageArea !== localStorage) {
+                return;
+            }
+            // clear() 触发的事件 key 为 null，也需要回退到默认主题。
+            if (event.key !== null && event.key !== storageKey) {
+                return;
+            }
+            if (isTheme(event.newValue)) {
+                setThemeState(event.newValue);
+                return;
+            }
+            // 存储项被移除、清空或写入无效值时，恢复默认主题。
+            setThemeState(defaultTheme);
+        };
+        window.addEventListener('storage', handleStorageChange);
+        return () => {
+            window.removeEventListener('storage', handleStorageChange);
+        };
+    }, [defaultTheme, storageKey]);
+    // 保持上下文值的引用稳定，避免父组件重渲染引起无关更新。
+    const value = react.useMemo(() => ({
+        theme,
+        setTheme,
+        toggleTheme,
+    }), [theme, setTheme, toggleTheme]);
+    return jsxRuntime.jsx(ThemeProviderContext.Provider, { value: value, children: children });
+}
+// 获取主题上下文，并在缺少 Provider 时给出明确错误。
+const useTheme = () => {
+    const context = react.useContext(ThemeProviderContext);
+    if (context === undefined) {
+        throw new Error('useTheme must be used within a ThemeProvider');
+    }
+    return context;
+};
+
+exports.ThemeProvider = ThemeProvider;
+exports.useTheme = useTheme;

package/dist/cjs/types/components/button.d.ts

@@ -0,0 +1,12 @@
+import * as react from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { Button as Button$1 } from '@base-ui/react/button';
+import { VariantProps } from 'class-variance-authority';
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, ...props }: Button$1.Props & VariantProps<typeof buttonVariants>): react.JSX.Element;
+
+export { Button, buttonVariants };

package/dist/cjs/types/components/index.d.ts

@@ -0,0 +1,3 @@
+export { Button, buttonVariants } from './button.js';
+export { Input } from './input.js';
+export { ThemeToggle, ThemeToggleProps } from './theme-toggle.js';

package/dist/cjs/types/components/input.d.ts

@@ -0,0 +1,5 @@
+import * as react from 'react';
+
+declare function Input({ className, type, ...props }: react.ComponentProps<"input">): react.JSX.Element;
+
+export { Input };

package/dist/cjs/types/components/theme-toggle.d.ts

@@ -0,0 +1,14 @@
+import * as react from 'react';
+import { ComponentProps } from 'react';
+import { Button } from './button.js';
+
+type ThemeToggleProps = Omit<ComponentProps<typeof Button>, 'children'> & {
+    /** 切换到深色模式的无障碍文案，默认为“切换到深色主题”。 */
+    darkLabel?: string;
+    /** 切换到浅色模式的无障碍文案，默认为“切换到浅色主题”。 */
+    lightLabel?: string;
+};
+declare function ThemeToggle({ darkLabel, lightLabel, variant, size, title, onClick, ...props }: ThemeToggleProps): react.JSX.Element;
+
+export { ThemeToggle };
+export type { ThemeToggleProps };

package/dist/cjs/types/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useHydrated } from './use-hydrated.js';

package/dist/cjs/types/hooks/use-hydrated.d.ts

@@ -0,0 +1,4 @@
+/** 服务端及客户端水合首帧返回 false，之后返回 true；纯客户端渲染直接返回 true。 */
+declare function useHydrated(): boolean;
+
+export { useHydrated };

package/dist/cjs/types/index.d.ts

@@ -0,0 +1,8 @@
+export { Button, buttonVariants } from './components/button.js';
+export { Input } from './components/input.js';
+export { ThemeToggle, ThemeToggleProps } from './components/theme-toggle.js';
+export { PreferenceProvider, usePreference } from './providers/preference-provider.js';
+export { ThemeProvider, useTheme } from './providers/theme-provider.js';
+export { useHydrated } from './hooks/use-hydrated.js';
+export { BASE_COLORS, BaseColor, COLOR_THEMES, ColorTheme, DEFAULT_PREFERENCE, Preference, RADIUS_OPTIONS } from './lib/preference.js';
+export { cn } from 'cn';

package/dist/cjs/types/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { BASE_COLORS, BaseColor, COLOR_THEMES, ColorTheme, DEFAULT_PREFERENCE, Preference, RADIUS_OPTIONS } from './preference.js';
+export { cn } from 'cn';

package/dist/cjs/types/lib/preference.d.ts

@@ -0,0 +1,85 @@
+declare const BASE_COLORS: readonly [{
+    readonly value: "neutral";
+    readonly label: "Neutral";
+    readonly color: "oklch(0.556 0 0)";
+}, {
+    readonly value: "mist";
+    readonly label: "Mist";
+    readonly color: "oklch(0.56 0.021 213.5)";
+}, {
+    readonly value: "zinc";
+    readonly label: "Zinc";
+    readonly color: "oklch(0.552 0.016 285.938)";
+}];
+declare const COLOR_THEMES: readonly [{
+    readonly value: "neutral";
+    readonly label: "Neutral";
+    readonly color: "oklch(0.205 0 0)";
+}, {
+    readonly value: "blue";
+    readonly label: "Blue";
+    readonly color: "oklch(0.488 0.243 264.376)";
+}, {
+    readonly value: "green";
+    readonly label: "Green";
+    readonly color: "oklch(0.527 0.154 150.069)";
+}, {
+    readonly value: "orange";
+    readonly label: "Orange";
+    readonly color: "oklch(0.553 0.195 38.402)";
+}, {
+    readonly value: "pink";
+    readonly label: "Pink";
+    readonly color: "oklch(0.525 0.223 3.958)";
+}, {
+    readonly value: "purple";
+    readonly label: "Purple";
+    readonly color: "oklch(0.496 0.265 301.924)";
+}, {
+    readonly value: "red";
+    readonly label: "Red";
+    readonly color: "oklch(0.505 0.213 27.518)";
+}, {
+    readonly value: "rose";
+    readonly label: "Rose";
+    readonly color: "oklch(0.514 0.222 16.935)";
+}, {
+    readonly value: "sky";
+    readonly label: "Sky";
+    readonly color: "oklch(0.5 0.134 242.749)";
+}, {
+    readonly value: "yellow";
+    readonly label: "Yellow";
+    readonly color: "oklch(0.852 0.199 91.936)";
+}];
+declare const RADIUS_OPTIONS: readonly [{
+    readonly value: 0;
+    readonly label: "0";
+}, {
+    readonly value: 0.25;
+    readonly label: "0.25";
+}, {
+    readonly value: 0.5;
+    readonly label: "0.5";
+}, {
+    readonly value: 0.625;
+    readonly label: "Default";
+}, {
+    readonly value: 0.75;
+    readonly label: "0.75";
+}, {
+    readonly value: 1;
+    readonly label: "1";
+}];
+type BaseColor = (typeof BASE_COLORS)[number]['value'];
+type ColorTheme = (typeof COLOR_THEMES)[number]['value'];
+type Preference = {
+    baseColor: BaseColor;
+    theme: ColorTheme;
+    /** 根字号单位 rem；0 表示直角，默认 0.625。 */
+    radius: number;
+};
+declare const DEFAULT_PREFERENCE: Preference;
+
+export { BASE_COLORS, COLOR_THEMES, DEFAULT_PREFERENCE, RADIUS_OPTIONS };
+export type { BaseColor, ColorTheme, Preference };

package/dist/cjs/types/lib/utils.d.ts

@@ -0,0 +1 @@
+export { cn } from 'cn';

package/dist/cjs/types/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types/providers/index.d.ts

@@ -0,0 +1,2 @@
+export { PreferenceProvider, usePreference } from './preference-provider.js';
+export { ThemeProvider, useTheme } from './theme-provider.js';

package/dist/cjs/types/providers/preference-provider.d.ts

@@ -0,0 +1,20 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Preference, BaseColor, ColorTheme } from '../lib/preference.js';
+
+type PreferenceProviderProps = {
+    children: ReactNode;
+    /** 可只覆盖部分默认值；已有的有效存储值优先。 */
+    defaultPreference?: Partial<Preference>;
+    /** 三项偏好共用的 localStorage 键，默认为 'bad-ui:preference'。 */
+    storageKey?: string;
+};
+type PreferenceContextValue = Preference & {
+    setBaseColor: (baseColor: BaseColor) => void;
+    setTheme: (theme: ColorTheme) => void;
+    setRadius: (radius: number) => void;
+};
+declare function PreferenceProvider({ children, defaultPreference, storageKey, }: PreferenceProviderProps): react.JSX.Element;
+declare function usePreference(): PreferenceContextValue;
+
+export { PreferenceProvider, usePreference };

package/dist/cjs/types/providers/theme-provider.d.ts

@@ -0,0 +1,25 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type Theme = 'dark' | 'light' | 'system';
+type ThemeProviderProps = {
+    children: ReactNode;
+    /** 没有有效的已保存主题时使用的模式，默认为 'system'（跟随系统配色）。 */
+    defaultTheme?: Theme;
+    /** 在 localStorage 中保存主题选择的键名，默认为 'bad-ui:theme'。 */
+    storageKey?: string;
+    /** 切换主题时是否短暂禁用全页 CSS transition，让新配色立即生效。默认为 true。 */
+    disableTransitionOnChange?: boolean;
+    /** 切换深浅主题的全局单键快捷键，使用 KeyboardEvent.key（如 'd' 或 'F8'），忽略大小写。省略时关闭。 */
+    keyboardShortcut?: string;
+};
+type ThemeProviderState = {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+    /** 根据当前实际配色切换深浅模式，切换后停止跟随系统。 */
+    toggleTheme: () => void;
+};
+declare function ThemeProvider({ children, defaultTheme, storageKey, disableTransitionOnChange, keyboardShortcut, }: ThemeProviderProps): react.JSX.Element;
+declare const useTheme: () => ThemeProviderState;
+
+export { ThemeProvider, useTheme };

package/dist/esm/components/button.js

@@ -0,0 +1,38 @@
+import { jsx } from 'react/jsx-runtime';
+import { Button as Button$1 } from '@base-ui/react/button';
+import { cva } from 'class-variance-authority';
+import { cn } from 'cn';
+
+const buttonVariants = cva("group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: 'bg-primary text-primary-foreground hover:bg-primary/80',
+            outline: 'border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
+            secondary: 'bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground',
+            ghost: 'hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50',
+            destructive: 'bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40',
+            link: 'text-primary underline-offset-4 hover:underline',
+        },
+        size: {
+            default: 'h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+            xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+            sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+            lg: 'h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+            icon: 'size-8',
+            'icon-xs': "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+            'icon-sm': 'size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg',
+            'icon-lg': 'size-9',
+        },
+    },
+    defaultVariants: {
+        variant: 'default',
+        size: 'default',
+    },
+});
+function Button({ className, variant = 'default', size = 'default', ...props }) {
+    return (jsx(Button$1, { "data-slot": "button", className: typeof className === 'function'
+            ? (state) => cn(buttonVariants({ variant, size }), className(state))
+            : cn(buttonVariants({ variant, size }), className), ...props }));
+}
+
+export { Button, buttonVariants };

package/dist/esm/components/input.js

@@ -0,0 +1,9 @@
+import { jsx } from 'react/jsx-runtime';
+import { Input as Input$1 } from '@base-ui/react/input';
+import { cn } from 'cn';
+
+function Input({ className, type, ...props }) {
+    return (jsx(Input$1, { type: type, "data-slot": "input", className: cn("h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40", className), ...props }));
+}
+
+export { Input };

package/dist/esm/components/theme-toggle.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { MoonIcon, SunIcon } from 'lucide-react';
+import { Button } from './button.js';
+import { useTheme } from '../providers/theme-provider.js';
+
+function ThemeToggle({ darkLabel = '切换到深色主题', lightLabel = '切换到浅色主题', variant = 'outline', size = 'icon', title = '切换主题', onClick, ...props }) {
+    const { toggleTheme } = useTheme();
+    return (jsxs(Button, { type: "button", variant: variant, size: size, title: title, ...props, onClick: (event) => {
+            // 先执行使用方回调，允许通过 preventDefault() 取消主题切换。
+            onClick?.(event);
+            if (!event.defaultPrevented)
+                toggleTheme();
+        }, children: [jsx(MoonIcon, { "data-icon": "inline-start", "aria-hidden": "true", className: "animate-in duration-200 ease-out zoom-in-75 fade-in spin-in-90 motion-reduce:animate-none dark:hidden" }), jsx(SunIcon, { "data-icon": "inline-start", "aria-hidden": "true", className: "hidden animate-in duration-200 ease-out zoom-in-75 fade-in spin-in-90 motion-reduce:animate-none dark:block" }), jsx("span", { className: "sr-only dark:hidden", children: darkLabel }), jsx("span", { className: "sr-only hidden dark:block", children: lightLabel })] }));
+}
+
+export { ThemeToggle };

package/dist/esm/hooks/use-hydrated.js

@@ -0,0 +1,13 @@
+"use client";
+import { useSyncExternalStore } from 'react';
+
+// 水合完成与否由 React 的服务端快照机制区分，无需 effect 中同步设置状态。
+const subscribe = () => () => { };
+const getSnapshot = () => true;
+const getServerSnapshot = () => false;
+/** 服务端及客户端水合首帧返回 false，之后返回 true；纯客户端渲染直接返回 true。 */
+function useHydrated() {
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+export { useHydrated };

package/dist/esm/index.js

@@ -0,0 +1,8 @@
+export { Button, buttonVariants } from './components/button.js';
+export { Input } from './components/input.js';
+export { ThemeToggle } from './components/theme-toggle.js';
+export { PreferenceProvider, usePreference } from './providers/preference-provider.js';
+export { ThemeProvider, useTheme } from './providers/theme-provider.js';
+export { useHydrated } from './hooks/use-hydrated.js';
+export { BASE_COLORS, COLOR_THEMES, DEFAULT_PREFERENCE, RADIUS_OPTIONS } from './lib/preference.js';
+export { cn } from 'cn';

package/dist/esm/lib/preference.js

@@ -0,0 +1,35 @@
+// color 用于选项色块预览：基础色取浅色模式的 muted-foreground，主题色取 primary。
+const BASE_COLORS = [
+    { value: 'neutral', label: 'Neutral', color: 'oklch(0.556 0 0)' },
+    { value: 'mist', label: 'Mist', color: 'oklch(0.56 0.021 213.5)' },
+    { value: 'zinc', label: 'Zinc', color: 'oklch(0.552 0.016 285.938)' },
+];
+// value 对应 CSS 的 data-theme 属性，label 用于展示，color 是固定的预览色。
+const COLOR_THEMES = [
+    { value: 'neutral', label: 'Neutral', color: 'oklch(0.205 0 0)' },
+    { value: 'blue', label: 'Blue', color: 'oklch(0.488 0.243 264.376)' },
+    { value: 'green', label: 'Green', color: 'oklch(0.527 0.154 150.069)' },
+    { value: 'orange', label: 'Orange', color: 'oklch(0.553 0.195 38.402)' },
+    { value: 'pink', label: 'Pink', color: 'oklch(0.525 0.223 3.958)' },
+    { value: 'purple', label: 'Purple', color: 'oklch(0.496 0.265 301.924)' },
+    { value: 'red', label: 'Red', color: 'oklch(0.505 0.213 27.518)' },
+    { value: 'rose', label: 'Rose', color: 'oklch(0.514 0.222 16.935)' },
+    { value: 'sky', label: 'Sky', color: 'oklch(0.5 0.134 242.749)' },
+    { value: 'yellow', label: 'Yellow', color: 'oklch(0.852 0.199 91.936)' },
+];
+// 圆角预设的 value 单位为 rem，可直接传给 setRadius，也可用于 borderRadius 预览。
+const RADIUS_OPTIONS = [
+    { value: 0, label: '0' },
+    { value: 0.25, label: '0.25' },
+    { value: 0.5, label: '0.5' },
+    { value: 0.625, label: 'Default' },
+    { value: 0.75, label: '0.75' },
+    { value: 1, label: '1' },
+];
+const DEFAULT_PREFERENCE = {
+    baseColor: 'neutral',
+    theme: 'neutral',
+    radius: 0.625,
+};
+
+export { BASE_COLORS, COLOR_THEMES, DEFAULT_PREFERENCE, RADIUS_OPTIONS };

package/dist/esm/providers/preference-provider.js

@@ -0,0 +1,124 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useMemo, useState, useRef, useCallback, useLayoutEffect, useEffect, useContext } from 'react';
+import { useHydrated } from '../hooks/use-hydrated.js';
+import { COLOR_THEMES, BASE_COLORS, DEFAULT_PREFERENCE } from '../lib/preference.js';
+
+const PreferenceContext = createContext(undefined);
+// 校验选项标识，并将 unknown 收窄为对应的字符串联合类型。
+function isOption(options, value) {
+    return options.some((option) => option.value === value);
+}
+// 存储内容不可信：逐项校验，单个字段无效时不影响其他有效偏好。
+function normalizePreference(value, fallback) {
+    const candidate = typeof value === 'object' && value !== null ? value : {};
+    return {
+        baseColor: isOption(BASE_COLORS, candidate.baseColor) ? candidate.baseColor : fallback.baseColor,
+        theme: isOption(COLOR_THEMES, candidate.theme) ? candidate.theme : fallback.theme,
+        // 预设用于展示，不限制自定义圆角；只接受有限的非负数。
+        radius: typeof candidate.radius === 'number' && Number.isFinite(candidate.radius) && candidate.radius >= 0
+            ? candidate.radius
+            : fallback.radius,
+    };
+}
+// 解析并校验存储字符串；没有记录或 JSON 损坏时回退到默认值。
+function parsePreference(value, fallback) {
+    try {
+        return normalizePreference(value === null ? null : JSON.parse(value), fallback);
+    }
+    catch {
+        return fallback;
+    }
+}
+// 将存储访问与 JSON 解析分开处理，兼容浏览器禁止存储的情况。
+function readPreference(storageKey, fallback) {
+    try {
+        return parsePreference(localStorage.getItem(storageKey), fallback);
+    }
+    catch {
+        // 存储不可用时，偏好仍可在当前页面内使用。
+        return fallback;
+    }
+}
+// 比较字段值，避免相同偏好触发重复渲染。
+function isSamePreference(current, next) {
+    return current.baseColor === next.baseColor && current.theme === next.theme && current.radius === next.radius;
+}
+// 管理基础色、主题配色和圆角；深浅模式继续由 ThemeProvider 管理。
+function PreferenceProvider({ children, defaultPreference, storageKey = 'bad-ui:preference', }) {
+    // 先补齐并校验调用方传入的默认值，再作为存储读取和重置时的回退值。
+    const { baseColor, theme, radius } = normalizePreference(defaultPreference, DEFAULT_PREFERENCE);
+    const defaults = useMemo(() => ({ baseColor, theme, radius }), [baseColor, theme, radius]);
+    const hydrated = useHydrated();
+    const [storedPreference, setPreference] = useState(() => readPreference(storageKey, defaults));
+    // 保存最新偏好，保证同一批次连续修改不同字段时保留先前修改。
+    const preferenceRef = useRef(storedPreference);
+    // 服务端及客户端水合首帧使用相同默认值，水合后才向子组件公开本地偏好。
+    const preference = hydrated ? storedPreference : defaults;
+    // 主动修改时才写入存储；跨标签页同步仅更新内存，避免删除后又写回默认值。
+    const updatePreference = useCallback((patch) => {
+        const current = preferenceRef.current;
+        const next = normalizePreference({ ...current, ...patch }, current);
+        if (isSamePreference(current, next))
+            return;
+        preferenceRef.current = next;
+        setPreference(next);
+        try {
+            localStorage.setItem(storageKey, JSON.stringify(next));
+        }
+        catch {
+            // 写入失败不阻断页面偏好更新。
+        }
+    }, [storageKey]);
+    const setBaseColor = useCallback((nextBaseColor) => {
+        updatePreference({ baseColor: nextBaseColor });
+    }, [updatePreference]);
+    // 此处 theme 是配色方案（如 blue），并非 light / dark / system。
+    const setTheme = useCallback((nextTheme) => {
+        updatePreference({ theme: nextTheme });
+    }, [updatePreference]);
+    // 圆角以 rem 保存，转换为 CSS 长度的工作由下方 effect 统一完成。
+    const setRadius = useCallback((nextRadius) => {
+        updatePreference({ radius: nextRadius });
+    }, [updatePreference]);
+    // 配色通过独立属性组合；圆角以内联变量覆盖主题默认值，不改动深浅模式类名。
+    useLayoutEffect(() => {
+        if (!hydrated)
+            return;
+        const root = document.documentElement;
+        // 在浏览器绘制前更新属性，分别匹配 base-color 和 themes 中的选择器。
+        root.dataset.baseColor = preference.baseColor;
+        root.dataset.theme = preference.theme;
+        root.style.setProperty('--radius', `${preference.radius}rem`);
+    }, [preference, hydrated]);
+    useEffect(() => {
+        // 接收其他标签页的变更；删除或清空存储时恢复默认偏好。
+        function handleStorageChange(event) {
+            // 只处理 localStorage 中当前键的变化；clear() 的事件 key 为 null。
+            if (event.storageArea !== localStorage || (event.key !== null && event.key !== storageKey)) {
+                return;
+            }
+            const next = parsePreference(event.newValue, defaults);
+            if (isSamePreference(preferenceRef.current, next))
+                return;
+            preferenceRef.current = next;
+            setPreference(next);
+        }
+        window.addEventListener('storage', handleStorageChange);
+        // 卸载或依赖变化时注销监听，避免重复订阅。
+        return () => window.removeEventListener('storage', handleStorageChange);
+    }, [defaults, storageKey]);
+    // 保持 Context 值的引用稳定，避免父组件重渲染引起无关的订阅更新。
+    const value = useMemo(() => ({ ...preference, setBaseColor, setTheme, setRadius }), [preference, setBaseColor, setTheme, setRadius]);
+    return jsx(PreferenceContext.Provider, { value: value, children: children });
+}
+// 统一读取偏好上下文，在缺少 Provider 时给出明确的使用错误。
+function usePreference() {
+    const context = useContext(PreferenceContext);
+    if (context === undefined) {
+        throw new Error('usePreference must be used within a PreferenceProvider');
+    }
+    return context;
+}
+
+export { PreferenceProvider, usePreference };