x-next 1.5.0 → 1.7.0

package/AI_USAGE.md

@@ -1,11 +1,11 @@
 <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage-recipes.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.5.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.7.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、版本与公开类型声明）：`8ed10e46d0e5b1359b27d93837370dcf2fca95d511be5e798e112ff5977d856f`。
+来源指纹（精选示例、映射、版本与公开类型声明）：`9a84aab8ad9388abbcade590e1a24c7d5049c9ef14d04313edfc96860c34ed86`。
 
-先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 22 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
+先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 23 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。这个文件名不会自动让所有 AI 工具加载，消费项目应在自己的指令中明确引用。
 
@@ -35,7 +35,8 @@
 | Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.ztes.com/components/steps) |
 | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.ztes.com/components/tabs) |
 | Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.ztes.com/components/empty) |
-这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 22 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
+| Upload | `Upload` | `<x-upload>` | `v-model:file-list` | [组件文档](https://x-next.ztes.com/components/upload) |
+这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 23 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
 
 每节提供一个可复制到 `App.vue` 的独立 Vue SFC，显式从 `x-next` 根入口导入，并包含全量 CSS。实际项目可将重复的 CSS 导入统一移到应用入口。本文是代码配方，不新增 live demo；每节链接的既有组件文档提供可交互示例和完整 API。
 
@@ -645,3 +646,55 @@ function refresh() { refreshed.value = true; }
   </Empty>
 </template>
 ```
+
+## Upload
+
+[组件文档与 live demo](https://x-next.ztes.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
+
+**接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，resolve 即成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 即失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。返回值是 fetch `Response` 时组件读取响应体；非 2xx 按失败处理，`error.status` 为状态码。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
+
+列表默认非受控，用 `defaultFileList` 给初值；需要外部驱动时用 `v-model:file-list`，列表项以 `uid` 为稳定标识。`listType` 取 `'text' | 'picture' | 'picture-card'`。`limit` 为数量上限，超出会触发 `exceed`，超出部分不进入列表；`beforeUpload` 返回 `false` 拦截、返回新 `File` 替换，支持 Promise。
+
+`change({ file, fileList })` 覆盖加入、进度、成功、失败和移除；`success` / `error` / `remove` / `progress` 是更细粒度的补充。`autoUpload=false` 时文件先以 `init` 入列，再用组件 `submit()` 上传、`abort()` 取消、`retry()` 重试。图片卡场景可加 `image-preview` 用内置 `ImagePreview` 看图。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Upload, type UploadFile } from 'x-next';
+import 'x-next/dist/style.css';
+const fileList = ref<UploadFile[]>([]);
+const status = ref('尚未选择文件');
+// 项目里已封装好的上传方法：返回 Promise 即可，组件自动显示成功与失败
+function uploadAttachment(params: { file: File; orderId: string }) {
+  const form = new FormData();
+  form.append('file', params.file);
+  form.append('orderId', params.orderId);
+  return fetch('/api/upload', { method: 'POST', body: form }).then((response) => {
+    if (!response.ok) throw new Error(`上传失败：${response.status}`);
+    return response.json() as Promise<{ data: { url: string } }>;
+  });
+}
+function changed(info: { file: UploadFile; fileList: UploadFile[] }) {
+  status.value = `${info.file.name}：${info.file.status ?? 'unknown'}`;
+}
+function beforeUpload(file: File) {
+  // 超过 2MB 直接拦截，文件不会进入列表
+  return file.size <= 2 * 1024 * 1024;
+}
+</script>
+<template>
+  <Upload
+    v-model:file-list="fileList"
+    :custom-request="({ file }) => uploadAttachment({ file, orderId: 'SO-20261003' })"
+    response-url-key="data.url"
+    name="file"
+    multiple
+    list-type="picture"
+    accept="image/*"
+    :limit="5"
+    :before-upload="beforeUpload"
+    @change="changed"
+  />
+  <p role="status">{{ status }}</p>
+</template>
+```

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.7.0] - 2026-10-04
+
+### 新增
+
+- **Upload 上传组件**：支持点击选择、拖拽（含文件夹递归读取并保留相对路径）、粘贴上传；文本 / 图片 / 图片卡三种列表形态；`limit` 数量限制与 `exceed`、`beforeUpload` 拦截或替换文件、`beforeRemove` 移除前钩子；`autoUpload=false` 手动上传配合 `submit()` / `abort()` / `retry()`；逐项取消回到待上传态（不同于 Arco 归属 error 的处理）；`updateFile(uid, file)` 原地替换文件；`tip` 提示、操作按钮开关、内置 `ImagePreview` 图片预览；`aria-live` 上传状态播报与操作按钮无障碍名称。
+- **接入已有上传方法（`customRequest` 返回 Promise）**：业务只需 `:custom-request="({ file }) => uploadApi({ file, orderId })"`，组件自动接管状态——resolve 即成功、reject 即失败并出现重试入口，结果写入 `file.response`；axios、flyio、fetch 或任何返回 Promise 的方法均可直接接入，无需手动调用 `onSuccess` / `onError`。返回 `{ abort }` 加手动回调的写法继续兼容。
+- **`UploadRequestOption.signal`**：每次尝试独立的 `AbortSignal`，取消上传、移除文件或组件卸载时触发，可直接透传给 fetch / axios 真正中止网络请求。
+- **fetch `Response` 自动归一化**：`customRequest` 直接返回 `fetch(...)` 时，JSON / text 响应体解析后写入 `file.response`，非 2xx 按失败处理并在 `error.status` 提供状态码；axios / flyio 已解析的响应对象原样透传。
+- **`responseUrlKey` 嵌套路径**：字符串支持 `data.url` 形式的路径提取；函数形态增加第二个参数 `response`。
+- 新增 Upload 中英文语言包（`trigger` / `drag` / `fileUploaded` 等 18 项）；ImagePreview 语言包补 `openLabel` / `loadError` / `loading`。
+- 新增 `_self/upload-icons` 图标（上传云、文件、图片、刷新、下载、删除）。
+
+### 修复
+
+- **Image 加载失败态**：默认错误占位由大红底改为中性色底 + 次级文字，错误占位补齐圆角，不再刺眼。
+- **ImagePreview 工具条**：亮色白底改为深色半透明 + 模糊背景，hover 反馈统一为透明底浅色图标，窄屏工具条可折行不再溢出。
+- **Image 换图与 SSR**：`src` 由 `watchEffect` 直写 DOM 改为声明式绑定带 key 的 `img`，SSR 正确输出地址；源变更重置加载状态，旧图片节点的 load / error 事件不再覆盖新图；`description` 按文档回退给 `alt`。
+- **Image / Preview 键盘可达性**：缩略图可聚焦并用 Enter 打开预览；预览弹层补齐 Tab 圈定与关闭后焦点恢复；快捷键只在顶层预览生效。
+- **ImagePreview 加载失败**：失败时提供可访问的错误占位而非只撤下 spinner；`actionsLayout=[]` 时自定义 actions 独立渲染，不再被一并隐藏。
+- **ImagePreview 动态配置与边界**：`keyboard` / `popupContainer` 动态变更时迁移监听并清理计时器；`defaultScale` / `zoomRate` 非法值与满屏零尺寸兜底，不再产生无效 transform。
+- **ImagePreviewAction**：`attrs` 不再覆盖内部 class、`disabled` 与 aria 属性，自定义样式与禁用语义同时生效。
+- **Image 拖拽 hook**：`use-image-drag` 在节点更换时解绑旧监听，移除 / 换图不再残留移动状态。
+- **ImagePreviewGroup 无障碍**：弹层读屏标签传入真实序号与总数，不再恒为「第 1 张，共 1 张」。
+- **多层预览滚动锁**：预览使用 `useOverflow` 引用计数与容器迁移，关闭上层预览不再提前解锁页面滚动。
+- **Image 外置 footer 高度**：根节点高度由内容撑开，多行说明不再溢出或与下方内容重叠。
+- **ImagePreview SSR**：仅客户端清理 wheel 的 RAF，`docs:build` 不再输出 `cancelAnimationFrame` 报错。
+- **Image 原生事件声明**：`load` / `error` 显式声明并转发，消费者 `strictTemplates` 编译通过。
+
+### 文档与测试
+
+- 新增 `upload.md`（15 个 live demo，覆盖接入已有方法、响应提取、进度与取消、多选限制、拖拽、图片卡、手动上传、校验重试、插槽、禁用粘贴、文件夹、替换文件、Form 联动）与 `volar` 注册；组件索引、侧栏同步。
+- `image.md` 重写扩充：12 个场景全部含 live demo 与完整 SFC，补换图、错误恢复、仅自定义工具条、局部容器、键盘组切换等。
+- Upload 单测 81 项（含 Promise resolve / reject、取消后晚到结果不覆盖、signal 中止、fetch Response 归一化、手动回调优先等 13 项新增回归）；Image 新增 21 项行为断言；全量测试 2136 项。
+- AI 使用手册新增 Upload（23 个公共组件），`ai-usage-recipes.md` 示例改为「接入已有上传方法」并重新生成 `AI_USAGE.md`。
+- `check:bundle-size` 的 Input 预算由 38,000 调整为 39,500：Input 消费者结构性携带整个共享语言包（zh-CN + en-US 合计 11,635 bytes，约占 30%），按组件拆分的方案继续在 `项目审查/2026-10-03-main-共享语言包与Input体积门禁.md` 跟踪。
+
+## [1.6.0] - 2026-10-02
+
+### 新增
+
+- **Heatmap 热力图**：以「周 × 星期」网格展示按天聚合的数值分布，支持自然年与自定义跨度、五档色阶、尺寸与首日配置、月/周标签与图例开关、格子点击事件与自定义提示。整块网格只挂一个 `mousemove` 做事件委托 + 单个浮层节点，避免 371 个格子各挂一个 Trigger 带来的开销。
+- **ColorPicker 颜色选择器**：SV 取色面板 + 色相条 + 透明度条 + hex/rgb/hsl 三格式输入 + 预设色板 + 确认/清除。受控与非受控、禁用与尺寸、表单校验联动、自定义触发器均支持；Esc 关闭并把焦点归还触发器。
+- 新增 `_utils/color.ts` 颜色工具（含 alpha 的 hex/rgb/hsl 解析、HSV 双向换算、格式化与混色），附 44 项单测。
+- **Spin `tipShimmer`**：提示文字扫光效果。新增 `--x-spin-tip-shimmer-color-highlight` / `--x-spin-tip-shimmer-duration` 两个 token；用 `background-clip: text` 实现，并包在 `@supports` 中兜底（不支持裁切时文字保持原色，不会变成空白）。
+- **Spin `delay`**：延迟显示加载态，避免快速请求闪一下遮罩。语义与 AntDV 有一处刻意差异——只延迟出现、结束时立即收起，不会让已加载完的内容再被多盖一段时间。
+- 修复 `Empty` 的插画色阶后新增 `--x-empty-illustration-*` 四个 token，使默认插画能随亮/暗主题换色。
+
+### 修复
+
+- **全库行高依赖宿主（系统性缺陷）**：组件文案未显式声明行高时会继承宿主（如 `body`）的行高，导致同一组件在不同项目中高度与文字位置不一致。实测宿主行高设为 3 时按钮内容盒涨到 42px、设为 1 时只有 14px。已为 Steps 描述、Pagination 跳转区、Image footer、Input/Select 前后缀、Input 字数统计、Radio/Checkbox、InputTag 输入框、Form 说明文字等补齐行高声明。
+- **Input 字数统计类名漂移**：`.x-input-word-limit`（单横线）与运行时类名 `x-input--word-limit`（双横线）不匹配，整条规则从未生效——该元素字号一直是宿主默认值而非规定的 12px。
+- **InputTag 输入框字号**：原生 `<input>` 不继承父级字体，此前一直渲染在 UA 默认的 `13.3333px`：既与标签字号（12/14px）不一致，也让内部测宽元素 `.x-input-tag--mirror` 的测量失准。现已显式 `font-size: inherit`。
+- **Radio / Checkbox 的 `line-height: unset`**：该写法会主动丢弃行高、完全继承宿主，比不声明更糟；改为显式声明。
+- **Table / Dropdown 空态来源标识**：两者渲染裸 `<Empty />`，导致 `ConfigProvider` 的 `#empty` 插槽回调 `component` 恒为 `'empty'`，文档承诺的「按来源区分空态」在这两个组件里失效。
+- **Spin 容器模式的无障碍语义**：`loading=false` 时仍保留 `aria-label="加载中"`，屏幕阅读器会把已加载完成的区域播报为加载中。
+- **Spin 默认图标旋转叠加**：默认图标同时叠加了 Icon 的 `spin` 层与图标自带的旋转动画，两层周期与缓动都不同，合成转速在 1~2 圈/秒之间波动，观感又快又乱。现只保留图标自带旋转；自定义 `icon` 插槽仍注入 `spin`。
+- **Spin 点状动画与文案扫光的动效降级**：新增 `prefers-reduced-motion` 适配，扫光在降级时还原成纯色（而非停在某处留下一块亮斑）。
+- **Network 字段缺失被误判为「较差」**：`navigator.connection` 存在但字段不全时（部分浏览器只给 `effectiveType`），旧逻辑把缺失值兜底成 `downlink=0 / rtt=Infinity` 再走阈值判断，结果一律判成 `poor`，比完全不支持该 API 还悲观，且与文档描述相反。现在字段不足回落为「检测中」，`4g` 直接判良好。
+- **Network 其它缺陷**：`connection.onchange` 降级会顶掉使用方已注册的处理器（现改为转发并在卸载时归还）；轮询无变化仍反复派发 `change`（现按语义字段去重，但仍保留首次状态派发）；`refresh()` 可能返回 `undefined`（现始终返回 `Promise<NetworkStatus>`）。
+- **Pagination `total` 非有限值导致死循环**：`total` 传 `Infinity`（「总数未知」）时会渲染出文案为 `Infinity` 的页码；若 `current` 同时非有限，页列表里的 `for (let i = Infinity; i <= Infinity; i++)` 条件恒为真（`Infinity++ === Infinity`），主线程死循环、页面卡死。现对 `total` / `current` 做归一化。
+- **Pagination 无障碍与边界**：根节点补 `role="navigation"` 与可访问名称；跳转输入框补无障碍名称；省略号在禁用态下不再可聚焦、不再响应键盘；`pageSize` 不在 `pageSizeOptions` 中时不再显示空 placeholder；`pageSizeProps` 不再能覆盖 `disabled` / `modelValue`。
+- **Skeleton 无障碍**：根节点补 `aria-busy`，装饰性的 `SkeletonLine` / `SkeletonShape` 补 `aria-hidden`（此前空 `<li>` 会被读屏念成一串无内容的列表项）。
+- **Skeleton 动画时长**硬编码 `1.5s` 提到 token；`SkeletonShape.size` 类型收窄。
+- **Empty 默认插画**：四个灰阶是硬编码浅色字面量，暗色主题下整块发白；现改为 `--x-empty-illustration-*` token，图形本身不变，亮色取值与原字面量逐位一致。
+- **forced-colors 适配**：补齐分页当前页描边与骨架屏轮廓，避免背景被强制成 Canvas 后这些状态不可见。
+- **Steps 描述行高**、**TimePicker / DatePicker 面板宽度自适应**等文档与样式细节。
+
+### 测试
+
+- 新增 Heatmap / ColorPicker / 颜色工具共 100+ 项单测。
+- 新增 Empty 插画单色契约、Table/Dropdown 空态来源、Spin `delay` 与 `tipShimmer`、Spin `inert` 键盘兜底（显式移除 `inert` 原型属性以覆盖真实降级路径）、Network 字段缺失与 `onchange` 转发、Pagination 非有限 `total` 等回归测试，测试总数 2034。
+
 ## [1.5.0] - 2026-10-02
 
 ### 修复

package/dist/_utils/color.d.ts

@@ -0,0 +1,53 @@
+import { hslToRgb, rgbToHsl } from './palette';
+export { hslToRgb, rgbToHsl };
+/**
+ * 带透明度的颜色工具。
+ *
+ * 与 `palette.ts` 的分工：那里的 `parseColor` 服务于主题色阶生成，语义是
+ * 「丢弃 alpha、只取不透明 RGB」（该行为被色阶测试锁定）。颜色选择器需要
+ * 保留 alpha、需要 HSV（取色面板的饱和度/明度轴）以及多格式输出，
+ * 因此单独放在这里，不修改 palette.ts 的既有语义。
+ */
+/** 通道 0-255，alpha 0-1 */
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** h 0-360，s/v 0-100 */
+export interface HSV {
+    h: number;
+    s: number;
+    v: number;
+}
+export type ColorFormat = 'hex' | 'rgb' | 'hsl';
+/**
+ * 解析颜色字符串为 RGBA。
+ *
+ * 支持 `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`、`rgb()` / `rgba()`、
+ * `hsl()` / `hsla()`（通道可用百分比），逗号与空格两种语法均可。
+ * 无法解析时返回 null。
+ */
+export declare const parseColorAlpha: (input: string) => RGBA | null;
+/** 解析失败时回退到给定颜色，便于受控输入容错 */
+export declare const parseColorAlphaOr: (input: string, fallback: RGBA) => RGBA;
+export declare const rgbToHsv: ({ r, g, b }: Pick<RGBA, "r" | "g" | "b">) => HSV;
+export declare const hsvToRgb: ({ h, s, v }: HSV) => [number, number, number];
+export declare const rgbaToHex: ({ r, g, b, a }: RGBA, showAlpha?: boolean) => string;
+/** alpha 输入框展示用：整数百分比 */
+export declare const formatAlphaPercent: (a: number) => number;
+/**
+ * 按目标格式输出颜色字符串。
+ * `showAlpha` 为 false 时忽略 alpha；为 true 但 alpha 为 1 时省略 alpha 通道。
+ */
+export declare const formatColor: (rgba: RGBA, format: ColorFormat, showAlpha?: boolean) => string;
+/**
+ * 输出 `rgba(r, g, b, a)`，用于渐变端点等需要精确 alpha 的场景。
+ * alpha 滑块的两端分别是「完全透明」与「当前色」，都靠它构造。
+ */
+export declare const toRgbaString: ({ r, g, b, a }: RGBA) => string;
+/** alpha 滑轨的渐变终点色：始终输出不透明的 `rgba()` */
+export declare const toAlphaSliderColor: ({ r, g, b }: RGBA) => string;
+/** 十六进制输入框的即时校验（供输入过程的分支判断，允许带 alpha） */
+export declare const isHexColor: (input: string) => boolean;

package/dist/components/color-picker/ColorPicker.d.ts

@@ -0,0 +1,239 @@
+import { PropType, SlotsType } from 'vue';
+import { ColorFormat } from '../../_utils/color';
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /**
+     * @zh 颜色值，支持 hex / rgb / hsl（含 alpha）
+     * @en Color value, supports hex / rgb / hsl with alpha
+     * @vModel
+     */
+    modelValue: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 非受控初值
+     * @en Default value for uncontrolled mode
+     */
+    defaultValue: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 面板是否可见
+     * @en Whether the panel is visible
+     * @vModel
+     */
+    show: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 面板默认是否可见
+     * @en Whether the panel is visible by default
+     */
+    defaultShow: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 可选的颜色格式
+     * @en Available color formats
+     * @defaultValue ['hex', 'rgb', 'hsl']
+     */
+    modes: {
+        type: PropType<ColorFormat[]>;
+        default: () => ColorFormat[];
+    };
+    /**
+     * @zh 是否启用透明度
+     * @en Whether alpha is enabled
+     * @defaultValue true
+     */
+    showAlpha: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 预设色块
+     * @en Preset swatches
+     */
+    swatches: {
+        type: PropType<string[]>;
+        default: () => never[];
+    };
+    /**
+     * @zh 是否展示确认按钮
+     * @en Whether to show the confirm button
+     * @defaultValue true
+     */
+    showConfirm: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示清除按钮
+     * @en Whether to show the clear button
+     * @defaultValue true
+     */
+    showClear: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否禁用
+     * @en Whether the picker is disabled
+     */
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 尺寸
+     * @en Size
+     * @values 'mini', 'small', 'medium', 'large'
+     */
+    size: {
+        type: PropType<"mini" | "small" | "medium" | "large">;
+    };
+    /**
+     * @zh 面板挂载容器
+     * @en Mount container for the panel
+     */
+    popupContainer: {
+        type: PropType<string | HTMLElement>;
+    };
+}>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    'update:modelValue': (_value: string, _ev?: Event) => true;
+    change: (_value: string, _ev?: Event) => true;
+    'update:show': (_visible: boolean) => true;
+    showChange: (_visible: boolean) => true;
+    confirm: (_value: string) => true;
+    clear: () => true;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /**
+     * @zh 颜色值，支持 hex / rgb / hsl（含 alpha）
+     * @en Color value, supports hex / rgb / hsl with alpha
+     * @vModel
+     */
+    modelValue: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 非受控初值
+     * @en Default value for uncontrolled mode
+     */
+    defaultValue: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 面板是否可见
+     * @en Whether the panel is visible
+     * @vModel
+     */
+    show: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    /**
+     * @zh 面板默认是否可见
+     * @en Whether the panel is visible by default
+     */
+    defaultShow: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 可选的颜色格式
+     * @en Available color formats
+     * @defaultValue ['hex', 'rgb', 'hsl']
+     */
+    modes: {
+        type: PropType<ColorFormat[]>;
+        default: () => ColorFormat[];
+    };
+    /**
+     * @zh 是否启用透明度
+     * @en Whether alpha is enabled
+     * @defaultValue true
+     */
+    showAlpha: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 预设色块
+     * @en Preset swatches
+     */
+    swatches: {
+        type: PropType<string[]>;
+        default: () => never[];
+    };
+    /**
+     * @zh 是否展示确认按钮
+     * @en Whether to show the confirm button
+     * @defaultValue true
+     */
+    showConfirm: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否展示清除按钮
+     * @en Whether to show the clear button
+     * @defaultValue true
+     */
+    showClear: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 是否禁用
+     * @en Whether the picker is disabled
+     */
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * @zh 尺寸
+     * @en Size
+     * @values 'mini', 'small', 'medium', 'large'
+     */
+    size: {
+        type: PropType<"mini" | "small" | "medium" | "large">;
+    };
+    /**
+     * @zh 面板挂载容器
+     * @en Mount container for the panel
+     */
+    popupContainer: {
+        type: PropType<string | HTMLElement>;
+    };
+}>> & Readonly<{
+    onClear?: (() => any) | undefined;
+    onChange?: ((_value: string, _ev?: Event | undefined) => any) | undefined;
+    onConfirm?: ((_value: string) => any) | undefined;
+    "onUpdate:modelValue"?: ((_value: string, _ev?: Event | undefined) => any) | undefined;
+    "onUpdate:show"?: ((_visible: boolean) => any) | undefined;
+    onShowChange?: ((_visible: boolean) => any) | undefined;
+}>, {
+    disabled: boolean;
+    defaultValue: string;
+    show: boolean;
+    modelValue: string;
+    modes: ColorFormat[];
+    showAlpha: boolean;
+    swatches: string[];
+    showConfirm: boolean;
+    showClear: boolean;
+    defaultShow: boolean;
+}, SlotsType<{
+    default?: () => unknown;
+    trigger?: (props: {
+        value: string;
+        visible: boolean;
+    }) => unknown;
+}>, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/color-picker/gradient-slider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 通用渐变滑轨，色相条与透明度条共用。
+ *
+ * 差异只在背景：色相条是固定的色相环渐变，透明度条是「透明 → 当前色」。
+ * 通过 `background` prop 注入，组件本身不关心颜色语义。
+ */
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /** 0-100 的位置百分比 */
+    value: {
+        type: NumberConstructor;
+        required: true;
+    };
+    /** 滑轨背景（CSS background 值） */
+    background: {
+        type: StringConstructor;
+        required: true;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 无障碍名称，由父组件传入已本地化的文案 */
+    ariaLabel: {
+        type: StringConstructor;
+    };
+}>, () => VNode, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    change: (_value: number) => true;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /** 0-100 的位置百分比 */
+    value: {
+        type: NumberConstructor;
+        required: true;
+    };
+    /** 滑轨背景（CSS background 值） */
+    background: {
+        type: StringConstructor;
+        required: true;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 无障碍名称，由父组件传入已本地化的文案 */
+    ariaLabel: {
+        type: StringConstructor;
+    };
+}>> & Readonly<{
+    onChange?: ((_value: number) => any) | undefined;
+}>, {
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;