@xihan-ui/web-components 1.0.0-alpha.0 → 1.0.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,216 @@
 # @xihan-ui/web-components
 
+## 1.0.0-alpha.1
+
+### Major Changes
+
+- d43624c: 把跨组件已经分叉的名字统一回一套。part 名与 prop 名在 1.0 之后就是公开 API——皮肤按
+  `data-part` 选择、使用者按 prop 名调用——改名一律是破坏性变更，所以趁 alpha 一次改完。
+
+  **time-picker 的列表条目由 `option` 改叫 `item`。** 另外 32 个组件的列表条目都叫 `item`，
+  只有它是 `option`。ARIA 角色仍是 `role="option"`（那是角色不是部件名），列里的候选值集合
+  `TimePickerColumn.options` 也不动（那是数据不是部件）。
+
+  迁移点：
+
+  - `data-part='option'` 改成 `data-part='item'`；皮肤覆盖槽 `--xh-time-picker-option-*`
+    改成 `--xh-time-picker-item-*`（共 10 个）。
+  - Vue 组件 `XhTimePickerOption` 改名 `XhTimePickerItem`。
+  - WC 的 `::part(option)` 改成 `::part(item)`。
+  - headless 导出：`timePickerOptionQuery` → `timePickerItemQuery`、`findTimePickerOption` →
+    `findTimePickerItem`、`timePickerOptionValue` → `timePickerItemValue`、
+    `TimePickerOptionProps` → `TimePickerItemProps`。
+  - `TimePickerApi` 上：`getOptionProps` → `getItemProps`、`isOptionSelected` → `isItemSelected`、
+    `isOptionDisabled` → `isItemDisabled`、`focusedOption` → `focusedItem`。
+  - 键盘规格号 `time-picker.kbd.option-*` → `time-picker.kbd.item-*`。
+
+  **transfer 的数据入口由 `items` 改叫 `collection`。** 另外 17 个集合组件的数据入口都叫
+  `collection`。单条的类型名 `TransferItem`、某一侧看得见的条目 `visibleItems`、纯函数
+  `transferVisibleItems` 都不动——它们说的是「条目」，不是「数据入口」。
+
+  迁移点：
+
+  - Vue：`<XhTransferRoot :items="…">` 改成 `:collection="…"`。
+  - WC：`el.items = […]` 改成 `el.collection = […]`（这个入口表达不成属性，本来就只能走 property）。
+  - `TransferApi.items` → `TransferApi.collection`。
+
+  **checkbox-group 的组内子部件对齐 radio-group。** 同一语义两套名字：checkbox-group 用
+  `item-control` / `item-hidden-input`，radio-group 用 `indicator` / `hidden-input`。裸名是全仓
+  多数（`indicator` 13 处、`hidden-input` 10 处），checkbox-group 随大流。`item-text` 不动
+  （21 份解剖都这么叫）。
+
+  迁移点：
+
+  - `data-part='item-control'` → `'indicator'`，`data-part='item-hidden-input'` → `'hidden-input'`。
+  - 皮肤覆盖槽 `--xh-checkbox-group-control-*` → `--xh-checkbox-group-indicator-*`（10 个），
+    与 radio-group 的 `--xh-radio-group-indicator-*` 对齐。
+  - `CheckboxGroupApi.getItemControlProps` → `getIndicatorProps`，
+    `getItemHiddenInputProps` → `getHiddenInputProps`（两个名字 radio-group 早就在用）。
+  - Vue 组件 `XhCheckboxGroupItemControl` → `XhCheckboxGroupIndicator`。
+
+  **table 的空态部件由 `empty-state` 改叫 `empty`。** 部件名不该与组件的 scope 名撞车——
+  `empty-state` 是一个独立组件的 `data-scope`，再拿它当 table 的部件名，写皮肤时
+  `[data-part='empty-state']` 与 `[data-scope='empty-state']` 混在一起读不出谁是谁。
+  combobox 早就叫 `empty`。独立的 `empty-state` 组件本身不动。
+
+  迁移点：
+
+  - `data-part='empty-state'` → `'empty'`。
+  - `TableApi.getEmptyStateProps` → `getEmptyProps`。
+  - Vue 组件 `XhTableEmptyState` → `XhTableEmpty`（`XhEmptyState*` 那一族是另一个组件，不变）。
+  - WC 的 `::part(empty-state)` → `::part(empty)`。
+
+  **transfer 的 `onSelectedChange` 改叫 `onSelectionChange`。** table 与 tree 都叫
+  `onSelectionChange`。受控的 `selected` prop 与载荷字段 `{ selected }` 不动——那是「被勾中的值」，
+  与回调名说的不是一回事。
+
+  - `TransferSelectedChangeDetails` → `TransferSelectionChangeDetails`。
+  - Vue 事件 `@selected-change` → `@selection-change`；WC 的 `selected-change` 事件同改。
+  - `v-model:selected` 不变。
+
+  **`size` 不再一名两用。** 三轴里的 `size` 是语气枚举，而 qr-code 的 `size` 是像素数值、
+  splitter 的 `size` 是百分比数组——两者占着同一个名字却是完全不同的类型，使用者写
+  `size="md"` 得到的是静默的错。
+
+  - qr-code：`size` → `pixelSize`（WC 属性 `size` → `pixel-size`）。中心 logo 挖空区的
+    `QrCodeLogoArea.size` 是模块数标量，不动。
+  - splitter：数组值的一律改复数——`size` → `sizes`、`defaultSize` → `defaultSizes`、
+    `onSizeChange` → `onSizesChange`、`onSizeChangeEnd` → `onSizesChangeEnd`、载荷字段
+    `{ size }` → `{ sizes }`、机器事件 `SIZE.SET` → `SIZES.SET`、Vue 的 `v-model:size` →
+    `v-model:sizes`、WC 属性 `size` → `sizes`。标量的不动：每块面板的 `collapsedSize`、
+    `BOUNDARY.SET` 的 `size`、`setPanelSize`、`SplitterPanelState.size`。
+
+  **没有合并的一处，记在这里免得后人重新翻案。** 就绪度审计说 pin-input 的 `onValueComplete`、
+  editable 的 `onValueCommit`、slider 的 `onValueChangeEnd` 是「三个名字表达同一语义」，
+  逐条读过源码后判定不成立：`onValueComplete` 是「每格都填满的那一刻」（值的形状谓词），
+  `onValueCommit` 是「提交那一刻」（用户显式确认），`onValueChangeEnd` 是「一次操作结束」
+  （手势结束，splitter 的 `onSizesChangeEnd` 用的是同一套）。三件不同的事，合并会让 API 更差。
+
+### Minor Changes
+
+- a19bbaa: 级联选择补空态兜底：新增 empty 部件，搜索无候选或 collection 为空（根列没有条目）时露面，其余时候带 hidden。
+
+  - headless：`getEmptyProps` 管空态占位的露面与收起；`getSearchListProps` 无候选时带 `data-empty`，`getContentProps` 根列没有条目时带 `data-empty`；新增 `translations` prop（`empty` / `noMatch` 两键，默认英文）与 api 上并入默认后的完整一份。
+  - vue：`XhCascaderContent` 自动补渲空态占位，`empty` 插槽可换内容，缺省文案按视图取无匹配或无数据；`translations` prop 接入全局 `provideXhConfig` 注入点（`translations.cascader`）。
+  - web-components：新增可缺省的 `empty` 部件，元素代管其 hidden，文案归作者。
+  - styles：空态占位居中排版（`--xh-cascader-empty-min-h` / `--xh-cascader-empty-p` / `--xh-cascader-empty-fg` 可覆写）；无候选时候选列表不再占位，根列没有条目时空列让位。
+
+- ea78591: checkbox 与 switch 能进 HTML 表单了。表单字段组件从 18 个变成 20 个，五个缺口清完。
+
+  **先纠正一条我此前记错的约束**：我曾把这两个记为「要单独一轮，因为 HTML 内容模型禁止 button 有
+  交互后代」。查规范后不成立——interactive content 的定义里 `input` 那条写的是「**type 属性不处于
+  Hidden 状态时**」，所以 `<input type="hidden">` 不是交互内容，放进 `<button>` 里是合法的。
+  DOM 不必重构，与 color-picker、combobox 同一条路。
+
+  - 新增 `hidden-input` 部件、`name` 与 `value` 两个 prop（`value` 缺省 `'on'`，与原生一致）。
+  - **勾上才带 `name`**：没勾就整条不参与提交，这是原生复选框的语义。
+  - **半选按未勾处理**：原生里 indeterminate 只是外观，提交与否看 `checked`。
+  - Vue 侧由组件自己渲染（单体控件没有子部件插槽，作者递不进来），**给了 `name` 才有这个节点**——
+    没给就与从前逐字节相同。WC 侧照旧由作者写 `data-xh-part="hidden-input"`。
+
+  **两者的重置走转移而不是写 context**：它们的值就是机器状态（`on` / `off` / `indeterminate`），
+  没有值 cell 可 reset。`FORM.RESET` 因此是一组带守卫的转移，受控时只发意图、非受控才真的转过去；
+  已经停在默认态就不白发一次通知。
+
+  如实记一处限制：`onCheckedChange` 的载荷刻意只有布尔（「用户交互的落点只可能是全选或全不选」），
+  表达不了半选。所以回落点是半选时状态照常转、通知不发；受控且默认半选的组合因此拿不到重置。
+  不为这一处去改已公开的载荷类型。
+
+- 72dc39c: color-picker 能进 HTML 表单了。
+
+  此前它既没有 `name` prop 也没有表单影子——放进 `<form>` 里提交，`FormData` 里没有这个字段。
+  同仓 11 个组件早就做全了这件事，它是缺口之一。
+
+  照仓内既成的形状补：新增 `hidden-input` 部件（`type=hidden`，排在解剖末位）、`name?: string` prop、
+  `ColorPickerApi.getHiddenInputProps()`。影子产出的属性恰好五条——parts 属性、`type`、`name`、`value`、
+  `disabled`——`type` 必须排在 `value` 前（改 type 会重置输入的值），`name` 不给就整条不产出、这份输入
+  不参与提交，禁用时带原生 `disabled` 不提交值，只读照常提交。
+
+  **这是纯增量**：影子是作者自己写的可选部件（Vue 侧新增 `XhColorPickerHiddenInput`，WC 侧新增
+  `::part(hidden-input)`），不写它就不存在，既有 DOM 与皮肤选择器一个字节不变。
+
+- a7e8755: combobox 能进 HTML 表单了。
+
+  此前它既没有 `name` prop 也没有表单影子——放进 `<form>` 提交，`FormData` 里没有这个字段。
+
+  **形状照 tree-select，不另起一套**：单个 `hidden-input` 部件（`type=hidden`，排在解剖末位），
+  多选按逗号拼成一串。同为多值浮层选择器的 tree-select 已经是这个形状，combobox 换一种（比如
+  一值一个影子输入、或隐藏 `<select multiple>`）会凭空造出第二套约定。
+
+  如实记一笔：逗号拼串对含逗号的值不可逆，也不是原生的多值 `FormData`（`name=a&name=b`）。
+  这是 tree-select 已有的性质，要改得两个一起改，是另一件事。
+
+  纯增量：影子是作者自己写的可选部件，不写它就不存在，既有 DOM 与皮肤选择器一个字节不变。
+  判据也按这个形状加——只在本用例的 fixture 里挂影子，其余用例的 order/counts 一条没改。
+
+  **顺带被门禁逼出来的一件事**：加了 `name` 之后 `check-form-reset` 当场变红——带 `name` 就是表单
+  字段，就必须认表单重置。combobox 因此一并接上了 `FORM.RESET`：值与输入串是两条独立受控轴各判各的，
+  高亮锚点一并清（它指向的条目可能已被过滤掉）。表单字段组件从 17 个变成 18 个。
+
+- 04a85b4: Web Components 侧接上表单重置。
+
+  上一版只接了 Vue：`MachineController` 里一处都没有，`xh-radio-group` 这类元素放进 `<form>` 点重置
+  一动不动。机器那侧 17 条 `FORM.RESET` 声明全在，事件却永远送不进去。
+
+  `MachineController` 现在在 `hostConnected` 里挂桥、`hostDisconnected` 里撤桥。元素自己就是锚点
+  （Light DOM），断连再重连会重建——搬出表单再搬回来仍然认新那份表单的重置。桥挂在 `mount` 之后：
+  挂上就可能有事件送进来，而 mount 之前送会撞上 `SEND_BEFORE_MOUNT`。
+
+  **门禁补上了让这次假绿成为可能的那一半。** `check-form-reset` 此前只查 headless 声明了事件，
+  不查适配器接没接——所以 WC 一直没接线，它一直是绿的。现在多一条总闸检查：两个适配器各自唯一的
+  接入点必须还在。桥一拆，17 个组件的重置会一起静默失效而每一条声明看着都还在，这正是逐组件检查
+  天生看不见的那类。拆掉 WC 那座桥实跑过，如期变红。
+
+- a41b931: 进度条新增环形与仪表盘两种形态。
+
+  - 新增 `variant` 轴：`line`（缺省，行为逐字不变）/ `circle` / `dashboard`，以及 `canvas`（承载环的 svg）与 `label`（环心那一块）两个可缺省部件。
+  - 新增 props：`strokeWidth`（环的线宽，viewBox 单位，缺省 6）、`gapDegree` 与 `gapPosition`（仪表盘的缺口，缺省 75 度朝下）、`valueText`（进度不是百分比时给读屏念的那句话）。线宽是 prop 不是令牌——它改的是几何，半径要跟着往里收；线形的厚度仍走 `--xh-progress-thickness`。
+  - 环的直径、底槽色、进度色与端点形状走令牌（`--xh-progress-size` / `-track` / `-range` / `-linecap`），几何由连接层算好写进标记，皮肤只上色。
+
+  顺带两处修正：
+
+  - 退化输入不再算成满进度：`max` 不为正或不是数时回落 100，`value` 不是数时按 0 处理（此前 `max=0` 会让进度算成满格）。
+  - 线形的长度不再取整：`value=3 / max=8` 由 38% 改为 37.5%，相邻两档不会再看起来一样长。
+
+### Patch Changes
+
+- 67375fe: cascader 的空态占位在 WC 侧补齐，两个适配器不再分叉。
+
+  空态占位在 Vue 侧由 `XhCascaderContent` 内部无条件渲染，作者一个字都不用写；WC 是 Light DOM、
+  解剖归作者，`put('empty', …)` 遇不到节点就是空操作。于是同一份标记在 Vue 上有 `empty`、在 WC
+  上没有——逐帧比对的 cascader 一整套 22 条从加空态那天起就是红的，而当时只补了 Vue 侧的单独用例。
+
+  WC 侧改成：标记里没写 `empty` 就在 `content` 末尾补一个，位置与 Vue 侧一致，文案按当前视图取
+  `noMatch` 或 `empty`。作者写了就用作者那份，只接线不新建，文案也一概不碰（判定沿用 `value-text`
+  那套「首次见到该节点时若已有内容即判为归作者」）。
+
+  顺带补上 `translations` 属性：cascader 是 WC 侧少数几个没声明它的元素之一，不补的话补出来的
+  占位文案改不动。
+
+  迁移点：无。作者已经写了 `empty` 的标记行为逐字不变；没写的从「什么都没有」变成「有一个按需
+  显隐的占位」。
+
+- Updated dependencies [a19bbaa]
+- Updated dependencies [ea78591]
+- Updated dependencies [72dc39c]
+- Updated dependencies [a7e8755]
+- Updated dependencies [e50a7c9]
+- Updated dependencies [98d7ffe]
+- Updated dependencies [d43624c]
+- Updated dependencies [239eb5d]
+- Updated dependencies [89d8c54]
+- Updated dependencies [a41b931]
+- Updated dependencies [0a57e2f]
+- Updated dependencies [24721f4]
+- Updated dependencies [4b949c2]
+  - @xihan-ui/headless@1.0.0-alpha.1
+  - @xihan-ui/machine@1.0.0-alpha.1
+  - @xihan-ui/behavior@1.0.0-alpha.1
+  - @xihan-ui/kernel@1.0.0-alpha.1
+  - @xihan-ui/position@1.0.0-alpha.1
+  - @xihan-ui/code-highlight@1.0.0-alpha.1
+  - @xihan-ui/backgrounds@1.0.0-alpha.1
+
 ## 1.0.0-alpha.0
 
 ### Major Changes

package/README.md

@@ -11,9 +11,9 @@ Web Components 适配器：把框架无关的 headless（anatomy + machine + con
   元素类的定义式不再在模块求值那一刻取 `HTMLElement`；`defineElement` 无 `customElements` 时静默跳过。
   判据在 `tests/node-smoke.spec.ts`。
 - **升级前的形态**：收起态由元素在 `wire()` 里用内联 display 做，`data-scope` / `data-part` 也是
-  那一刻才打上，所以 JS 到达前浮层子树既没有皮肤也没有收起。styled 的 `styles/undefined.css`
+  那一刻才打上，所以 JS 到达前浮层子树既没有皮肤也没有收起。styles 的 `css/undefined.css`
   按作者写的 `data-xh-part` 把浮层族的 backdrop / content / positioner / viewport 收起来，
-  SSR 直出的首屏不会把浮层内容倾泻进页面流。不引 styled 的宿主需自行处理这一段。
+  SSR 直出的首屏不会把浮层内容倾泻进页面流。不引 styles 的宿主需自行处理这一段。
 - 基类在 `src/reactive/`：属性 → 字段的单向转换、批量异步更新、控制器生命周期。
   `tests/reactive-parity.spec.ts` 是差分判据，逐条对拍 `@lit/reactive-element`（仅 devDependency）。
 
@@ -21,7 +21,7 @@ Web Components 适配器：把框架无关的 headless（anatomy + machine + con
 
 - **Presence 模型不同（已知差异，非缺陷）**：Vue 用 Presence 卸载 content（关闭即从 DOM 移除）；
   WC 是 Light DOM，不能删用户节点，content **常驻**，关闭态只由 `data-state="closed"` 标记，
-  视觉隐藏交给 styled 层的 `[data-state='closed']{display:none}`。因此两端关闭态 DOM 不同
+  视觉隐藏交给 styles 层的 `[data-state='closed']{display:none}`。因此两端关闭态 DOM 不同
   （Vue 无 content 节点，WC 有 content[data-state=closed]），Button 可做逐帧 parity、
   Dialog 暂用各自 conformance（Dialog 全量 parity 需 presence 容差，留待后续）。
 - **顶层/Portal**：真机可给 content 加 Popover API 上顶层；jsdom 无 Popover，当前只靠