@moubing/bing-ui 0.11.1 → 0.12.0

package/README.md

@@ -1,171 +1,300 @@
-# bing-ui
-
-基于 Vue 3 的组件库，采用简约的中性外观，保留富有反馈的交互与动效。
-
-## Stack
-
-- Vue 3 + TypeScript
-- Vite library mode
-- GSAP
-- Vitest + Vue Test Utils
-- Vitest Browser Mode
-- Playwright visual regression
-- Storybook
-- Changesets
-
-## Development
-
-```powershell
-pnpm install
-pnpm dev
-```
-
-## Scripts
-
-```powershell
-pnpm test:run
-pnpm test:browser
-pnpm test:visual
-pnpm build
-pnpm storybook
-pnpm build-storybook
-```
-
-Browser-mode tests always run headlessly. To reuse an installed Chrome when Playwright's bundled Chromium is unavailable, set `BING_UI_BROWSER_CHANNEL=chrome` for the test command.
-
-## Package Entry
-
-```ts
-import { BingButton } from '@moubing/bing-ui'
-import '@moubing/bing-ui/style.css'
-```
-
-## SSR 浮层
-
-弹窗、选择器菜单、提示及预览的 Teleport 浮层在客户端挂载后创建，服务端仍输出页面与控件本体。这样无需应用手动拼接 `body` 浮层 HTML，也能避免多个异步组件水合时误认正文节点。初始设为打开的浮层会在挂载后的更新中显示；组件测试需等待 Vue 的 `nextTick()` 后检查其内容。
-
-## 滚动条稳定占位
-
-`BingScrollbar` 的默认内容容器按启用的方向固定预留轨道空间：纵向在右侧、横向在底部。预留从首次渲染生效，不随内容溢出、轨道显隐或禁用状态改变。`always` 仍只控制轨道可见性，`vertical` / `horizontal` 仍控制对应轨道与平滑滚动。
-
-默认占位宽度为 `--bing-scrollbar-gutter: 13px`。页面需要相对整个视口居中时，在该滚动组件上设置 `--bing-scrollbar-gutter-left: var(--bing-scrollbar-gutter)`，左右将对称预留。该变量在每个实例重置为 `0px`，不会传给嵌套的局部滚动区域。已有安全留白的布局可以显式将 `--bing-scrollbar-gutter` 设为 `0px`。
-
-自定义 `viewport` 插槽的尺寸和内边距仍由调用方负责，应在内容溢出之前就预留轨道空间。BingTextarea、BingTabs 和 BingTable 的内置滚动区域已采用固定占位；表格独立的横向轨道始终保留高度，未溢出时隐藏，并保持表头与固定列对齐。嵌套滚动条的占位、轨道显隐和表格样式仅作用于所属实例。
-
-Storybook 的 **BingScrollbar / 稳定占位** 可切换短内容与长内容，检查正文中心和起始位置是否保持一致。
-
-## 主题与外观
-
-样式包包含 `light`、`dark` 和 `system` 三种主题，未设置时默认浅色。默认配色采用中性灰黑，浅色为白色表面，深色为炭灰表面；原有粉色、蓝色等色阶继续保留，可用于品牌与业务状态。
-
-第一批外观试做覆盖 `BingButton`、`BingInput`、`BingSelect`、`BingCard` 和 `BingDropDown`，可在 Storybook 的 **Design / 外观试做** 中交互体验。提供「图层工作区」「实色表面」「紧凑尺寸」三个示例，并支持切换主题。
-
-- Button 的 xs / sm / md / lg / xl 高度为 28 / 32 / 36 / 40 / 44px。
-- Button 点击时本体保持稳定，以点击位置散开的短促碎屑替代缩放和下沉；键盘触发时从中心播放。禁用、加载、节流拦截及减少动态效果模式不触发新粒子，可在 **BingButton / 点击碎屑** 中体验。
-- Button 的 `loading` 保留文字并循环逐字 jump，沿用 `textJump` 系列参数；结束后恢复配置的文字效果。带文字按钮的图标继续显示，纯图标按钮使用加载图标；显式禁用及减少动态效果时保留静态文字。可在 **BingButton / 加载文字** 和 **Loading Transition** 中体验。
-- 共享表单控件的 sm / md / lg 高度为 32 / 36 / 40px。共享主题和尺寸会影响其他组件，其专属视觉仍待后续逐个调整。
-- Select、TreeSelect 与 DropDown 默认单行选项的 sm / md / lg 行高为 28 / 32 / 36px。含自定义内容或说明的菜单项可增高；虚拟列表的自定义内容应配合 `virtualItemHeight` 指定实际行高。
-- 普通控件以实色为主，首批卡片与菜单的磨砂默认使用 16px 模糊、1.05 饱和度、浅色 0.86 / 深色 0.92 底色不透明度。显式 `glassBlur` / `glassOpacity` / `glassSaturation` 优先于主题变量，设置 `:glass="false"` 后使用实色底。
-
-将主题设置在文档根元素上，使 Teleport 到 `body` 的弹层与触发器继承相同变量：
-
-```ts
-document.documentElement.dataset.bingTheme = 'dark'
-
-// 跟随操作系统主题。
-document.documentElement.dataset.bingTheme = 'system'
-```
-
-建议在挂载 Vue 前应用持久化的主题，避免启动时闪烁。导入组件库样式后，可覆盖语义变量，例如自定义深色模式的强调色：
-
-```css
-html[data-bing-theme='dark'] {
-  --bing-accent-rgb: 251 113 133;
-  --bing-accent-strong-rgb: 254 205 211;
-  --bing-accent-solid-rgb: 253 164 175;
-  --bing-accent: #fb7185;
-  --bing-accent-strong: #fecdd3;
-  --bing-accent-solid: #fda4af;
-  --bing-focus: rgb(var(--bing-accent-rgb) / 0.62);
-}
-```
-
-当前主题以文档根元素为作用域，局部容器上的主题不会自动传播到 Teleport 弹层。
-
-`BingCodeBlock` 默认使用 `theme="auto"`，浅色对应 `vitesse-light`，深色对应 `github-dark`。需要独立固定代码配色时，可传入明确的 Shiki 主题名。
-
-## 数字输入与浏览器自动填充
-
-`BingInput` 支持原生 `type="number"`，可设置 `min`、`max`、`step`，保留上下键步进和浏览器范围校验。数值输入的 `v-model` 返回数字，清空时返回空字符串 `''`；文本类型仍返回字符串。`input` 和 `debounced-input` 事件继续返回原始字符串。
-
-右侧步进按钮使用透明底 SVG 箭头，随主题调整颜色，支持点击和长按连续增减。`step="any"` 时，点击箭头从当前值加减 1；只读、禁用、松开或卸载时停止连续步进。
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { BingInput } from '@moubing/bing-ui'
-
-const width = ref<number | string>(2)
-</script>
-
-<template>
-  <BingInput v-model="width" type="number" :min="0.5" :max="12" :step="0.5" />
-</template>
-```
-
-浏览器保存的历史输入与自动填充弹层由浏览器自身绘制，组件不能用页面 CSS 为它换肤。`:autofill` 只匹配已自动填充的输入框，不控制弹层外观。参考：[Chromium 弹层实现](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/chrome/browser/ui/views/autofill/popup/README.md)、[MDN :autofill](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:autofill)。
-
-组件默认设置 `autocomplete="off"`，关闭浏览器的历史输入提示。接入方显式传入的 `autocomplete` 原样透传，例如 `on`、`email`、`current-password`。浏览器或密码管理器仍可能忽略 `off`，无法保证所有原生弹层都被隐藏。组件不提供自定义输入建议。参考：[MDN autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)。
-
-在 Storybook 的 **Components / BingInput / 数字输入** 中可以体验步进按钮；**Default** 的 Controls 可调整 `autocomplete`。
-
-## 自定义鼠标
-
-`BingCursor` 提供参考 macOS 黑白轮廓的 16 种本地 SVG 光标，支持普通、链接、禁用、文本、抓取、移动、十字、调整尺寸和缩放。默认自动识别元素的 CSS `cursor` 与交互状态，仅作用于默认插槽中的内容。
-
-```vue
-<script setup lang="ts">
-import { BingButton, BingCursor, BingInput } from '@moubing/bing-ui'
-</script>
-
-<template>
-  <BingCursor :size="28">
-    <BingButton>自动显示链接手形</BingButton>
-    <BingButton disabled>自动显示禁用光标</BingButton>
-    <BingInput placeholder="自动显示文本光标" />
-    <div data-bing-cursor="grab">可抓取区域，按住时切换为抓取中</div>
-    <div data-bing-cursor="native">这里使用原生光标</div>
-  </BingCursor>
-</template>
-```
-
-在应用根部挂载 `<BingCursor global />` 可覆盖当前文档，包括 Teleport 到 `body` 的普通弹层。局部实例优先于全局实例，嵌套实例以内层优先。局部实例不自动覆盖 Teleport 到其 DOM 之外的内容。
-
-通过 `color`、`outlineColor` 和 `size` 调整预设；也可设置主题变量 `--bing-cursor-color`、`--bing-cursor-outline`。主题变量从组件所在位置读取。`type` 可固定状态，`data-bing-cursor` 可在局部覆盖，禁用语义优先。
-
-自动识别 CSS 状态需要浏览器允许读取对应的样式表。对于无法读取的跨域样式表，可用 `data-bing-cursor` 明确指定状态。
-
-**光标统一由浏览器原生绘制，以性能和跟手性优先。** 本地 SVG 作为 CSS `cursor` 图片交给浏览器绘制，移动时不更新 DOM 坐标、不运行位置动画；图形按状态直接切换。颜色、尺寸和点击热点仍可配置，图片会复用缓存。尺寸取整到 8–128 px，热点取整并限制在画布内。图片无法加载或被浏览器限制时，回退到同类系统光标。CSS 光标图片及热点规则见 [MDN cursor 文档](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor)。
-
-状态识别在目标、按键、作用域或相关 DOM 变化时更新；同一目标内的移动复用识别结果，样式表扫描不会每帧执行。直接调用 CSSOM API 修改规则没有 DOM 通知，移动期间最多每 100 ms 校验一次；停止移动后没有轮询定时器。
-
-`change` 事件在光标类型变化时触发，`visibility-change` 在启用或释放光标图片时触发。图片不影响点击、键盘焦点和无障碍树；触摸、笔输入和强制颜色模式下使用系统光标。退出作用域、禁用或卸载后恢复原有样式。
-
-iframe、开放的 Shadow DOM 边界、原生选择框与滚动条、浏览器顶层弹窗、原生 HTML 拖放以及未内置的 CSS cursor（例如 `wait`、`progress` 和图片光标）保留原生光标。封闭的 Shadow DOM 宿主请设置 `data-bing-cursor="native"`；该属性也可用于明确排除任何区域。
-
-Storybook 提供 **BingCursor / mac 风格光标、全局与局部** 两个示例，可在 Controls 中调整颜色、尺寸和热点。
-
-从旧版迁移时，删除 `renderer`、`mode`、`followDuration`、`transitionDuration`、`zIndex` 和 `#cursor` 插槽。DOM 跟随、SVG 形变及 `data-bing-cursor-label` 提示已移除；仅保留包裹页面内容的默认插槽。
-
-## Project Layout
-
-```txt
-src/
-  components/
-    BingButton/
-    BingIcon/
-  motion/
-  theme/
-tests/
-  visual/
-```
+<p align="center">
+  <img src="public/bing-ui-logo.png" width="88" alt="Bing UI 标识">
+</p>
+
+<h1 align="center">Bing UI</h1>
+
+<p align="center"><strong>让界面，动得恰到好处。</strong></p>
+<p align="center">Vue 3 · TypeScript · GSAP · 38 个主要组件 · 浅色 / 深色 / 跟随系统</p>
+
+Bing UI 是一套面向创意交互和真实产品场景的 Vue 3 组件库。它以中性配色、清晰边界和轻磨砂建立安静的视觉基础，把文字反馈、卡片翻面、面板转场与平滑滚动融入日常操作，适合构建工作台、内容工具、配置面板和需要细腻反馈的应用。
+
+从按钮、表单到虚拟化表格、文件预览和可调整布局，组件通过显式的 Props、Emits、Slots 和 TypeScript 类型组合使用。当前仓库版本为 **0.12.0**，版本变化见 [更新日志](CHANGELOG.md)。
+
+[![Bing UI 组件总览：按钮状态、角色多选、日期与颜色、滑块、内容卡片、数据表格和代码高亮](docs/images/components-overview-light.png)](docs/images/components-overview-light.png)
+
+*实际组件截图：Storybook「Design / 组件总览 / 组件与交互」。集中展示操作反馈、输入选择、卡片内容、数据协作与代码展示，点击图片可查看原图。*
+
+[设计与交互](#设计与交互) · [快速开始](#快速开始) · [组件一览](#组件一览) · [交互细节](#交互细节) · [主题与外观](#主题与外观) · [本地开发](#本地开发) · [进一步阅读](#进一步阅读)
+
+## 设计与交互
+
+### 把反馈放在操作发生的地方
+
+- **按钮与文字**：按钮提供点击碎屑、悬停反馈和加载时的逐字跳动；`BingAnimatedText` 可单独用于文字扫光和字符跳动。
+- **卡片与转场**：卡片支持倾斜、反光、入场与点击 / 长按翻面；应用切换、横向轮播和卡组转场分别封装为独立组件。
+- **输入与滚动**：Input / Textarea 支持平滑光标；Scrollbar 提供平滑滚动和固定轨道占位，减少内容变化时的布局偏移。
+- **指针反馈**：`BingCursor` 提供 16 种本地 SVG 光标状态，使用浏览器原生 CSS 光标绘制，可在局部区域或整个文档启用。
+
+动效遵循 `prefers-reduced-motion`，并在组件卸载时清理。键盘操作、焦点反馈与禁用状态按各组件的交互方式提供；复杂组合的具体边界请查阅对应示例和说明。
+
+### 让组件能组成实际产品
+
+- **表单**：使用 `BingForm` / `BingFormItem` 组织响应式布局、统一尺寸和禁用状态，并通过 Zod schema 校验、定位错误和管理表单。
+- **数据工作台**：表格支持树形行、行选择、分页、排序、固定列、列宽调整和虚拟滚动；可配合独立列设置、分栏和尺寸调整组件。
+- **内容工具**：图片、图片预览、文件预览与代码块覆盖常见内容展示，配合菜单、弹窗、提示和消息反馈完成操作流程。
+- **主题适配**：浅色、深色和系统主题共享语义变量，支持品牌色覆盖；有磨砂能力的组件可以切换为实色表面。
+
+## 快速开始
+
+### 安装
+
+在已有 Vue 3 项目中安装组件库与 GSAP：
+
+```powershell
+pnpm add @moubing/bing-ui gsap
+```
+
+当前包的 peer dependencies 为 `vue@^3.5.0` 和 `gsap@^3.15.0`。`zod@^4` 是可选 peer dependency：使用 `BingForm` 的 schema 校验时，请在应用中安装 Zod。
+
+组件库以纯 ESM 多文件形式发布，其余运行时依赖（Shiki、Day.js、dnd-kit）不再打进产物，由包管理器安装与去重；打包器只会包含实际导入的组件。`BingCodeBlock` 的 Shiki 语法与主题在首次高亮时按需加载。
+
+### 引入样式
+
+在应用入口全局引入一次：
+
+```ts
+// src/main.ts
+import '@moubing/bing-ui/style.css'
+```
+
+### 使用组件
+
+组件通过具名导入使用，无需全局注册。下面是一份可直接放入 `App.vue` 的示例：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BingButton, BingCard } from '@moubing/bing-ui'
+
+const count = ref(0)
+</script>
+
+<template>
+  <main class="demo">
+    <BingCard
+      title="从一个交互开始"
+      description="把内容、状态和操作放在一起。"
+      :tilt="false"
+    >
+      <p role="status">你已经点击了 {{ count }} 次。</p>
+
+      <template #footer>
+        <BingButton @click="count += 1">体验交互</BingButton>
+        <BingButton variant="secondary" @click="count = 0">重置</BingButton>
+      </template>
+    </BingCard>
+  </main>
+</template>
+
+<style scoped>
+.demo {
+  max-width: 420px;
+  margin: 64px auto;
+  padding: 0 20px;
+}
+</style>
+```
+
+组件对应的类型也从包入口导出，例如：
+
+```ts
+import type { BingButtonProps, BingTableColumn } from '@moubing/bing-ui'
+```
+
+### 全局配置
+
+用 `BingConfigProvider` 包住应用或局部区域，统一默认尺寸、浮层层级和动效策略。组件显式传入的 props 始终优先；嵌套的 Provider 只覆盖自己设置的字段。
+
+```vue
+<template>
+  <BingConfigProvider size="sm" :z-index="4000" reduced-motion="user">
+    <RouterView />
+  </BingConfigProvider>
+</template>
+```
+
+- **`size`**：未传 `size` 的组件使用此尺寸，优先级为组件 props → 表单 / 表单项 → 全局配置 → `md`。
+- **`zIndex`**：浮层层级基准，默认 `2000`。弹窗、消息、文件 / 图片预览、颜色选择、下拉与选择面板、日期面板、提示依次在基准上加 `0 / 100 / 300 / 400 / 900 / 1000 / 1100 / 1200`。
+- **`reducedMotion`**：`user`（默认）跟随系统的 `prefers-reduced-motion`，`always` 始终减少 JS 动效，`never` 忽略系统设置。CSS 中的 `@media (prefers-reduced-motion)` 规则仍只跟随系统。
+
+自定义组件可以用 `useReducedMotion()` 获得同样的判断函数，用 `useBingConfig()` 读取当前配置。
+
+### 在 Nuxt 中使用
+
+在 Nuxt 配置中全局加载样式，页面中仍使用显式导入：
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: ['@moubing/bing-ui/style.css'],
+})
+```
+
+Teleport 浮层在客户端挂载后创建，服务端保留页面和控件本体。初始打开的弹层会在挂载后的更新中显示；相关测试需等待 Vue 的 `nextTick()`。业务代码若直接读取 `window` / `document`，应放在客户端生命周期中。
+
+## 组件一览
+
+目前提供 38 个主要组件，按使用场景组织如下。完整公开导出以 [组件入口](src/components/index.ts) 为准，各目录内包含实现、类型和 Storybook 示例。
+
+| 场景 | 组件 | 主要能力 |
+| --- | --- | --- |
+| 基础操作与展示 | `BingButton` · `BingIcon` · `BingCard` · `BingTag` | 操作层级、图标规范、内容卡片、状态标签 |
+| 文本与候选输入 | `BingInput` · `BingTextarea` · `BingAutocomplete` | 文本 / 数字输入、多行编辑、候选搜索与异步状态 |
+| 选择与数值 | `BingSelect` · `BingTreeSelect` · `BingDatePicker` · `BingColorPicker` · `BingSlider` | 搜索选择、树形选择、日期时间、颜色与滑块 |
+| 单选与多选 | `BingCheckbox` · `BingCheckboxGroup` · `BingRadio` · `BingRadioGroup` | 独立控件、选项组、统一状态与键盘操作 |
+| 表单组织 | `BingForm` · `BingFormItem` | 布局、标签、校验、错误提示与实例方法 |
+| 浮层与反馈 | `BingDialog` · `BingDropDown` · `BingTooltip` · `BingToast` | 弹窗、普通 / 右键菜单、提示与全局消息 |
+| 布局与操作 | `BingTabs` · `BingScrollbar` · `BingResizable` · `BingSplitPane` · `BingSortableList` | 标签切换、滚动、尺寸调整、分栏、拖拽排序 |
+| 数据表格 | `BingTable` · `BingTableColumnControls` | 树形行、虚拟化、服务端排序 / 分页、共享列设置 |
+| 内容与预览 | `BingImage` · `BingImagePreview` · `BingFilePreview` · `BingCodeBlock` | 图片与图库、文件预览、代码高亮与复制 |
+| 动效与指针 | `BingAnimatedText` · `BingAppSwitcherTransition` · `BingCarouselTransition` · `BingDeckTransition` · `BingCursor` | 文字效果、面板 / 轮播 / 卡组转场、原生光标 |
+
+另提供 `BingConfigProvider` 全局配置、`BingDropDownItem` 菜单子组件、`bingToast` / `useBingToast` 消息服务，以及 `motion`、`prefersReducedMotion` / `useReducedMotion` 和平滑滚动相关工具。
+
+`BingIcon` 接收本地或第三方 Vue / SVG 图标组件，负责统一尺寸、描边、颜色和可访问名称。组件库内部图标已固化为本地 SVG 组件，不需要额外安装图标库。按钮图标通过 `prefix` / `suffix` 插槽传入，可以自由选择图标来源。
+
+### 表格与复杂交互
+
+[![BingTable 数据工作台：搜索框、已选行、状态标签、完成进度、排序入口和列设置](docs/images/table.png)](docs/images/table.png)
+
+*总览中的表格特写：选中行、状态标签与进度可同时展示，顶部搜索框与状态标签能联动筛选数据。*
+
+`BingTable` 将数据、列定义和交互状态分开管理。通过 `v-model` 可以控制选择、展开、分页、排序和列设置；`remoteSort` 与 `remotePagination` 分别用于服务端排序和分页。多个表格需要共用列偏好时，可使用 `BingTableColumnControls`。
+
+Storybook 的「Composition / 组件联动」进一步展示弹窗内表单、表格内操作控件，以及表单尺寸和禁用状态的传递。
+
+## 交互细节
+
+### 卡片的内容、操作与背面
+
+`BingCard` 通过插槽容纳资源列表、图标、状态标签和操作按钮，点击或长按可以切换到背面。下面是同一张卡片翻面前后的实际状态：
+
+| 正面：资源列表与底部操作 | 背面：补充信息与返回提示 |
+| :---: | :---: |
+| [![卡片正面，展示资源列表、图标、同步状态与操作按钮](docs/images/card-front.png)](docs/images/card-front.png) | [![卡片翻面后，展示扩展详情和返回提示](docs/images/card-back.png)](docs/images/card-back.png) |
+
+总览示例使用默认内容、`footer` 和 `back` 插槽组织信息；卡片中的按钮保留自己的点击操作。倾斜、反光、入场和翻面效果可以在 Storybook 中实际体验。
+
+### 多选状态与候选详情
+
+选中的内容以可移除标签显示，展开后可以继续勾选、全选或查看禁用状态。悬停候选项时，旁侧详情面板展示补充说明和元数据，适合需要解释选项含义的场景。
+
+[![BingSelect 展开特写，包含已选标签、多选勾选框、禁用选项与悬停详情面板](docs/images/select-details.png)](docs/images/select-details.png)
+
+*实际组件截图：Storybook「Components / BingSelect / 多选」。总览中的协作角色选择器另展示了搜索过滤能力。*
+
+### 颜色、透明度与预设色板
+
+`BingColorPicker` 在同一个面板中提供二维取色、色相、透明度、预设色板、格式切换和颜色值复制。下图展示展开后的完整面板，可以直接看到各项调节能力。
+
+<p align="center">
+  <a href="docs/images/color-picker.png"><img src="docs/images/color-picker.png" width="420" alt="BingColorPicker 展开特写，包含取色区域、色相、透明度、预设色板、HEX 输入与复制按钮"></a>
+</p>
+
+*实际组件截图：Storybook「Components / BingColorPicker / 自定义色板」。*
+
+## 主题与外观
+
+默认浅色主题采用中性灰黑、白色表面、细边框和轻阴影；深色主题使用炭灰表面。配色、尺寸和磨砂参数集中在 [主题样式](src/theme/index.css)。
+
+[![Bing UI 深色组件总览：按钮、表单控件、卡片、表格与代码高亮共用主题变量](docs/images/components-overview-dark.png)](docs/images/components-overview-dark.png)
+
+*与开篇相同的组件总览，切换为深色主题；输入状态、表格选中行、标签和代码配色一同变化。*
+
+把主题设置在文档根元素上，让 Teleport 到 `body` 的弹层继承同一套变量：
+
+```ts
+// 在客户端执行；也可设为 'light' 或 'system'。
+document.documentElement.dataset.bingTheme = 'dark'
+```
+
+`system` 会跟随操作系统外观。应用可自行保存主题偏好，并在挂载 Vue 前恢复，减少启动时的主题闪烁。局部容器上的主题不会自动传递到其 DOM 范围之外的 Teleport 浮层。
+
+品牌定制优先覆盖语义变量，同时维护颜色值和对应的 RGB 通道：
+
+```css
+html[data-bing-theme='dark'] {
+  --bing-accent-rgb: 139 92 246;
+  --bing-accent-strong-rgb: 196 181 253;
+  --bing-accent-solid-rgb: 167 139 250;
+  --bing-accent: rgb(var(--bing-accent-rgb));
+  --bing-accent-strong: rgb(var(--bing-accent-strong-rgb));
+  --bing-accent-solid: rgb(var(--bing-accent-solid-rgb));
+  --bing-accent-soft: rgb(var(--bing-accent-rgb) / 0.16);
+  --bing-accent-contrast: #0f172a;
+  --bing-focus: rgb(var(--bing-accent-rgb) / 0.62);
+}
+```
+
+- **尺寸**：常规输入和选择控件的 `sm / md / lg` 高度为 `32 / 36 / 40px`；Button 另外提供 `xs=28px`、`xl=44px`。表格行高等特殊尺寸以组件 API 为准。
+- **磨砂**：支持 `glass` 的组件可通过 `:glass="false"` 使用实色底；显式传入的 `glassBlur` / `glassOpacity` / `glassSaturation` 优先于主题变量。
+- **代码配色**：`BingCodeBlock` 的默认 `theme="auto"` 随明暗主题切换，也可指定 Shiki 主题名。
+
+## 本地开发
+
+本仓库使用 pnpm；组件开发和交互验证主要在 Storybook 中进行。
+
+```powershell
+pnpm install
+pnpm storybook
+```
+
+Storybook 默认使用 `6006` 端口，端口被占用时自动寻找下一个可用端口。需要临时指定起始端口时，在 PowerShell 中设置 `$env:STORYBOOK_PORT=6007` 后启动；不要追加另一组 `-p` 参数。需要独立演示入口时运行 `pnpm dev`。
+
+### 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `pnpm dev` | 启动 Vite 演示页面 |
+| `pnpm storybook` | 启动组件示例与交互调试环境 |
+| `pnpm test:run` | 运行单元 / 组件测试 |
+| `pnpm test:browser` | 运行无头浏览器组件测试 |
+| `pnpm build` | 类型检查并构建组件库，输出到 `dist/` |
+| `pnpm build-storybook` | 生成静态 Storybook |
+| `pnpm changeset` | 为需要发版的改动记录变更说明 |
+| `pnpm version-packages` | 根据 Changesets 更新版本 |
+
+视觉回归在组件迭代阶段暂停，仅在明确需要时运行 `pnpm test:visual`，不随日常验证更新截图基线。纯文档修改通常无需构建；逻辑改动运行单元测试，涉及公开 API / 构建的改动再执行构建，界面改动需用无头 Playwright 检查受影响的 Storybook 页面。
+
+浏览器测试默认使用无头模式。内置 Chromium 不可用时，可以为本次测试临时设置 `BING_UI_BROWSER_CHANNEL=chrome` 或 `msedge`；运行后恢复环境变量，不把本机浏览器路径提交到仓库。
+
+### 技术栈与目录
+
+| 层次 | 实现 |
+| --- | --- |
+| 组件与类型 | Vue 3、TypeScript、单文件组件 |
+| 动效与拖拽 | GSAP、`@dnd-kit/vue` / `@dnd-kit/dom` |
+| 表单、日期与内容 | Zod、Day.js、Shiki |
+| 开发与打包 | Vite 库模式、`vue-tsc`、`vite-plugin-dts` |
+| 示例与验证 | Storybook、Vitest、Vue Test Utils、Playwright |
+| 版本管理 | Changesets |
+
+```text
+src/
+  components/              # 组件实现、类型、测试和 Storybook 示例
+    BingButton/
+    BingTable/
+    ...
+  motion/                  # 动效令牌与平滑滚动工具
+  theme/                   # 全局主题与设计变量
+  utils/                   # 组件间共享能力
+  index.ts                 # 公开入口
+.storybook/                # Storybook 配置与组合展示
+tests/visual/              # 视觉回归测试
+docs/                      # 接入说明、设计记录与 README 配图
+.changeset/                # 版本变更记录
+```
+
+新增组件应通过组件目录的 `index.ts`、`src/components/index.ts` 和 `src/index.ts` 导出。动画需限定在实例范围内，优先使用 transform / opacity，并处理卸载清理和减少动态效果偏好。
+
+## 进一步阅读
+
+- [组件接入与行为说明](docs/component-notes.md)：SSR 浮层、稳定滚动条占位、数字输入、自动填充、自定义光标及旧版迁移细节。
+- [更新日志](CHANGELOG.md)：已发布版本的组件与行为变化。
+- [开发约定](AGENTS.md)：目录规范、动效原则和验证要求。
+- [组件联动示例源码](src/components/Composition.stories.ts)：查看表单、弹窗和表格如何组合。
+- [组件总览示例源码](.storybook/ReadmeShowcase.vue)：查看 README 中的组件组合，或在 Storybook「Design / 组件总览 / 组件与交互」中操作并更新配图。
+- **配套项目 `bing-ui-docs`**：基于 Nuxt 的使用文档站，包含快速开始、38 个组件页面、完整示例和 `llms.txt` AI 文档入口。
+
+本文七张效果图均来自本仓库的实际 Storybook 页面，使用 2 倍像素密度保存到 `docs/images/`。点击图片可查看原图；阅读 README 无需启动开发服务，动态交互可在对应 Storybook 示例中体验。

package/dist/_virtual/_plugin-vue_export-helper.js

@@ -0,0 +1,8 @@
+//#region \0plugin-vue:export-helper
+var e = (e, t) => {
+	let n = e.__vccOpts || e;
+	for (let [e, r] of t) n[e] = r;
+	return n;
+};
+//#endregion
+export { e as default };