@5even7/dlc-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-08-07
+
+- 从 画境观屿 演示项目抽出框架无关组件核心：`createCapsule` / `createProgressCapsule`。
+- 包名正式改为 `@5even7/dlc-ui`，入口：根入口、`/capsule`、`/progress`、`/color`、`/vue3`、`/vue2`，样式入口 `style.css` / 各组件 `style.css`。
+- 目录重构为组件独立文件夹：`src/dlc-capsule`、`src/dlc-progress`、`src/dlc-color`，共享预置/配色/默认值/文案集中在 `src/config/`，渲染与公共逻辑在 `src/core/`。
+- 删除 NC-07～NC-09 柔光流带（aurora）及对应 shader，胶囊仅保留 NC-01～NC-06 星云材质。
+- 新增 `dlc-color`：复用同一星云渲染器做背景层（`createColorBackground`），与 Capsule 效果一致，支持 z-index 层级变量。
+- 新增 `NC-13 TIDE` 潮汐进度预置（`edgeStyle: 'tide'`），原有进度数据冻结不变。
+- 尺寸支持数字（px）与 `px/%/vw/vh/vmin/vmax/em/rem` 字符串；默认值集中在 `src/config/defaults.js`。
+- 文案集中在 `src/config/copy.js`，可按实例覆盖。
+- 事件系统开放：`on/off` 接受任意事件名；Vue wrapper 转发 `$emit`。
+- 性能：WebGL2 激活时跳过隐藏的 Canvas2D 每帧绘制；组件级可见性（IntersectionObserver + 页面可见性）；质量档位。
+- 构建：Rollup 产出现代 ESM + legacy CJS/UMD（ES5 + polyfill），现代浏览器零影响。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yizhe21803
+
+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

@@ -0,0 +1,248 @@
+# @5even7/dlc-ui
+
+框架无关的**星云胶囊**、**流体进度胶囊**与**星云背景层（dlc-color）**组件库：WebGL2 实时渲染，WebGL2 不可用时自动降级 Canvas2D。一套核心，H5 / Vue2 / Vue3 都能用，每个胶囊/进度条/背景层都是独立组件，通过 `preset` 选择外观。
+
+零运行时依赖；现代浏览器加载原生 ESM（完整效果），旧浏览器 / Vue2 老工具链走转译后的 legacy 构建（Canvas2D 降级），互不影响。
+
+## 安装
+
+```bash
+npm install @5even7/dlc-ui
+```
+
+## 预置列表
+
+| 类型 | 预置 | 说明 |
+| --- | --- | --- |
+| capsule | `NC-01` ORIGINAL / `NC-02` OCEAN / `NC-03` KLEIN / `NC-04` ULTRAVIOLET / `NC-05` CHROME / `NC-06` PLUS | 星云材质 |
+| progress | `NC-10` MODEL TRAINING / `NC-11` AGENT MIGRATION / `NC-12` VISUAL TRAINING | 流体进度 |
+| progress | `NC-13` TIDE | 潮汐边界（潮起潮落） |
+
+`dlc-color` 复用同一套星云渲染器，只做背景层，没有自己的预置表，直接使用上表 capsule 的 6 个预置。
+
+`preset` 可以传 id（`'ocean'`）、编号（`'NC-02'`）、名称（`'OCEAN'`）或自定义预置对象（含 `colors` 等字段）。
+
+## H5 使用
+
+### 现代浏览器（ESM）
+
+```js
+import { createCapsule, createProgressCapsule } from '@5even7/dlc-ui';
+import '@5even7/dlc-ui/style.css';
+
+const capsule = createCapsule(document.querySelector('#host-a'), {
+  preset: 'ocean',
+  width: '100%',
+  height: 160
+});
+
+const progress = createProgressCapsule(document.querySelector('#host-b'), {
+  preset: 'tide',
+  width: 454,
+  height: 104
+});
+
+progress.on('change', ({ value, source }) => console.log(value, source));
+```
+
+### 星云背景层（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: 'ocean',
+  quality: 'auto'
+});
+
+// 需要时再切换/暂停
+background.setPreset('klein');
+background.pause();
+```
+
+层级规则：宿主会被自动设为 `position: relative; isolation: isolate`，色层是 `position: absolute; inset: 0; z-index: -1`，画在宿主普通内容**下面**——所以文字、按钮、图片直接放进宿主就能显示在星云上方，一行 CSS 都不用写：
+
+```html
+<style>
+  #bg-host {
+    height: 240px;
+    border-radius: 16px;
+    overflow: hidden;
+  }
+</style>
+<div id="bg-host">
+  <div class="content">放在星云上面的内容（不需要任何定位）</div>
+</div>
+```
+
+色层 z-index 可用 CSS 变量 `--dlc-color-layer-z` 调整；如果宿主里某个内容元素自己有复杂层级、想确保浮在星云上，也可以给它 `position: relative; z-index: var(--dlc-color-content-z, 1)`，两种写法都行。
+
+> 隔离说明：宿主自动带 `isolation: isolate`，会成为一个独立层叠上下文。绝大多数场景这正是你要的“背景和内容一体化”，色层与内容都被密封在宿主内，不会影响页面其它层；但宿主内部 `position: fixed` 或负 `z-index` 的子元素也会被限制在这个宿主内，不能穿出盒子去和页面其它元素混层。需要逃出宿主的弹层/浮层，请渲染到宿主外部（例如把 `fixed` 层挂到 body，或在 Vue 里用 Teleport）。
+
+透明度与兜底色：`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 } from '@5even7/dlc-ui/vue3';
+import '@5even7/dlc-ui/style.css';
+
+function onProgressChange({ value }) {
+  console.log(value);
+}
+</script>
+
+<template>
+  <CosmicCapsule preset="ocean" width="100%" height="160" @click="...">
+  <ProgressCapsule preset="tide" :width="454" :height="104" @change="onProgressChange" />
+</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="tide" :width="454" :height="104" @change="onChange" />'
+};
+```
+
+## 属性（props）
+
+两个组件共有的属性：`preset`、`width`、`height`（数字=px，或 `px/%/vw/vh/vmin/vmax/em/rem` 字符串）、`colors`、`quality`（`auto/low/medium/high`）、`renderer`（`auto/webgl2/canvas2d`，`canvas2d` 可强制走降级路径，便于对比观感或省电）、`respectReducedMotion`、`copy`、`cssVars`。
+
+星云胶囊专属：`seed`、`speed`、`interactive`（指针交互，默认 `true`）、`mouseColor`（颜色随鼠标旋涡，默认 `true`；关闭后不影响 click/悬浮/长按等事件）。
+
+进度胶囊专属：`value`、`min`、`max`、`draggable`、`keyboard`、`edgeStyle`（`flow/tide`）。
+
+dlc-color 背景层专属（`createColorBackground(host, options)`）：`preset`、`colors`、`seed`、`speed`、`quality`、`renderer`、`mouseColor`、`respectReducedMotion`、`opacity`（0~1）、`fallbackColor`（预置底色/十六进制色/false）。它返回的控制器支持 `setPreset / setColors / setQuality / setOpacity / randomize / pause / resume / dispose` 和 `ready / presetchange / error` 事件。
+
+> 进度条是完全受控组件：组件自身不再自动增长，`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` 并允许 class/style/attrs 透传到根节点；未知 props 会被保留，后续新增属性/事件不需要破坏性变更。
+
+## 事件
+
+| 组件 | 事件 | 载荷 |
+| --- | --- | --- |
+| 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 }` |
+
+## 样式自定义
+
+所有可调值都是 CSS 变量，直接覆盖即可：
+
+```css
+.hj-progress-root {
+  --hj-radius: 24px;
+  --hj-value-right: 16px;
+}
+```
+
+也可以在创建时传 `cssVars`：
+
+```js
+createProgressCapsule(el, { preset: 'tide', cssVars: { '--hj-radius': '12px' } });
+```
+
+主要变量：`--hj-radius`、`--hj-bg`、`--hj-ink`、`--hj-muted`、`--hj-font`、`--hj-mono`、`--hj-copy-width`、`--hj-copy-min-width`、`--hj-copy-pad-x`、`--hj-copy-gradient`、`--hj-shadow`、`--hj-name-size`、`--hj-copy-left`、`--hj-value-right`、`--hj-copy-max-width`。
+
+## 文案
+
+所有品牌文案集中在 `src/config/copy.js`（`COPY`），可通过 `copy` 属性按实例覆盖，例如 `copy: { brandName: '我的品牌', dragLabel: 'DRAG ME' }`。
+
+## 兼容性
+
+| 目标 | 构建 | 渲染 |
+| --- | --- | --- |
+| 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/` 下。
+
+### H5 示例（最轻量，无需前端工程）
+
+```bash
+npm run demo:h5
+```
+
+浏览器打开 `http://127.0.0.1:4173/examples/h5/`。页面使用 `dist/index.umd.min.js`（UMD 全局 `CosmicCapsules`），双击 HTML 文件不能运行（ES Module 需要 HTTP 服务）。
+
+### Vue3 示例
+
+```bash
+cd examples/vue3
+npm install
+npm run dev
+```
+
+浏览器打开 `http://127.0.0.1:5173/`。示例通过 `file:../..` 直接引用本地包源码构建产物，展示 `@5even7/dlc-ui/vue3` 组件的完整用法（v-for 渲染全部实例 + 控制台调节）。
+
+### Vue2 示例
+
+```bash
+cd examples/vue2
+npm install
+npm run dev
+```
+
+浏览器打开 `http://127.0.0.1:5174/`。Vue2.7 + Vite（`@vitejs/plugin-vue2`）工程，展示 `@5even7/dlc-ui/vue2` 组件的完整用法。
+
+也可以从 `publish/` 根目录直接跑：
+
+```bash
+npm run demo:vue3   # http://127.0.0.1:5173/
+npm run demo:vue2   # http://127.0.0.1:5174/
+```
+
+> 首次运行时请先确保 `publish/` 下已执行过 `npm run build`（示例引用的是打包产物 `dist/`），三个示例的依赖各自独立安装。
+
+## License
+
+MIT