hys-ui 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0
+
+- 示例站点为新增能力补充交互示例，API 参考补全参数、事件、插槽和实例方法的具体说明。
+
+- Button 增加石板灰、钴蓝、靛蓝、紫罗兰、湖青、青绿、翡翠绿、青柠、琥珀、柑橘、朱红、玫红十二种内置配色，支持深浅色和原有文字、链接及朴素样式。悬停只变更视觉样式，按钮位置保持稳定。
+
+- Button 支持可取消的异步操作、延迟加载、按下状态、自定义根标签与键盘激活、两字中文间距、危险色与透明描边组合及文字底色。新增 ButtonGroup 统一按钮的方向、尺寸和状态。
+- Search 增加独立搜索按钮、确认提交模式、非受控初值、清空策略及原生输入属性。
+- Select 支持值与标签模型、远程标签回显、首选高亮值和动态清空值。多选批量事件使用同一模型格式。
+
+- Tour 支持定位到元素、选择器和目标函数，增加跟随滚动的高亮遮罩、目标点击策略、非模态引导、逐步外观、自定义内容与导航、挂载与层级配置。
+- SplitPane 增加两侧独立的像素或百分比约束、折叠和恢复、延迟拖动提交、拖动预览事件及非受控比例。
+- SplitPane 支持按标识管理任意数量的面板、按分隔条调整相邻尺寸、受控尺寸集合和面板插槽。未设置尺寸的面板自动分配可用空间。
+- SplitPane 更新细线、抓手和方向箭头，增加可配置分隔条尺寸、键盘折叠、双击操作、非受控布局记忆和按标识调整面板尺寸。
+
+- Mention 支持独立触发规则、模糊和拼音搜索、多源分页与缓存、推荐和最近记录、分组虚拟候选、富文本实体、程序化编辑、序列化、撤销重做、权限校验、表单及浮层定制。
+- AnimatedNumber 支持精确十进制字符串、统计标题与前后缀、自定义数值格式和截止时间倒计时。
+- Table 增加外部容器粘性表头和同步滚动条、列级受控排序和筛选、自定义表格结构与表头合并。支持下一次排序提示、自定义批量选择和统一单元格文本转换。
+- Table 支持分页布局、默认分页值、自定义分页器与服务端总页数，以及固定汇总、当前页汇总和自定义汇总行。新增横向最小宽度、列标题渲染和溢出提示样式配置。
+- Pagination 支持非受控初始值、总页数、单页隐藏、控件布局和尺寸，以及总数、按钮内容和跳转插槽。受控模式按已生效的页大小调整页码。
+
 ## 0.3.0
 
 - DataGrid 支持受控查询、远程加载取消与重试、单选和多选、选择保留、自定义列字段与汇总，以及按行键滚动定位。树形行事件返回原始记录，列宽拖动按帧预览并在释放时保存，支持键盘调整和取消。TypeScript 模板引用可使用 `HysDataGridInstance`。

package/README.md

@@ -1,110 +1,105 @@
 # HYS UI
 
-面向 Vue 3.5+ 的组件库，提供 TypeScript 类型、主题配置和独立的中文交互文档。
+HYS UI 是面向管理后台和业务应用的 Vue 3 组件库。用它搭建筛选表单、数据列表和项目排期界面。组件支持按需导入、TypeScript 类型提示和主题定制。
 
-[在线文档与交互示例](https://lampo1024.github.io/hys-ui/)
+[在线文档与交互示例](https://lampo1024.github.io/hys-ui/) · [npm](https://www.npmjs.com/package/hys-ui) · [更新记录](https://github.com/lampo1024/hys-ui/blob/main/packages/ui/CHANGELOG.md)
 
-## 安装
+## 按场景找组件
+
+每个组件的文档都可以直接试用。展开示例即可复制 Vue 源码，属性、事件和插槽见该页的 API 参考。
+
+| 场景 | 可以做什么 | 在线示例 |
+| --- | --- | --- |
+| 表单与输入 | 配置字段联动、异步校验、远程搜索和多选。 | [表单](https://lampo1024.github.io/hys-ui/components/hys-form/) · [下拉选择](https://lampo1024.github.io/hys-ui/components/hys-select/) · [自动补全](https://lampo1024.github.io/hys-ui/components/hys-autocomplete/) |
+| 层级与批量选择 | 按层级挑选分类，在两侧列表之间批量移动成员。 | [树形选择](https://lampo1024.github.io/hys-ui/components/hys-tree-select/) · [穿梭框](https://lampo1024.github.io/hys-ui/components/hys-transfer/) |
+| 日期与排期 | 按日期或周筛选，拖动甘特任务、连接前置依赖、查看排期冲突。 | [日期选择](https://lampo1024.github.io/hys-ui/components/hys-date-picker/) · [日期范围](https://lampo1024.github.io/hys-ui/components/hys-date-range-picker/) · [甘特图](https://lampo1024.github.io/hys-ui/components/hys-gantt/) |
+| 弹层与反馈 | 在对话框中编辑长表单，用抽屉查看详情，用轻提示反馈操作结果。 | [对话框](https://lampo1024.github.io/hys-ui/components/hys-modal/) · [抽屉](https://lampo1024.github.io/hys-ui/components/hys-drawer/) · [轻提示](https://lampo1024.github.io/hys-ui/components/hys-toast/) |
+| 文件与进度 | 选择文件、控制上传队列，显示进度、失败和重试状态。 | [文件上传](https://lampo1024.github.io/hys-ui/components/hys-upload/) · [进度条](https://lampo1024.github.io/hys-ui/components/hys-progress/) |
+
+### 三种表格怎么选
+
+- **`HysTable`** 适合常规列表和树形数据。支持固定列、展开行、合并单元格、表尾汇总和分页。[表格示例](https://lampo1024.github.io/hys-ui/components/hys-table/)
+- **`HysDataGrid`** 适合让用户自行筛选和整理数据。支持按列搜索、拖拽调整列顺序、列显隐、分组、CSV 导出和服务端查询。[高级表格示例](https://lampo1024.github.io/hys-ui/components/hys-data-grid/)
+- **`HysVirtualTable`** 适合需要连续滚动的大数据列表。按视口渲染行，也可开启列虚拟化。支持固定行列和滚动加载。[虚拟表格示例](https://lampo1024.github.io/hys-ui/components/hys-virtual-table/)
+
+例如，任务管理页可以用日期范围和多选下拉框筛选任务，用高级表格展示结果，用对话框编辑记录。需要调整计划时，可以在甘特图里拖动任务、查看前置依赖和撤销排期修改。
+
+## 快速开始
+
+适用于 Vue 3.5+ 浏览器应用。通过 ESM 命名导入使用组件，无需全局注册或安装 Vue Router。
 
 ```bash
 npm install hys-ui
 ```
 
+把下面的任务状态选择示例放到任意 Vue 页面即可运行。项目中可以把 `hys-ui/style.css` 移到应用入口统一导入。
+
 ```vue
 <script setup lang="ts">
-import { HysButton } from 'hys-ui'
+import { ref } from 'vue'
+import { HysSelect } from 'hys-ui'
 import 'hys-ui/style.css'
+
+const status = ref('all')
+const options = [
+  { label: '全部状态', value: 'all' },
+  { label: '待办', value: 'todo' },
+  { label: '进行中', value: 'in-progress' },
+  { label: '已完成', value: 'done' },
+]
 </script>
 
 <template>
-  <HysButton round @click="console.log('confirmed')">确认</HysButton>
+  <HysSelect v-model="status" :options="options" aria-label="任务状态" />
+  <p>当前状态值：{{ status }}</p>
 </template>
 ```
 
-通过命名导入按需使用组件。组件源码、文件名、导出名统一采用 `HysXxxxx`。ESM 包的 Vue peer dependency 为 `>=3.5.0 <4`，无需 Vue Router。图标使用 Lucide outline，宿主项目可以传入自有图标。
-
-## 主题和动效
-
-在根组件 setup 中调用，参数可以是响应式 ref 或 getter。配置会传递给子组件与 Teleport 浮层。
-
-```ts
-import { ref } from 'vue'
-import { provideHysConfig, type HysTheme } from 'hys-ui'
-
-const theme = ref<HysTheme>('blue')
-provideHysConfig({ theme, motion: 'subtle' })
-```
-
-主题支持 `blue / dark / green / purple / orange / forest`，动效支持 `full / subtle / off`，系统减少动态效果设置优先。组件库不会写入浏览器存储或修改全局页面主题。
-
-可以使用 `--hys-ui-primary`、`--hys-ui-surface`、`--hys-ui-text`、`--hys-ui-border`、`--hys-ui-font-family` 等公开变量覆盖组件外观。组件类名与变量采用独立前缀，没有 body/html 全局重置。
+## 用轻提示反馈操作结果
 
-
-浮层组件统一通过 `popupTransition` 设置展开与收起动效：`scale`（默认柔和缩放）、`fade`（淡入淡出）、`slide`（轻移）、`slide-fade`（轻移缩放）、`none`（关闭）。`popupTransitionDuration` 设置时长，默认 160ms，设为 0 立即切换。该配置适用于选择、日期、自动补全、提及、颜色、提示、菜单，以及表格、树形、头像组、日历事件和甘特图关系等浮层。Modal、Drawer 和 Toast 保留各自的动画配置。
+在组件的 `<script setup>` 里调用 `useHysToast()`，即可在保存、上传等操作后显示提示。下面用定时器模拟上传，完成后更新同一条消息。
 
 ```vue
-<HysSelect
-  v-model="value"
-  :options="options"
-  popup-transition="slide-fade"
-  :popup-transition-duration="200"
-/>
-```
+<script setup lang="ts">
+import { ref } from 'vue'
+import { HysButton, useHysToast } from 'hys-ui'
+import 'hys-ui/style.css'
 
-系统减少动态效果和 `motion: 'off'` 优先于局部设置；内嵌日期面板不播放浮层动效。动画仅改变透明度和合成层变换，关闭时立即停止交互，退出完成后移除内容。
+const toast = useHysToast()
+const uploading = ref(false)
 
-## 开发与文档
+async function simulateUpload() {
+  uploading.value = true
+  const message = toast.loading('正在上传…')
 
-```bash
-npm install
-npm run dev:docs
-```
-
-访问 http://127.0.0.1:5174。每个组件有独立路由、运行场景、源码、API 与说明，页面状态通过 KeepAlive 保留。API 从源码生成。
+  await new Promise(resolve => setTimeout(resolve, 700))
 
-- `packages/ui`：唯一的组件源码及 npm 包。
-- `apps/docs`：独立组件文档与交互示例。
-- `tests`：核心行为回归。
-- `scripts`：元信息提取、完整性检查、打包与发布验证。
+  message.update({ type: 'success', message: '上传完成', duration: 2000 })
+  uploading.value = false
+}
+</script>
 
-```bash
-npm run build:ui
-npm run build:docs
-npm test
-npm run check:contracts
-npm run check:release
+<template>
+  <HysButton :loading="uploading" @click="simulateUpload">模拟上传</HysButton>
+</template>
 ```
 
-`build:docs` 输出到 `apps/docs/dist`，部署服务需要将未知路径回退到 `index.html`。
+轻提示默认在顶部居中。可设置显示位置、停留时长和队列上限，也可以合并重复消息。[轻提示 API 与示例](https://lampo1024.github.io/hys-ui/components/hys-toast/)
 
-## 轻提示
+## 主题与动效
 
-轻提示默认显示在顶部中间，支持七种位置、五种状态和自定义内容。
+在根组件的 `<script setup>` 中调用 `provideHysConfig`，下级组件及其浮层会继承配置。主题支持响应式切换。
 
 ```ts
-import { useHysToast } from 'hys-ui'
-
-// 在组件 setup 中使用
-const toast = useHysToast({ maxCount: 5 })
-toast.success('保存成功')
-const task = toast.loading('正在上传…')
-task.update({ type: 'success', message: '上传完成', duration: 2000 })
-```
-
-## 发布
-
-根工作区和文档应用为私有，npm 包名为 `hys-ui`，版本 `0.3.0`，MIT 公开发布。
+import { ref } from 'vue'
+import { provideHysConfig, type HysTheme } from 'hys-ui'
 
-```bash
-npm run pack:ui
-npm login --registry=https://registry.npmjs.org/
-npm run release:ui
+const theme = ref<HysTheme>('blue')
+provideHysConfig({ theme, motion: 'subtle' })
 ```
 
-发布流程先执行全部检查、打包和仓库外安装验证，再检查登录账号、包名/版本及压缩包 SHA256，发布同一个已验证压缩包到 `latest`。凭证通过 npm 本地交互管理，不写入仓库。
-
-后续版本按语义化版本发布，并更新 CHANGELOG。暂不承诺 SSR/Nuxt 支持。
+内置主题有 `blue`、`dark`、`green`、`purple`、`orange` 和 `forest`。可用 `--hys-ui-primary`、`--hys-ui-surface` 等 CSS 变量调整外观。动效可设为 `full`、`subtle` 或 `off`，并遵循系统的减少动态效果设置。支持浮层动效的组件还可以单独设置 `popup-transition` 和 `popup-transition-duration`。
 
-## 许可证
+## 源码与问题反馈
 
-[MIT](LICENSE)
+[GitHub 仓库](https://github.com/lampo1024/hys-ui) · [提交问题](https://github.com/lampo1024/hys-ui/issues) · [MIT 许可证](https://github.com/lampo1024/hys-ui/blob/main/LICENSE)

package/dist/components/HysAnimatedNumber/HysAnimatedNumber.vue.js

@@ -1,43 +1,7 @@
-import { defineComponent as A, ref as b, watch as M, onDeactivated as x, onActivated as y, onBeforeUnmount as N, openBlock as w, createElementBlock as B, mergeProps as k, unref as q, toDisplayString as D } from "vue";
-import { useHysRootAttrs as H } from "../../config.js";
-import { useMotion as R } from "../../motion/useMotion.js";
-const S = ["aria-label"], P = /* @__PURE__ */ A({
-  __name: "HysAnimatedNumber",
-  props: {
-    value: {},
-    duration: { default: 650 },
-    decimals: { default: 0 }
-  },
-  setup(o) {
-    const l = H(), { effectiveMotion: u } = R(), t = o, n = b(Number.isFinite(t.value) ? t.value : 0);
-    let a = 0, r = !0;
-    function i(e) {
-      return Number.isFinite(e) ? e : 0;
-    }
-    function f(e) {
-      if (e = i(e), cancelAnimationFrame(a), u.value === "off" || !Number.isFinite(t.duration) || t.duration <= 0) {
-        n.value = e;
-        return;
-      }
-      const s = n.value, v = performance.now(), h = Math.max(1, t.duration);
-      function m(p) {
-        const c = Math.min(1, (p - v) / h), F = 1 - Math.pow(1 - c, 3);
-        n.value = s + (e - s) * F, c < 1 && (a = requestAnimationFrame(m));
-      }
-      a = requestAnimationFrame(m);
-    }
-    return M(() => [t.value, t.duration, u.value], ([e]) => {
-      r ? f(e) : n.value = i(e);
-    }), x(() => {
-      r = !1, cancelAnimationFrame(a);
-    }), y(() => {
-      r = !0, n.value = i(t.value);
-    }), N(() => cancelAnimationFrame(a)), (e, d) => (w(), B("span", k(q(l), {
-      class: "hys-ui-motion-number",
-      "aria-label": String(i(o.value))
-    }), D(n.value.toFixed(Number.isFinite(o.decimals) ? Math.max(0, Math.min(5, Math.floor(o.decimals))) : 0)), 17, S));
-  }
-});
+import o from "./HysAnimatedNumber2.vue.js";
+/* empty css                       */
+import t from "../../_virtual/_plugin-vue_export-helper.js";
+const a = /* @__PURE__ */ t(o, [["__scopeId", "data-v-11d35ec9"]]);
 export {
-  P as default
+  a as default
 };

package/dist/components/HysAnimatedNumber/HysAnimatedNumber2.vue.js

@@ -1,4 +1,148 @@
-import f from "./HysAnimatedNumber.vue.js";
+import { defineComponent as Z, useSlots as _, ref as G, watch as E, computed as c, onMounted as ee, onActivated as te, onDeactivated as ne, onBeforeUnmount as ae, openBlock as m, createElementBlock as v, mergeProps as ie, unref as b, renderSlot as x, createTextVNode as M, toDisplayString as N, createCommentVNode as V, createElementVNode as oe, normalizeStyle as re, normalizeProps as $, guardReactiveProps as C, createBlock as se, Fragment as ue } from "vue";
+import { useHysRootAttrs as le } from "../../config.js";
+import { useMotion as ce } from "../../motion/useMotion.js";
+import { decimal as me, decimalText as I, decimalRound as de } from "../../composables/numberInput.js";
+const fe = {
+  key: 0,
+  class: "hys-ui-motion-number-title"
+}, ve = ["role"], pe = {
+  key: 0,
+  class: "hys-ui-motion-number-affix"
+}, he = {
+  key: 1,
+  class: "hys-ui-motion-number-affix"
+}, xe = /* @__PURE__ */ Z({
+  __name: "HysAnimatedNumber",
+  props: {
+    value: { default: 0 },
+    duration: { default: 650 },
+    decimals: {},
+    precision: {},
+    groupSeparator: {},
+    decimalSeparator: { default: "." },
+    title: {},
+    prefix: {},
+    suffix: {},
+    valueStyle: { type: [Boolean, null, String, Object, Array] },
+    formatter: {},
+    deadline: {},
+    format: { default: "HH:mm:ss" }
+  },
+  emits: ["change", "finish"],
+  setup(r, { expose: L, emit: U }) {
+    const t = r, j = U, A = _(), X = le(), { effectiveMotion: P } = ce(), F = (e) => typeof e == "number" && !Number.isFinite(e) ? 0 : e, s = G(F(t.value));
+    let p = 0, d = !1;
+    function q() {
+      if (cancelAnimationFrame(p), !d) return;
+      const e = F(t.value), n = s.value, u = t.duration;
+      if (typeof e != "number" || typeof n != "number" || n === e || t.deadline !== void 0 || P.value === "off" || !Number.isFinite(u) || u <= 0) {
+        s.value = e;
+        return;
+      }
+      const a = performance.now(), o = (l) => {
+        const R = Math.max(0, Math.min(1, (l - a) / u)), W = 1 - (1 - R) ** 3;
+        s.value = R === 1 ? e : n * (1 - W) + e * W, R < 1 && (p = requestAnimationFrame(o));
+      };
+      p = requestAnimationFrame(o);
+    }
+    E([() => t.value, () => t.duration, P], q);
+    const f = c(() => {
+      const e = t.deadline instanceof Date ? t.deadline.getTime() : t.deadline;
+      return e !== void 0 && Number.isFinite(e) ? e : void 0;
+    }), w = () => f.value === void 0 ? 0 : Math.max(
+      0,
+      Math.min(Number.MAX_SAFE_INTEGER, f.value - Date.now())
+    ), i = G(w()), D = c(
+      () => t.format.match(/\[[^\]]*\]|SSS|DD?|HH?|mm?|ss?|[\s\S]/g) ?? []
+    ), h = c(() => D.value.includes("SSS"));
+    let H, T, k;
+    function y() {
+      if (clearTimeout(H), !d || f.value === void 0) return;
+      const e = f.value;
+      if (i.value = w(), i.value !== k && (k = i.value, j("change", i.value)), i.value === 0) {
+        T !== e && (T = e, j("finish"));
+        return;
+      }
+      const n = h.value ? 16 : 1e3;
+      H = setTimeout(
+        y,
+        h.value ? n : i.value % n || n
+      );
+    }
+    E(f, () => {
+      T = void 0, k = void 0, i.value = w(), q(), y();
+    }), E(h, y);
+    function z() {
+      d || (d = !0, s.value = F(t.value), y());
+    }
+    function O() {
+      d = !1, clearTimeout(H), cancelAnimationFrame(p);
+    }
+    ee(z), te(z), ne(O), ae(O);
+    const J = c(() => {
+      const e = t.precision ?? t.decimals;
+      return e === void 0 && typeof s.value == "string" ? void 0 : e !== void 0 && Number.isFinite(e) ? Math.max(0, Math.min(20, Math.floor(e))) : 0;
+    });
+    function K() {
+      const e = me(s.value);
+      if (!e) return String(s.value);
+      const n = J.value, u = n === void 0 ? I(e) : I(de(e, n), n), [a, o] = u.split("."), l = t.groupSeparator ? a.replace(/\B(?=(\d{3})+(?!\d))/g, () => t.groupSeparator) : a;
+      return o === void 0 ? l : l + t.decimalSeparator + o;
+    }
+    function Q() {
+      let e = h.value ? Math.floor(i.value) : Math.ceil(i.value / 1e3) * 1e3;
+      const n = { D: 864e5, H: 36e5, m: 6e4, s: 1e3, S: 1 }, u = /* @__PURE__ */ new Map();
+      for (const [a, o] of Object.entries(n))
+        D.value.some(
+          (l) => l[0] === a && /^(D{1,2}|H{1,2}|m{1,2}|s{1,2}|SSS)$/.test(l)
+        ) && (u.set(a, Math.floor(e / o)), e %= o);
+      return D.value.map((a) => {
+        if (a.startsWith("[") && a.endsWith("]"))
+          return a.slice(1, -1);
+        const o = u.get(a[0]);
+        return o === void 0 ? a : String(o).padStart(a.length, "0");
+      }).join("");
+    }
+    const S = c(() => t.deadline !== void 0), B = c(
+      () => S.value ? Q() : K()
+    ), g = c(() => ({
+      value: S.value ? i.value : s.value,
+      displayValue: B.value,
+      remaining: S.value ? i.value : void 0
+    })), Y = ({ value: e }) => e;
+    return L({ displayValue: B, remaining: i }), (e, n) => (m(), v("span", ie(b(X), { class: "hys-ui-motion-number" }), [
+      r.title || b(A).title ? (m(), v("span", fe, [
+        x(e.$slots, "title", {}, () => [
+          M(N(r.title), 1)
+        ], !0)
+      ])) : V("", !0),
+      oe("span", {
+        class: "hys-ui-motion-number-value",
+        style: re(r.valueStyle),
+        role: S.value ? "timer" : void 0
+      }, [
+        r.prefix || b(A).prefix ? (m(), v("span", pe, [
+          x(e.$slots, "prefix", $(C(g.value)), () => [
+            M(N(r.prefix), 1)
+          ], !0)
+        ])) : V("", !0),
+        x(e.$slots, "formatter", $(C(g.value)), () => [
+          r.formatter ? (m(), se(Y, {
+            key: 0,
+            value: r.formatter(g.value)
+          }, null, 8, ["value"])) : (m(), v(ue, { key: 1 }, [
+            M(N(B.value), 1)
+          ], 64))
+        ], !0),
+        r.suffix || b(A).suffix ? (m(), v("span", he, [
+          x(e.$slots, "suffix", $(C(g.value)), () => [
+            M(N(r.suffix), 1)
+          ], !0)
+        ])) : V("", !0)
+      ], 12, ve)
+    ], 16));
+  }
+});
 export {
-  f as default
+  xe as default
 };

package/dist/components/HysButton/HysButton.vue.js

@@ -1,7 +1,7 @@
 import o from "./HysButton2.vue.js";
 /* empty css               */
 import t from "../../_virtual/_plugin-vue_export-helper.js";
-const m = /* @__PURE__ */ t(o, [["__scopeId", "data-v-646a4efb"]]);
+const p = /* @__PURE__ */ t(o, [["__scopeId", "data-v-f242e243"]]);
 export {
-  m as default
+  p as default
 };