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

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# @xihan-ui/web-components
+
+## 1.0.0-alpha.0
+
+### Major Changes
+
+- bc65cb7: 首个公开版本：框架无关的 UI 基座。
+
+  自研薄 FSM 内核 + headless（anatomy / machine / connect）+ 设计令牌与主题运行时 + 样式层，
+  102 个组件在 Vue 与 Web Components 两套适配器上共用同一份内核，跨适配器一致性套件与
+  真实 Chromium 里的无障碍扫描、浮层定位契约全绿。
+
+  浮层定位、虚拟滚动、Web Components 响应式基类、代码着色、流式 Markdown 均为自研，
+  运行时不带第三方依赖。
+
+- 84b1aa3: 新增 Icon 原语，`@xihan-ui/icons` 整包重写为首方图标集。
+
+  旧的 `@xihan-ui/icons` 是 27 个第三方图标集的聚合（约四万个图标），已整体移除并在
+  npm 上弃用。新包只收自研图标，第一批 29 个覆盖组件库自用的全部语义，24×24 单色
+  描边、`stroke-width` 2。
+
+  用法：
+
+  - `@xihan-ui/kernel` 导出 `IconRecord` / `IconNode` / `IconTag` 三个类型
+  - `@xihan-ui/headless` 导出 `connectIcon` / `iconAnatomy` / `iconMeta` / `iconKeyboard`
+  - `@xihan-ui/vue` 导出 `XhIcon`，`@xihan-ui/web-components` 注册 `<xh-icon>`
+  - `@xihan-ui/styles` 新增 `icon.css`，`data-size` 与 `data-weight` 各三档
+
+  图标记录是结构化节点数组而不是 SVG 字符串，渲染端逐节点建元素，运行期不经 HTML
+  解析器。图标数据传的是记录本身而不是名字：按名字查表要把全表静态引进来，摇树会
+  整个失效。
+
+  WC 侧要在 `<svg data-xh-part="root">` 里留一个空的 `<g data-xh-part="glyph"></g>`
+  作为授权点，元素只在它内部铺图元；不留这个空壳就一个节点都不动，手写内联 SVG 与
+  `<use>` 引用两种写法因此都还能用。`icon` 是对象，只能走 property 传，属性里写不出来。
+
+  可及名字两态互斥：`label` 给了非空白文本就输出 `role="img"` 与 `aria-label`，否则
+  输出 `aria-hidden="true"`。只有图标的按钮请把名字写在按钮上而不是图标上，两处都写
+  读屏会念两遍。
+
+- e788896: Select 支持多选，选中值由单值改为集合，公开 API 破坏性变更。
+
+  多选打开方式是 `multiple`：点中条目即在集合里增删该项，列表不收起；单选行为不变，只是选中值
+  的容器形状统一成了数组（单选恒为长度 ≤ 1）。
+
+  迁移点：
+
+  - `SelectValueChangeDetails.value` 由 `string | null` 变 `string[]`。原先判空写 `details.value === null`
+    的，改判 `details.value.length === 0`；取单选值写 `details.value[0]`。
+  - `SelectApi` 的 `value` 与 `valueText` 由单值变数组，两者逐项对应；`setValue` 签名变
+    `(next: string | string[]) => void`，裸串按单选简写处理；新增 `multiple`。
+    想拿「显示成什么字」不必自己拼，用 `displayText`：有选中取选中项文本（多选按半角逗号加空格连起来），
+    否则取 `placeholder`。
+  - Vue 默认插槽暴露的 `value` 与 `setValue` 随之变化；`update:value` 的载荷由单值变数组，
+    因此 `v-model:value` 绑定的变量类型要一并改。`value` / `default-value` 两个 prop 仍接受裸串与 `null`。
+  - WC `value-change` 事件的 `detail` 由 `{ value: string | null }` 变 `{ value: string[] }`；
+    新增 `multiple` 属性。`value` 属性只递得进单值，多选集合请写 property。
+    表单影子 `hidden-select` 不再写 `value`，选中态一律由 `option` 的 `selected` 表达（多选时开原生
+    `multiple`）—— 靠读 `hidden-select.value` 反查选中项的代码要改成读 `selectedOptions`。
+
+### Minor Changes
+
+- c5c5f7f: 两个适配器接上视觉层，各自走独立子入口 `@xihan-ui/vue/backgrounds` 与 `@xihan-ui/web-components/backgrounds`。
+
+  `@xihan-ui/backgrounds` 声明为**可选 peer**：主入口一行都不引它，不用视觉效果的应用不会因为装了适配器
+  而多出一个 WebGL 引擎。
+
+  Vue 侧三种用法，从轻到重：`v-background` 指令、`XhBackground` 组件、`useBackground` 组合式函数。
+  指令用在组件上时 Vue 会把它落到该组件的单一根元素上，所以给现成组件加背景不必改动组件本身。
+
+  WC 侧是 `<xh-background>`：元素自身就是画布容器，内容照常写在里面，效果铺在内容底下，
+  画布 `pointer-events: none` 不挡交互。参数走 `.params` property，点云走 `.setCloud()`。
+
+### Patch Changes
+
+- Updated dependencies [bc65cb7]
+- Updated dependencies [84b1aa3]
+- Updated dependencies [e788896]
+- Updated dependencies [46b82b0]
+  - @xihan-ui/kernel@1.0.0-alpha.0
+  - @xihan-ui/machine@1.0.0-alpha.0
+  - @xihan-ui/behavior@1.0.0-alpha.0
+  - @xihan-ui/headless@1.0.0-alpha.0
+  - @xihan-ui/position@1.0.0-alpha.0
+  - @xihan-ui/code-highlight@1.0.0-alpha.0
+  - @xihan-ui/backgrounds@1.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-Present XiHanFun and contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @xihan-ui/web-components
+
+Web Components 适配器：把框架无关的 headless（anatomy + machine + connect）落在
+自研基类 `XhReactiveElement` 上的 **Light-DOM 行为宿主**（零第三方运行时依赖）。
+
+- 元素不渲染结构；用户写带 `data-xh-part` 的 Light-DOM 子节点，元素发现后用
+  `spreadProps` 把 `connect()` 产出命令式打上去。每个组件一个 `xh-*` 元素，part 不是各自的元素。
+- `MachineController` 把机器唯一解释器 `createService` 桥到 controller 生命周期，
+  不重造 FSM。元素类只在 `@xihan-ui/web-components/define` 子路径，`defineXhElements()` 显式注册。
+- **两个入口在 Node 下都可安全 import**：基类无 DOM 时取一个替身基座（`src/reactive/element.ts`），
+  元素类的定义式不再在模块求值那一刻取 `HTMLElement`；`defineElement` 无 `customElements` 时静默跳过。
+  判据在 `tests/node-smoke.spec.ts`。
+- **升级前的形态**：收起态由元素在 `wire()` 里用内联 display 做，`data-scope` / `data-part` 也是
+  那一刻才打上，所以 JS 到达前浮层子树既没有皮肤也没有收起。styled 的 `styles/undefined.css`
+  按作者写的 `data-xh-part` 把浮层族的 backdrop / content / positioner / viewport 收起来，
+  SSR 直出的首屏不会把浮层内容倾泻进页面流。不引 styled 的宿主需自行处理这一段。
+- 基类在 `src/reactive/`：属性 → 字段的单向转换、批量异步更新、控制器生命周期。
+  `tests/reactive-parity.spec.ts` 是差分判据，逐条对拍 `@lit/reactive-element`（仅 devDependency）。
+
+## 与 Vue 适配器的取舍记录（写 WC 适配器时发现的 core/adapter 差异）
+
+- **Presence 模型不同（已知差异，非缺陷）**：Vue 用 Presence 卸载 content（关闭即从 DOM 移除）；
+  WC 是 Light DOM，不能删用户节点，content **常驻**，关闭态只由 `data-state="closed"` 标记，
+  视觉隐藏交给 styled 层的 `[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，当前只靠
+  `data-state` + focus-scope + dismiss-layer，不搬运 DOM。
+- **重连（元素在 DOM 中移动）**：解释器 stop 后不可复活，`MachineController` 在 stop 后
+  重建机器（从 `initialState`、context 重置）——状态不跨移动保留。
+  重建后的状态与重建前相同，cell 不会 bump 版本，因此**不会**自动排更新；
+  `connectedCallback` 显式 `requestUpdate()` 重跑一次 `wire()`，否则角色节点上仍挂着
+  指向已停机器的处理器（送事件在 dev 下抛 `SEND_AFTER_STOP`）。
+- **运行期增删角色节点（已抹平的差异）**：Vue 侧条目是组件，增删自带整套 props 渲染；
+  WC 侧作者直接改 Light DOM，元素若不看着点就会留下"死条目"（没有 `data-scope`/`data-part`/
+  `data-value` 与事件处理器，集合查询也看不见它）。`XhElement` 用 `MutationObserver`
+  观察 `childList`（**不观察 attributes**——`wire()` 正是往角色节点写属性，一并观察会自触发成死循环），
+  命中即重新发现 part 并接线。两道过滤：增删里得真有元素节点；目标与宿主之间隔着别的
+  `xh-*` 元素则跳过（内层子树归内层元素自己管）。
+- **受控 open**：HTML 布尔属性表达不了 `undefined`，`open` 用自定义 converter（属性缺省→
+  `undefined`=非受控，`open="false"`→受控关）。受控 open 的跨适配器一致性留待后续。