npm - @hxdhxd/harmony-flow-ui - Versions diffs - 0.1.1 → 0.2.0 - Mend

@hxdhxd/harmony-flow-ui 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -1,197 +1,312 @@
-# Harmony Flow UI
-面向通用 React 场景的轻量组件库。默认视觉取意 HarmonyOS 7：清透白底、云水浅蓝、柔和层级与克制动效，同时通过 CSS Design Tokens 支持运行时定制。
-## 项目概览
-- 137 个可用组件，覆盖基础控件、表单、导航、数据展示、反馈、布局、协作、调度与 AI 交互场景
-- React + TypeScript 实现，同时输出 ESM、CommonJS、类型声明和独立样式文件
-- 内置组件展厅、成品场景、交互示例、Props 文档与无障碍说明
-- 支持主题 Token、界面密度以及桌面、平板和移动视口预览
-- 统一质量门覆盖类型检查、构建、144 项公开 API、142 条展示路由、浏览器交互和视觉回归
-## 项目结构
-```text
-src/       组件实现、主题 Token 与样式
-demo/      组件展厅、文档和成品场景
-scripts/   构建、静态服务与维护脚本
-test/      API、浏览器、文档、视觉及完整性测试
-plan/      批次计划与完成记录
-```
-## 本地运行
-```powershell
-npm install
-npm run check
-npm run build
-npm run build:demo
-npm run serve
-```
-默认静态服务地址为 `http://127.0.0.1:4173`。
-`npm run test:quality` 是统一质量门，覆盖类型、正式构建、公共 API、浏览器路由、组件文档、视觉证据与完整性。质量门还会锁定 HarmonyOS 7 的白＋浅蓝主题，并按文件阻止新增渐变、毛玻璃、超限圆角、阴影和组件文档裸色值；现有功能性视觉与历史样式只允许逐步减少，不允许数量反弹或转移到其他文件。
-可单独执行以下视觉规范检查：
-```powershell
-npm run test:theme-contract
-npm run test:ui-quality-gate
-npm run test:ui-quality-gate:self-test
-```
-展示页由 esbuild 正式构建，并由项目内 Node 静态服务托管，不使用 Vite。
-展示页提供“组件展厅”和“成品场景”两个入口：前者包含组件分类、搜索、真实交互预览、示例代码、Props 与无障碍说明，后者展示学习工作台、身份入口和运营洞察等跨组件组合。页面底部提供安装、样式引入与 ThemeProvider 的快速接入示例。
-核心组件详情支持可复制 URL，例如 `/components/button`；成品页支持 `/templates/dashboard`、`/templates/onboarding` 与 `/templates/insights` 全屏预览。全屏预览可实时切换主题色、界面密度以及桌面、平板和移动视口。
-## 发布状态与下一步
-正式 npm 包名为 `@hxdhxd/harmony-flow-ui`，当前版本为 `0.1.1`。后续建议在每次发布前更新版本号、运行完整质量门，并在 GitHub 创建对应 Release 或维护变更日志。
-本项目采用 [MIT License](./LICENSE)，允许免费用于个人和商业项目；再分发时须保留原许可证和版权声明。
-## 在其他项目中使用
-### 环境要求
-- Node.js 18 或更高版本
-- React 18 或更高版本
-- React DOM 18 或更高版本
-### npm 正式安装
-在目标 React 项目中执行：
-```powershell
-npm install @hxdhxd/harmony-flow-ui
-```
-如果目标项目还没有 React：
-```powershell
-npm install react react-dom @hxdhxd/harmony-flow-ui
-```
-在应用入口导入一次全局样式，然后直接使用组件：
-```tsx
-import { Button, ThemeProvider } from '@hxdhxd/harmony-flow-ui';
-import '@hxdhxd/harmony-flow-ui/style.css';
-export default function App() {
-  return (
-    <ThemeProvider tokens={{ colorPrimary: '#0a7cff' }}>
-      <Button onClick={() => console.log('saved')}>保存更改</Button>
-    </ThemeProvider>
-  );
-}
-```
-`ThemeProvider` 建议放在应用根部。主题覆盖支持颜色、形状、阴影与动效语义令牌。新代码优先使用 `radiusControl`、`radiusPanel`、`radiusOverlay`、`shadowPopover` 与 `shadowModal`；`radiusMd`、`radiusLg`、`shadowElevated` 仅为现有消费者保留，后续版本将逐步迁移。
-默认主题继续遵循 HarmonyOS 7 的白色内容面、浅蓝窗口背景、鸿蒙蓝主强调色与深蓝正文。形状和深度令牌建议按语义覆盖，而不是为单个组件写死圆角或阴影。
-### Next.js App Router
-在 `app/layout.tsx` 中导入全局样式，并通过客户端组件挂载主题：
-```tsx
-// app/providers.tsx
-'use client';
-import { ThemeProvider } from '@hxdhxd/harmony-flow-ui';
-export function Providers({ children }: { children: React.ReactNode }) {
-  return <ThemeProvider>{children}</ThemeProvider>;
-}
-```
-```tsx
-// app/layout.tsx
-import '@hxdhxd/harmony-flow-ui/style.css';
-import { Providers } from './providers';
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="zh-CN">
-      <body><Providers>{children}</Providers></body>
-    </html>
-  );
-}
-```
-### 在其他项目中安装本地构建包
-先在本仓库生成经过验证的 npm 压缩包：
-```powershell
-npm run test:package
-npm pack
-```
-然后在目标项目中安装生成的 `.tgz` 文件（请替换为实际路径和文件名）：
-```powershell
-npm install "D:\path\to\harmony-flow-ui-0.1.1.tgz"
-```
-安装后仍按正式 npm 包的方式从 `@hxdhxd/harmony-flow-ui` 导入。当前不建议直接通过 GitHub URL 安装，因为仓库不提交 `dist/`，Git 依赖安装流程无法保证生成完整发布产物。
-### 更新版本
-在目标项目中更新到最新版：
-```powershell
-npm install @hxdhxd/harmony-flow-ui@latest
-```
-## 构建产物
-执行 `npm run build` 后，`dist/` 将包含：
-- `index.js`：ESM 入口
-- `index.cjs`：CommonJS 入口
-- `index.d.ts` / `index.d.cts`：类型声明
-- `index.css`：组件样式
-## 发布
-包名使用当前 npm 账号的个人 scope `@hxdhxd`。发布账号必须拥有该 scope，并登录 npm 官方注册表：
-```powershell
-npm login --registry=https://registry.npmjs.org/
-npm whoami --registry=https://registry.npmjs.org/
-npm view @hxdhxd/harmony-flow-ui --registry=https://registry.npmjs.org/
-```
-发布前可在本地验证实际 tarball 内容：
-```powershell
-npm run build
-npm run test:package
-npm pack
-```
-正式发布：
-```powershell
-npm publish --access public --registry=https://registry.npmjs.org/
-```
-发布完成后验证注册表中的版本：
-```powershell
-npm view @hxdhxd/harmony-flow-ui version --registry=https://registry.npmjs.org/
-```
-`npm publish` 会先执行完整质量门；`prepack` 会重新检查类型、构建 ESM/CJS/CSS/类型声明，并验证发布包只包含 README、LICENSE、package.json 和 `dist/`。
-## 导航组件
-导航模块包含 `FloatingNav`、`Sidebar`、`Breadcrumb`、`DropdownMenu`、`MegaMenu`、`MobileNavigation`、`Scrollspy` 与 `ShrinkNav`。`MobileNavigation` 通过 `mode="drawer | fullscreen"` 覆盖汉堡抽屉和全屏导航。
-所有导航组件共享 `NavigationItem`，业务选择事件统一为 `onItemSelect(item)`；该命名刻意避开 React 原生 DOM 的 `onSelect` 事件。
+# Harmony Flow UI
+面向通用 React 场景的轻量组件库。默认视觉取意 HarmonyOS 7：清透白底、云水浅蓝、柔和层级与克制动效，同时通过 CSS Design Tokens 支持运行时定制。
+## 组件工作区布局改造（2026-09-03）
+展示站现采用顶部产品导航、九类组件导航、159组件卡片/列表浏览、全局搜索、收藏与最近访问。组件详情保持原URL，提供本页目录、真实预览与基于文档Props的属性控制。复杂对象和回调沿用可运行示例，浮层开关由示例触发器管理。
+- 本地预览：`npm run build:demo` 后运行 `npm run serve`，访问 `http://127.0.0.1:6633`。
+- 构建产物：`build/workspace-<构建时间>`；`demo-dist` 为兼容运行入口，旧产物先归档到 `laji`。
+- 组件查找：Ctrl/Cmd+K、分类、中文用途/英文别名、首字母、分页、收藏和最近访问。
+- 组合与模板：六个组合模式、三个现有模板、源码预览及完整模板ZIP。
+- [改造执行与验收](./plan/frontend/component-workspace-20260903/04-执行与验收.md)
+## 0.2.0 版本
+前十批交互组件和组件工作区统一纳入0.2.0，保留0.1.2公开API。发布记录见[0.2.0](./plan/release/0.2.0.md)。
+```sh
+npm install @hxdhxd/harmony-flow-ui@0.2.0
+```
+## 项目概览
+- 当前工作区含 159 个可用组件（0.2.0新增共 22 个交互组件，另增强原有看板），覆盖基础控件、表单、导航、数据展示、反馈、布局、协作、调度与 AI 交互场景
+- React + TypeScript 实现，同时输出 ESM、CommonJS、类型声明和独立样式文件
+- 内置组件展厅、成品场景、交互示例、Props 文档与无障碍说明
+- 支持主题 Token、界面密度以及桌面、平板和移动视口预览
+- 统一质量门覆盖类型检查、构建、166 项公开 API、164 条展示路由、浏览器交互和视觉回归
+## 第十批：乐观更新（2026-09-07，纳入0.2.0）
+新增泛型 `OptimisticUpdate`：收藏、通知偏好等目标值先显示，再串行保存；等待期间合并最后一次意图，最终失败回滚最近确认值，支持重试及对象切换后的旧响应隔离。
+`initialValue`仅初始化；业务对象或服务端版本变化时更新`operationKey`。`onUpdate(next, signal)`须返回服务端确认值，业务负责超时、取消配合和版本冲突。用于绝对目标值设置，不用于必须逐条执行的命令。
+预览 `/components/optimisticupdate`；构建 `node test/build-douyin-batch10.mjs`；专项 `python test/verify-douyin-batch10.py`；兼容 `node test/verify-douyin-batch10-api.mjs`。详见[第十批执行与验收](./plan/development/douyin-20260907-10/执行与验收.md)及[后续总计划](./plan/development/抖音参考交互模式总计划.md)。
+## 抖音参考交互总计划与第九批（2026-09-07，纳入0.2.0）
+- [未覆盖交互总计划：第九至二十五批](./plan/development/抖音参考交互模式总计划.md)：新增、增强、组合与可选动效统一排期，避免与旧质量整改批次混淆。
+- 第九批新增 `LoadMore`（异步加载与显式重试）、`InfiniteScroll`（进入底部触发并保留手动入口）、`LazyLoad`（首次进入视口挂载并保留子树）。
+- 预览：`/components/loadmore`、`/components/infinitescroll`、`/components/lazyload`。
+- 构建：`node test/build-douyin-batch9.mjs`；专项：`python test/verify-douyin-batch9.py`；兼容：`node test/verify-douyin-batch9-api.mjs`。
+- [第九批执行与验收](./plan/development/douyin-20260907-09/执行与验收.md)。`onLoad(signal)` 由业务维护游标、追加数据、检查取消信号；`resetKey` 更换查询。触底持续可见不自动循环拉取，失败由用户重试。
+## 第七批：操作后撤销（2026-09-03，纳入0.2.0）
+新增 `UndoNotice`，区分异步撤销中、成功、失败重试与过期；默认无倒计时，不自动消失。`onUndo(signal)` 只有在业务确认恢复成功后才 resolve；业务负责权限、幂等、超时和持久恢复入口。更换 `operationKey` 重置会话并中止旧请求信号。
+预览 `/components/undonotice`。无删除构建：`node test/build-douyin.mjs --batch7`，产物 `build/douyin-20260903-07`；复验 `python test/verify-douyin-batch7.py`。[第七批执行与验收](./plan/development/douyin-20260903-07/执行与验收.md)。
+## 第六批：行操作与逐项确认（2026-09-03，纳入0.2.0）
+- `SwipeActions`：左滑露出行操作，右滑/Escape收起；显式按钮提供键盘替代，滑动不执行删除。预览 `/components/swipeactions`。
+- `ChecklistConfirm`：逐项确认全部后提交，内容/对象变化清空，每次提交后重新确认。预览 `/components/checklistconfirm`。
+组件只发出操作请求，业务负责权限、幂等和异步结果。运行 `node test/build-douyin.mjs --batch6` 构建到 `build/douyin-20260903-06`，运行 `python test/verify-douyin-batch6.py` 复验。[第六批执行与验收](./plan/development/douyin-20260903-06/执行与验收.md)。
+## 第五批：防误触确认（2026-09-02，纳入0.2.0）
+- `HoldToConfirm`：长按达到时长才发出请求，提前松开或失焦取消；提供无需持续按住的分步确认。预览 `/components/holdtoconfirm`。
+- `TypedConfirm`：确认文字精确匹配后才可提交，发出请求后清空；操作对象变化重置。预览 `/components/typedconfirm`。
+两者均只提供前端确认，不执行数据删除，不替代后端权限与幂等校验。业务通过 `loading`、`error` 管理结果；更换操作对象必须更新 `actionKey`。执行 `node test/build-douyin.mjs --batch5` 生成项目内正式产物及测试夹具，再运行 `python test/verify-douyin-batch5.py`。范围与证据见 [第五批执行与验收](./plan/development/douyin-20260902-05/执行与验收.md)。
+## 本地新增交互组件（2026-09-02，纳入0.2.0）
+| 组件 | 用途 | 本地预览路径 |
+| --- | --- | --- |
+| ReadMore | 长文原地展开/收起，短文自动隐藏操作 | `/components/readmore` |
+| AnnouncementBar | 可暂停轮播公告，支持焦点、后台与减少动态暂停 | `/components/announcementbar` |
+| OnboardingChecklist | 由业务状态驱动的任务清单与进度反馈 | `/components/onboardingchecklist` |
+| SortableList | 同列表指针/触摸/键盘排序，支持取消与禁用 | `/components/sortablelist` |
+素材对应关系、范围、测试证据和回滚说明见 [本批执行与验收](./plan/development/douyin-20260902/执行与验收.md)。本批正式产物位于 `build/douyin-20260902-01`；开发时未单独发布，本次统一纳入0.2.0。
+本批可复验命令：
+```powershell
+node test/build-douyin.mjs
+node test/verify-douyin-api.mjs
+npm run test:api
+# 先启动 npm run serve，以下浏览器测试使用本地 6633 端口
+python test/verify-douyin-patterns.py
+```
+`test/build-douyin.mjs` 关闭构建自动清理，追加备份旧产物并在项目内生成构建，同时同步既有 `dist` 和 `demo-dist` 兼容入口。安装包测试使用项目内临时目录，并将测试结束后的目录移动到 `laji/package-tests`，不会永久删除。
+## 项目结构
+```text
+src/       组件实现、主题 Token 与样式
+demo/      组件展厅、文档和成品场景
+scripts/   构建、静态服务与维护脚本
+test/      API、浏览器、文档、视觉及完整性测试
+plan/      批次计划与完成记录
+```
+## 本地运行
+```powershell
+npm install
+npm run check
+npm run build
+npm run build:demo
+npm run serve
+```
+默认静态服务地址为 `http://127.0.0.1:6633`。服务监听 `0.0.0.0`，可通过服务器 IP 从外部访问。
+`npm run test:quality` 是统一质量门，覆盖类型、正式构建、公共 API、浏览器路由、组件文档、视觉证据与完整性。质量门还会锁定 HarmonyOS 7 的白＋浅蓝主题，并按文件阻止新增渐变、毛玻璃、超限圆角、阴影和组件文档裸色值；现有功能性视觉与历史样式只允许逐步减少，不允许数量反弹或转移到其他文件。
+可单独执行以下视觉规范检查：
+```powershell
+npm run test:theme-contract
+npm run test:ui-quality-gate
+npm run test:ui-quality-gate:self-test
+```
+展示页由 esbuild 正式构建，并由项目内 Node 静态服务托管，不使用 Vite。
+## 部署预览页
+执行以下命令生成可直接上传服务器的部署目录：
+```powershell
+npm run build:preview
+```
+将生成的 `preview-deploy/` 整个上传到服务器。服务器只需安装 Node.js 18 或更高版本，不需要上传源码、`node_modules/`、测试、计划、备份或开发依赖，也不需要执行 `npm install`。
+在服务器的 `preview-deploy/` 目录中启动：
+```bash
+npm start
+```
+默认监听 `0.0.0.0:6633`，请同时在服务器防火墙或云安全组放行 TCP 6633。需要守护进程时，可使用服务器已有的 systemd、Supervisor 或 PM2 托管 `npm start`。
+展示页提供概览、组件、组合模式、页面模板、设计与资源入口。组件通过分类、全局搜索和卡片浏览发现；安装说明集中在资源页，主题说明集中在设计页。
+核心组件详情支持可复制 URL，例如 `/components/button`；成品页支持 `/templates/dashboard`、`/templates/onboarding` 与 `/templates/insights` 全屏预览。全屏预览可实时切换主题色、界面密度以及桌面、平板和移动视口。
+## 发布状态与下一步
+正式 npm 包名为 `@hxdhxd/harmony-flow-ui`，当前版本为 `0.1.1`。后续建议在每次发布前更新版本号、运行完整质量门，并在 GitHub 创建对应 Release 或维护变更日志。
+本项目采用 [MIT License](./LICENSE)，允许免费用于个人和商业项目；再分发时须保留原许可证和版权声明。
+## 在其他项目中使用
+### 环境要求
+- Node.js 18 或更高版本
+- React 18 或更高版本
+- React DOM 18 或更高版本
+### npm 正式安装
+在目标 React 项目中执行：
+```powershell
+npm install @hxdhxd/harmony-flow-ui
+```
+如果目标项目还没有 React：
+```powershell
+npm install react react-dom @hxdhxd/harmony-flow-ui
+```
+在应用入口导入一次全局样式，然后直接使用组件：
+```tsx
+import { Button, ThemeProvider } from '@hxdhxd/harmony-flow-ui';
+import '@hxdhxd/harmony-flow-ui/style.css';
+export default function App() {
+  return (
+    <ThemeProvider tokens={{ colorPrimary: '#0a7cff' }}>
+      <Button onClick={() => console.log('saved')}>保存更改</Button>
+    </ThemeProvider>
+  );
+}
+```
+`ThemeProvider` 建议放在应用根部。主题覆盖支持颜色、形状、阴影与动效语义令牌。新代码优先使用 `radiusControl`、`radiusPanel`、`radiusOverlay`、`shadowPopover` 与 `shadowModal`；`radiusMd`、`radiusLg`、`shadowElevated` 仅为现有消费者保留，后续版本将逐步迁移。
+默认主题继续遵循 HarmonyOS 7 的白色内容面、浅蓝窗口背景、鸿蒙蓝主强调色与深蓝正文。形状和深度令牌建议按语义覆盖，而不是为单个组件写死圆角或阴影。
+### Next.js App Router
+在 `app/layout.tsx` 中导入全局样式，并通过客户端组件挂载主题：
+```tsx
+// app/providers.tsx
+'use client';
+import { ThemeProvider } from '@hxdhxd/harmony-flow-ui';
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>;
+}
+```
+```tsx
+// app/layout.tsx
+import '@hxdhxd/harmony-flow-ui/style.css';
+import { Providers } from './providers';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="zh-CN">
+      <body><Providers>{children}</Providers></body>
+    </html>
+  );
+}
+```
+### 在其他项目中安装本地构建包
+先在本仓库生成经过验证的 npm 压缩包：
+```powershell
+npm run test:package
+npm pack
+```
+然后在目标项目中安装生成的 `.tgz` 文件（请替换为实际路径和文件名）：
+```powershell
+npm install "D:\path\to\harmony-flow-ui-0.1.1.tgz"
+```
+安装后仍按正式 npm 包的方式从 `@hxdhxd/harmony-flow-ui` 导入。当前不建议直接通过 GitHub URL 安装，因为仓库不提交 `dist/`，Git 依赖安装流程无法保证生成完整发布产物。
+### 更新版本
+在目标项目中更新到最新版：
+```powershell
+npm install @hxdhxd/harmony-flow-ui@latest
+```
+## 构建产物
+执行 `npm run build` 后，`dist/` 将包含：
+- `index.js`：ESM 入口
+- `index.cjs`：CommonJS 入口
+- `index.d.ts` / `index.d.cts`：类型声明
+- `index.css`：组件样式
+## 发布
+包名使用当前 npm 账号的个人 scope `@hxdhxd`。发布账号必须拥有该 scope，并登录 npm 官方注册表：
+```powershell
+npm login --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm view @hxdhxd/harmony-flow-ui --registry=https://registry.npmjs.org/
+```
+发布前可在本地验证实际 tarball 内容：
+```powershell
+npm run build
+npm run test:package
+npm pack
+```
+正式发布：
+```powershell
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+发布完成后验证注册表中的版本：
+```powershell
+npm view @hxdhxd/harmony-flow-ui version --registry=https://registry.npmjs.org/
+```
+`npm publish` 会先执行完整质量门；`prepack` 会重新检查类型、构建 ESM/CJS/CSS/类型声明，并验证发布包只包含 README、LICENSE、package.json 和 `dist/`。
+## 视频交互扩充第二批（0.2.0）
+新增 `ProductTour` 分步高亮导览、`LegendFilter` 交互图例、`RangeBrush` 双端点区间刷选、`ExpandablePanel` 可展开内容面板。原有 API 保持兼容，不新增依赖。区间滑块实时请求更新，不支持选区整体平移；导览不代替业务完成状态。
+无删除构建：`node test/build-douyin.mjs --batch2`，产物位于 `build/douyin-20260902-02`；通过原有 Node 服务预览（不使用 Vite）。执行与验收记录见 `plan/development/douyin-20260902-02/执行与验收.md`。
+## 视频交互扩充第三批（0.2.0）
+第三批本地扩充新增 `HotspotGuide` 热点提示、`ChartCrosshair` 单序列逐点读数和 `DrilldownChart` 层级条形数据下钻。使用 `node test/build-douyin.mjs --batch3` 无删除构建，产物位于 `build/douyin-20260902-03`。验收及范围见 `plan/development/douyin-20260902-03/执行与验收.md`。纳入0.2.0。
+## 视频交互扩充第四批（0.2.0）
+第四批增强已有 `KanbanBoard` 的指针/触摸/键盘跨列移动、取消和跨实例隔离，保持原有公开接口；新增 `ZoomableChart`，组合逐点读数与区间筛选提供放大、缩小、平移及还原。无删除构建：`node test/build-douyin.mjs --batch4`，产物 `build/douyin-20260902-04`，记录 `plan/development/douyin-20260902-04/执行与验收.md`。纳入0.2.0。
+## 导航组件
+导航模块包含 `FloatingNav`、`Sidebar`、`Breadcrumb`、`DropdownMenu`、`MegaMenu`、`MobileNavigation`、`Scrollspy` 与 `ShrinkNav`。`MobileNavigation` 通过 `mode="drawer | fullscreen"` 覆盖汉堡抽屉和全屏导航。
+所有导航组件共享 `NavigationItem`，业务选择事件统一为 `onItemSelect(item)`；该命名刻意避开 React 原生 DOM 的 `onSelect` 事件。
+## 视频交互扩充第八批（0.2.0）
+新增 `ReadingProgress` 阅读进度，支持整页与独立滚动容器，自动响应内容与尺寸变化。表示滚动位置，不记录已读或业务完成度；不可滚动内容显示100%，未挂载目标显示0%。沿用现有主题，无新依赖。
+无删除构建：`node test/build-douyin-batch8.mjs`；行为与旧组件像素回归：`python test/verify-douyin-batch8.py`。记录见 `plan/development/douyin-20260905-08/执行与验收.md`。