@badnpm/ui 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 badnpm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# UI components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React 19 组件库，提供 ESM、CommonJS、UMD 三种产物，以及独立的预编译 CSS。
+
+## 安装
+
+包发布后，在应用中安装组件库及 React 依赖：
+
+```sh
+npm install @badnpm/ui react@^19 react-dom@^19
+```
+
+当前包标记为 private，发布前可使用本地 tarball 验证。下文统一使用当前包名 `@badnpm/ui`。
+
+## 样式入口
+
+三种 JS 格式共用 `dist/styles`，JS 入口不会自动加载 CSS。
+
+| 样式入口                           | 用途                                        | 引入方式                     |
+| ---------------------------------- | ------------------------------------------- | ---------------------------- |
+| `@badnpm/ui/styles/index.css`      | Tailwind 重置、组件工具类、主题和基础色变量 | 使用内置组件样式时引入       |
+| `@badnpm/ui/styles/body.css`       | 将 `body` 背景色和文字色设为主题颜色        | 按需引入，与默认样式配合使用 |
+| `@badnpm/ui/styles/font/geist.css` | 加载 Geist 字体，并设置默认无衬线字体       | 按需引入                     |
+
+仅引入默认样式即可使用组件。页面配色与字体可以分别选择，字体文件随包提供。
+主题和基础色已包含在默认样式中。`@badnpm/ui/globals.css` 是默认样式的兼容入口，使用示例统一采用 `styles/index.css`。
+
+使用方无需安装 Tailwind、shadcn、tw-animate-css 或 Geist 字体包。
+应用自行编写的额外 Tailwind 类需要由应用自己的 Tailwind 配置生成。
+
+## ESM
+
+适用于支持 TSX 和 CSS 导入的应用构建工具。`import` 自动选择 `dist/esm/index.js`。
+以下示例作为浏览器入口使用，HTML 中需提供 `<div id="root"></div>`。
+
+```tsx
+import { createRoot } from 'react-dom/client';
+import { Button, ThemeProvider, ThemeToggle } from '@badnpm/ui';
+
+// 默认组件样式。
+import '@badnpm/ui/styles/index.css';
+// 可选，让整个页面的背景色、文字色跟随主题。
+import '@badnpm/ui/styles/body.css';
+// 可选，使用 Geist 字体。
+import '@badnpm/ui/styles/font/geist.css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Button>保存</Button>
+      <ThemeToggle />
+    </ThemeProvider>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+删除可选的 CSS 导入，即可由应用自行决定页面配色和字体。
+`ThemeToggle` 通过 `ThemeProvider` 读取并切换深浅模式，单独使用 `Button`、`Input` 时可直接渲染。
+
+## CommonJS
+
+`require` 自动选择 `dist/cjs/index.cjs`。以下示例用于支持 CommonJS 且配置了 CSS 处理的浏览器打包入口，HTML 中需提供 `<div id="root"></div>`。
+
+```js
+const React = require('react');
+const { createRoot } = require('react-dom/client');
+const { Button, ThemeProvider, ThemeToggle } = require('@badnpm/ui');
+
+// 这些 CSS require 由应用的打包器处理。
+require('@badnpm/ui/styles/index.css');
+// 可选页面配色。
+require('@badnpm/ui/styles/body.css');
+// 可选字体。
+require('@badnpm/ui/styles/font/geist.css');
+
+const app = React.createElement(
+  ThemeProvider,
+  null,
+  React.createElement(Button, null, '保存'),
+  React.createElement(ThemeToggle)
+);
+
+createRoot(document.getElementById('root')).render(app);
+```
+
+在 Node.js 中进行服务端渲染时，可以直接加载 CJS 组件。CSS 通过浏览器端入口或 HTML 的 `link` 标签加载。
+
+```js
+const React = require('react');
+const { renderToString } = require('react-dom/server');
+const { Button } = require('@badnpm/ui');
+
+const html = renderToString(React.createElement(Button, null, '保存'));
+console.log(html);
+```
+
+## UMD
+
+将安装包中的 `dist` 目录放到网站静态目录，例如 `public/vendor/ui`。浏览器可以通过 `/vendor/ui/umd/index.js` 加载组件库，通过 `/vendor/ui/styles` 加载样式和字体。部署时保留整个 `styles` 目录结构，使 CSS 中的字体相对路径保持有效。
+
+UMD 导出挂载到 `window.BadUI`。页面先准备 React、ReactDOM 全局对象，再加载组件库。
+React 19 的浏览器加载示例采用 ESM CDN，并将 React 显式共享给 ReactDOM，下面使用 import map 配置依赖地址。 [React 官方说明](https://react.dev/blog/2024/04/25/react-19-upgrade-guide#umd-builds-removed)
+
+```html
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>UI 组件示例</title>
+
+    <!-- 默认组件样式。 -->
+    <link rel="stylesheet" href="/vendor/ui/styles/index.css" />
+    <!-- 可选，删除此行后由应用自行设置 body 配色。 -->
+    <link rel="stylesheet" href="/vendor/ui/styles/body.css" />
+    <!-- 可选，删除此行后使用应用自己的字体。 -->
+    <link rel="stylesheet" href="/vendor/ui/styles/font/geist.css" />
+
+    <script type="importmap">
+      {
+        "imports": {
+          "react": "https://esm.sh/react@19",
+          "react-dom": "https://esm.sh/react-dom@19?external=react",
+          "react-dom/client": "https://esm.sh/react-dom@19/client?external=react,react-dom"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module">
+      import React from 'react';
+      import * as ReactDOM from 'react-dom';
+      import { createRoot } from 'react-dom/client';
+
+      window.React = React;
+      window.ReactDOM = ReactDOM;
+
+      // 等待全局对象设置完成后再加载 UMD 文件。
+      await import('/vendor/ui/umd/index.js');
+      const { Button, ThemeProvider, ThemeToggle } = window.BadUI;
+
+      createRoot(document.getElementById('root')).render(
+        React.createElement(
+          ThemeProvider,
+          null,
+          React.createElement(Button, null, '保存'),
+          React.createElement(ThemeToggle)
+        )
+      );
+    </script>
+  </body>
+</html>
+```
+
+通过 HTTP 静态服务访问上述页面。示例中的 CDN 地址可替换为应用自行托管的 React 依赖地址。
+UMD 已合并普通运行依赖，React 与 ReactDOM 由页面提供，CSS 通过 `link` 独立加载。
+
+## TypeScript
+
+ESM 使用 `dist/types/index.d.ts`，CommonJS 使用 `dist/cjs/types/index.d.ts`，包的 `exports` 会根据导入方式选择对应声明。两份声明均按源码目录逐文件生成。
+
+TypeScript 项目可以加载构建工具提供的 CSS 类型声明，例如 Vite 的 `vite/client`。
+也可在应用纳入编译范围的声明文件（例如 `src/styles.d.ts`）中统一添加：
+
+```ts
+declare module '*.css' {}
+```
+
+## 构建与打包
+
+在仓库根目录执行：
+
+```sh
+pnpm --filter @badnpm/ui build
+npm pack ./packages/ui --pack-destination /tmp
+```
+
+构建命令直接运行 `rollup -c`，产物目录如下：
+
+```text
+dist/
+├── esm/                 # ESM 模块
+├── types/               # 按源码结构生成的 ESM 类型声明
+├── cjs/                 # CommonJS 模块，types 子目录提供逐文件类型声明
+├── umd/index.js         # 浏览器单文件，导出 window.BadUI
+└── styles/              # 默认样式、可选 body 配色和字体资源
+```
+
+TypeScript 插件编译 JS，rollup-plugin-dts 配合 preserveModules 按源码目录逐文件生成类型声明。PostCSS 编译独立 CSS 并处理字体资源，样式规则集中在 `postcss.config.mjs`。
+声明生成阶段会将目录导入和源码路径别名转换为完整相对路径，兼容使用方的 NodeNext 类型解析。
+入口和依赖统一在包根目录的 `package.json` 中维护。工作区 demo 的 Vite 别名指向源码，保留本地热更新。

package/dist/cjs/components/button.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var button = require('@base-ui/react/button');
+var classVarianceAuthority = require('class-variance-authority');
+var cn = require('cn');
+
+const buttonVariants = classVarianceAuthority.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 (jsxRuntime.jsx(button.Button, { "data-slot": "button", className: typeof className === 'function'
+            ? (state) => cn.cn(buttonVariants({ variant, size }), className(state))
+            : cn.cn(buttonVariants({ variant, size }), className), ...props }));
+}
+
+exports.Button = Button;
+exports.buttonVariants = buttonVariants;

package/dist/cjs/components/input.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var input = require('@base-ui/react/input');
+var cn = require('cn');
+
+function Input({ className, type, ...props }) {
+    return (jsxRuntime.jsx(input.Input, { type: type, "data-slot": "input", className: cn.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 }));
+}
+
+exports.Input = Input;

package/dist/cjs/components/theme-toggle.cjs

@@ -0,0 +1,19 @@
+"use client";
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var lucideReact = require('lucide-react');
+var button = require('./button.cjs');
+var themeProvider = require('../providers/theme-provider.cjs');
+
+function ThemeToggle({ darkLabel = '切换到深色主题', lightLabel = '切换到浅色主题', variant = 'outline', size = 'icon', title = '切换主题', onClick, ...props }) {
+    const { toggleTheme } = themeProvider.useTheme();
+    return (jsxRuntime.jsxs(button.Button, { type: "button", variant: variant, size: size, title: title, ...props, onClick: (event) => {
+            // 先执行使用方回调，允许通过 preventDefault() 取消主题切换。
+            onClick?.(event);
+            if (!event.defaultPrevented)
+                toggleTheme();
+        }, children: [jsxRuntime.jsx(lucideReact.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" }), jsxRuntime.jsx(lucideReact.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" }), jsxRuntime.jsx("span", { className: "sr-only dark:hidden", children: darkLabel }), jsxRuntime.jsx("span", { className: "sr-only hidden dark:block", children: lightLabel })] }));
+}
+
+exports.ThemeToggle = ThemeToggle;

package/dist/cjs/hooks/use-hydrated.cjs

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

package/dist/cjs/index.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+var button = require('./components/button.cjs');
+var input = require('./components/input.cjs');
+var themeToggle = require('./components/theme-toggle.cjs');
+var preferenceProvider = require('./providers/preference-provider.cjs');
+var themeProvider = require('./providers/theme-provider.cjs');
+var useHydrated = require('./hooks/use-hydrated.cjs');
+var preference = require('./lib/preference.cjs');
+var cn = require('cn');
+
+
+
+exports.Button = button.Button;
+exports.buttonVariants = button.buttonVariants;
+exports.Input = input.Input;
+exports.ThemeToggle = themeToggle.ThemeToggle;
+exports.PreferenceProvider = preferenceProvider.PreferenceProvider;
+exports.usePreference = preferenceProvider.usePreference;
+exports.ThemeProvider = themeProvider.ThemeProvider;
+exports.useTheme = themeProvider.useTheme;
+exports.useHydrated = useHydrated.useHydrated;
+exports.BASE_COLORS = preference.BASE_COLORS;
+exports.COLOR_THEMES = preference.COLOR_THEMES;
+exports.DEFAULT_PREFERENCE = preference.DEFAULT_PREFERENCE;
+exports.RADIUS_OPTIONS = preference.RADIUS_OPTIONS;
+Object.defineProperty(exports, "cn", {
+	enumerable: true,
+	get: function () { return cn.cn; }
+});

package/dist/cjs/lib/preference.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+// 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,
+};
+
+exports.BASE_COLORS = BASE_COLORS;
+exports.COLOR_THEMES = COLOR_THEMES;
+exports.DEFAULT_PREFERENCE = DEFAULT_PREFERENCE;
+exports.RADIUS_OPTIONS = RADIUS_OPTIONS;

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

@@ -0,0 +1,127 @@
+"use client";
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var useHydrated = require('../hooks/use-hydrated.cjs');
+var preference = require('../lib/preference.cjs');
+
+const PreferenceContext = react.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(preference.BASE_COLORS, candidate.baseColor) ? candidate.baseColor : fallback.baseColor,
+        theme: isOption(preference.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, preference.DEFAULT_PREFERENCE);
+    const defaults = react.useMemo(() => ({ baseColor, theme, radius }), [baseColor, theme, radius]);
+    const hydrated = useHydrated.useHydrated();
+    const [storedPreference, setPreference] = react.useState(() => readPreference(storageKey, defaults));
+    // 保存最新偏好，保证同一批次连续修改不同字段时保留先前修改。
+    const preferenceRef = react.useRef(storedPreference);
+    // 服务端及客户端水合首帧使用相同默认值，水合后才向子组件公开本地偏好。
+    const preference$1 = hydrated ? storedPreference : defaults;
+    // 主动修改时才写入存储；跨标签页同步仅更新内存，避免删除后又写回默认值。
+    const updatePreference = react.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 = react.useCallback((nextBaseColor) => {
+        updatePreference({ baseColor: nextBaseColor });
+    }, [updatePreference]);
+    // 此处 theme 是配色方案（如 blue），并非 light / dark / system。
+    const setTheme = react.useCallback((nextTheme) => {
+        updatePreference({ theme: nextTheme });
+    }, [updatePreference]);
+    // 圆角以 rem 保存，转换为 CSS 长度的工作由下方 effect 统一完成。
+    const setRadius = react.useCallback((nextRadius) => {
+        updatePreference({ radius: nextRadius });
+    }, [updatePreference]);
+    // 配色通过独立属性组合；圆角以内联变量覆盖主题默认值，不改动深浅模式类名。
+    react.useLayoutEffect(() => {
+        if (!hydrated)
+            return;
+        const root = document.documentElement;
+        // 在浏览器绘制前更新属性，分别匹配 base-color 和 themes 中的选择器。
+        root.dataset.baseColor = preference$1.baseColor;
+        root.dataset.theme = preference$1.theme;
+        root.style.setProperty('--radius', `${preference$1.radius}rem`);
+    }, [preference$1, hydrated]);
+    react.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 = react.useMemo(() => ({ ...preference$1, setBaseColor, setTheme, setRadius }), [preference$1, setBaseColor, setTheme, setRadius]);
+    return jsxRuntime.jsx(PreferenceContext.Provider, { value: value, children: children });
+}
+// 统一读取偏好上下文，在缺少 Provider 时给出明确的使用错误。
+function usePreference() {
+    const context = react.useContext(PreferenceContext);
+    if (context === undefined) {
+        throw new Error('usePreference must be used within a PreferenceProvider');
+    }
+    return context;
+}
+
+exports.PreferenceProvider = PreferenceProvider;
+exports.usePreference = usePreference;