@moubing/bing-ui 0.5.3 → 0.7.0

package/README.md

@@ -1,93 +1,157 @@
-# bing-ui
-
-A Vue 3 component library starter focused on expressive motion, polished interaction, and non-traditional UI aesthetics.
-
-## 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'
-```
-
-## Themes
-
-The bundled stylesheet includes `light`, `dark`, and `system` themes. Light remains the
-default when no theme attribute is present. The light theme uses the library's signature
-pink interaction accent, while dark mode shifts the semantic accent toward night purple;
-the original pink palette remains available for brand and decorative details.
-
-Set the theme on the document element so components teleported to `body` inherit the
-same tokens as their triggers:
-
-```ts
-document.documentElement.dataset.bingTheme = 'dark'
-
-// Follow the operating-system preference.
-document.documentElement.dataset.bingTheme = 'system'
-```
-
-Apply a persisted theme before mounting Vue to avoid a light-to-dark flash during startup.
-Applications can override any semantic token after importing the library stylesheet:
-
-```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);
-}
-```
-
-The first theme release intentionally uses the document element as its scope. This keeps
-regular components and overlays teleported to `body` on the same theme.
-
-`BingCodeBlock` uses `theme="auto"` by default, mapping light mode to `vitesse-light`
-and dark mode to the higher-contrast `github-dark` palette. Pass an explicit Shiki theme
-name when a code sample must remain fixed independently of the application theme.
-
-## Project Layout
-
-```txt
-src/
-  components/
-    BingButton/
-    BingIcon/
-  motion/
-  theme/
-tests/
-  visual/
-```
+# 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'
+```
+
+## 主题与外观
+
+样式包包含 `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/
+```