@moubing/bing-ui 0.5.3 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # bing-ui
 
-A Vue 3 component library starter focused on expressive motion, polished interaction, and non-traditional UI aesthetics.
+基于 Vue 3 的组件库，采用简约的中性外观，保留富有反馈的交互与动效。
 
 ## Stack
 
@@ -40,25 +40,29 @@ 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.
+样式包包含 `light`、`dark` 和 `system` 三种主题，未设置时默认浅色。默认配色采用中性灰黑，浅色为白色表面，深色为炭灰表面；原有粉色、蓝色等色阶继续保留，可用于品牌与业务状态。
 
-Set the theme on the document element so components teleported to `body` inherit the
-same tokens as their triggers:
+第一批外观试做覆盖 `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'
 
-// 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:
+建议在挂载 Vue 前应用持久化的主题，避免启动时闪烁。导入组件库样式后，可覆盖语义变量，例如自定义深色模式的强调色：
 
 ```css
 html[data-bing-theme='dark'] {
@@ -72,12 +76,87 @@ html[data-bing-theme='dark'] {
 }
 ```
 
-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.
+当前主题以文档根元素为作用域，局部容器上的主题不会自动传播到 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`。光标层 Teleport 到 `body`，局部 CSS 变量请通过 props 传入。`type` 可固定状态，`data-bing-cursor` 可在局部覆盖，禁用语义优先。
+
+自动识别 CSS 状态需要浏览器允许读取对应的样式表。对于无法读取的跨域样式表，可用 `data-bing-cursor` 明确指定状态。
+
+内置光标通过 SVG 路径形变（morphing）连续切换轮廓，默认时长 0.24 秒。主体、指缝和符号保持相同的路径节点，坐标与颜色同步插值；主体始终可见，点击热点保持对齐。使用 `<BingCursor :transition-duration="0.36">` 调整时长，设为 `0` 可关闭。快速往返切换会从当前轮廓继续，鼠标位置始终即时跟随。实现使用项目已有的 GSAP MorphSVG，原理可参考 [Motion 的 morphing 说明](https://motion.dev/docs/svg-animation#motion)和 [MorphSVG 文档](https://gsap.com/docs/v3/Plugins/MorphSVGPlugin/)。
+
+使用 `cursor` 作用域插槽自定义图形和提示文字，`hotspot` 表示自定义内容左上角到点击位置的偏移，单位为 CSS 像素，默认 `[0, 0]`：
+
+```vue
+<BingCursor :hotspot="[8, 8]">
+  <a href="/gallery" data-bing-cursor-label="查看作品">作品集</a>
+  <template #cursor="{ type, pressed, label }">
+    <div class="my-cursor" :class="{ 'is-pressed': pressed }">
+      <span class="my-cursor__dot" />
+      <span v-if="label">{{ label }}</span>
+      <span v-else>{{ type }}</span>
+    </div>
+  </template>
+</BingCursor>
+```
+
+插槽提供 `type`、`pressed`、`size`、`label` 和 `target`；其中 `label` 来自 `data-bing-cursor-label`。`change` 事件在光标类型变化时触发，`visibility-change` 在显示或隐藏时触发。自定义内容须自行设置尺寸和样式，点击热点应与图形指向的位置一致。
+
+任意 HTML 或 SVG 自定义插槽在 `type` 或 `label` 变化时使用交叠淡化与缩放过渡，不自动转换为可形变路径；`pressed` 等状态持续传入当前图形，可用于自己的按压反馈。插槽过渡期间最多同时渲染两份装饰内容，内置光标始终只使用一组路径。
+
+`mode="follow"` 保留原生光标并显示圆环，可通过 `followDuration` 调整跟随时长，也支持自定义插槽。替换模式始终精确跟手。触摸、笔输入、强制颜色模式下保留原生行为；减少动态效果时关闭跟随层并跳过图形过渡。光标层不拦截点击、不进入键盘焦点，退出作用域、禁用或卸载后立即结束动画并恢复原生样式。
+
+iframe、开放的 Shadow DOM 边界、原生选择框与滚动条、浏览器顶层弹窗、原生 HTML 拖放以及未内置的 CSS cursor（例如 `wait`、`progress` 和图片光标）保留原生光标。封闭的 Shadow DOM 宿主请设置 `data-bing-cursor="native"`；该属性也可用于明确排除任何区域。
 
-`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.
+Storybook 提供 **BingCursor / mac 风格光标、轮廓形变、自定义光标、柔和跟随、全局与局部** 五个示例；轮廓形变页附带与鼠标同步的放大演示。
 
 ## Project Layout