更新日志 · XiHan.UI

本文件记录 XiHan.UI 各版本的变更。每条标注 新增 / 修复 / 优化 / 调整 / 移除 类别。只收录使用者可感知的变更，仓库自身的配置、CI、测试与门禁不列入。组件以 npm 包形式发布，升级前请留意「调整」类中的破坏性变更。

v2.1.0 (2026-09-24)

本版补齐集合类组件的条目契约：逐条语气、说明、快捷键与首尾两格的逐条钩子，菜单的 collection 可以直接铺出分组；选中标记统一为行尾对号。本版包含少量破坏性变更（Tree、Listbox、TagGroup 的选中外观与相关部件、槽名），按次版本发布，升级前请看下方升级须知。

升级须知

Tree

• expandOnClick 缺省由 true 改为 false，与 TreeSelect 一致：点行与确认键只选中，展开交给展开箭头（branch-trigger）与左右方向键。需要「点目录即展开」的，显式打开 expandOnClick（Web Components 写 expand-on-click）；分支行只放了不可点的 branch-indicator 的树，缺省下只能用方向键展开，请在分支行补一枚 branch-trigger
• 勾选框部件删除：item-checkbox / branch-checkbox，三端的 XhTreeItemCheckbox / XhTreeBranchCheckbox（React 另有 XhTreeItemCheckboxProps / XhTreeBranchCheckboxProps），以及 connect 上的 getItemCheckboxProps / getBranchCheckboxProps。单选、多选与级联都改为在行尾画对号：把勾选框换成 XhTreeItemIndicator，分支行同样放一枚；Web Components 把 data-xh-part="item-checkbox" / "branch-checkbox" 换成 data-xh-part="item-indicator"
• 删除组件槽 --xh-tree-checkbox-*（8 个）与 --xh-tree-row-bg-selected；行的 data-xh-collection-context 由 page 改为 overlay

Listbox

• 选中行不再铺品牌淡底、不换字色，只在行尾亮对号；删除组件槽 --xh-listbox-item-bg-selected，--xh-listbox-item-fg-selected 保留但缺省回到条目自己的字色；条目的 data-xh-collection-context 由 page 改为 overlay

TagGroup

• 选中的标签不再换面、换字色与描边，只在文字后亮一枚对号；删除组件槽 --xh-tag-group-item-bg-selected、--xh-tag-group-item-bg-selected-hover、--xh-tag-group-item-bg-selected-pressed、--xh-tag-group-item-fg-selected、--xh-tag-group-item-border-selected；实心标签选中时不再描出字色描边

Menu

• 由 collection 代铺的条目，文字从 item 里的裸文本改放进 item-text（与 ContextMenu、Menubar 一致）。直接对条目文本节点写样式的自定义皮肤，请改为选中 item-text

• 新增 集合条目逐条语气：条目数据写 tone（MenuNode 与另外十二个集合组件的节点）即按该语气族着色，静息只换字色，悬停、键盘高亮与按下换语气淡底；选中与当前压过语气，禁用压过一切，强制颜色模式下退回系统色

• 新增 条目说明与快捷键：MenuNode 补上 indicator / description / shortcut，Menu 新增 item-shortcut 部件；ContextMenu、Menubar 补上 item-shortcut 与 shortcut；另外九个集合组件补上 item-description 与 description；Command 补上快捷键提示。快捷键以次级字号显示且不换行，不进入读屏可及名与连打检索

• 新增 首尾两格的逐条钩子：Menu、ContextMenu、Menubar 新增 item-suffix 部件与 item-prefix / item-suffix 插槽（React 为 renderItemPrefix / renderItemSuffix），给条目加图标或徽标不必再用 item 插槽整条重写；Listbox、Select、Combobox、Mention、Command 补上 item-prefix / item-suffix；Tree、TreeSelect、Cascader、Transfer 补上行尾一格

• 新增 MenuNode 的 group 与 groupLabel：collection 按相邻同值收成分组并输出分组标题

• 新增 组件文档补充「React 适配器 props」表与条目数据表，插槽表写明 item / item-prefix / item-suffix 的分工

• 修复 浮层打开后不再常驻 will-change：此前入场动画中途的栅格会被沿用，动画结束后文字与 1px 分隔线仍然发虚；浮层文字也与页面其余文字一样使用亚像素抗锯齿

• 修复 Vue 的 XhKbd 在平台探测之后不再丢失全局配置

• 优化 三端状态机读取 props 不再按 prop 个数重复展开：Vue 200 个按钮的挂载由 29.5ms 降至 16.0ms，Web Components 100 个分页的挂载约由 112ms 降至 24ms

• 优化 Portal 视觉桥不再按「浮层数 × 自定义属性数」重读计算样式；焦点域的 Tab 判定不再按「候选数 × 容器层数」查询计算样式

• 调整 选中标记统一为行尾对号：Collection Item 家族 page 语境的对号从行首移到行尾，与浮层内的列表同列；Listbox、Tree、TagGroup 的选中外观随之统一（见升级须知）

v2.0.0 (2026-09-22)

本版为主版本升级。主要变化：@xihan-ui/kernel、@xihan-ui/machine、@xihan-ui/behavior 合并为 @xihan-ui/core；新增 React 19 适配器 @xihan-ui/react；组件由 121 个增至 134 个（新增 20 个，删除 3 个，合并 4 个，更名 5 个）。所有更名与删除均不保留别名、转发或兼容层，引用旧名会直接报错。

升级须知

以下按包、组件、部件与属性、行为四类列出破坏性变更的范围与去向。完整对照表（旧名 → 新名，逐部件、逐槽名）见各包随 npm 发布的 CHANGELOG.md。

包与依赖

• @xihan-ui/kernel、@xihan-ui/machine、@xihan-ui/behavior 合并为 @xihan-ui/core，旧包不再发布，无转发包。导出名称不变，子入口按原名平移：kernel/metadata → core/metadata、kernel/skin-check → core/skin-check、kernel/vite → core/vite、machine/vanilla → core/vanilla、behavior/presence → core/presence。诊断 core.version-mismatch 的 detail.kernelVersion 更名为 coreVersion。仅安装适配器的项目无需改动
• @xihan-ui/code-highlight 由适配器的直接依赖改为可选 peer 依赖，使用代码着色的项目需自行安装；包由 engine 组移至 features 组，包名不变
• 新增 @xihan-ui/react。公开包由 18 个变为 17 个

组件的增删与更名

• 删除 thread、composer、code-block，分别由 message-feed（配合 log）、prompt-input、code-view 替代
• result 并入 empty-state（live 默认为 polite，默认尺寸档比原来小一号；保持原样需写 live="off" 与 size="lg"）；space 并入 flex（XhSpace 未写 gap 时默认有间距，XhFlex 默认为 0，迁移时需显式写 gap="md"）；countdown 并入 timer；popselect 退役，随表单提交的场景改用 select，仅切换视图参数的场景改用 popover 组合 listbox
• 更名：ellipsis → truncate、dynamic-input → field-array、time → timestamp、qr-code → matrix-code（新增 format 选择码制）、calendar → calendar-picker（区间选择拆为新组件 calendar-range-picker；date-picker 只保留单选与多选，区间改用新组件 date-range-picker）
• color-picker 重组为组合组件：色相与透明度滑块为内嵌的 color-slider，预设色板为内嵌的 color-swatch-picker；非法或越界的文本输入不再静默复原，改为保留状态并抛出错误
• select、tags-input、tag-group 的标签统一改用 tag 组件渲染：item-delete-trigger、item-preview、item-text 不再是这三个组件的部件，对应节点为 tag 的 root / label / close-trigger；select 多选未指定 maxTagCount 时最多显示 3 枚标签，其余折叠为 +N

部件、属性与槽名

• 32 个部件更名、1 个部件并入他处；10 处同一角色在不同组件中命名不一致的部件统一命名
• 14 组 prop 更名、2 组事件更名。例如 resizable / floating-panel 的像素尺寸 size 更名为 dimensions；password-input 的 visible / defaultVisible / onVisibilityChange 更名为 revealed / defaultRevealed / onRevealedChange；virtualizer 的 onChange 更名为 onRangeChange
• 13 个 data-* 属性名删除，每组只保留一个（如 data-affixed → data-fixed；data-borderless → data-bordered，取值反转）；data-type 拆分为 data-value-type、data-severity、data-select-mode、data-reveal-mode、data-format；data-phase 与六个组件的生命周期 data-status 并入 data-state；table 的 expanded-row、tree 的 branch-content、heatmap 的 tooltip 收起态由 hidden 属性改为 data-state。CSS 选择器不会因属性名失配而报错，请在代码库中检索旧属性名
• dialog / drawer 新增 header / body / footer 三个部件，body 为面板内唯一的滚动区域；文本输入的两套控件盒槽名合并为一套，被替代的槽名删除
• 形态轴收敛：字段类组件未传 variant 时显式输出 data-variant="outline"，自定义皮肤若以「无 data-variant」判定默认态，需改为匹配 outline；button / float-button 移除 shape；loading-bar 移除 color；card 收敛为 default / secondary / tertiary / transparent 四种表面，移除 size / hoverable / split 属性与 media / body 部件
• 轻提示与通知的 type 更名为 tone，取值收敛为 info | success | warning | danger，加载态独立为布尔 loading；通知队列 max 默认值由不限改为 5；toast / alert 的 content 改为必需；empty-state 的 status 只接受 '404' | '403' | '500'，语义改由 tone 表达；steps 的 StepStatus 收敛为 completed | current | incomplete，出错与警示改由逐步 tones 表达
• 读屏文案只接受函数，不再接受字符串；flex 的 direction 别名与 FlexDirection 类型删除，只保留 orientation；listbox 的 multiple 删除，只保留 selectionMode；kbd 的单键与组合键统一为 keys 数组，默认仅展示，显式 register 后才注册监听；grid 的 cols / span / offset 增加运行时取值范围校验

行为

• 部件上同名事件处理器的执行顺序统一为「使用者的处理器先执行，部件的处理器后执行」；此前是否使用 asChild 会导致顺序相反。依赖部件先更新状态再读取的代码需改为微任务或变更回调
• pin-input 改为按顺序录入，焦点落在第一个空格；mention 的输入框改为单行；number-field 的 control 部件改为必需
• combobox、tree-select、cascader、transfer 的原生表单提交改为每个选中值一个同名隐藏字段，不再以逗号拼接；cascader 的 value 对非数组、混合类型、空路径一律拒绝
• FieldControl 与 asChild 的组合宿主改为严格检查：Fragment 内唯一控件正常接线，零个或多个节点、非空文本混排时抛出错误，不再降级生成默认按钮
• @xihan-ui/motion 删除 TweenEasing、tweenEasings、resolveTweenEasing，统一使用 EasingName、easing、resolveEasing
• 三端 XhConfig.motion 的隐式全局覆盖移除，视觉环境统一由 createVisualEnvironmentController 管理；表单字段标识统一为 FormPath，XhFormFieldGroup 的 value 更名为 name

• 新增 @xihan-ui/react：React 19 适配器，覆盖全部 134 个组件。组件名与 Vue 侧一致（Xh*），受控 / 非受控与变更载荷为同一份合同，带载荷的插槽以函数式 children 提供，无需安装 provider

• 新增 20 个组件。数据录入：calendar-range-picker、date-range-picker、time-range-picker、color-field、color-slider、color-swatch-picker、input-group、tag-group；数据展示：bar-code（一维码，七种码制）、color-swatch；浮层：command（命令面板）；AI 对话：approval（危险动作执行前的人工确认）、code-view、diff-view（单栏与并排）、markdown-stream、message-feed、prompt-input、question-flow（执行前的澄清问卷）、reasoning、tool-call

• 新增 七轴视觉环境 createVisualEnvironmentController：色彩模式、品牌、密度、书写方向、对比度、动效、透明材质统一解析、继承、持久化并投影到根元素，局部作用域只影响自身子树；Portal 按实例桥接来源处的局部视觉环境

• 新增 按压通道：Space / Enter 与触屏按住时输出 data-pressed，与指针 :active 共用同一套按压样式，覆盖全库可按下的部件

• 新增 浮层退场生命周期由 Presence 租约管理：逻辑关闭后 content 立即设为 inert 并退出可访问树，Layer、消解层与焦点域在退场动画结束后释放；dialog / drawer 新增 onExitComplete

• 新增 集合类组件补齐三种非条目状态：empty、loading、load-more-trigger；tree-select 新增懒加载分支合同（hasChildren、loadChildren({ node, signal })）及 loading / error / retry / loaded-empty 状态结构

• 新增 tabs 标签溢出时不再折行，改为沿主轴滚动：新增 prev-trigger / next-trigger，支持滚轮、焦点跟随与触屏拖动；segment 档的指示条改为滑动式

• 新增 layout 的 siderPresentation（inline / sheet），sheet 档下侧栏以覆盖方式展开

• 新增 dialog / drawer / image-viewer 的遮罩形态轴 variant；scroll-area 的边缘渐隐与到头状态；scrollbar 的 anchor

• 新增 浮层类与选择类组件的 Portal 部件支持实例级 container

• 新增 命令式对话框服务的 actionError / onActionError({ cause }) 与可本地化的 actionErrorText；popconfirm 的 onConfirm 支持返回 PromiseLike；form 新增 validationError 状态与校验异常事件，字段状态轴接入 text-field 控件

• 新增 Web Components 侧补齐四个命令式反馈服务；轻提示与通知的队列合并为一套

• 新增 @xihan-ui/tokens 十二色相基础色板；matrix-code 新增 data-matrix、gs1、pdf417、aztec 码制；tag 新增 ghost 形态与 readOnly；form 的 layout 新增 grid 档

• 新增 cascader、transfer 支持 name / form 原生表单提交，含禁用排除与原生重置

• 新增 RenderedBlock.source：代码块与公式块在已消毒的 html 之外提供未转义的原文

• 修复 四个浮层以指针打开后关闭时，焦点未按键盘规格返回触发器

• 修复 皮肤自绘的状态字形（勾选、半选、分支箭头）统一按指示符档取尺，compact 密度下与标记盒尺寸不一致的问题：select、combobox、listbox、cascader、menubar、context-menu、steps、file-upload 等

• 修复 几何类过渡按角色选择曲线档；集合条目的描边色不再参与过渡，切换标签页时不再闪烁

• 修复 补齐 11 处缺失的读屏文案；补齐两个适配器未暴露的 headless 能力（七个浮层的 dir、五个元素的 translations、分页省略位浮层的四项）

• 修复 Vue date-picker 挂载在 iframe 或其他 Document 时的运行时归属；trackHoverIntent 固定使用触发器所属的 Document

• 修复 pin-input 受控模式下输入一位跳过一格；tags-input 就地编辑框宽度随内容变化，不再按原生 input 的 20 字符宽度展开；carousel 在减弱动效档下不再自动播放

• 修复 粗指针热区平移在 RTL 下行内方向反向，热区中心偏离宿主

• 调整 带边框的控件盒统一为浅边框不填底，与浮层面板、卡片使用同一条边线；字段类组件未传尺寸时统一宽度为 16rem

• 调整 侧栏导航当前项去掉起始侧 2px 竖线，只保留品牌淡底与字色；标签页 line / card 档的标签宽度随文字；导航菜单与锚点目录中指向当前页的链接绘制静态指示线

• 调整 toggle-group 默认外观改为浅色胶囊分段控件，选中项使用品牌淡底；kbd 收敛为固定 24px 键帽，新增 default / light 两种外观；徽标 sm 档收为 14px

• 调整 菜单类组件接入集合条目配方：条目按压面由 300 改为 200，展开中的触发器改为中性面，浮层滚动条走 4px 档并增加 overscroll 隔离

v1.1.0 (2026-08-31)

• 新增 sortable 组件：列表 / 网格拖拽排序，拖动中其余条目实时让位，sort 事件直接给出重排好的 ids，键盘路径默认开着

• 新增 resizable 组件：八条边都能推的可调容器，带上下限、宽高比与吸附步进，指针与键盘两条路都通

• 新增 @xihan-ui/pointer：指针会话、多指会话与双指几何、拖放几何、尺寸调整几何四层，自研零依赖

• 新增 table 的列拖拽排序：新增部件 column-drag-trigger 与 live-region，把手自占一个 Tab 位，落点按列 id 认

• 新增 table 的行拖拽排序：rowReorderable 打开后整行可拖，树形行支持换父，搬完发 onRowMove

• 新增 table 的列宽拖拽：标了 resizable 的列产出改宽把手，宽度落进列偏好可存可还原

• 新增 tree 的节点拖拽搬家：落点三档（前 / 后 / 落进去），Alt + 方向键改同层次序与缩进，搬完发 onNodeMove

• 新增 tabs 的标签拖拽换位：reorderable 打开后整个标签可拖，Alt + 主轴方向键可挪，搬完发 onTabMove

• 新增 三个触屏拖动把手 row-drag-trigger / node-drag-trigger / tab-drag-trigger，不占 Tab 位

• 新增 选中原语 applySelection / toggleSelectAll / rangeBetween；table / tree / transfer 接上 Shift 范围选，table 另加 Ctrl / Cmd + A 全选

• 新增 image-viewer 的双指缩放

• 新增 @xihan-ui/kernel/vite 子入口：开发服务器启动时在终端打一次横幅

• 调整 浏览器控制台的启动摘要默认不打，要打显式 setMetadataAutoPrint(true)

• 调整 XIHAN_UI_LOGO 与 XIHAN_UI_SEND_WORD 从 XIHAN_UI_METADATA 摘出来单独导出，getMetadataSummary() / getMetadataDetails() 不再带寄语

• 调整 tree 的拖拽播报报出落脚处，新增 movedInto / droppedInto / canceledInto / rootLevel 四个文案键

• 调整 tree 对禁用节点只拦 inside 落点，在它前后插不再拦

• 调整 carousel 的划动与 image-viewer 的平移改走多指会话，不再逐个捕获指针

• 修复 dialog / drawer / image-viewer 的 closeOnEscape 与 closeOnInteractOutside 改为交互当时现读——浮层开着时改这两个开关此前不算数

• 修复 按住切换类的按键会来回翻转（按住 Ctrl / Cmd + A 在全选与全不选之间闪、按住空格反复拾起放下），12 处补上自动重复守卫

• 修复 八个 Vue 组件收不到全局配置里的读屏文案：combobox / popselect / resizable / sortable / table / tabs / text-field / tree

• 修复 XhTableRoot 丢掉作者写在它上面的 class / aria-* / 监听器

• 修复 table 与 tree 的键盘处理器吞掉落在可编辑单元格 / 节点内容里的按键

• 修复 开着 striped 的表里，偶数行既不响应悬停也显不出选中

v1.0.0 (2026-08-26)

版本与兼容性

首个正式版。从这一版起，版本与兼容性政策的全部条款生效。

• 新增 框架无关的无头内核：状态、交互与无障碍逻辑住在 @xihan-ui/headless，适配器只把 connect() 产出挂到宿主元素上；同一份内核在两端行为一致
• 新增 119 个组件，每个同时产出无头内核、Vue 组件、自定义元素与默认皮肤——通用 15、布局 8、导航 16、数据录入 32、数据展示 30、反馈 9、浮层 7、AI 对话 2，逐个见组件总览
• 新增 @xihan-ui/vue Vue 3 适配器，729 个部件：受控 / 非受控、v-model、带类型的作用域插槽；behavior 子入口出五个行为原语的组合式，另有四件命令式服务（轻提示、通知、对话框、顶部进度条）
• 新增 @xihan-ui/web-components 适配器，121 个自定义元素：元素不生成结构，作者写带 data-xh-part 的 Light DOM 子节点；随包出 custom-elements.json
• 新增 引擎四包：@xihan-ui/kernel 结构原语、@xihan-ui/machine 状态机运行时、@xihan-ui/behavior 行为原语、@xihan-ui/motion 动效原语
• 新增 @xihan-ui/position 浮层定位：放置、翻转、贴边、箭头锚点、rtl，自研无第三方依赖
• 新增 样式与逻辑解耦：皮肤只认 data-scope / data-part / data-*，不认框架也不认类名，整包换皮肤不用碰一行 JS
• 新增 @xihan-ui/tokens 设计令牌：DTCG 源在构建期产出 CSS 变量（原语 95、语义 158，另有紧凑 49、浅色 41、深色 44、减弱动效 8 条覆盖），运行时不做 CSS-in-JS
• 新增 @xihan-ui/styles 默认皮肤 125 份，按 @layer 分层（xihan.reset → tokens → base → components → overrides），使用者的覆盖恒排在最后
• 新增 三条视觉轴：variant 管形态、tone 管语气（六族）、size 管尺寸；实心底上的前景与交互态由语气色按 WCAG 相对亮度现推
• 新增 主题五个维度独立切换：明暗、品牌、密度、对比度、书写方向，带 createThemeController 与品牌色派生
• 新增 浮层一律 Teleport 到单一落点 #xh-portal-root，层号不受宿主祖先影响；13 个滚动宿主自带自绘滚动条
• 新增 兜底字形二十个 --xh-glyph-mark-* 令牌，构建期内联图标包 SVG，跨系统长相一致
• 新增 @xihan-ui/icons 首方图标集：IconRecord 结构化记录，运行期不解析 SVG 字符串，另有 SVG → IconRecord 的构建期转换器
• 新增 @xihan-ui/animations 可序列化动效配方、@xihan-ui/sound 程序化 UI 音效（三套主题，零音频文件）、@xihan-ui/backgrounds WebGL2 效果与粒子云
• 新增 @xihan-ui/chat-stream AI 协议内核：SSE 读取 → 协议归一 → parts 归约 → 会话 store，零 DOM 零框架
• 新增 @xihan-ui/markdown 流式 Markdown 渲染内核（CommonMark 子集一致率 489/652）与 @xihan-ui/code-highlight 自研词法着色
• 新增 键盘交互依 W3C APG 落地，77 份机读键盘规格表共 463 行键位随包提供
• 新增 焦点环、按下反馈、禁用态对比度与语气配色（2 档主题 × 6 族，158 组配对）逐条达标，无障碍扫描跑在真实 Chromium（axe）
• 新增 119 个组件都留了文案位并挂进覆盖表，全局 ConfigProvider 一处注入；rtl 下浮层放置、方向键语义与图形朝向一并对调
• 新增 24 个表单字段组件认原生表单重置；field 提供标签、描述、错误与 asChild 逃生口
• 新增 17 个公开包同版发布，运行时第三方依赖只有一个（@internationalized/date，仅日期族使用）；混装两个版本在 dev 下报 core.version-mismatch
• 新增 摇树是真的：只引一枚图标 149 B、整集合 7.37 kB，XhButton 1.38 kB、XhDialogRoot 15 kB（均 gzip）
• 新增 ESM-only，子路径导出都带类型
• 调整 元数据的宿主行只报宿主与版本，不再报版本一致性

v1.0.0-preview.0 (2026-08-26)

这一版的主线是把 alpha 里遗留的形状问题一次改完：两对做着同一件事的组件分家（toast / notification、badge / tag），三处与同族对不上的 prop 名归位，语气色从逐族写死改为按底色现推。

• 新增 notification 组件，与 toast 分家：前者是系统推来的卡片（左侧类型字形、右上角关闭钮、两列网格、九宫格落位），后者收窄成操作反馈（顶部居中、宽度包着内容、一行图标加一句话）

• 新增 分页的省略号能摊开：折进去的那几页有了入口，分页因此升级成浮层族（新增 positioner / content）；每页条数从只读 prop 升成真状态，配 XhPaginationPageSizeSelect 与 pageSizeOptions

• 新增 表格的前缀列（行号 / 勾选 / 展开，按给定顺序插在最前并占住列号）、树形子行，以及一份可序列化的列偏好（列序 / 隐藏列 / 列宽）

• 新增 树的 multiple、leafOrientation（末端全是叶子的那层横排）与节点级 childrenOrientation

• 新增 json-viewer 的原文视图 view="text"：直接出缩进过的 JSON，可整段拷走，值不再受截断与折减

• 新增 13 个宿主的滚动层自带自绘滚动条：12 个浮层族的 content 与 json-viewer 的两档，作者一个部件都不用写；滚动条同时新增 scroll-hover 档并定为缺省

• 新增 Vue 侧三条逃生口：@xihan-ui/vue/behavior 子入口（五个行为原语的组合式）、useHotkeys（只注册不渲染键帽）、XhFieldControl 的 asChild 与配套 useFieldControl

• 新增 命令式服务补齐三件：createLoadingBarService（句柄上是在途计数而不是布尔开关）、取值型 prompt、配置源可运行期换（应用切语言后服务子树跟着变）

• 新增 @xihan-ui/tokens 导出颜色能力：相对亮度、对比度、择色、混色与深浅——这套数学此前在四处各写了一份，判据各走各的

• 新增 date-picker 的 defaultFocusedValue，决定展开时先落在哪一页

• 新增 thread 补 provideThread / useThreadContext，与孪生组件 log 对称

• 调整 badge 收窄成「只做角标」：删掉 variant，解剖从单层 root 拆成 root（锚点）+ indicator（角标），新增 placement，定位归组件自己管。行内的状态药丸请改用 tag

• 调整 生命周期相位改走 data-state，data-status 退回「结果种类」一轴——此前一条 [data-status='error'] 会同时命中「加载失败的头像」和「一整页 500 报错」

• 调整 树的 selectionMode 转为 multiple 的旧写法，与同族七家对齐

• 调整 实心底上的前景色与交互态挪动方向改由语气色现推（WCAG 相对亮度，白字黑字的交叉点 0.179 是解析解），换肤下配对自动成立；装饰档 --xh-_tone-soft 从 500 提到与控件边界同一档，六族十二组都够到 3:1

• 调整 描边档的标签改用「可操作区边界」那一档语气色，边相对面的对比从 1.44–2.18 抬到 4.56–7.83（浅色）

• 调整 浮层里的条目之间加 2px 行距，新增语义令牌 --xh-list-option-gap 统一这把尺——此前库内自己就有 0 / 2 / 4px 三种方言

• 调整 select 的盒不再自带 320px 宽度上限，框宽交回布局

• 调整 上一页 / 下一页默认就画两枚箭头，不再要每份示例手写「上一页 / 下一页」四个字

• 调整 147 个注入键改用 Symbol.for：模块被加载成两份时不再整棵子树白屏

• 修复 点字段的标题聚不到复合控件的焦点；套进字段的复合控件读屏一个名字都没有——标签的 for 指向 div 时什么也不会发生，而且不报错

• 修复 useStickToBottom 吞掉句柄，最常见的用法（两个 getter 读模板 ref）下根本没挂上

• 修复 XhJsonViewerRoot 的 value 在类型上被推成 undefined，任何跑 vue-tsc 的工程传真实数据都编译不过

• 修复 命令式服务的宿主挂不起来时连累调用方：一条轻提示能让整次导航失败、整站白屏，现在退化成空操作并发一条说得清的诊断

• 修复 日历的「大步翻」两颗钮被一条 display: none 无条件收掉，从来就没画出来过

• 修复 date-picker 展开态初值为真且铺了格子时抛 SEND_BEFORE_MOUNT

• 修复 条目之间一有缝，select / combobox / popselect 的高亮就一跨一闪，读屏跟着一路播报

• 修复 四处被祖先 overflow 裁掉的聚焦环改成往内收

• 修复 树上三个对读屏隐藏的把手不再被指针聚焦（浏览器告警「aria-hidden 的后代仍持有焦点」）；叶子行补上箭头那一格的缩进，层级关系读得出来了

• 修复 菜单族两家（context-menu / menubar）的勾选标记没跟着语气走

• 优化 不可关闭的标签走快路不建状态机：400 枚从 39.1ms 降到 18.3ms

• 优化 进度条服务的宿主自己渲染，不再经 provide/inject 拿 api

• 移除 toaster：轻提示不再需要额外的容器组件

• 移除 @xihan-ui/kernel 的 DATA_SCROLL_SHARD：配套的分片机制从未实现，声明处之外全库零引用

v1.0.0-alpha.3 (2026-08-23)

这一版的主线是一致性收口：把「同一件事在不同组件里有几种做法」逐条查出来、裁一种、再钉住。

• 新增 scrollbar 组件：自绘滚动条可以挂在任意一个滚动容器上，不必是本组件的后代

• 新增 date-picker / time-picker 的快捷选项（presets）：给数据就在浮层里多排一列，自成一套 listbox 键盘

• 新增 日历的多面板、按月 / 季度 / 年 / 周挑、快速翻年、周选整周预览；周序号成为一等部件 week-number

• 新增 select 浮层的底部操作区，「新建」「全选」这类按钮有了位置

• 新增 热力图的 palette 色板轴（六色），与语气轴各管各的

• 新增 number-field 的 parse / format 与可选 control 部件；pin-input 的 pattern

• 新增 全局配置做成真正的 ConfigProvider：全局默认 + 局部覆盖，两个适配器一份语义

• 调整 浮层搬进单一落点：19 个浮层的 positioner 一律 Teleport 到 #xh-portal-root。宿主祖先只要建了层叠上下文，原地渲染的浮层层号就退化成局部序号——这是库无法从自身约束的。按 wrapper.querySelector 取浮层节点的代码要改从 document 取

• 调整 盒的定义统一：有 control 部件就是盒，trigger 退化成盒内的 flex: 1 按钮。此前 16 个输入 / 选择控件有三种盒，盒是 <button> 的那五家没法把清空钮放进框里

• 调整 清空 / 关闭 / 移除按钮收成四类契约：焦点模型、空态、尺寸、圆角、互斥、文案键、键盘路径逐条统一；select / cascader / tree-select / popselect 补上了此前完全缺席的键盘清空

• 调整 状态属性收成一套词汇：当前项一律 data-current，data-active 的一名三义拆成 data-in-path 与 data-passed，组级混合态归 checked | unchecked | indeterminate

• 调整 默认语言跟随运行时：日期系兜底从写死 zh-CN 改成「显式 locale → 全局配置 → 宿主语言 → en-US」。默认周首日随之从周一变成周日，要固定就显式传 locale 或 firstDayOfWeek

• 调整 「移除这一枚 chip / 这一行」统一叫 item-delete-trigger，四个文案键归成 deleteItem

• 调整 选择态一族（table / tree / transfer）的选中集合统一叫 selection，载荷键统一 { value }

• 调整 兜底字形改用真图标（--xh-glyph-mark-* 二十个令牌），不再是跨系统长相各异的 Unicode 字符

• 调整 减弱动效只剩一条通道，CSS 侧新增 [data-motion='reduce'] 钩子；缓动与时长的真源是令牌

• 调整 并排成对的面板定高——穿梭框搬走条目后整体不再变矮

• 调整 菜单族三家（menu / menubar / context-menu）逐条同值：menubar 此前根本没有「子菜单触发项展开态」这条规则

• 修复 side-nav 折叠成图标栏后，行按钮与链接没有可及名——读屏用户完全不知道每一项是什么（真机 axe 扫出，critical）

• 修复 date-picker / time-picker / combobox 有值时下拉钮被藏掉：鼠标用户没有打开入口，Escape 收起时焦点掉到 body

• 修复 日历周序号在周日起算时整列少 1（ISO 周里周日属于上一周）

• 修复 TimeProps.locale 的窄联合与全局 BCP 47 locale 对不上，配 de-DE 会拿到中文用词

• 修复 4 条子路径导出的类型文件根本不存在，按这些子路径引入时类型全部解析不到

• 优化 无障碍：真机 axe 覆盖到 dialog / drawer / image-viewer 三个模态，全部通过

• 优化 版本策略页按实测重算：data-state 取值清单删掉 4 个库里已不存在的，WC 命令式方法从 22 条改成 29 条

v1.0.0-alpha.2 (2026-08-16)

@xihan-ui/motion 与 @xihan-ui/animations 是新包，这一版首次发布。

• 新增 @xihan-ui/motion 动效原语与 @xihan-ui/animations 现成动效两个包，并补齐动效地基的四个缺口

• 新增 @xihan-ui/icons 的 SVG → IconRecord 构建期转换器：xihan-icons 命令与 @xihan-ui/icons/codegen 子路径，把任意 SVG 目录转成可摇树的运行期模块

• 新增 首方图标集扩到覆盖中后台界面的常用语义，共 179 枚手绘图标，分九类；只引一枚仍是 149 B（gzip），集合变大不影响你的产物

• 新增 自定义元素的全局文案层 setXhConfig()

• 新增 startSkinCheck() 开发期探测与 styles.missing-skin 诊断码——漏引皮肤不再静默

• 优化 75 个组件的插槽写上真类型，vue-tsc 从此接得住插槽名与载荷键名的拼写错误

• 优化 104 个组件全部留出 <Comp>Translations 的位，哪怕眼下一句文案都没有——后面要加时不必改结构

• 优化 每份皮肤都能单独引入，动画不再指望别处的文件在场

• 修复 官网作为第一个真实消费方落地时暴露的四条问题（宿主定位、图层序等），全部改代码而非只改文档

• 调整 collection 铺开的结构必须凑齐必备部件，三档语义写进文档

v1.0.0-alpha.1 (2026-08-13)

@xihan-ui/sound 是新包，这一版首次发布；@xihan-ui/icons 在上一版没能发出去，这一版补齐。

• 新增 @xihan-ui/sound 声音层：纯 Web Audio 的程序化 UI 音效，零音频文件、零第三方依赖、框架无关；命令式反馈服务已接上

• 新增 进度条的环形与仪表盘两种形态（variant 由 line 扩成 line / circle / dashboard）

• 新增 级联选择的空态兜底：empty 部件、data-empty 标记与文案覆盖

• 新增 checkbox / switch / combobox / color-picker 能进 HTML 表单，表单字段组件由 18 个变 20 个，五个缺口清完

• 新增 复合控件响应表单重置：机制本体加 17 个组件全部接上；Web Components 侧同步

• 新增 --xh-border-control / --xh-border-control-hover 两支控件边界令牌，data-contrast 随之接上

• 新增 popconfirm 与 float-button 的组件文档页第一次有了 Props 表

• 修复 摇树第一次真的生效：只用一个组件不再拖来整个库。此前七个库包都是单入口打包，500+ 模块被摊平进一份 dist/index.js，sideEffects: false 随之失效。实测只用 XhBadge 由 168,947 B 降到 538 B

• 修复 RTL 下浮层的 start / end 第一次真的翻过来

• 修复 浮层箭头指向锚点，不再钉死在浮层中点

• 修复 index.css 的级联层序：层序声明挪到入口最顶，此前令牌与部分组件皮肤抢先立层

• 修复 四处只在真实宿主里才现形的缺陷（含首屏即展开的对话框与抽屉能服务端直出、无 window 的宿主里不再抛异常）

• 修复 带语气的 outline 控件边框补到 3:1，控件边界切到 border.control，WCAG SC 1.4.11 第一次真的达标

• 修复 补齐 4 处「边框改不动」的覆盖槽

• 修复 combobox 展开按钮翻面只转箭头字形，不再带着悬停底色一起转

• 修复 级联选择的空态占位在 Web Components 侧补齐，两个适配器不再分叉

• 调整 跨组件已经分叉的名字统一回一套（7 处）。part 名与 prop 名在 1.0 之后就是公开 API，趁 alpha 一次改完，逐条迁移点见各包 CHANGELOG

• 调整 下拉与列表族的条目度量与高亮档位统一成两档制，分两批铺完 12 个组件

• 调整 级联选择皮肤翻修：展开路径改品牌淡底加粗、分支条目补右向箭头、列改内容撑宽定高

• 调整 hideOutside 的入参形状随真实宿主那四处修复一并变化

v1.0.0-alpha.0 (2026-08-11)

框架无关重写

基座

• 新增 @xihan-ui/kernel 结构原语：anatomy、mergeProps、normalizeProps、Scope、context、id 生成，以及浮层定位、虚拟滚动、代码着色三个端口的类型契约
• 新增 @xihan-ui/machine 自研薄状态机：定义层、createService 解释器与 vanilla 运行时，受控值绑定与效应生命周期
• 新增 @xihan-ui/behavior 交互行为原语：消解层、焦点域、滚动锁、进出场，随后补上条目集合导航（roving tabindex 底座）与首字母连打检索
• 新增 @xihan-ui/tokens 设计令牌体系与主题运行时，令牌从 DTCG 源产出 CSS / JSON / TS 三种形态
• 新增 @xihan-ui/styles 纯 CSS 皮肤层，后续补上 reset 层
• 新增 @xihan-ui/kernel 全局诊断通道，状态机错误投递进该通道而不是抛在使用者脸上

适配器

• 新增 @xihan-ui/vue Vue 3 适配器，Button / Dialog 纵切片先打穿全链路
• 新增 @xihan-ui/web-components Web Components 适配器，Light DOM 行为宿主；xh-dialog 把「有状态组件也能框架无关」这件事验证掉
• 新增 WC 侧观察 Light DOM 增删并重新接线，抹平「运行期增删条目」上的适配器分叉
• 新增 WC 角色节点契约校验与 Custom Elements Manifest 生成

组件

• 新增 102 个组件逐批铺开，每个都同时产出无头内核、Vue 组件、自定义元素与默认皮肤：从 Button / Dialog 起，经 Switch、Checkbox / Collapsible / Separator、Toggle / Progress / Badge、RadioGroup / Tabs / Accordion、Tooltip / Popover、Menu、Select / Avatar / Field、NumberField，到日期族与最后一批，双适配器铺满
• 新增 alert / spinner / skeleton / empty-state 四个反馈类组件
• 新增 Checkbox 三态
• 调整 Select 支持多选，选中值由单值改为集合：SelectValueChangeDetails.value 由 string | null 变 string[]，SelectApi 的 value / valueText 变数组，setValue 签名变 (next: string | string[]) => void；Vue 侧 update:value 载荷与 WC 侧 value-change 的 detail 随之变化。见选择器

视觉词汇表

• 新增 三个正交的视觉轴：variant 形态（solid / subtle / outline / ghost）、tone 语气（brand / neutral / success / warning / danger / info）、size 尺寸（sm / 缺省 / lg）。语气做成与组件无关的共享一层，各组件的形态规则只消费它声明的私有槽——加一个语气改一处，不是逐个组件写六遍
• 新增 34 个组件接入这套词汇表：按钮族与表单控件、十个输入类组件、以及标签页、步骤条、菜单族、分页、表格、对话框、抽屉等。没写轴的组件外观与接入前逐值一致
• 调整 实心底上的前景色按实测对比度分派而非统一白字：600 档上白字对 brand 5.08、neutral 7.80、danger 4.83 达标，而 success 3.04、warning 2.70、info 3.47 都不到 4.5，这三族配深字
• 调整 破坏性变更：alert 的 variant 改名为 tone。它原本的取值是 success / warning / danger——那是语气不是形态，与全库词汇表冲突。取值不变，只改属性名；同时移除公开导出的 AlertVariant 类型
• 调整 toast 的配色改走共享语气层，由 type 内部派生（error → danger，loading → 中性），公开 API 不变
• 调整 三条轴由裸 string 收成联合类型，从 @xihan-ui/kernel 导出：Tone（六档）、Size（sm / md / lg）、ControlVariant（outline / subtle / ghost，十二个输入控件）与 ActionVariant（前者再加 solid，按钮族）
• 修复 checkbox 半选态的横杠此前不可见：方框只在全选时填色，半选保持画布底，而横杠用的是实心底上的前景色，白压白等于没画

自研替换第三方

• 新增 @xihan-ui/position 自研浮层定位引擎（包含块解析、缩放换算、翻面与避让、跟随更新），移除 @floating-ui/dom
• 新增 自研虚拟滚动内核，移除 @tanstack/virtual-core
• 新增 WC 自研响应式基类，移除 @lit/reactive-element
• 新增 @xihan-ui/markdown 自研解析与渲染，移除 markdown-it
• 新增 代码着色走端口，内置自研粗粒度词法器，可换 Shiki
• 调整 至此全部库包的运行时第三方依赖只剩一个（@internationalized/date，仅日期族使用）。见包与依赖关系

AI 与 Markdown

• 新增 @xihan-ui/chat-stream 协议内核与 AI 组件族第一批：SSE 读取、协议归一、parts 归约、会话 store，配 Thread / Composer / CodeBlock 三件与粘底原语，双适配器
• 新增 @xihan-ui/markdown 流式渲染内核，增量切块 + 稳定 key + 消毒
• 优化 Markdown 逐步实现缩进代码块、Setext 标题、跨行链接引用定义与列表松紧排布，CommonMark 官方用例一致率由 375 提升至 489

视觉层

• 新增 @xihan-ui/backgrounds：WebGL2 背景效果与数据驱动粒子点云，框架无关、零第三方依赖。流场跑片元着色器、粒子走 gl.POINTS，两通道共用同一段 GLSL；内置 14 个效果，不支持 WebGL2 时降级为 CSS 静态背景
• 新增 两个适配器接上视觉层，各走独立子入口 @xihan-ui/vue/backgrounds 与 @xihan-ui/web-components/backgrounds，@xihan-ui/backgrounds 声明为可选 peer
• 修复 修复画面在真实页面里一片空白的三个成因

图标

• 新增 Icon 原语：IconRecord / IconNode / IconTag 类型、connectIcon、XhIcon、<xh-icon> 与 icon.css。图标数据是结构化节点数组而非 SVG 字符串，渲染端逐节点建元素，运行期不经 HTML 解析器
• 移除 旧 @xihan-ui/icons（27 个第三方图标集的聚合，约四万个图标）整包移除并在 npm 上弃用，重写为只收自研图标的首方集，第一批 29 个覆盖组件库自用的全部语义

无障碍

• 新增 无障碍扫描接上真实浏览器与 axe，逐个组件扫
• 新增 键盘规格表机读化，随包提供
• 修复 存量无障碍违规清零，由 24 条降到 2 条（WC 侧 steps 一条，外加一条步骤重放豁免）
• 修复 令牌 fg-subtle 达到 AA，并给对比度立下判据
• 修复 焦点陷阱抓不住第一次逃逸；移除持有焦点的条目后不再让整组脱离 Tab 序列；删掉文件上传条目后把焦点交回投放区
• 修复 浮层族改用 fixed 坐标系，不再被 overflow 祖先裁掉
• 修复 挡住输入法组合态
• 修复 Dialog 三处：模态背景失活、非模态焦点域、收起态 hidden
• 修复 Field 的名字关联不再依赖 control 是可标注元素；Splitter root 不再输出 aria-orientation
• 修复 消解层只在展开期间入栈，不再与开合无关地常驻
• 修复 状态机停机后送入的事件一律静默丢弃，dev 下不再抛

令牌与发布

• 调整 皮肤层令牌成为唯一事实源，删掉全部字面量兜底，跨组件共享的默认值全部令牌化
• 新增 14 个公开包锁步同版发布