@5even7/dlc-ui 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,36 +1,47 @@
-# Changelog
-
+# Changelog
+
 > **发版规则**：默认每次发布只递增补丁号（0.x.y → 0.x.(y+1)，即 +0.01）；除非手动明确指定新版本号，否则不升次版本。
 
-## 0.2.1 - 2026-08-08
+## 0.2.3 - 2026-08-08
 
-- 移除 `copy` / `showCopy` 属性：文字区内容改由插槽提供（Vue 默认插槽；H5/工厂用 `text` 选项），并新增颜色区插槽（Vue `#color`；H5/工厂用 `colorContent` 选项）。
-- 新增 `textRatio` 属性（0~100，单位 %）：控制文字区宽度占比，胶囊默认 39、进度条默认 54；写入统一变量 `--hj-text-width`，旧 `--hj-copy-*` 变量保留为兼容别名。
-- 新增进度条 `showValue` 属性（默认 true）：控制右侧百分比数字显示。
-- 插槽容器默认透明且只做几何定位：不传插槽即为纯画面；组件不再对插槽内容施加文字样式。
-- 移除进度条右下角 DRAG 提示（`dragLabel` 相关配置一并删除）。
-- 文字区容器应用 `--hj-text-radius` 并裁剪内容（默认 0，无影响）。
-- 新增控制器方法：`setText(content)` / `setColorContent(content)` / `setTextRatio(ratio)`（胶囊与进度条）。
-- `ready` / `error` 改为创建后异步触发（先创建、后监听也能收到）；Progress 补齐 WebGL 降级时的 `error` 事件。
-- `randomize()` 会把新 seed 同步回 `preset.seed`；Canvas2D 降级路径的 `seed` / `speed` 现在真实生效。
-- 新增 `setCssVars(vars)` / `setLabel(label)`（胶囊与进度条）、进度条 `setValueSuffix(suffix)`；Vue 组件实例暴露与 H5 对称的插槽/CSS 变量方法。
-- Progress 新增 `disabled`（禁用拖动/键盘、aria-disabled、置灰）、`label`、`valueSuffix`；Capsule 补 `role="img"` 并支持 `label`。
-- `min` / `max` 水线归一化到 `[min, max]`，键盘步进按范围百分比（方向键 ±2%、PageUp/PageDown ±10%），右侧数字仍显示原始 value。
-- 拖动进度时 `change` 按 rAF 合并为一帧一次，避免高频重渲染。
-- Vue 结构属性变化重建实例时会继承运行时状态（seed/speed/colors/textRatio/cssVars/value 等）。
-- 新增官方 Vue 组件 `ColorBackground`；Color 控制器补齐 `setSeed` / `setSpeed` / `setFallbackColor` / `setMouseColor`。
-- Vue wrapper 的 `id` / `data-*` / `title` 等普通属性会落到组件内部根节点；`class` / `style` 留在外层宿主并写入文档。
-- `colors` 支持更通用的写法：`#rgb` / `#rrggbb` / CSS 命名色（`red`、`green`…）/ `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 忽略（透明请用 `opacity`），新增公共工具 `normalizeColor(color)`。
-- 文档补全插槽 CSS 约定与 cssVars 完整变量表。
+- 修复：Vue wrapper 重建组件（如 showValue 开关）后插槽内容丢失的问题（插槽容器改为整体搬入文字区/颜色区）。
+- 修复：进度条点击后无法直接使用键盘方向键的问题（拖动开始时自动聚焦）。
+- 修复：胶囊 `textRatio=0` 时文字区仍因最小宽度 164px 占位的问题，现 0 即完全隐藏。
+- 新增 Progress `readonly` 属性：与 disabled 行为一致但不置灰（`aria-readonly`）。
 
-## 0.2.0 - 2026-08-08
+## 0.2.2 - 2026-08-08
 
-- `preset` 简化为只接受文学名称字符串：胶囊 `初光 / 沧溟 / 玄夜 / 紫霄 / 银汉 / 熔金`，进度 `星火 / 迁流 / 幻境 / 汐潮`；不再支持编号、id、名称三选一或自定义预置对象。
-- `colors` / `seed` / `speed` 改为独立属性，传入即覆盖预置内置值，不传用预置默认；新增胶囊控制器 `setSeed()` / `setSpeed()`。
-- 移除 `interactive` 属性（指针扭曲效果统一由 `mouseColor` 控制，组件事件始终派发）。
-- 新增进度控制器 `setEdgeStyle('flow' | 'tide')` 热切换边界风格。
+- 修复：Progress 的 `setLabel()` 对 const 变量重新赋值，导致打包产物被 esbuild 拒绝、文档站无法构建的问题；label 热更新恢复正常。
 
-## 0.1.0 - 2026-08-07
+## 0.2.1 - 2026-08-08
+
+- 移除 `copy` / `showCopy` 属性：文字区内容改由插槽提供（Vue 默认插槽；H5/工厂用 `text` 选项），并新增颜色区插槽（Vue `#color`；H5/工厂用 `colorContent` 选项）。
+- 新增 `textRatio` 属性（0~100，单位 %）：控制文字区宽度占比，胶囊默认 39、进度条默认 54；写入统一变量 `--hj-text-width`，旧 `--hj-copy-*` 变量保留为兼容别名。
+- 新增进度条 `showValue` 属性（默认 true）：控制右侧百分比数字显示。
+- 插槽容器默认透明且只做几何定位：不传插槽即为纯画面；组件不再对插槽内容施加文字样式。
+- 移除进度条右下角 DRAG 提示（`dragLabel` 相关配置一并删除）。
+- 文字区容器应用 `--hj-text-radius` 并裁剪内容（默认 0，无影响）。
+- 新增控制器方法：`setText(content)` / `setColorContent(content)` / `setTextRatio(ratio)`（胶囊与进度条）。
+- `ready` / `error` 改为创建后异步触发（先创建、后监听也能收到）；Progress 补齐 WebGL 降级时的 `error` 事件。
+- `randomize()` 会把新 seed 同步回 `preset.seed`；Canvas2D 降级路径的 `seed` / `speed` 现在真实生效。
+- 新增 `setCssVars(vars)` / `setLabel(label)`（胶囊与进度条）、进度条 `setValueSuffix(suffix)`；Vue 组件实例暴露与 H5 对称的插槽/CSS 变量方法。
+- Progress 新增 `disabled`（禁用拖动/键盘、aria-disabled、置灰）、`label`、`valueSuffix`；Capsule 补 `role="img"` 并支持 `label`。
+- `min` / `max` 水线归一化到 `[min, max]`，键盘步进按范围百分比（方向键 ±2%、PageUp/PageDown ±10%），右侧数字仍显示原始 value。
+- 拖动进度时 `change` 按 rAF 合并为一帧一次，避免高频重渲染。
+- Vue 结构属性变化重建实例时会继承运行时状态（seed/speed/colors/textRatio/cssVars/value 等）。
+- 新增官方 Vue 组件 `ColorBackground`；Color 控制器补齐 `setSeed` / `setSpeed` / `setFallbackColor` / `setMouseColor`。
+- Vue wrapper 的 `id` / `data-*` / `title` 等普通属性会落到组件内部根节点；`class` / `style` 留在外层宿主并写入文档。
+- `colors` 支持更通用的写法：`#rgb` / `#rrggbb` / CSS 命名色（`red`、`green`…）/ `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 忽略（透明请用 `opacity`），新增公共工具 `normalizeColor(color)`。
+- 文档补全插槽 CSS 约定与 cssVars 完整变量表。
+
+## 0.2.0 - 2026-08-08
+
+- `preset` 简化为只接受文学名称字符串：胶囊 `初光 / 沧溟 / 玄夜 / 紫霄 / 银汉 / 熔金`，进度 `星火 / 迁流 / 幻境 / 汐潮`；不再支持编号、id、名称三选一或自定义预置对象。
+- `colors` / `seed` / `speed` 改为独立属性，传入即覆盖预置内置值，不传用预置默认；新增胶囊控制器 `setSeed()` / `setSpeed()`。
+- 移除 `interactive` 属性（指针扭曲效果统一由 `mouseColor` 控制，组件事件始终派发）。
+- 新增进度控制器 `setEdgeStyle('flow' | 'tide')` 热切换边界风格。
+
+## 0.1.0 - 2026-08-07
 
 - 从 画境观屿 演示项目抽出框架无关组件核心：`createCapsule` / `createProgressCapsule`。
 - 包名正式改为 `@5even7/dlc-ui`，入口：根入口、`/capsule`、`/progress`、`/color`、`/vue3`、`/vue2`，样式入口 `style.css` / 各组件 `style.css`。

package/README.md

@@ -1,277 +1,277 @@
-# @5even7/dlc-ui
-
-框架无关的 **星云胶囊**、**流体进度胶囊** 与 **星云背景层（dlc-color）** 组件库：WebGL2 实时渲染，不可用时自动降级 Canvas2D。一套核心，H5 / Vue2 / Vue3 都能用。
-
-零运行时依赖；现代浏览器加载原生 ESM，旧浏览器 / Vue2 老工具链走转译后的 legacy 构建（Canvas2D 降级），互不影响。
-
-## 发版规则
-
-默认每次发布**只递增补丁号（+0.01）**，例如 `0.2.0 → 0.2.1`；除非手动明确指定新版本号，否则不升次版本。
-
-## 安装
-
-```bash
-npm install @5even7/dlc-ui
-```
-
-## 预置列表
-
-| 类型 | 预置 | 说明 |
-| --- | --- | --- |
-| capsule | `初光`（NC-01）、`沧溟`（NC-02）、`玄夜`（NC-03）、`紫霄`（NC-04）、`银汉`（NC-05）、`熔金`（NC-06） | 星云材质 |
-| progress | `星火`（NC-10）、`迁流`（NC-11）、`幻境`（NC-12） | 流体进度 |
-| progress | `汐潮`（NC-13） | 潮汐边界（潮起潮落） |
-
-`dlc-color` 复用同一套星云渲染器，只做背景层，直接使用上表 capsule 的 6 个预置。
-
-`preset` 只接受上表中的文学名称（如 `'沧溟'`），大小写不敏感、首尾空格忽略；不传时使用默认预置 `初光`（胶囊/背景层）或 `星火`（进度条）。`colors`、`seed`、`speed` 是独立属性，传了覆盖预置内置值，不传用预置默认值。
-
-## H5 使用
-
-### 现代浏览器（ESM）
-
-```js
-import { createCapsule, createProgressCapsule } from '@5even7/dlc-ui';
-import '@5even7/dlc-ui/style.css';
-
-const capsule = createCapsule(document.querySelector('#host-a'), {
-  preset: '沧溟',
-  width: '100%',
-  height: 160,
-  text: '<span class="cap-name">沧溟</span>',          // 文字区插槽内容
-  colorContent: '<span class="cap-chip">DLC</span>',   // 颜色区插槽内容
-  textRatio: 39                                        // 文字区宽度占比（%）
-});
-
-const progress = createProgressCapsule(document.querySelector('#host-b'), {
-  preset: '汐潮',
-  width: 454,
-  height: 104,
-  text: '<span class="prog-name">画境观屿</span>',
-  showValue: true
-});
-
-progress.on('change', ({ value, source }) => console.log(value, source));
-```
-
-工厂调用用 `text` / `colorContent` 选项填插槽；Vue 组件直接用默认插槽和 `#color` 插槽（见下）。
-
-### 插槽与 CSS 约定（重要）
-
-两个组件都固定有两个插槽容器：
-
-- **默认插槽（文字区）**：占左侧 `textRatio` 宽度的区域；
-- **`#color` 插槽（颜色区）**：占剩余区域（文字区右侧到右边缘）。
-
-容器**默认完全透明、无内容**：不传插槽等于没有任何文字/覆盖层。容器只负责几何定位，对插槽内容施加的样式影响**只有**：
-
-1. `box-sizing: border-box` 会作用到插槽内所有元素（组件根节点统一规则）；
-2. `pointer-events: none` 会继承（组件要把点击/拖拽留给进度条和事件系统）；需要交互时在你的内容上写 `pointer-events: auto`；
-3. 根节点 `overflow: hidden` + `border-radius` 会裁剪超出区域的内容；文字区容器自身也带 `overflow: hidden`，设置 `--hj-text-radius` 时内容按圆角裁剪；
-4. **不继承组件任何文字样式**：颜色、字体、字距、大小写、padding、背景全是页面默认——空白盒子放进去就是“干净的盒子”。
-
-层级：canvas（1）< 颜色区插槽（3）< 文字区插槽（4）< 进度数字（5，仅进度条）。
-
-进度条的 `textRatio` 建议 ≤70%：再大时右侧进度数字会压到文字区上方；需要自定义数字就 `showValue=false` 并在 `#color` 插槽里自己写。
-
-### 星云背景层（dlc-color）
-
-把星云材质铺进任意容器当背景，效果与 Capsule 完全一致：
-
-```js
-import { createColorBackground } from '@5even7/dlc-ui/color';
-import '@5even7/dlc-ui/color/style.css';
-
-const background = createColorBackground(document.querySelector('#bg-host'), {
-  preset: '沧溟',
-  quality: 'auto'
-});
-
-background.setPreset('玄夜');
-background.pause();
-```
-
-层级规则：宿主会被自动设为 `position: relative; isolation: isolate`，色层是 `position: absolute; inset: 0; z-index: -1`，画在宿主普通内容**下面**——文字、按钮、图片直接放进宿主就能显示在星云上方，一行 CSS 都不用写。色层 z-index 可用 `--dlc-color-layer-z` 调整；宿主内需要保证浮在星云上的复杂层级内容可加 `position: relative; z-index: var(--dlc-color-content-z, 1)`。
-
-透明度与兜底色：`opacity`（0~1，默认 1）让宿主自己的背景透出来；`fallbackColor` 默认用预置底色兜底，消除 WebGL 首帧编译前的空窗闪烁，传十六进制色可自定义，传 `false` 可关闭。运行中可用 `setOpacity(value)` 热更新。`mouseColor` 默认开启，颜色随鼠标像油画一样旋涡，可传 `{ mouseColor: false }` 关闭，不影响宿主上其它元素的交互。
-
-### 旧浏览器 / CDN（UMD legacy）
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@5even7/dlc-ui/styles/theme.css" />
-<script src="https://unpkg.com/@5even7/dlc-ui/dist/index.umd.min.js"></script>
-<script>
-  const { createCapsule, createProgressCapsule } = window.CosmicCapsules;
-</script>
-```
-
-## Vue3
-
-```vue
-<script setup>
-import { CosmicCapsule, ProgressCapsule, ColorBackground } from '@5even7/dlc-ui/vue3';
-import '@5even7/dlc-ui/style.css';
-
-function onProgressChange({ value }) {
-  console.log(value);
-}
-</script>
-
-<template>
-  <CosmicCapsule preset="沧溟" width="100%" height="160" :text-ratio="45" @click="...">
-    <span class="cap-code">NC-02</span>
-    <span class="cap-name">沧溟</span>
-    <template #color><span class="cap-chip">DLC</span></template>
-  </CosmicCapsule>
-
-  <ProgressCapsule preset="汐潮" :width="454" :height="104" @change="onProgressChange">
-    <span class="prog-name">画境观屿</span>
-  </ProgressCapsule>
-
-  <ColorBackground preset="沧溟" style="height: 200px">
-    这段内容显示在星云背景上方
-  </ColorBackground>
-</template>
-```
-
-## Vue2
-
-```js
-import { CosmicCapsule, ProgressCapsule } from '@5even7/dlc-ui/vue2';
-import '@5even7/dlc-ui/style.css';
-
-export default {
-  components: { CosmicCapsule, ProgressCapsule },
-  template: `
-    <ProgressCapsule preset="汐潮" :width="454" :height="104" @change="onChange">
-      <span class="prog-name">画境观屿</span>
-      <template v-slot:color><span>自定义颜色区内容</span></template>
-    </ProgressCapsule>
-  `
-};
-```
-
-## 属性（props）
-
-两个组件共有：`preset`、`width`、`height`（数字=px，或 `px/%/vw/vh/vmin/vmax/em/rem` 字符串）、`colors`（4 个颜色，支持 `#rgb` / `#rrggbb` / CSS 命名色 / `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 会被忽略，透明请用组件级 `opacity`）、`textRatio`（文字区宽度占比 0~100，默认胶囊 39 / 进度条 54）、`label`（覆盖默认 aria-label，胶囊另带 `role="img"`）、`quality`（`auto/low/medium/high`）、`renderer`（`auto/webgl2/canvas2d`）、`respectReducedMotion`、`cssVars`。
-
-胶囊专属：`seed`、`speed`、`mouseColor`（颜色随鼠标旋涡，默认 `true`，关闭不影响 click/悬浮/长按等事件）。
-
-进度条专属：`value`、`min`、`max`（value 的合法区间，默认 0~100；**水线归一化到 [min, max]**，键盘 ±2% 与 PageUp/PageDown ±10% 都是“范围的百分比”，右侧数字仍显示原始 value）、`draggable`、`keyboard`、`disabled`（true 时同时禁用拖动/键盘、tabindex=-1、aria-disabled、视觉置灰）、`edgeStyle`（`flow/tide`）、`valueSuffix`（右侧数字后缀，默认 `%`）、`showValue`（是否显示右侧百分比数字，默认 `true`，`false` 只隐藏数字、不影响无障碍信息）。
-
-插槽内容属性（H5/工厂）：`text`、`colorContent`，支持 HTML 字符串或 DOM 节点（数组）；Vue 组件请用默认插槽 / `#color` 插槽。**注意：字符串走 innerHTML，不要传入不可信/用户直接输入的内容（XSS 风险）。**
-
-dlc-color 背景层（`createColorBackground(host, options)`）：`preset`、`colors`、`seed`、`speed`、`quality`、`renderer`、`mouseColor`、`respectReducedMotion`、`opacity`（0~1）、`fallbackColor`（预置底色 / 十六进制色 / false）。控制器支持 `setPreset / setColors / setSeed / setSpeed / setQuality / setOpacity / setFallbackColor / setMouseColor / randomize / pause / resume / dispose` 和 `ready / presetchange / error` 事件。Vue 里可用官方组件 `ColorBackground`（从 `@5even7/dlc-ui/vue2` 或 `/vue3` 导入），它的默认插槽内容会显示在背景层上方。
-
-胶囊控制器额外支持 `setSeed(seed)` / `setSpeed(speed)` / `setText(content)` / `setColorContent(content)` / `setTextRatio(ratio)` / `setCssVars(vars)` / `setLabel(label)` 热更新；进度控制器额外支持 `setEdgeStyle('flow' | 'tide')` / `setValueSuffix(suffix)` 和同样的插槽热更新方法。`setPreset` 只接受文学名称字符串（如 `'汐潮'`）。Vue 组件实例也暴露 `setText` / `setColorContent` / `setTextRatio` / `setCssVars` / `setLabel`（进度另有 `setValueSuffix`），与 H5 控制器对称。
-
-> 进度条是完全受控组件：组件自身不再自动增长，`value` 由使用方驱动。要自动步进，自己写定时器加值即可：
->
-> ```js
-> let value = 0;
-> const timer = setInterval(() => {
->   value = Math.min(100, value + 1);
->   progress.setValue(value); // 或 Vue 里改绑定的 value
-> }, 100);
-> // 组件销毁时记得 clearInterval(timer)
-> ```
-
-> API 是可扩展的：核心返回的控制器 `on(event, fn)` 接受任意事件名；Vue wrapper 会转发 `$emit`。`ready` / `error` 在创建后异步触发，所以先创建、后监听也能收到。attrs 落点：`id` / `data-*` / `title` 等普通属性会同步到组件内部根节点；`class` / `style` 落在外层宿主 `.hj-vue-host` 上（CSS 变量可继承到内部，类选择器请写成 `.my-class .hj-capsule-root`）。
-
-## 属性 vs cssVars 边界
-
-- **内容（文字/图片/按钮）**：只归插槽管，组件不施加任何样式；
-- **文字区宽度**：只归 `textRatio` 属性管（唯一入口，写入 `--hj-text-width`）；
-- **区域外观（背景/内边距/圆角/左侧距）**：只归 cssVars 管；
-- **星云颜料**：只归 `colors` 属性管（与 `#color` 插槽无关，前者改画布颜料，后者放你的覆盖内容）；
-- 旧的 `--hj-copy-*`、`--hj-progress-copy-*` 变量保留为**兼容别名**，只兜底不优先。
-
-优先级统一为：**`textRatio` > cssVars（新变量） > 旧别名 > 样式表默认**。
-
-## cssVars 完整变量表
-
-所有可调值都是 CSS 变量，直接覆盖即可：
-
-```css
-.hj-progress-root {
-  --hj-radius: 24px;
-  --hj-value-right: 16px;
-}
-```
-
-也可以在创建时传 `cssVars`：
-
-```js
-createProgressCapsule(el, {
-  preset: '汐潮',
-  cssVars: { '--hj-radius': '12px', '--hj-text-bg': 'rgba(0,0,0,0.4)' }
-});
-```
-
-| 变量 | 作用 | 默认 |
-| --- | --- | --- |
-| `--hj-text-width` | 文字区宽度（`textRatio` 写这里） | 胶囊 39% / 进度条 54% |
-| `--hj-text-min-width` | 文字区最小宽度（仅胶囊） | `164px` |
-| `--hj-text-left` | 文字区左侧距离（仅进度条） | `30px` |
-| `--hj-text-bg` | 文字区背景 | 透明 |
-| `--hj-text-pad` | 文字区内边距 | `0` |
-| `--hj-text-radius` | 文字区圆角（由容器应用，内容会被裁剪到圆角内） | `0` |
-| `--hj-radius` | 根节点圆角 | `999px` |
-| `--hj-bg` / `--hj-ink` / `--hj-muted` | 全局令牌（可被插槽内容引用） | 浅色主题值 |
-| `--hj-font` / `--hj-mono` | 字体令牌（可被插槽内容引用） | Inter / 等宽栈 |
-| `--hj-shadow` | 根节点阴影 | 柔和阴影 |
-| `--hj-value-right` | 进度数字右侧距离（仅进度条） | `30px` |
-| `--dlc-color-opacity` | 色层透明度（dlc-color） | `1` |
-| `--dlc-color-bg` | 色层兜底背景（dlc-color） | 预置底色 |
-| `--dlc-color-layer-z` | 色层 z-index（dlc-color） | `-1` |
-| `--dlc-color-content-z` | 宿主内容参考 z-index（dlc-color，由用户使用） | `1` |
-
-兼容别名（deprecated，只兜底）：`--hj-copy-width`、`--hj-copy-min-width`、`--hj-copy-pad-x`、`--hj-copy-left`、`--hj-copy-max-width`、`--hj-progress-copy-pad`、`--hj-progress-copy-bg`。
-
-## 事件
-
-| 组件 | 事件 | 载荷 |
-| --- | --- | --- |
-| capsule | `ready` / `presetchange` | `{ preset }` |
-| capsule | `click` / `pointerdown` / `pointerup` / `dblclick` | `{ event, preset }` |
-| capsule | `pointerenter` / `pointerleave` | `{ event, preset }` |
-| capsule | `error` | `{ message }`（WebGL2 不可用降级时触发） |
-| progress | `ready` / `presetchange` | `{ preset }` |
-| progress | `change` | `{ value, source }`，source ∈ `drag/keyboard/prop` |
-| progress | `dragstart` / `dragend` | `{ value }` |
-| progress | `error` | `{ message }` |
-
-## 兼容性
-
-| 目标 | 构建 | 渲染 |
-| --- | --- | --- |
-| Chrome 56+ / Edge 79+ / Firefox 51+ / Safari 15+ / iOS 15+ / 新版 Android WebView | `dist/*.mjs`（原生 ESM） | WebGL2 完整效果 |
-| IE11 / 旧 WebView / Vue2 老工具链（webpack4） | `dist/*.cjs` / `dist/index.umd.min.js`（ES5 + 内置 polyfill） | Canvas2D 降级动画 |
-
-现代浏览器永远加载不到 legacy 代码，所以老设备兼容不影响新浏览器的效果、性能与观感。
-
-## 开发
-
-```bash
-npm install
-npm run build   # 产出 dist（ESM + CJS + UMD）
-npm test        # node --test tests/
-```
-
-源码入口：`src/dlc-capsule/`（星云胶囊）、`src/dlc-progress/`（进度胶囊）、`src/dlc-color/`（星云背景层）、`src/config/`（预置/默认值/文案）、`src/core/`（调度/尺寸/质量/可见性等公共核心）。
-
-## 示例怎么看
-
-三个示例页都会展示全部 6 组星云胶囊与 4 组流体进度（含潮汐 TIDE），并为两类组件各提供一个控制台（可切换“全部/单个”目标、实时调节属性），属性表详细说明每个属性/方法/事件的用途。示例代码在 `examples/` 下。
-
-```bash
-npm run demo:h5      # http://127.0.0.1:4173/examples/h5/
-cd examples/vue3 && npm install && npm run dev   # http://127.0.0.1:5173/
-cd examples/vue2 && npm install && npm run dev   # http://127.0.0.1:5174/
-```
-
-> 首次运行前请先执行 `npm run build`（示例引用的是打包产物 `dist/`），三个示例的依赖各自独立安装。
-
-## License
-
-MIT
+# @5even7/dlc-ui
+
+框架无关的 **星云胶囊**、**流体进度胶囊** 与 **星云背景层（dlc-color）** 组件库：WebGL2 实时渲染，不可用时自动降级 Canvas2D。一套核心，H5 / Vue2 / Vue3 都能用。
+
+零运行时依赖；现代浏览器加载原生 ESM，旧浏览器 / Vue2 老工具链走转译后的 legacy 构建（Canvas2D 降级），互不影响。
+
+## 发版规则
+
+默认每次发布**只递增补丁号（+0.01）**，例如 `0.2.0 → 0.2.1`；除非手动明确指定新版本号，否则不升次版本。
+
+## 安装
+
+```bash
+npm install @5even7/dlc-ui
+```
+
+## 预置列表
+
+| 类型 | 预置 | 说明 |
+| --- | --- | --- |
+| capsule | `初光`（NC-01）、`沧溟`（NC-02）、`玄夜`（NC-03）、`紫霄`（NC-04）、`银汉`（NC-05）、`熔金`（NC-06） | 星云材质 |
+| progress | `星火`（NC-10）、`迁流`（NC-11）、`幻境`（NC-12） | 流体进度 |
+| progress | `汐潮`（NC-13） | 潮汐边界（潮起潮落） |
+
+`dlc-color` 复用同一套星云渲染器，只做背景层，直接使用上表 capsule 的 6 个预置。
+
+`preset` 只接受上表中的文学名称（如 `'沧溟'`），大小写不敏感、首尾空格忽略；不传时使用默认预置 `初光`（胶囊/背景层）或 `星火`（进度条）。`colors`、`seed`、`speed` 是独立属性，传了覆盖预置内置值，不传用预置默认值。
+
+## H5 使用
+
+### 现代浏览器（ESM）
+
+```js
+import { createCapsule, createProgressCapsule } from '@5even7/dlc-ui';
+import '@5even7/dlc-ui/style.css';
+
+const capsule = createCapsule(document.querySelector('#host-a'), {
+  preset: '沧溟',
+  width: '100%',
+  height: 160,
+  text: '<span class="cap-name">沧溟</span>',          // 文字区插槽内容
+  colorContent: '<span class="cap-chip">DLC</span>',   // 颜色区插槽内容
+  textRatio: 39                                        // 文字区宽度占比（%）
+});
+
+const progress = createProgressCapsule(document.querySelector('#host-b'), {
+  preset: '汐潮',
+  width: 454,
+  height: 104,
+  text: '<span class="prog-name">画境观屿</span>',
+  showValue: true
+});
+
+progress.on('change', ({ value, source }) => console.log(value, source));
+```
+
+工厂调用用 `text` / `colorContent` 选项填插槽；Vue 组件直接用默认插槽和 `#color` 插槽（见下）。
+
+### 插槽与 CSS 约定（重要）
+
+两个组件都固定有两个插槽容器：
+
+- **默认插槽（文字区）**：占左侧 `textRatio` 宽度的区域；
+- **`#color` 插槽（颜色区）**：占剩余区域（文字区右侧到右边缘）。
+
+容器**默认完全透明、无内容**：不传插槽等于没有任何文字/覆盖层。容器只负责几何定位，对插槽内容施加的样式影响**只有**：
+
+1. `box-sizing: border-box` 会作用到插槽内所有元素（组件根节点统一规则）；
+2. `pointer-events: none` 会继承（组件要把点击/拖拽留给进度条和事件系统）；需要交互时在你的内容上写 `pointer-events: auto`；
+3. 根节点 `overflow: hidden` + `border-radius` 会裁剪超出区域的内容；文字区容器自身也带 `overflow: hidden`，设置 `--hj-text-radius` 时内容按圆角裁剪；
+4. **不继承组件任何文字样式**：颜色、字体、字距、大小写、padding、背景全是页面默认——空白盒子放进去就是“干净的盒子”。
+
+层级：canvas（1）< 颜色区插槽（3）< 文字区插槽（4）< 进度数字（5，仅进度条）。
+
+进度条的 `textRatio` 建议 ≤70%：再大时右侧进度数字会压到文字区上方；需要自定义数字就 `showValue=false` 并在 `#color` 插槽里自己写。
+
+### 星云背景层（dlc-color）
+
+把星云材质铺进任意容器当背景，效果与 Capsule 完全一致：
+
+```js
+import { createColorBackground } from '@5even7/dlc-ui/color';
+import '@5even7/dlc-ui/color/style.css';
+
+const background = createColorBackground(document.querySelector('#bg-host'), {
+  preset: '沧溟',
+  quality: 'auto'
+});
+
+background.setPreset('玄夜');
+background.pause();
+```
+
+层级规则：宿主会被自动设为 `position: relative; isolation: isolate`，色层是 `position: absolute; inset: 0; z-index: -1`，画在宿主普通内容**下面**——文字、按钮、图片直接放进宿主就能显示在星云上方，一行 CSS 都不用写。色层 z-index 可用 `--dlc-color-layer-z` 调整；宿主内需要保证浮在星云上的复杂层级内容可加 `position: relative; z-index: var(--dlc-color-content-z, 1)`。
+
+透明度与兜底色：`opacity`（0~1，默认 1）让宿主自己的背景透出来；`fallbackColor` 默认用预置底色兜底，消除 WebGL 首帧编译前的空窗闪烁，传十六进制色可自定义，传 `false` 可关闭。运行中可用 `setOpacity(value)` 热更新。`mouseColor` 默认开启，颜色随鼠标像油画一样旋涡，可传 `{ mouseColor: false }` 关闭，不影响宿主上其它元素的交互。
+
+### 旧浏览器 / CDN（UMD legacy）
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@5even7/dlc-ui/styles/theme.css" />
+<script src="https://unpkg.com/@5even7/dlc-ui/dist/index.umd.min.js"></script>
+<script>
+  const { createCapsule, createProgressCapsule } = window.CosmicCapsules;
+</script>
+```
+
+## Vue3
+
+```vue
+<script setup>
+import { CosmicCapsule, ProgressCapsule, ColorBackground } from '@5even7/dlc-ui/vue3';
+import '@5even7/dlc-ui/style.css';
+
+function onProgressChange({ value }) {
+  console.log(value);
+}
+</script>
+
+<template>
+  <CosmicCapsule preset="沧溟" width="100%" height="160" :text-ratio="45" @click="...">
+    <span class="cap-code">NC-02</span>
+    <span class="cap-name">沧溟</span>
+    <template #color><span class="cap-chip">DLC</span></template>
+  </CosmicCapsule>
+
+  <ProgressCapsule preset="汐潮" :width="454" :height="104" @change="onProgressChange">
+    <span class="prog-name">画境观屿</span>
+  </ProgressCapsule>
+
+  <ColorBackground preset="沧溟" style="height: 200px">
+    这段内容显示在星云背景上方
+  </ColorBackground>
+</template>
+```
+
+## Vue2
+
+```js
+import { CosmicCapsule, ProgressCapsule } from '@5even7/dlc-ui/vue2';
+import '@5even7/dlc-ui/style.css';
+
+export default {
+  components: { CosmicCapsule, ProgressCapsule },
+  template: `
+    <ProgressCapsule preset="汐潮" :width="454" :height="104" @change="onChange">
+      <span class="prog-name">画境观屿</span>
+      <template v-slot:color><span>自定义颜色区内容</span></template>
+    </ProgressCapsule>
+  `
+};
+```
+
+## 属性（props）
+
+两个组件共有：`preset`、`width`、`height`（数字=px，或 `px/%/vw/vh/vmin/vmax/em/rem` 字符串）、`colors`（4 个颜色，支持 `#rgb` / `#rrggbb` / CSS 命名色 / `rgb()` / `rgba()`，统一归一化为小写 6 位十六进制；`rgba()` 的 alpha 会被忽略，透明请用组件级 `opacity`）、`textRatio`（文字区宽度占比 0~100，默认胶囊 39 / 进度条 54）、`label`（覆盖默认 aria-label，胶囊另带 `role="img"`）、`quality`（`auto/low/medium/high`）、`renderer`（`auto/webgl2/canvas2d`）、`respectReducedMotion`、`cssVars`。
+
+胶囊专属：`seed`、`speed`、`mouseColor`（颜色随鼠标旋涡，默认 `true`，关闭不影响 click/悬浮/长按等事件）。
+
+进度条专属：`value`、`min`、`max`（value 的合法区间，默认 0~100；**水线归一化到 [min, max]**，键盘 ±2% 与 PageUp/PageDown ±10% 都是“范围的百分比”，右侧数字仍显示原始 value）、`draggable`、`keyboard`（点击组件会自动聚焦，之后即可用方向键/PageUp/PageDown/Home/End）、`disabled`（禁用交互并置灰）、`readonly`（禁用交互但不置灰）、`edgeStyle`（`flow/tide`）、`valueSuffix`（右侧数字后缀，默认 `%`）、`showValue`（是否显示右侧百分比数字，默认 `true`，`false` 只隐藏数字、不影响无障碍信息）。
+
+插槽内容属性（H5/工厂）：`text`、`colorContent`，支持 HTML 字符串或 DOM 节点（数组）；Vue 组件请用默认插槽 / `#color` 插槽。**注意：字符串走 innerHTML，不要传入不可信/用户直接输入的内容（XSS 风险）。**
+
+dlc-color 背景层（`createColorBackground(host, options)`）：`preset`、`colors`、`seed`、`speed`、`quality`、`renderer`、`mouseColor`、`respectReducedMotion`、`opacity`（0~1）、`fallbackColor`（预置底色 / 十六进制色 / false）。控制器支持 `setPreset / setColors / setSeed / setSpeed / setQuality / setOpacity / setFallbackColor / setMouseColor / randomize / pause / resume / dispose` 和 `ready / presetchange / error` 事件。Vue 里可用官方组件 `ColorBackground`（从 `@5even7/dlc-ui/vue2` 或 `/vue3` 导入），它的默认插槽内容会显示在背景层上方。
+
+胶囊控制器额外支持 `setSeed(seed)` / `setSpeed(speed)` / `setText(content)` / `setColorContent(content)` / `setTextRatio(ratio)` / `setCssVars(vars)` / `setLabel(label)` 热更新；进度控制器额外支持 `setEdgeStyle('flow' | 'tide')` / `setValueSuffix(suffix)` 和同样的插槽热更新方法。`setPreset` 只接受文学名称字符串（如 `'汐潮'`）。Vue 组件实例也暴露 `setText` / `setColorContent` / `setTextRatio` / `setCssVars` / `setLabel`（进度另有 `setValueSuffix`），与 H5 控制器对称。
+
+> 进度条是完全受控组件：组件自身不再自动增长，`value` 由使用方驱动。要自动步进，自己写定时器加值即可：
+>
+> ```js
+> let value = 0;
+> const timer = setInterval(() => {
+>   value = Math.min(100, value + 1);
+>   progress.setValue(value); // 或 Vue 里改绑定的 value
+> }, 100);
+> // 组件销毁时记得 clearInterval(timer)
+> ```
+
+> API 是可扩展的：核心返回的控制器 `on(event, fn)` 接受任意事件名；Vue wrapper 会转发 `$emit`。`ready` / `error` 在创建后异步触发，所以先创建、后监听也能收到。attrs 落点：`id` / `data-*` / `title` 等普通属性会同步到组件内部根节点；`class` / `style` 落在外层宿主 `.hj-vue-host` 上（CSS 变量可继承到内部，类选择器请写成 `.my-class .hj-capsule-root`）。
+
+## 属性 vs cssVars 边界
+
+- **内容（文字/图片/按钮）**：只归插槽管，组件不施加任何样式；
+- **文字区宽度**：只归 `textRatio` 属性管（唯一入口，写入 `--hj-text-width`；`0` 即隐藏文字区）；
+- **区域外观（背景/内边距/圆角/左侧距）**：只归 cssVars 管；
+- **星云颜料**：只归 `colors` 属性管（与 `#color` 插槽无关，前者改画布颜料，后者放你的覆盖内容）；
+- 旧的 `--hj-copy-*`、`--hj-progress-copy-*` 变量保留为**兼容别名**，只兜底不优先。
+
+优先级统一为：**`textRatio` > cssVars（新变量） > 旧别名 > 样式表默认**。
+
+## cssVars 完整变量表
+
+所有可调值都是 CSS 变量，直接覆盖即可：
+
+```css
+.hj-progress-root {
+  --hj-radius: 24px;
+  --hj-value-right: 16px;
+}
+```
+
+也可以在创建时传 `cssVars`：
+
+```js
+createProgressCapsule(el, {
+  preset: '汐潮',
+  cssVars: { '--hj-radius': '12px', '--hj-text-bg': 'rgba(0,0,0,0.4)' }
+});
+```
+
+| 变量 | 作用 | 默认 |
+| --- | --- | --- |
+| `--hj-text-width` | 文字区宽度（`textRatio` 写这里） | 胶囊 39% / 进度条 54% |
+| `--hj-text-min-width` | 文字区最小宽度（仅胶囊） | `164px` |
+| `--hj-text-left` | 文字区左侧距离（仅进度条） | `30px` |
+| `--hj-text-bg` | 文字区背景 | 透明 |
+| `--hj-text-pad` | 文字区内边距 | `0` |
+| `--hj-text-radius` | 文字区圆角（由容器应用，内容会被裁剪到圆角内） | `0` |
+| `--hj-radius` | 根节点圆角 | `999px` |
+| `--hj-bg` / `--hj-ink` / `--hj-muted` | 全局令牌（可被插槽内容引用） | 浅色主题值 |
+| `--hj-font` / `--hj-mono` | 字体令牌（可被插槽内容引用） | Inter / 等宽栈 |
+| `--hj-shadow` | 根节点阴影 | 柔和阴影 |
+| `--hj-value-right` | 进度数字右侧距离（仅进度条） | `30px` |
+| `--dlc-color-opacity` | 色层透明度（dlc-color） | `1` |
+| `--dlc-color-bg` | 色层兜底背景（dlc-color） | 预置底色 |
+| `--dlc-color-layer-z` | 色层 z-index（dlc-color） | `-1` |
+| `--dlc-color-content-z` | 宿主内容参考 z-index（dlc-color，由用户使用） | `1` |
+
+兼容别名（deprecated，只兜底）：`--hj-copy-width`、`--hj-copy-min-width`、`--hj-copy-pad-x`、`--hj-copy-left`、`--hj-copy-max-width`、`--hj-progress-copy-pad`、`--hj-progress-copy-bg`。
+
+## 事件
+
+| 组件 | 事件 | 载荷 |
+| --- | --- | --- |
+| capsule | `ready` / `presetchange` | `{ preset }` |
+| capsule | `click` / `pointerdown` / `pointerup` / `dblclick` | `{ event, preset }` |
+| capsule | `pointerenter` / `pointerleave` | `{ event, preset }` |
+| capsule | `error` | `{ message }`（WebGL2 不可用降级时触发） |
+| progress | `ready` / `presetchange` | `{ preset }` |
+| progress | `change` | `{ value, source }`，source ∈ `drag/keyboard/prop` |
+| progress | `dragstart` / `dragend` | `{ value }` |
+| progress | `error` | `{ message }` |
+
+## 兼容性
+
+| 目标 | 构建 | 渲染 |
+| --- | --- | --- |
+| Chrome 56+ / Edge 79+ / Firefox 51+ / Safari 15+ / iOS 15+ / 新版 Android WebView | `dist/*.mjs`（原生 ESM） | WebGL2 完整效果 |
+| IE11 / 旧 WebView / Vue2 老工具链（webpack4） | `dist/*.cjs` / `dist/index.umd.min.js`（ES5 + 内置 polyfill） | Canvas2D 降级动画 |
+
+现代浏览器永远加载不到 legacy 代码，所以老设备兼容不影响新浏览器的效果、性能与观感。
+
+## 开发
+
+```bash
+npm install
+npm run build   # 产出 dist（ESM + CJS + UMD）
+npm test        # node --test tests/
+```
+
+源码入口：`src/dlc-capsule/`（星云胶囊）、`src/dlc-progress/`（进度胶囊）、`src/dlc-color/`（星云背景层）、`src/config/`（预置/默认值/文案）、`src/core/`（调度/尺寸/质量/可见性等公共核心）。
+
+## 示例怎么看
+
+三个示例页都会展示全部 6 组星云胶囊与 4 组流体进度（含潮汐 TIDE），并为两类组件各提供一个控制台（可切换“全部/单个”目标、实时调节属性），属性表详细说明每个属性/方法/事件的用途。示例代码在 `examples/` 下。
+
+```bash
+npm run demo:h5      # http://127.0.0.1:4173/examples/h5/
+cd examples/vue3 && npm install && npm run dev   # http://127.0.0.1:5173/
+cd examples/vue2 && npm install && npm run dev   # http://127.0.0.1:5174/
+```
+
+> 首次运行前请先执行 `npm run build`（示例引用的是打包产物 `dist/`），三个示例的依赖各自独立安装。
+
+## License
+
+MIT