# 曦寒视图组件 · 核心概念与运行时

共 30 页：核心概念、两个适配器的接法、以及命令式服务与运行时。
索引见 https://ui.docs.xihanfun.com/llms.txt

---

来源：https://ui.docs.xihanfun.com/adapters/react

# React 适配器

`@xihan-ui/react` 是无头内核的 React 外壳。它负责三件事：把状态机接入 React 的渲染周期、把部件封装为组件、把 `connect` 产出的 props 展开到元素上。它不实现任何组件逻辑。

依赖：`react` 与 `react-dom` 是 peer 依赖，下限 19。当前版本只支持 React 19：状态机要求宿主提交完当前帧、DOM 落定之后再运行回调，`flushSync` 与 `useSyncExternalStore` 的行为是这条契约的基础。

覆盖进度：136 个组件中已覆盖 136 个，与 Vue 侧一致。
登记在 `ui/tooling/scripts/react-coverage.json`，多项门禁按它决定核对哪些组件：登记多余会核对不存在的组件，登记缺失会静默漏检，两种情况都判失败。

## 组件命名

与 Vue 侧同名：每个部件一个组件，一律 `Xh` 前缀 + 组件名 + 部件名。

```tsx
import { XhDialogContent, XhDialogRoot, XhDialogTitle, XhDialogTrigger } from "@xihan-ui/react";
```

只有一个部件的组件不带部件后缀（`XhButton`、`XhSwitch`）。没有必须安装的 provider，按名称 import 即可。

## 受控与非受控

传受控属性即受控，只传 `default*` 即非受控。变更回调是普通的 React 回调，没有第二套事件：

受控：

```tsx
<XhDialogRoot open={open} onOpenChange={({ open }) => setOpen(open)} />;
```

非受控：

```tsx
<XhDialogRoot defaultOpen />;
```

载荷与 Vue 侧的明细对象相同：`{ open }`、`{ value }`、`{ checked }`。Vue 侧额外发出裸值事件是为了 `v-model`，React 没有这层语法，只保留明细一种。

受控属性每帧读取：状态机不缓存上一次的值，浮层打开时修改 `closeOnEscape` 立即生效。

## 带载荷的插槽写成函数式 children

派生值由这一层计算，作者通过函数式 children 接收：

```tsx
<XhSelectRoot value={value} onValueChange={({ value }) => setValue(value)}>
  {({ hasValue, valueText }) => (hasValue ? valueText : "请选择")}
</XhSelectRoot>;
```

类型是 `SlotChildren<P>`：传节点也可以，传函数才能获得载荷。每个组件的载荷类型（如 `SelectRootSlotProps`）都一并导出。

## asChild

要把部件的行为落到自定义元素上，传 `asChild` 并提供单个子元素：

```tsx
<XhDialogTrigger asChild>
  <MyButton>打开</MyButton>
</XhDialogTrigger>;
```

同名事件先运行作者处理器；作者调用 `preventDefault()` 后，不再运行部件内部动作。这条规则同时适用于写在部件和 `asChild` 子元素上的处理器。普通回调仍保留全部参数，ref 的登记和清理不受事件取消影响。

`asChild` 必须包含恰好一个可挂载子元素，Fragment 会展开后检查，仅忽略空白和条件占位。零个或多个元素、元素旁并列的非空文本或数字都会明确报错，不会生成默认按钮或丢弃可见内容。迁移时请把内容放到一个实际宿主中；确实需要默认按钮时移除 `asChild`。ref 遵循 React 19 的普通 props 合同。

## 组合式函数

不使用现成结构时直接获取 `api`：

```tsx
const { api, service } = useDialog({ open, onOpenChange });
```

`api` 每次渲染重新求值，随状态机状态变化。上下文类型（如 `DialogContext`）也导出，便于向下透传 `api` 时标注类型。父子部件之间的 context 是内部实现，不对外开放。

## 全局配置

`XhConfigProvider` 向下提供 locale、文案覆盖、尺寸、浮层落点与八轴视觉环境：

```tsx
<XhConfigProvider config={{ locale: "zh-CN", size: "sm" }}>
  <App />
</XhConfigProvider>;
```

视觉环境必须显式绑定 DOM 根，不推测 Provider 对应的元素。嵌套 Provider 自动继承外层控制器，局部 motion 只投影当前根，不修改全局 JS override：

```tsx
<XhConfigProvider config={{
  visualEnvironment: {
    root: workspaceElement,
    initial: { mode: "dark", density: "compact", motion: "reduce" },
  },
}}
>
  <Workspace />
</XhConfigProvider>;
```

配置经代理提供给部件 props：作者未传的属性从配置中取，传了的以作者为准。代理实现了 `ownKeys` 与 `getOwnPropertyDescriptor`：`{ ...props }` 展开在 React 中很常见，只有 `get` 陷阱的代理一经展开就退化为空对象，配置默认值会静默消失。

## 状态机接入 React

内部只有一层薄适配。`createReactRuntime()` 实现 `ReactiveRuntime` 的五个接口：

| 接口 | React 实现 |
| --- | --- |
| `cell` | 闭包存值 + 受控语义（受控时值从 `prop()` 读取，内部值不写）；写入递增版本号，经 `useSyncExternalStore` 触发重渲染 |
| `track` | 拉式：每次提交后逐项比对依赖，变化时才触发 |
| `flush` | `flushSync` 强制一次提交，回调在 DOM 落定之后运行 |
| `onMount` / `onCleanup` | `useLayoutEffect` 的挂载与清理 |

`track` 是拉式的，与 Vue 侧不同。Vue 的 `watch` 挂在响应式源上，源变化即通知；React 中 props 的变化不经过任何可订阅的源，它是下一次渲染函数的入参。推式实现在这里永远收不到 props 变化：85 个状态机中的 `track` 与 84 个 `watch` 块会全部静默失效且不报错。

`useMachine(machine, getProps, options)` 封装了它。props 传的是 getter：每次渲染读取，状态机读到的始终是当前帧的值。

getter 的求值带一份记忆，钥匙有两把：渲染轮次与机器版本号。前者盖住组件 props 与渲染期赋值的 ref，后者是「任意一台机器的 cell 变过一次」的全局计数，盖住那些从别的机器现读的派生 props（取色器里内嵌的滑杆、分页里内嵌的页长下拉）。连接层一趟要读十几个 prop，两把钥匙都没动时它们共用同一份展开结果；任一动了当场作废。因此 getter 应当只读这两类来源。确实要在同一拍生效、等不到下一轮渲染的状态（气泡确认的挂起态就是一例）落 ref 之后调一次 `invalidateMachineProps()` 让记忆作废，别默默地读。

## 部分处理器挂为原生监听器

`connect` 按 DOM 语义编写，有两类处理器无法通过 React 的合成事件层：

- `pointerenter` / `pointerleave` 不冒泡。React 的同名合成事件由 `pointerover` / `pointerout` 合成，直接派发到节点上的事件无法到达。
- `stopImmediatePropagation()` 在 `SyntheticEvent` 上不存在，调用会抛错。载入态的按钮依靠它拦截同节点上作者的处理器。

这类 props 由适配器改为真实的 DOM 监听器，行为与另外两个适配器一致。

这一条由门禁保证：`check-native-events` 逐组件核对 `connect` 派发了哪些不冒泡的事件、React 侧是否逐个摘出，摘出 `connect` 未派发的名称同样判失败。`onFocusIn` / `onFocusOut` 不在其列：它们经 `reactNormalize` 归到 React 的 `onFocus` / `onBlur`，这两个合成事件挂的正是冒泡的 `focusin` / `focusout`。

## 行为原语

`@xihan-ui/react/behavior` 是单独的子入口，提供行为原语的 React 包装：滚动锁、悬停意图、滚动观察、贴底、连续输入检索五项：

```tsx
import { useHoverIntent, useScrollLock, useScrollTracker, useStickToBottom, useTypeahead } from "@xihan-ui/react/behavior";
```

自建浮层时才需要。不使用的应用不需要把它计入主入口的体积。

`useHoverIntent` 在布局提交期读取 `getTriggerEl()`，因此已渲染元素的 ref 已就位，下一次指针输入不会落在旧节点上。本次提交未渲染 trigger 时释放绑定；节点更替或 `openDelay`、`closeDelay`、`buffer` 改变时重建。content getter 和两个意图回调只更新已提交引用，不会因普通闭包更替取消挂起的计时。需要显式标注选项时，从这个子入口导入 `UseHoverIntentOptions`，不借用 core 的元素快照类型。

`useScrollLock` 在布局 effect 中加锁，首帧绘制前就生效，服务端不执行 DOM 副作用。锁跟随 active 而不是配置对象身份；关闭再开启时读取最新配置，StrictMode 清理与重建保持一致。

## 背景层

React 侧的视觉适配也位于单独的子入口，不引入就不会把 WebGL 引擎打进包：

```tsx
import { useBackground, XhBackground } from "@xihan-ui/react/backgrounds";
```

`@xihan-ui/backgrounds` 是可选 peer，使用前先安装；不使用视觉效果的应用安装本包也不会引入引擎。

`XhBackground` 是独立视觉组件，children 浮在效果之上；`useBackground` 提供画面实例，它返回的 `ref` 挂到哪个元素上，效果就铺在哪个元素上。Vue 侧另有第三种写法 `v-background`，React 没有对应物：指令是 Vue 特有的介质，挂 `ref` 是同一件事。

两种用法见[背景层](../guide/backgrounds#在-react-里用)。

## 命令式服务

对话框、轻提示、通知、顶部进度条四个服务从组件树之外调用，自带宿主树：

```ts
import { createToastService } from "@xihan-ui/react";

const toast = createToastService();
toast.success("已保存");
```

行为与命令面见[命令式服务](../runtime/services)。React 侧有一处实现差别：`createRoot().render()` 是排队的，而 Vue 的 `app.mount()` 同步完成，因此首帧提交由 `flushSync` 包裹：服务创建后紧接着发出的命令（拦截器中常见）不会因为宿主尚未渲染而丢失。

宿主树在组件树之外，无法接入组件树中的 `XhConfigProvider`。需要与应用同语言时，通过 `config` 选项提供，或之后用 `setConfig` 更新。

## 声音层

`@xihan-ui/react/sound` 是单独的子入口。`withToastSound` / `withDialogSound` 为上述两个命令式服务配置声音，调用点不需要修改；`useSoundOnPress` 为单个元素配置声音，返回值挂到该元素的 `ref` 上：

```tsx
import { setSoundPlayer, useSoundOnPress, withToastSound } from "@xihan-ui/react/sound";
```

Vue 侧由 `v-sound` 指令完成同一件事。React 没有指令介质，改为返回 ref 回调的 hook；两侧的服务包装名与选项完全同名同形。默认映射与开关见[声音层](../guide/sound#在-react-里用)。

## 服务端渲染

- `createReactRuntime()` 的 `isServer` 由 `typeof window === 'undefined'` 判定，服务端不挂事件、不读媒体查询；
- scope 的基名取自 `useId`，同一棵树两端一致，不会 hydration 不匹配；
- 主题属性建议在服务端就渲染到 `<html>` 上，见[设计令牌与主题](../guide/theme#服务端渲染)。

## 与另外两个适配器的关系

三个适配器运行同一个状态机、同一份 `connect`，输出的 DOM 属性完全一致：跨适配器一致性测试逐帧比对归一化快照，无法消除的差异即判失败。React 侧另有一道服务端渲染一致性判据。

## 相关

- [组件参考](../components/)：全部组件与部件
- [connect 与属性产出](../guide/connect)
- [Vue 适配器](./vue)
- [Web Components 适配器](./web-components)

---

来源：https://ui.docs.xihanfun.com/adapters/vue

# Vue 适配器

`@xihan-ui/vue` 是无头内核的 Vue 3 外壳。它负责三件事：把状态机接入 Vue 的响应式、把部件封装为组件、把 `connect` 产出的 props 展开到 vnode 上。它不实现任何组件逻辑。

依赖：`vue` 是 peer 依赖（由项目提供）；`@xihan-ui/backgrounds` 与 `@xihan-ui/sound` 是可选 peer，不使用视觉效果或音效时不需要安装。

## 组件命名

每个部件一个组件，一律 `Xh` 前缀 + 组件名 + 部件名：

```ts
import {
  XhAccordionContent,
  XhAccordionHeader,
  XhAccordionIndicator,
  XhAccordionItem,
  XhAccordionRoot,
  XhAccordionTrigger,
} from "@xihan-ui/vue";
```

只有一个部件的组件不带部件后缀（`XhButton`、`XhSwitch`、`XhBadge`）。全部 1052 个导出组件按组件分组列在[组件参考](../components/)。

没有插件，不需要 `app.use()`。按名称 import 即可，`sideEffects: false` 让打包器移除未使用的部分。

## 配置与视觉环境

`provideXhConfig` 接收响应式配置。八轴视觉环境必须显式给出对应 DOM 根；嵌套 provide 自动接父控制器，局部 motion 不改全局 JS override：

```ts
provideXhConfig({
  locale: "zh-CN",
  visualEnvironment: {
    root: workspaceElement,
    initial: { mode: "dark", density: "compact", motion: "reduce" },
  },
});
```

物理 Portal 会由 Core 从该根桥接已解析八轴到实例壳，Vue 适配器不复制视觉状态。

## 事件与 v-model

值类组件同时发两个事件：

<!-- eslint-skip -->

```ts
emits: {
  'value-change': (details: PayloadOf<AccordionProps, 'onValueChange'>) => true,
  'update:value': (value: PayloadOf<AccordionProps, 'onValueChange'>['value']) => true,
}
```

| 事件 | 载荷 | 用途 |
| --- | --- | --- |
| `value-change` | 完整明细对象，如 `{ value }` | 需要全部上下文时 |
| `update:value` | 裸值 | 供 `v-model` 使用 |

```vue
<template>
  <!-- 双向绑定 -->
  <XhAccordionRoot v-model:value="panels" multiple />

  <!-- 或自行处理明细 -->
  <XhAccordionRoot :value="panels" @value-change="onChange" />
</template>
```

具体的绑定名按组件而定：开关是 `v-model:checked`，浮层是 `v-model:open`，输入框是 `v-model:value`。

## asChild 与事件取消

支持 `asChild` 的部件可以把行为接到作者提供的单个子节点上。Fragment 会展开后检查，仅忽略空白、注释和条件占位；零个或多个可挂载子节点、元素旁并列的非空文本或数字都会明确报错，不会生成默认按钮或丢弃可见内容。需要默认按钮时移除 `asChild`，组合多个内容时提供一个实际宿主节点。

作者写在部件或子节点上的事件处理器先执行；调用 `preventDefault()` 后，部件内部动作不再执行。作者的处理器数组仍按原顺序运行，`stopImmediatePropagation()` 仍可停止同节点后续处理器。普通回调保留全部参数，ref 的登记和清理不受事件取消影响。

## 受控与非受控

传受控属性即受控，只传 `default*` 即非受控：

```vue
<template>
  <XhSwitch v-model:checked="wifi" />      <!-- 受控 -->
  <XhSwitch :default-checked="false" />     <!-- 非受控 -->
</template>
```

受控时组件不会自行改变：它只发出变更意图，由使用者写回新值后才真正改变。这条语义收在状态机的 `cell` 与 `watch` 中，不由各组件自行判断。详见[状态机运行时](../guide/machine#受控与非受控-cell)。

## 作用域插槽

根组件通过作用域插槽提供命令式方法：

```vue
<template>
  <XhDialogRoot v-slot="{ setOpen }">
    <XhDialogTrigger>打开</XhDialogTrigger>
    <XhDialogContent>
      <XhButton @click="setOpen(false)">取消</XhButton>
    </XhDialogContent>
  </XhDialogRoot>
</template>
```

### 载荷有类型

插槽载荷都写进了组件的 `SlotsType`，`vue-tsc` 可以捕获两类拼写错误：

```vue
<template>
  <XhTabsRoot :collection="tabs">
    <!-- ✓ node 是 TabsNodeMeta，字段可补全 -->
    <template #panel="node">{{ node.label }}</template>
  </XhTabsRoot>
</template>
```

两类拼写错误分别如下：

```vue
<template>
  <!-- ✗ TS2551: Property 'lable' does not exist on type 'TabsNodeMeta'. Did you mean 'label'? -->
  <XhTabsRoot :collection="tabs">
    <template #panel="node">{{ node.lable }}</template>
  </XhTabsRoot>

  <!-- ✗ TS2339: 组件没有这个插槽 -->
  <XhTabsRoot :collection="tabs">
    <template #panle>…</template>
  </XhTabsRoot>
</template>
```

载荷类型本身也从主入口导出（命名如 `TabsPanelSlotProps`、`StepsRootSlotProps`），需要把插槽内容拆成子组件时可以直接用于标注 props。

插槽键在类型上一律可选：组件内部按作者是否编写该插槽决定是否按 `collection` 铺开默认结构，键若非可选，该判断在类型上恒为真。

不使用现成 DOM 结构时，直接使用 `api` 自行渲染：

```vue
<script setup lang="ts">
import { useAccordion } from "@xihan-ui/vue";

const { api } = useAccordion(
  { multiple: true, defaultValue: ["a"] },
  details => console.log(details.value), // onValueChange
);
</script>

<template>
  <section v-bind="api.getRootProps()">
    <article v-bind="api.getItemProps({ value: 'a' })">
      <h3 v-bind="api.getHeaderProps({ value: 'a' })">
        <button v-bind="api.getTriggerProps({ value: 'a' })">第一节</button>
      </h3>
      <div v-bind="api.getContentProps({ value: 'a' })">内容</div>
    </article>
  </section>
</template>
```

`api` 是一个 `ComputedRef`，随状态机状态变化重新求值。纯展示型组件（如 `XhBadge` 等没有状态机的组件）不提供组合式函数。

上下文类型（`AccordionContext` 等）也一并导出，便于向下透传 `api` 时标注类型。父子组件之间的 provide / inject 是内部实现，不对外开放；自定义结构请直接用组合式函数获取 `api`，不接入现成组件的上下文。

## 状态机接入 Vue 响应式

内部只有一层薄适配。`createVueRuntime()` 实现 `ReactiveRuntime` 的五个接口：

| 接口 | Vue 实现 |
| --- | --- |
| `cell` | `shallowRef` + 受控语义（受控时值从 `prop()` 读，内部 ref 不写） |
| `track` | `watch(deps, fn, { flush: 'pre' })` |
| `flush` | `nextTick` |
| `onMount` / `onCleanup` | `onMounted` / `onBeforeUnmount`（不在组件内则立即执行 / 忽略） |

`useMachine(machine, props, scope)` 封装了它。props 传的是 getter 而不是对象，因此在模板中原地修改某个 prop 也能生效。

getter 的求值放在一个 `computed` 里：连接层每读一个 prop 都会经过它，依赖没动时复用同一份展开结果（状态机的身份缓存跟着命中），依赖一动就产出新对象，身份缓存照旧失效。失效面与组件自己的重渲一致，getter 因此必须只读响应式来源——组件 props、`attrs`、ref、注入的上下文、全局配置。读普通变量或普通数组的长度不会让它重算；那类来源本来也驱动不了 `computed(() => connectX(...))` 的重算，只是以前靠每次重新展开碰巧读到过新值。

## 行为原语

`@xihan-ui/vue/behavior` 单独提供滚动锁、悬停意图、滚动观察、贴底和连敲检索的 Vue 包装。`useHoverIntent` 到 mounted 后才读取模板 ref，并持续观察 trigger 与三个计时参数；trigger 暂时为 `null` 时释放旧绑定，节点重新出现后再建立。content getter 与回调现读当前响应式选项，不会因浮层内容挂载或普通闭包换代重启安全三角。选项对象本身也可传 ref 或 getter；显式类型使用该子入口的 `UseHoverIntentOptions`。

`useScrollLock` 在组件 mounted 后才读取模板 ref，并以 post watcher 跟随 active；释放时先清本地句柄，清理抛错后再次激活仍可建立。active 为真期间不因配置对象更新重锁，关闭再开启才读取新配置。

## 背景层

Vue 侧的视觉适配位于单独的子入口，不引入就不会把 WebGL 引擎打进包：

```ts
import { useBackground, vBackground, XhBackground } from "@xihan-ui/vue/backgrounds";
```

三种用法见[背景层](../guide/backgrounds#在-vue-里用)。

## 声音层

同样是单独的子入口。`withToastSound` / `withDialogSound` 为命令式反馈服务配置声音，调用点不需要修改；`v-sound` 为单个元素配置声音：

```ts
import { setSoundPlayer, vSound, withToastSound } from "@xihan-ui/vue/sound";
```

默认映射与开关见[声音层](../guide/sound#在-vue-里用)。

## 服务端渲染

- `createVueRuntime()` 的 `isServer` 由 `typeof window === 'undefined'` 判定，服务端不挂事件、不读媒体查询；
- id 由 `createVueIdGenerator()` 生成，同一棵树两端一致，不会 hydration 不匹配；
- 主题属性建议在服务端就渲染到 `<html>` 上，见[设计令牌与主题](../guide/theme#服务端渲染)。

## 与 Web Components 适配器的关系

两者运行同一个状态机、同一份 `connect`，输出的 DOM 属性完全一致：跨适配器一致性测试逐帧比对归一化快照，无法消除的差异即判失败。

Vue 项目使用本适配器；需要在多个框架或无框架页面中复用同一套组件时使用[自定义元素](./web-components)。两者可以在同一页面共存。

## 相关

- [组件参考](../components/)：全部组件与部件
- [connect 与属性产出](../guide/connect)
- [Web Components 适配器](./web-components)

---

来源：https://ui.docs.xihanfun.com/adapters/web-components

# Web Components 适配器

`@xihan-ui/web-components` 把同一套无头内核封装为原生自定义元素。它采用一种不常见的形态：Light DOM 行为宿主。元素本身不渲染任何结构，结构由作者编写，元素只负责发现角色节点并写入属性与事件。

响应式基类为自研（`XhReactiveElement`），不依赖任何第三方运行时。

## 注册

```ts
import { defineXhElements } from "@xihan-ui/web-components/define";

defineXhElements(); // 注册全部 138 个 xh-* 元素
```

主入口的 `import` 本身不注册，必须显式调用这一行。注册是幂等的：同版本重复调用直接返回；同标签不同版本，或标签已被非 XiHan.UI 代码占用，都会抛错而不是静默覆盖。无 `customElements` 的环境（SSR）静默跳过。

背景层单独注册，不引入就不会把 WebGL 引擎打进包：

```ts
import { defineXhBackground } from "@xihan-ui/web-components/backgrounds";

defineXhBackground();
```

## 配置与视觉环境

`<xh-config>` 本身就是 Light DOM 局部 scope，八轴一次声明后会投影为 Core Portal 能桥接的标准属性：

```html
<xh-config
  mode="dark"
  brand="acme"
  density="compact"
  direction="rtl"
  contrast="more"
  motion="reduce"
  transparency="reduce"
>
  <my-workspace></my-workspace>
</xh-config>
```

局部 `motion` 只降低该子树的 CSS 动效，不隐式调用全局 `setMotionOverride`。应用根需要同时驱动 JS 动画时，用 `setXhConfig({ visualEnvironment: { root, initial, motionSink } })` 显式绑定；详见[设计令牌与主题](../guide/theme)。

## 结构由作者编写

```html
<xh-dialog>
  <button data-xh-part="trigger">打开对话框</button>
  <div data-xh-part="backdrop"></div>
  <div data-xh-part="positioner">
    <div data-xh-part="content">
      <h3 data-xh-part="title">确认操作</h3>
      <p data-xh-part="description">这条操作不可撤销。</p>
      <button data-xh-part="close-trigger" aria-label="关闭">✕</button>
    </div>
  </div>
</xh-dialog>
```

接线后元素会向这些节点写入 `data-scope` / `data-part` / `aria-*` / `data-state` 与事件处理器，在 DevTools 中可以直接查看。

::: tip 为什么是 Light DOM 而不是 Shadow DOM
Shadow DOM 会封闭结构：无法更换标签、无法插入自定义节点、外部 CSS 无法进入、表单关联和 `aria-*` 跨边界引用都需要额外机制。本库的定位是行为可复用、外观完全由使用者决定，Light DOM 与之匹配。

代价是需要自行编写结构，因此必备部件的校验必须存在。
:::

## 部件契约校验

元素接线时比对作者编写的 DOM 与组件解剖，三种问题报告到[诊断通道](../guide/diagnostics)：

| 码 | 级别 | 触发条件 |
| --- | --- | --- |
| `wc.missing-part` | error | 缺必备角色节点，该部件不会被接线 |
| `wc.unknown-part` | warn | 角色节点的 part 名不在组件解剖内 |
| `wc.wrong-part-tag` | error | 角色节点用的标签不满足要求 |

第三条只登记写错即静默失效的情况。例如表单字段的 `label` 必须是原生 `<label>`，写成 `<div>` 会使 `for` 关联失效、点击标签不再聚焦控件，而页面看起来一切正常。

部分宿主会把内嵌部件的 DOM 铺在自己的 Light DOM 中接线（日期选择器之于日期输入与日历），这些角色节点由内嵌部件管理，通过契约中的 `delegates` 登记，不会被当作未知节点报警。

## 属性

属性遵循自定义元素惯例：kebab-case 的 HTML attribute ↔ camelCase 的 JS property。

```html
<xh-dialog default-open modal="false" role="alertdialog">
```

```ts
const dialog = document.querySelector("xh-dialog");
dialog.open = true; // 受控
dialog.closeOnEscape = false;
```

布尔属性使用三态转换器：属性缺席 = `undefined`（使用组件默认值），`="false"` = `false`，其余 = `true`。这个区分是必要的：`modal` 的默认值是 `true`，缺席与 `="false"` 不能区分时就无法关闭它。

## 事件

组件的变更以 `CustomEvent` 派发，`bubbles: true, composed: true`，事件名是 kebab-case：

```ts
document.querySelector("xh-dialog")
  .addEventListener("open-change", (e) => {
    console.log(e.detail.open); // { open: boolean }
  });
```

`detail` 即无头内核中的明细对象，与 Vue 适配器的 `value-change` 载荷完全一致。

## 生命周期

一台状态机对应一个控制器：

- `connectedCallback` → 创建状态机并 mount（旧状态机已停止时从 `initialState` 重建）；
- 每次更新 → 运行依赖追踪；
- `disconnectedCallback` → unmount。

角色节点的进出由 `MutationObserver` 监视，但只在确实有角色节点进出时才重新接线：业务内容（图表、虚拟列表、面板内的业务 DOM）的增删与部件集合无关。这条判断同时避免了一条死循环：角色节点若本身是会在属性变化时改写自身子节点的自定义元素，“宿主重新接线 → 写属性 → 该节点改子节点 → 再次命中观察器”会形成环。

属性观察同理只监视 `value` / `disabled` / `aria-disabled` 三个作者编写的声明，不监视状态机每帧写入的 `aria-*` / `data-*`，全量观察等于自我触发。

## 收起态

浮层关闭时使用内联 `style.display` 而不只依靠 `hidden` 属性：作者层若为该部件声明了 `display`，会覆盖 UA 的 `[hidden] { display: none }`，只靠 `hidden` 无法收起。

展开时恢复作者原本的内联值而不是清为空串：后者会把作者写在该节点上的 `style="display:grid"` 一并清除，且无法恢复。

## 多级菜单的 Portal 所有权

`<xh-menu submenu>` 仍由作者在父 Menu、ContextMenu 或 Menubar 的 Light DOM 中声明。展开时只有它的 `positioner` 会搬到所属 Document 的 `#xh-portal-root`：父菜单的磨砂 `backdrop-filter` 因此不会把 fixed 子层困在局部包含块。每层有自己的无盒 Portal 壳，壳会桥接触发条目祖先上的主题、品牌、密度、对比度、动效与文字方向。

搬运不会转移行为所有权。子菜单宿主继续观察并接线 positioner 里的动态部件，父宿主通过内部逻辑 owner 给 trigger 补齐父层 item 身份；末级选择按叶到根关闭，并只由根派发一次 `select`。关闭、断连或 trigger 换代时，positioner 会恢复到原占位。展开期间应持有部件引用或从 `ownerDocument` 查询，不能假设 `submenu.querySelector(...)` 仍能找到已搬走的 positioner。

## 升级前

自定义元素在 JS 到达之前不会升级，这段时间 `data-scope` / `data-part` 尚未写入，浮层内容会以裸文本出现在页面流中。`@xihan-ui/styles` 的 `undefined.css` 用 `:not(:defined)` 配合作者编写的 `data-xh-part` 先收起浮层子树，见[皮肤与样式分层](../guide/styling#升级前的形态)。

## 自定义元素清单

包内附带 `custom-elements.json`（CEM 格式），包含 138 个元素的标签名、属性、事件、CSS part。编辑器与框架的自定义元素支持可以直接读取它获得补全与类型提示。

清单由构建生成，`pnpm gate:cem` 会重新生成后比对，修改元素后未重新生成会被拦截。

## 与 Vue 适配器的关系

两者运行同一个状态机、同一份 `connect`，输出的 DOM 属性完全一致。文档站每个组件页的示例多套写法并排，便于逐帧对照。

在同一页面共存没有问题：诊断通道是全局的、层栈按文档共享，两套适配器的浮层会正确叠放在同一层栈中。

## 相关

- [组件参考](../components/)：每个组件的标签名与必备部件
- [解剖与部件契约](../guide/anatomy)
- [诊断通道](../guide/diagnostics)

---

来源：https://ui.docs.xihanfun.com/guide/a11y

# 无障碍与键盘规格

无障碍在 XiHan.UI 中是判据：每个组件都有一份机读的键盘规格表，它同时是测试的分母。

## 键盘规格表

```ts
export const accordionKeyboard: KeyboardTable = {
  component: "accordion",
  source: "https://www.w3.org/WAI/ARIA/apg/patterns/accordion/#keyboardinteraction",
  rows: [
    {
      id: "accordion.kbd.toggle",
      keys: ["Space", "Enter"],
      when: "focus in trigger, not disabled",
      does: "展开/收起该条目的 content",
    },
    {
      id: "accordion.kbd.next",
      keys: ["ArrowDown", "ArrowRight"],
      when: "focus in trigger, 按键与 orientation 同轴（dir=rtl 时左右键语义互换）",
      does: "焦点移到下一个 trigger，末条不回绕",
    },
    // …
  ],
};
```

每一行有稳定的 `id`、触发按键、生效前置条件与效果。全库共 695 条，分布在 136 个组件上。

规格表由三方共同消费：

1. 测试：一致性用例通过 `covers` 字段反查行 id，缺一行即套件失败；
2. 文档：[组件参考](../components/)中每个组件的键盘表由它渲染；
3. 校验：`source` 字段指向规格出处（W3C APG 模式、WAI-ARIA、HTML 标准或 WCAG 技术），修改行为时可以追溯依据。

::: tip 分母外化
让键盘测试通过只能编写用例，不能修改分母。规格表是先行确立的契约，不是事后补充的记录。
:::

## ARIA 上的几处明确选择

组件源码中反复出现以下处理，都是经过权衡的：

- `aria-disabled` 而非 `disabled`：禁用项仍需可聚焦时使用。原生 `disabled` 会使元素失去焦点，读屏用户无法 Tab 到它，也读不到不可用的原因。手风琴的禁用条目、加载中的按钮都采用这种方式。
- 不该使用 roving tabindex 的地方不使用：手风琴的每个触发器都是独立的 Tab 停靠点，这是 APG 对该模式的规定。组件不输出 `tabindex` 是有意的。
- 方向键的轴向与书写方向：垂直列表不响应左右键；RTL 下左右键语义互换。这两条收在 `navIntentFromKey` 一处，所有列表型组件共享同一份判断。
- 不由导航处理的按键不 `preventDefault`，否则会吞掉输入法、浏览器快捷键和默认行为。
- 输入法组合期不误判：`isComposingEvent()` 识别输入法组合中的按键，避免把确认候选词的 `Enter` 当作提交。

## 背景失活与焦点

模态浮层打开时按固定顺序装配：

1. 注册层，压入层栈；
2. 建立消隐层（Esc、点击外部、焦点移出）；
3. 建立焦点域（捕获、回绕、归还）；
4. 锁定滚动；
5. 推迟一帧为背景添加 `inert`。

顺序不可调换，细节见[行为原语](./behavior)。

## 焦点可见

焦点环由一份公共皮肤绘制，全库共用：粗细 `--xh-ring-width`、颜色 `--xh-_ring-color`（默认 `--xh-ring-focus`）、偏移 `--xh-ring-offset`。偏移是负的一个环宽：环向元素内收，外沿与元素边框外沿重合，聚焦前后占位一致，不会挤开周围内容。

WCAG 2.2 的非文本对比（SC 1.4.11）要求焦点指示器对相邻颜色至少 3:1。环内收之后，相邻的是两块颜色：

- 内侧：元素自己的面。这是判定基准。
- 外侧：元素所在的背景。它随使用者放置组件的位置而变化，库无法决定，因此只测量不判定。

### 实心面上环取 `currentColor`

面为实心的档位（实心按钮、选中的开关轨道、选中的日历格、拖拽中的滑块等），环色与面同族，对比度最低可到 1.00:1。这些档位在各自皮肤的 `:focus-visible` 规则中把环色槽设为 `currentColor`，环改取该面配对的前景色。该前景色本就要在这块面上保证文字可读（与实心底 4.5:1），作为环色自然超过 3:1。

改环色按求值判定，不按字面量判定：给 `--xh-_ring-color` 或 `outline-color` 赋值、或在键盘聚焦规则中写 `outline` 简写，值沿皮肤中的槽展开、再沿令牌链解到颜色，在任一主题 × 语气下与库的两支环（`--xh-ring-focus`、`--xh-ring-invalid`）都不相等即视为改环色；解不出的值（`currentColor`、使用者传入的色值、没有兜底的使用者令牌）同样视为改环色。因此写成 `var(--xh-fg-on-brand)` 等与面配对的前景色令牌（开关选中的轨道即如此，它是 `<button>`、皮肤没有给它 `color`）与写 `currentColor` 受同样约束；写回 `var(--xh-ring-focus)` 不算改环色；直接写 `outline-color`、把属性名写成大写、把规则包进 `@supports` 或 `@media screen` / `@container` 等静态无法判断何时不成立的条件块、写在裸 `:focus` 中、用 `[data-variant]` / `[data-state]` 等属性存在式选择器覆盖多档，都在判定范围内。库环两支令牌与它们解析链上经过的名称（如 `--xh-color-brand-500`）在皮肤内一律不允许赋值：在子树上修改它们，库环在该子树上就不再是库环。

::: warning 这不是环随语气变化
四条口径需要一起理解：

- 环不随语气：`data-tone` 切换的是颜色族，环不随之切换。语气色本体作为环色达不到 3:1（warning 对白底 2.70:1、success 3.04:1）。没有实心面的档位一律使用 `--xh-ring-focus`。
- 实心面上取 `currentColor`：取的是该面配对的前景色，不是语气色。同一块 danger 实心底上，环是这块底上的文字色，不是 danger 本体。
- 达标的淡色档不为统一而改环色：淡底、透空的面使用默认环即可（3.40:1 起），改为 `currentColor` 反而把品牌色环换成近黑近白，与同族组件分叉。`currentColor` 只在实心档使用，选择器的粒度与面的粒度对齐。
- 失效档豁免对比度，但环不允许消失：WCAG 1.4.11 对失效控件不要求 3:1，库内照此不追求该数值；但 `color: transparent` 或置灰文字与置灰面同色会让 `currentColor` 环整体不可见，这不是对比不足，而是没有焦点提示。这类档位要么退回默认环，要么另给一支配对前景色。

判据是环压着的面，不是组件的语气。皮肤的写法见[皮肤与样式分层](./styling)。
:::

### 浮层壳是否接焦点

浮层的面板多数只是焦点陷阱的兜底落点（`tabindex=-1`），环位于内部的控件上，皮肤关闭面板自身的环，并在 `ringless` 分区中登记环由谁绘制。tour 的气泡是例外：Enter / Space 落在它上面会推进下一步，它是可操作目标（WCAG 2.4.7），必须有可见焦点；程序化聚焦后使用默认内收环，面是 `--xh-bg-surface`，默认环达标。浏览器判据 `focus-ring-inset-grpring` 保证这一条。

### 相关判据

| 判据 | 检查内容 |
| --- | --- |
| `check-focus-ring` | 环的粗细、颜色、偏移写了字面量而不是令牌，主题与全局调整对它无效 |
| `check-focus-ring-surface` | 静态解出每个可聚焦档的面与环色，面对环不到 3:1 却未改环色的判红；改环色的规则（`--xh-_ring-color` / `outline-color` / 聚焦规则中的 `outline` 简写，求值后落在库环之外）覆盖到非实心档、`:focus-visible` 中关闭环（`outline: none` / `outline-width: 0`）却未登记、绘制实心面却不接焦点也未登记的，同样判红；聚焦规则把环色写成透明直接判红，没有登记表。`@supports` 块内的规则按条件成立处理；`@media` 只认打印、高对比、减弱动效、粗指针、断点这几种真实媒体条件为条件块，其他写法（`screen` / `all` / 逗号并列 / `not`）与任何 `@container` 一律按成立处理；规则写了但档位未写取值的属性，存在式一律视为覆盖，写了取值的按是否有兄弟档认领判定 |
| `check-focus-outline-reset` | 皮肤在 `:focus:not(:focus-visible)` 下复位 `outline`（含 `outline-style` / `outline-width` / `outline-color`）。UA 只在 `:focus-visible` 绘制环，这条复位是死代码，而 `outline` 简写会把 `outline-color` 复位成 `currentColor`，描边色一旦进过渡，焦点离开时就闪出一圈近黑描边 |
| `focus-ring-inset-grpring` | 浏览器态：环内收后聚焦前后占位不变、全库只有一种偏移；改环色的每条规则（同样按求值判定；`@media` 按当前页面的媒体环境判断，`@container` 照常处理）逐条落焦测量 3:1；tour 气泡落焦有环 |
| `focus-ring-face-contrast` | 浏览器态：从皮肤推出档位，在真实 Chromium 中逐档测量环与面的实测对比 |
| `focus-ring-disabled-ink` | 浏览器态：失效档使用默认环、不取被置灰的前景色；未失效的实心档仍取面自己的前景色 |

`focus-ring-face-contrast` 只测量库绘制的面：皮肤未绘制面、计算出的底色等于同标签裸元素 UA 底色的部件（菜单的触发器只绘制展开档，基础档露出的是原生 `button` 的 `buttonface`）不进入档位表，环内侧的颜色不属于库。明确不达标且更换环色无法解决的档位登记在 `KNOWN` 中，两侧反查：无法挂出该档、该档不再绘制环、或它已经达到 3:1，三种情况都判定登记过期。

两条判据的分母互相对账。静态算出的每个实心档，浏览器态都要能挂出、测量结果也是实心的、环是否撤销两侧一致；浏览器态测出的每个实心档，静态要么算出同一块面（同键或覆盖它的档，比值一致），要么在登记表的 `declared` 中说明为何算不出。两边的键先归一为同一形态再比较（`:is()` 展开、只写了 root 的祖先去掉），叠出同一份面的组合只测量一次、沿别名找到已测量的档。对不上的逐条登记在 `focus-ring-face-contrast.reconcile.json` 中写明理由，登记的必须仍然对不上，对不上的必须已登记。

静态与浏览器态各有盲区，因此都保留。静态判据运行快，交互后才出现的状态（`[data-dragging]`、`[data-state='picking']`）同样能计算，但看不到面绘制在祖先上、改了环色却被另一条规则替换 `color`、同一档后面又有规则把环色写回默认等级联叠加；浏览器态测量的是实测值，覆盖更全，但 `:hover` / `:active` 叠加聚焦无法测量（真实指针移动会使浏览器退出键盘模态，`:focus-visible` 立即消失），`::before` 铺的底、真实媒体条件中的面、连接层内联进 `style` 的面（颜色选择器的色板格、裁剪器的图）也不在范围内。

## 浏览器中的自动扫描

一致性套件的 fixture 挂载到真实 Chromium，对初始态与各用例终态运行 axe。终态按形态签名去重，避免同一形态重复扫描。

每套 fixture 按根元素的 `data-theme` 明暗各运行一遍，body 铺 `bg-canvas` / `fg-default` 作为底色：axe 沿祖先找不到绘制底色的元素时按白底计算，深色一遍不铺底色等于用深色文字对比白底。

必须在真实浏览器中运行：jsdom 没有布局，对比度、目标尺寸、翻面与避让都无法表现。

```bash
pnpm exec playwright install chromium # 首次
pnpm test:browser
```

## 存量违规登记表

扫描出的存量问题登记在 `tooling/testing/src/a11y/known.ts`。命中已登记的规则不判失败，但一条都不再命中时判定登记过期：修复后必须从表中删除，不保留已不成立的豁免。

当前共五条。三个适配器共用的四条：`tag` 的禁用标签文字使用全库统一的 `fg-disabled` / `bg-muted`（浅色 2.36:1、深色 1.93:1），按 1.4.3 的失效控件豁免不算违规，但 tag 的 root 没有 axe 识别的禁用语义，因此被扫出；`select` 位于触发器外的可删除标签属于同一档（触发器内的标签在原生 disabled 的按钮内，axe 跳过；外部的标签是没有角色的 span）；`file-upload` 禁用时文件条目的名字与大小同走 `fg-disabled`（浅色 2.58:1、深色 2.27:1），条目是 `role=listitem`、不能写 `aria-disabled`，三颗按钮都是原生 disabled 被 axe 跳过，只有这两段文字被扫出；`prompt-input` 的输入框有意不无条件发出 `aria-label`（会覆盖作者的 `<label for>`），一致性夹具有意不提供文案以保证这条契约，扫描结果是一个没有名称的 textarea，真实用法中由作者命名。Web Components 适配器自身的一条：`steps` 的必需子节点由作者编写，可能缺少角色要求的直接子节点。全局登记为空。登记按主题记录：明暗两遍都命中的写在共用表，只在一个主题下成立的放在 `knownByTheme`，两侧都有过期反查，登记了却已扫不出的同样判失败。

::: warning
这份表是当前状态的如实记录，不代表可接受。表中仍有条目时，请自行评估对合规要求的影响。
:::

## 步骤重放豁免

只有一个组件在真实浏览器中无法推进到用例终态，两个适配器共用这条登记：

- `breadcrumb`：扫描必须拦截跨文档跳转，否则测试宿主会被导航离开；而用例断言的正是不拦截，同一文档内无法兼得。

## 相关

- [组件参考](../components/)：每个组件的完整键盘表
- [测试与质量门禁](./testing)：三套判据的运行方式
- [行为原语](./behavior)：焦点域与背景失活
- [皮肤与样式分层](./styling)：聚焦环在皮肤侧的写法

---

来源：https://ui.docs.xihanfun.com/guide/ai

# AI 对话内核

流式对话界面要解决三个问题：读流、收敛状态、增量渲染。XiHan.UI 把它们拆为三个互不依赖的包，均不涉及 DOM 与框架。

| 包 | 职责 |
| --- | --- |
| `@xihan-ui/chat-stream` | SSE 读取 → 协议归一 → parts 归约 → 会话 store |
| `@xihan-ui/markdown` | 流式 Markdown 渲染：增量切块、稳定 key、消毒 |
| `@xihan-ui/code-highlight` | 代码着色，自研粗粒度词法器；可选 peer，安装后可用 |

配套的组件按职责分为四件：[消息流](../components/message-feed)渲染结构化会话，[日志](../components/log)渲染持续追加的内容，[提示输入框](../components/prompt-input)接收输入，[代码视图](../components/code-view)呈现代码。

## 数据流

```
fetch(SSE)  ──►  sse-reader  ──►  normalize  ──►  reduce  ──►  thread-store
  网络            拆帧           协议归一        parts 归约      快照 + 订阅
```

四步各负责一件事，每一步都可以单独替换或单独测试。

## 传输

```ts
import { createHttpSseTransport } from "@xihan-ui/chat-stream";

const transport = createHttpSseTransport({
  url: "/api/chat",
  headers: () => ({ authorization: `Bearer ${token}` }), // 每次请求取一次
  fetch: customFetch, // 可选
});
```

`Transport` 是一个接口，`stream(req, signal)` 返回归一化事件的异步生成器。HTTP + SSE 只是它的一个实现：换成 WebSocket 或其他协议时实现同一个接口即可，上层无需修改。

`stream()` 不抛异常。错误路径一律先产出一条事件再结束：取消产出 `abort`，其余产出 `retryable` 的 `error`。异常在流的边界转换为数据，上层不必到处 try/catch。

服务端协议按 Data Stream v1 归一（`normalizeDataStreamV1`），请求头 `x-vercel-ai-ui-message-stream: v1`。

## 消息模型

一条消息由若干 part 组成，而不是一个字符串：

```ts
type UIMessagePart
  = | TextPart // 正文
    | ReasoningPart // 思维链
    | ToolPart // 工具调用（含审批状态）
    | FilePart // 文件
    | SourcePart // 引用来源（URL / 文档 + 引文锚点）
    | DataPart // 结构化数据
    | ErrorPart
    | StepStartPart;
```

配套的类型守卫 `isTextPart` / `isToolPart` / `isSourcePart` 等按 part 类型分流渲染。消息元数据带 `TokenUsage` 与 `CostBreakdown`。

## 归约

流上传来的是增量事件，界面需要的是消息此刻的完整形态。`reduceEvent` 负责这个折叠：

```ts
import { createReduceState, reduceEvent } from "@xihan-ui/chat-stream";

let state = createReduceState();
for await (const event of transport.stream(req, signal))
  state = reduceEvent(state, event);
```

块注册表按 `BlockKey` 索引，同一个块的后续增量能找回原位：工具调用先到 `input` 后到 `output`、思维链与正文交错，都不会错位。

## 会话容器

日常使用的是封装好的 store：

```ts
import { createThreadStore } from "@xihan-ui/chat-stream";

const store = createThreadStore({
  transport,
  onData: (name, data) => {}, // 瞬态 data 帧，不进 parts
  generateId: () => crypto.randomUUID(),
});

store.subscribe((snapshot) => {
  snapshot.messages; // readonly UIMessage[]
  snapshot.status; // 'idle' | 'submitted' | 'streaming' | 'error'
  snapshot.error;
});

store.submit("你好"); // 追加 user 消息并发起运行；已有运行先被取消
store.stop(); // 取消当前运行，保留已产出的 parts
store.clear(); // 清空全部消息
store.dispose();
```

两个性能装置：

- 帧批处理（`createFrameBatcher`）：把一帧内的多次增量合并为一次通知，token 级的高频更新不会变成高频重渲染；
- 打字机（`visibleLength`）：按每秒字符数的速率计算此刻应显示到第几个字，把网络的突发抖动平摊为匀速输出。

## 流式 Markdown

```ts
import { createStreamRenderer } from "@xihan-ui/markdown";

const renderer = createStreamRenderer();

// 幂等：传入截至当前的全文，返回带稳定 key 的块列表
const blocks = renderer.render(fullText, { ended: false });
// [{ key, kind: 'markdown' | 'code' | 'math' | 'html', html, complete, lang, source }]
```

两条设计要点：

冻结前缀。文本只会向后增长，尾部保留一段前瞻余量之后，前面的块不再变化。每次只解析未冻结的部分，冻结块直接从缓存读取。否则每到一个 token 就要把整篇重新解析重新渲染，长回复到后段会明显卡顿。

唯一的例外是引用定义写在引用它的块之后：此时只把用到该标签的冻结块就地重渲染，其余不变。

稳定 key。生长中的块 key 恒为 `'live'`，定型块的 key 由下标与内容摘要拼成。生长块 key 不变，框架才会复用同一份 DOM 只改文本；每帧更换 key 时用户每收到一个 token 就重建一次节点，选区和滚动位置全部丢失。

`complete` 标记该块是否已闭合。未闭合的块随时会变，宿主据此决定是否执行高亮这类昂贵渲染。

`html` 一律已消毒，可以直接插入 DOM。渲染器只暴露这一个工厂，中间态（解析结果、切块、冻结缓存）一概不暴露：暴露后消费方迟早会绕过缓存直接修改块，增量渲染的保证随之失效。

::: tip CommonMark 覆盖面
实现的是 CommonMark 的一个子集，官方用例通过 489/652。仓库中有一道一致率棘轮监测这个数字，只允许上升不允许下降。
:::

## 代码着色

```ts
import { createHighlighter } from "@xihan-ui/code-highlight";

const highlighter = createHighlighter();
const tokens = highlighter.highlight(code, "typescript"); // CodeToken[] | null
```

自研的粗粒度词法器，只区分注释、字符串、数字、关键字、标点五类。类型名、函数名、属性名这类需要语法树才能区分的内容一概不分：那属于 TextMate 语法一档的工作，本实现不追求。

无法识别的语言、超长代码一律返回 `null`，调用方原样渲染纯文本。

`HighlighterPort` 同样是 `@xihan-ui/core` 中的端口。需要更高精度时，把其他高亮库接到同一个端口即可，`code-view` 组件侧不需修改。

## 相关

- [消息流](../components/message-feed) 与 [提示输入框](../components/prompt-input)：合起来即一个最小对话界面
- [日志](../components/log)：不分条、只向下追加的输出，同样贴底
- [代码视图](../components/code-view)：把流中的代码原文渲染为带行号的代码块

- [行为原语](./behavior#贴底)：消息列表的自动贴底

---

来源：https://ui.docs.xihanfun.com/guide/anatomy

# 解剖与部件契约

解剖（anatomy）是 XiHan.UI 的基础约定：把一个组件拆成若干具名部件（part），每个部件在 DOM 上由 `data-scope` + `data-part` 两个属性唯一标识。皮肤、测试、诊断、跨适配器一致性判据都建立在这条约定上。

## 声明

```ts
import { createAnatomy } from "@xihan-ui/core";

export const accordionAnatomy = createAnatomy("accordion", [
  "root",
  "item",
  "header",
  "trigger",
  "content",
  "indicator",
]);
```

`build()` 把它展开成属性与选择器：

```ts
const parts = accordionAnatomy.build();

parts.content.attrs;
// { 'data-scope': 'accordion', 'data-part': 'content' }

parts.content.selector;
// '[data-scope="accordion"][data-part="content"]'
```

部件名一律 kebab-case，即 `data-part` 的值，也是 CSS 选择器中出现的字面量；三处同名，不做任何转换。

## 三类属性

DOM 上出现的属性分三类，只有前两类是对外的样式接口：

| 属性 | 含义 | 谁写 |
| --- | --- | --- |
| `data-scope` / `data-part` | 结构标识：所属组件与部件 | 解剖 |
| `data-state` / `data-disabled` / `data-orientation` / `data-highlighted` / `data-side` / `data-align` | 状态：当前的状态 | `connect` |
| `data-xh-*` | 内部标记（层栈、集合项、焦点哨兵、滚动分片等） | 原语内部 |

第三类以 `data-xh-` 前缀与前两类区分。不在皮肤中选择它们，它们是实现细节，不承诺稳定。

## 必备部件

每个组件另有一份机读元数据，声明缺少哪些部件组件就无法工作：

```ts
export const accordionMeta: ComponentMeta = {
  component: "accordion",
  requiredParts: ["trigger", "content"],
};
```

这份元数据具有执行力：

- Web Components 适配器在接线时比对作者编写的 DOM，缺少必备部件时报告 `wc.missing-part`（error），出现解剖之外的部件名时报告 `wc.unknown-part`（warn）；
- 部分部件还登记了必须使用的标签：例如表单字段的 `label` 必须是原生 `<label>`，写成 `<div>` 会使 `for` 关联失效、点击标签不再聚焦控件，这类写错即静默失效的情况报告 `wc.wrong-part-tag`。

每个组件的必备部件在[组件参考](../components/)中加粗标出。

## collection 是否铺开结构

不少组件接受 `collection`（或 `columns` / `rows`）作为数据入口。接受数据不等于会渲染结构，分为两档：

| 档 | 传了数据之后 | 哪些组件 |
| --- | --- | --- |
| 根级代铺 | `<XhXxxRoot :collection>` 可以单独使用，整套部件由组件铺开；写了默认插槽即整体接管 | `accordion` `checkbox-group` `combobox` `context-menu` `listbox` `mention` `menu` `menubar` `navigation-menu` `radio-group` `select` `tabs` `toggle-group` |
| 仅元信息 | 不铺任何节点，结构全部手写；数据只供组件内部判断禁用、层级、选中 | `tree` `tree-select` `cascader` `transfer` `side-nav` `table`（`columns` / `rows`）`steps`（`count`） |

判据是结构的自由度：扁平集合的 DOM 形状确定，代铺不会限制任何写法；层级与多区（树、级联、穿梭框）的结构有较多合理变体，代铺会迫使作者推翻重写。

代铺一档有一条硬约束，由 `tests/collection-required-parts.spec.ts` 逐个组件保证：铺出的结构必须包含该组件的必备部件，与手写全套部件产出的 DOM 一致。少一个部件即渲染出一个看似正常、实际不工作的组件：浮层无法打开、方向键找不到条目、读屏在自定义元素侧报告 `wc.missing-part`。为新组件增加代铺时，先在该测试中增加一行。

## 两套适配器的用法

Vue 适配器把部件封装为组件。`XhAccordionContent` 内部把 `api.getContentProps()` 展开到一个 `<div>` 上，属性由 `connect` 提供，`data-part` 不需要作者编写，但它存在于 DOM 上。

Web Components 适配器相反：结构由作者编写，用 `data-xh-part` 声明节点的角色，元素发现它们之后写入属性。

```html
<xh-accordion>
  <div data-xh-part="item" data-value="a">
    <h3 data-xh-part="header">
      <button data-xh-part="trigger">第一节</button>
    </h3>
    <div data-xh-part="content">内容</div>
  </div>
</xh-accordion>
```

::: tip 为什么是两个不同的属性名
作者写的是 `data-xh-part`（声明：该节点担任 trigger），元素接线后写入的是 `data-part`（事实：它已经被接为 trigger）。两者分开，才能区分“作者写了但未接上”与“已经接上”，`wc.missing-part` 等诊断才有意义。
:::

部件发现逐层向下遍历，遇到嵌套的 `xh-*` 子树即跳过：嵌套的另一个组件的部件由它自己管理。

## 皮肤只识别属性不识别类名

类名属于框架，属性不属于框架。

```css
@layer xihan.components {
  [data-scope='button'][data-part='root'] { /* … */ }
  [data-scope='button'][data-part='root'][data-variant='solid'] { /* … */ }
  [data-scope='button'][data-part='root'][data-disabled] { /* … */ }
}
```

同一份 CSS 同时作用于 Vue 组件与自定义元素，因为两者在 DOM 上完全一致。这也意味着可以整体替换默认皮肤，组件行为不受影响。

## 归一化与属性合并

`connect` 产出的是框架无关的 prop 字典，交给适配器的归一化器落到具体框架上：

```ts
export function connectAccordion<T extends PropTypes>(
  service: Service<AccordionSchema>,
  normalize: NormalizeProps<T>,
): AccordionApi<T>;
```

`normalize` 按元素类型分成 `element` / `button` / `input` / `label` / `img` 等若干 getter，各框架各实现一份。Vue 适配器传 `vueNormalize`，Web Components 适配器传 `wcNormalize`，无头场景直接用 `@xihan-ui/core` 的恒等归一化器 `normalizeProps`。

需要叠加自定义属性时使用 `mergeProps`，合并语义固定：

| 键 | 语义 |
| --- | --- |
| `class` / `className` | 空格拼接 |
| `style` | 对象浅合并 |
| `onXxx` 事件处理器 | 顺序组合，前者先执行 |
| 其余 | 后者覆盖前者 |

## 相关

- [connect 与属性产出](./connect)：`getXxxProps()` 的内容
- [皮肤与样式分层](./styling)：属性选择器如何组织为一套皮肤
- [诊断通道](./diagnostics)：契约违约如何被报告

---

来源：https://ui.docs.xihanfun.com/guide/animations

# 动画层

`@xihan-ui/animations` 提供现成的动效：11 个进场预设、6 个注意预设，外加错开起播与文字拆分。零第三方依赖，框架无关，任何框架（或无框架）都可直接安装使用。

它建立在 [动效原语](/guide/motion) 之上：减弱动效的降级由该层统一处理，本层不另开通道。减弱动效下两族预设都不播，元素直接呈现终态：它们是表现性的动效，不承载信息。

```vue
<script setup lang="ts">
import { BUILTIN_MOTION_NAMES, createMotionPlayer } from "@xihan-ui/animations";
import { XhButton } from "@xihan-ui/vue";
import { onBeforeUnmount, ref, useTemplateRef } from "vue";

const enter = BUILTIN_MOTION_NAMES.slice(0, 11);
const attention = BUILTIN_MOTION_NAMES.slice(11);

const motion = createMotionPlayer();
const card = useTemplateRef<HTMLElement>("card");
const last = ref("");

function play(name: string) {
  const el = card.value;
  if (!el)
    return;
  last.value = name;
  void motion.play(el, name);
}

onBeforeUnmount(() => motion.cancel());
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: 100%">
    <div
      style="
        display: grid;
        place-items: center;
        min-height: 140px;
        border: 1px dashed var(--vp-c-divider);
        border-radius: 12px;
      "
    >
      <div
        ref="card"
        style="
          padding: 16px 24px;
          border-radius: 10px;
          background: var(--vp-c-brand-1);
          color: #fff;
          font-weight: 600;
        "
      >
        {{ last || "点下面的名字" }}
      </div>
    </div>

    <div>
      <p style="margin: 0 0 8px; font-size: 13px; opacity: 0.7">进场</p>
      <div style="display: flex; flex-wrap: wrap; gap: 8px">
        <XhButton
          v-for="name in enter"
          :key="name"
          variant="outline"
          size="sm"
          @click="play(name)"
        >
          {{ name }}
        </XhButton>
      </div>
    </div>

    <div>
      <p style="margin: 0 0 8px; font-size: 13px; opacity: 0.7">注意</p>
      <div style="display: flex; flex-wrap: wrap; gap: 8px">
        <XhButton
          v-for="name in attention"
          :key="name"
          variant="outline"
          size="sm"
          @click="play(name)"
        >
          {{ name }}
        </XhButton>
      </div>
    </div>
  </div>
</template>
```

## 动画是配方，不是类名

一段动画是一份可 JSON 序列化的配方（`MotionSpec`）：若干视觉帧加一组时序参数。

```ts
import type { MotionSpec } from "@xihan-ui/animations";

const riseUp: MotionSpec = {
  frames: [
    { opacity: 0, y: 24, scale: 0.98 },
    { opacity: 1, y: 0, scale: 1 },
  ],
  duration: 420,
  easing: "emphasized",
};
```

一帧可以修改六个属性：`opacity` `x` `y` `scale` `rotate` `blur`。位移写数字按 px，写字符串原样透传（`'100%'`）。省略的字段表示该帧不参与该属性的插值。

配方是纯数据，因此可以存入数据库、由界面下拉切换、由用户修改后存回。播放器在入口按 `validateMotionSpec` 校验合上本次选项与时长系数之后的配方，不合法时同步抛错、不起播，不做钳制或补值：

- 帧数 1–60（`MAX_FRAMES`），时长与起播延迟 0–60000ms（`MAX_DURATION`），有限播放次数不超过 1000（`MAX_ITERATIONS`）。
- `opacity` 在 0–1，`scale` 与 `blur` 不为负，位移与旋转是有限数，偏移量在 0–1 且按帧序不减。
- 整段与逐帧缓动必须是命名缓动或合法的 CSS 缓动函数，由 [`resolveEasing`](/guide/motion#缓动) 判定。
- 闪烁：任意一秒内明暗交替不得超过三次（`MAX_FLASHES_PER_SECOND`，WCAG 2.3.1）。按不透明度计算，同一方向连续变化满 0.1 算一次起落，一明一暗算一次闪烁；连播时上一遍末帧跳回下一遍首帧也算一次变化。`peakFlashesPerSecond(spec)` 返回一份配方任意一秒内最多闪几次。

展开为宿主可识别的关键帧时有一条规则：某个属性只要有一帧声明过，其余帧就补上它的中性值。只在中间帧出现的属性，宿主会以元素当前的计算值作为端点，而该值随皮肤变化：同一份配方在不同皮肤下会成为不同的动画。

## 预设

进场一族把元素从不在场带到静息态：

`fade` `fade-up` `fade-down` `fade-start` `fade-end` `zoom-in` `zoom-out` `blur-in` `rise` `drop-in` `spin-in`

注意一族从静息态出发，回到静息态：

`shake` `pulse` `bounce` `wobble` `flash` `heartbeat`

两族都不保留终值：播完后元素回到皮肤定义的外观，动画不接管静息态。这也是它们可以反复播放的原因。

`fade-start` / `fade-end` 标了 `logical`，横向位移在 RTL 下自动取反；`fade-up` 这类纵向的不受影响。

预设的时长、位移与曲线取自 [动效令牌](/design/motion)，由 `@xihan-ui/motion` 的语义常量传过来，与令牌逐条对账：

| 预设 | 时长 | 位移 | 缓动 |
| --- | --- | --- | --- |
| `fade` | `--xh-motion-duration-enter` | — | `--xh-motion-ease-enter` |
| `fade-up` `fade-down` `fade-start` `fade-end` `zoom-in` `zoom-out` `blur-in` | `--xh-motion-duration-slide` | `--xh-motion-distance-lg` | `--xh-motion-ease-enter` |
| `rise` `drop-in` `spin-in` | `slide` 加 `enter` | `--xh-motion-distance-lg` 的 1.5 倍 | `--xh-motion-ease-emphasis` |
| `shake` `pulse` `bounce` `wobble` `flash` `heartbeat` | `--xh-motion-duration-attention` | `--xh-motion-distance-md` 为准 | 各预设自带 |

缩放、旋转与模糊的幅度是各预设自身的形状，不对应令牌。核心组件不使用注意一族：校验失败用颜色、图标与文字表达，是否抖动由应用决定。

## 播

```ts
import { createMotionPlayer } from "@xihan-ui/animations";

const motion = createMotionPlayer();

await motion.play(card, "fade-up");
motion.play(input, "shake"); // 校验未通过时抖动
motion.play(el, { frames: [{ opacity: 0 }, { opacity: 1 }], duration: 500 }); // 直接传配方
```

同一元素上再次播放会先撤销上一段：两段同时写同一批属性时，后一段会从被修改的中间态起步。被撤销的 `play` 以 `'cancelled'` 结算，不抛异常。

播放器上有开关、时长系数与预设表。时长系数取 (0, 100]，越界时 `createMotionPlayer` 抛错：

```ts
const motion = createMotionPlayer({
  enabled: true, // 接入用户偏好，不替最终用户决定
  speed: 1, // 全局时长系数，越大越慢
  presets: myPresets, // 省略时使用内置预设
});

motion.setEnabled(false); // 关闭时撤销正在播放的动画，但 play 照常结算
motion.cancel(el); // 撤销一个
motion.cancel(); // 全部撤销
```

播放未收录的名字不播放、不抛异常，只产出一条诊断告警（见 [诊断通道](/guide/diagnostics)）。

## 错开起播

```vue
<script setup lang="ts">
import type { StaggerFrom } from "@xihan-ui/animations";
import { createMotionPlayer, splitText } from "@xihan-ui/animations";
import { XhButton, XhRadioGroupRoot } from "@xihan-ui/vue";
import { onBeforeUnmount, ref, useTemplateRef } from "vue";

const fromOptions = [
  { value: "first", label: "从头" },
  { value: "last", label: "从尾" },
  { value: "center", label: "从中间" },
];

const motion = createMotionPlayer();
const list = useTemplateRef<HTMLElement>("list");
const title = useTemplateRef<HTMLElement>("title");
const from = ref<StaggerFrom>("first");
const gap = ref(60);

function playList() {
  const el = list.value;
  if (!el)
    return;
  void motion.playAll([...el.children] as HTMLElement[], "rise", {
    stagger: gap.value,
    from: from.value,
  });
}

async function playTitle() {
  const el = title.value;
  if (!el)
    return;
  const { parts, restore } = splitText(el);
  await motion.playAll(parts, "fade-up", { stagger: 30 });
  restore();
}

onBeforeUnmount(() => motion.cancel());
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: 100%">
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 20px">
      <XhRadioGroupRoot
        v-model:value="from"
        :collection="fromOptions"
        label="起点"
        name="stagger-from"
      />
      <label style="display: flex; align-items: center; gap: 8px">
        间隔 {{ gap }}ms
        <input v-model.number="gap" type="range" min="0" max="200" step="10">
      </label>
    </div>

    <div style="display: flex; gap: 8px">
      <XhButton size="sm" @click="playList">播列表</XhButton>
      <XhButton size="sm" variant="outline" @click="playTitle">播标题</XhButton>
    </div>

    <h3 ref="title" style="margin: 0; font-size: 24px">曦寒 UI 动画层</h3>

    <div ref="list" style="display: flex; flex-wrap: wrap; gap: 8px">
      <div
        v-for="n in 8"
        :key="n"
        style="
          display: grid;
          place-items: center;
          width: 48px;
          height: 48px;
          border-radius: 10px;
          background: var(--vp-c-brand-soft);
          font-weight: 600;
        "
      >
        {{ n }}
      </div>
    </div>
  </div>
</template>
```

```ts
await motion.playAll(list.children, "rise", { stagger: 40, from: "center" });
```

`from` 决定从哪一端铺开：`first` 从头、`last` 从尾、`center` 从中间向两侧。间隔缺省取 `--xh-motion-stagger-step`（40ms），叠加在给定的基础延迟上。任意一个被打断，整体即视为被打断。

## 文字拆分

`splitText` 把一段文字拆为逐字或逐词的行内块，正好是 `playAll` 需要的一组元素。

```ts
import { splitText } from "@xihan-ui/animations";

const { parts, restore } = splitText(title, { by: "char" });
await motion.playAll(parts, "fade-up", { stagger: 30 });
restore();
```

按码点切分，不会把 emoji 拆成两半；空白原样保留，换行正常。每一段都是 `inline-block`：行内元素不受 `translate` 与 `scale` 影响。

::: warning 无障碍
原文会写入容器的 `aria-label`，拆出的每一段标记 `aria-hidden`：逐字的 `span` 会让部分读屏逐字朗读。

这意味着容器的角色必须支持命名（标题、按钮、链接等）。套在裸 `div` 上时读屏可能读不到无障碍名，此时需另行提供可访问文本。使用完毕后调用 `restore()`。
:::

## 反向播放

`reverseSpec` 把一份进场配方翻转为退场配方：帧序反转、偏移量镜像。逐帧缓动会被丢弃：它描述的是本帧到下一帧的过渡，反转之后该区间的归属改变。

```ts
import { motionPresets, reverseSpec } from "@xihan-ui/animations";

await motion.play(el, reverseSpec(motionPresets["fade-up"]));
```

弹窗这类会挂载卸载的进出场不使用它：那需要在卸载前播完动画，应使用 [行为原语](/guide/behavior) 的进出场时序，动画本身交给 CSS `@keyframes`。这里的退场适合元素常驻、只是隐藏的场景。

## 滚动进入视口后播放

观察不是动画，不收纳在本包中。用 `@xihan-ui/core` 的 `createViewportEntry` 观察，在回调中调用 `play`：

```ts
import { createViewportEntry } from "@xihan-ui/core";

createViewportEntry({
  scope,
  target: () => card,
  onEnter: () => void motion.play(card, "rise"),
});
```

## 相关

- [动效原语](/guide/motion)：缓动、弹簧、减弱动效偏好
- [行为原语](/guide/behavior)：进出场时序、滚动观察
- [声音层](/guide/sound)：同一套配方、预设、播放器的形态，换为听觉

---

来源：https://ui.docs.xihanfun.com/guide/backgrounds

# 背景层

`@xihan-ui/backgrounds` 是一层 WebGL2 背景效果与数据驱动粒子点云，框架无关、零第三方依赖。它是可选的：适配器把它声明为 optional peer，不使用视觉效果的应用不会因为安装了 `@xihan-ui/vue` 而多出一个 WebGL 引擎。

WebGL2 缺席时自动降级成 CSS 静态背景，不报错、不留白。

## 两条主线

1. 程序化效果：传入一个效果对象与一份参数，铺在任意元素的背景上；
2. 点云：图片、文字、SVG、参数方程都能采样成点云，交给 `particles` 效果显示，两份点云之间自动形变过渡。

## 内置效果

14 个：`aurora` `beam` `flow-field` `fluid` `glass` `grain` `mesh` `nebula` `orb` `particles` `plasma` `ripple` `starfield` `wave`。

每个效果自带参数规格（数值、布尔、枚举、颜色四类），可以据此自动生成调参面板。

这 14 个不自动注册。按名字取用前需要先注册；直接传效果对象则不需要，见下文。

## 基础用法

两条路径，按场景选择。

传效果对象：不经过注册表，未引用的效果会被打包器摇掉。只使用少量效果时选它：

```ts
import { auroraEffect, createBackgroundSurface, nebulaEffect } from "@xihan-ui/backgrounds";

const surface = createBackgroundSurface(el, {
  effect: auroraEffect,
  params: { speed: 1.6 },
  quality: "high",
  pointer: true, // 自动绑定指针事件，需要自行提供坐标时关闭
  autoplay: true,
  respectReducedMotion: true, // 系统开启减弱动态效果时冻结时间轴
  pauseOffscreen: true, // 滚出视口时暂停绘制
});

surface.setParams({ speed: 2 });
surface.setEffect(nebulaEffect);
surface.pause();
surface.destroy();
```

按名字：适合参数保存在配置中、由界面下拉切换。名字需要先注册：

```ts
import { auroraEffect, createBackgroundSurface, nebulaEffect, registerBuiltinEffects, registerEffects } from "@xihan-ui/backgrounds";

registerBuiltinEffects(); // 14 个内置效果全部注册
registerEffects([auroraEffect, nebulaEffect]); // 或只注册用到的效果

createBackgroundSurface(el, { effect: "aurora" });
```

内置效果不自动注册，是因为注册表一旦静态引用这 14 个，任何使用 `createBackgroundSurface` 的应用都会把它们全部打进包：实测约 35 kB（gzip 约 8.6 kB），占整包四成。未注册即按名字取用会抛错，错误信息会指明应调用的函数与该效果的导出名。合法的内置名字可以从 `BUILTIN_EFFECT_NAMES` 获取，它是纯字符串清单，引用它不会把效果对象带进包。

后两个选项默认开启，是这层在真实页面中不成为负担的关键：不可见的画面不消耗 GPU，声明了减弱动态效果的用户不会受到动画干扰。

## 宿主的定位

`target` 传容器元素时，画布是绝对定位的，因此容器必须是它的定位祖先。库的处理：

- 容器已有定位（内联或类名）：不做任何修改；
- 容器计算为 `static`：写一句内联 `position: relative` 兜底；
- 容器尚未进入文档：先不挂画布、也不写定位。此时 `getComputedStyle` 无法计算，写入会覆盖类名中的定位且无法撤回。等容器进入文档得到盒子后，库再判定一次。

因此容器的定位写在类名中是安全的，不必为这层背景改为内联样式。

## 在 Vue 里用

Vue 侧的适配放在单独的子入口 `@xihan-ui/vue/backgrounds`，三种用法从轻到重：

```vue
<script setup lang="ts">
import { auroraEffect, fluidEffect, nebulaEffect } from "@xihan-ui/backgrounds";
import { useBackground, vBackground, XhBackground } from "@xihan-ui/vue/backgrounds";

const visual = useBackground({ effect: fluidEffect });
</script>

<template>
  <!-- 1. 指令：给任意元素或组件的根元素铺一层背景，不修改组件 -->
  <XhButton v-background="auroraEffect">提交</XhButton>
  <div v-background="{ effect: auroraEffect, params: { speed: 1.6 } }" />

  <!-- 2. 组件：插槽内容浮在效果之上，画布 pointer-events: none 不挡交互 -->
  <XhBackground :effect="nebulaEffect" :params="{ density: 0.8 }">
    <h1>标题浮在效果上</h1>
  </XhBackground>

  <!-- 3. 组合式函数：获取画面实例，接自定义调度或调参面板 -->
  <div :ref="visual.attach" />
</template>
```

Vue 子入口不自动注册内置效果。要在模板中写字符串名（`v-background="'aurora'"`、`effect="nebula"`），先在应用入口调用一次 `registerBuiltinEffects()` 或 `registerEffects([...])`。

## 在 React 里用

React 侧的适配同样在单独的子入口 `@xihan-ui/react/backgrounds`，两种用法：

```tsx
import { fluidEffect, nebulaEffect } from "@xihan-ui/backgrounds";
import { useBackground, XhBackground } from "@xihan-ui/react/backgrounds";

function Cover() {
  const visual = useBackground({ effect: fluidEffect });

  return (
    <>
      {/* 1. 组件：children 浮在效果之上，画布 pointer-events: none 不挡交互 */}
      <XhBackground effect={nebulaEffect} params={{ density: 0.8 }}>
        <h1>标题浮在效果上</h1>
      </XhBackground>

      {/* 2. 钩子：获取画面实例，接自定义调度或调参面板 */}
      <div ref={visual.ref} />
    </>
  );
}
```

没有 Vue 侧的第三种用法。`v-background` 依靠指令这层介质挂到其他元素上，React 没有这层介质：把 `useBackground` 返回的 `ref` 挂到元素上即为同一件事，挂到其他组件上同理，只要该组件把 `ref` 转发给自己的根元素。

`visual.ref` 的身份跨渲染稳定，直接写 `ref={visual.ref}` 即可；`visual.surface` 是 ref 对象，读 `.current` 获取画面实例，没有元素挂载时为 `null`。

React 子入口同样不自动注册内置效果。要按名字写（`effect="aurora"`），先在应用入口调用一次 `registerBuiltinEffects()` 或 `registerEffects([...])`。

## 在自定义元素里用

同样单独注册，不引用这一行就不会把引擎打进包：

```ts
import { defineXhBackground } from "@xihan-ui/web-components/backgrounds";

defineXhBackground();
```

`defineXhBackground()` 会把内置效果一并注册进注册表，因此 `<xh-background effect="aurora">` 直接可用；代价是这条入口一定带上全部 14 个效果。

## 点云

把任意内容采样成点，再让粒子排列成该形状：


```ts
import { imageToCloud, shapeCloud, svgToCloud, textToCloud } from "@xihan-ui/backgrounds";

const cloud = await textToCloud("曦寒", { count: 8000 });
surface.setCloud(cloud, { duration: 1.2 }); // 与上一份点云之间形变过渡
```

| 来源 | 函数 |
| --- | --- |
| 文字 | `textToCloud` |
| 图片 | `imageToCloud` / `drawableToCloud` |
| SVG 路径 | `svgToCloud` / `pathToCloud` |
| 内置形状 | `shapeCloud`（`SHAPE_NAMES` 里列出全部） |
| 自定义 | `createCloud` + `normalizeCloud` / `resample` / `mergeClouds` |

点云工具还有 `boundsOf`（包围盒）、`lerpArrays`（插值）、`scatterShell`（球壳散布）、`createRng`（可复现随机）。

## 自定义效果

```ts
import { colorSpec, defineEffect, numberSpec, registerEffect } from "@xihan-ui/backgrounds";

const myEffect = defineEffect({
  name: "my-effect",
  params: {
    // (label, min, max, step, default)
    speed: numberSpec("速度", 0, 4, 0.1, 1),
    tint: colorSpec("主色", "#3b82f6"),
  },
  shared: "/* 两个通道共用的 uniform 声明与函数 */",
  fragment: "/* 流场通道的片元着色器主体，含 main() */",
  uniforms: ctx => ({ /* 每帧算的 uniform */ }),
  fallback: params => "linear-gradient(…)", // 无 WebGL2 时当 CSS background
  scale: 0.75, // 渲染分辨率倍率；柔和的画面调低可省掉大半像素
});

registerEffect(myEffect);
```

注册后就能按名字引用，和已注册的内置效果一样进调参面板。画质档位有 `auto` / `high` / `balanced` / `eco` 四挡，`auto` 按设备像素比与硬件并发数推断。

## 调度

所有画面共享一个调度器（`joinScheduler`），页面上开十个效果也只有一条 `requestAnimationFrame` 循环。`scheduledCount()` 可以查此刻有几个在跑。

## 相关

- [Vue 适配器](../adapters/vue)
- [Web Components 适配器](../adapters/web-components)

---

来源：https://ui.docs.xihanfun.com/guide/behavior

# 行为原语

`@xihan-ui/core` 中的行为原语收纳跨组件复用的交互机制：对话框、抽屉、气泡、菜单、右键菜单、悬浮卡片等的差别在触发方式和视觉，但点击外部关闭、焦点陷入、背景禁止滚动是同一套机制。在这里实现一次，组件只负责调用。

配套的层栈与背景失活也在 `@xihan-ui/core` 中（它们是结构原语，比行为更底层）。

`createScope(node, idGenerator)` 从节点自己的 realm 解析 Document、Window、Element 与 ShadowRoot。传入 iframe 或画中画窗口中的节点时，`getRootNode/getDoc/getWin` 不会因当前页面的 `instanceof` 失败而回落到主文档。把这份显式 Scope 传给 `createRuntimeConfig({ scope })` 后，默认 locale、LayerRegistry、PortalRoot 与 reduced-motion 都从该 Scope 的 document/window 派生；显式传入的配置仍然优先，其中 `layerRegistry.ownerDocument` 必须与 Scope Document 相同。

无全局 DOM 时必须提供有效 Scope；只提供 layer registry 不会得到一个伪造的空 Scope。Scope 的 root、document、window 必须互相归属，离线 Document 没有活动 Window 时直接报错。默认 PortalRoot 保持惰性创建，但 Document 没有 body 时会给出明确错误；需要其他容器就显式传 `portalContainer`。

`createScope(null, ...)` 本身保持惰性，便于在 CSR 中先建立机器再挂载组件节点；这份 Scope 始终表示 ambient Document，不会在之后改绑节点。真正读取 root/document 时若宿主没有有效全局 Document，会抛出稳定错误。传入离线 Document 的节点时 `getDoc()` 仍返回该 Document，但 `getWin()` 明确失败，不会借用主页面 Window 伪造一组混合 realm。

## Portal 的视觉环境

Vue 浮层与 React `XhPortal` 为每个实例建立独立的 `display: contents` 容器，把逻辑来源的视觉环境带到浮层落点。主题、品牌、密度、对比度、动效、透明度和方向分别读取最近的显式声明；语气经 `data-tone` 属性一并带过去，浮层内按[在自定义节点上使用语气](./styling#在自定义节点上使用语气)读 `--xh-tone-*` 的节点取到的是来源那一族。来源祖先链上局部覆盖的 CSS 自定义属性也会投影到实例壳。局部深色或局部令牌覆盖的弹层因此仍保持来源外观，同一落点下的其他实例不受影响。来源没有声明的轴与变量继续继承落点容器。

自定义属性只带属于视觉环境的那部分。作者自己的属性（不以 `--xh-` 开头）照投；`--xh-` 命名空间只投文档根上有声明的名字，即令牌与按[覆盖样式的三种粒度](./styling#覆盖样式的三种粒度)写在 `:root` 上的组件槽覆盖。皮肤写在组件或家族元素上的公开槽（`--xh-<组件>-*`、`--xh-collection-*` 等）、私有槽 `--xh-_*` 与挂在 `[data-tone]` 上的 `--xh-tone-*` 是组件内部级联，不跨 Portal：斑马行改写的行底不会顺着行内的触发器进到菜单项，列表项里的下拉、卡片里的提示同理。判定按每次同步时的文档根计算样式做，不维护名单。

实例壳自己就能解析出来的那些不复制。只由文档根（`:root`、`html`）或桥复制过去的那些属性选中的声明——令牌层的 `:where(:root)`、`:where([data-density='compact'])`、`:where([data-theme='dark'])`，以及作者按同样形状写的规则——在壳上会被同一条规则再命中一次，壳因此只拿属性、不拿逐条 inline 声明；祖先上密度或主题的局部切换仍然完整生效，浮层内解析到的令牌与来源处一致。来源没有显式声明该轴时壳也不写该属性，按既有语义继续继承落点容器。

框架外可使用 `createPortalVisualBridge({ source, shell })`：`source` 是逻辑来源元素，`shell` 是该实例独占的容器，两者必须属于同一 Document。返回的 `sync()` 可立即重读，`dispose()` 停止观察并恢复接管前的容器属性与自定义属性。普通属性、`style` 改动、祖先移动及 Shadow DOM 插槽重新分配会在 MutationObserver 或 slotchange 通知后同步；需要同一调用栈内更新时显式调用 `sync()`。普通计算样式不会复制。

`class` 改动只在增删的名字出现在「声明了自定义属性的选择器」里时才重算：页面级过渡类、展开态与加载态每帧都在祖先链上增删 class，它们与自定义属性无关，链下每个浮层不必为此各读一遍整张令牌表。判定来自一份按文档缓存的样式表索引，样式表增删或整段替换会让它失效；通过 CSSOM 往已有分组规则内部插入声明自定义属性的规则不改变索引指纹，这种改动后需要显式 `sync()`。样式表跨域读不到规则、或选择器里出现 `[class]` 时，索引整体让位，按原来的方式重算。

```ts
import { createPortalVisualBridge } from "@xihan-ui/core";

const bridge = createPortalVisualBridge({ source, shell });
// 卸载该实例时释放观察与属性。
bridge.dispose();
```

桥接的属性为 `data-theme`、`data-brand`、`data-density`、`data-contrast`、`data-motion`、`data-transparency`、`dir`，以及语气 `data-tone` 与材质轴 `data-material`。三端物理 Portal 都从逻辑来源的 composed 祖先逐项取最近显式声明，并把它们与上述自定义属性投影到实例壳；来源变化、跨 realm 与退场回收均由 Core 桥接生命周期处理。

## 在 Vue 中使用

原语都是框架无关的：接收一份配置与几个元素 getter，返回一个需要自行释放的句柄。接入 Vue 只是把释放挂到作用域结束，这层包装位于 `@xihan-ui/vue/behavior`：

```ts
import { useHoverIntent, useScrollLock } from "@xihan-ui/vue/behavior";

useScrollLock(() => open.value, config);

useHoverIntent({
  getTriggerEl: () => triggerRef.value,
  getContentEl: () => (open.value ? contentRef.value : null),
  onOpenIntent: () => (open.value = true),
  onCloseIntent: () => (open.value = false),
});
```

Vue 与 React 包装在 DOM 提交后解析 `getTriggerEl()`：节点为 `null` 时表示这一帧没有绑定目标，旧绑定会立即释放；节点重新出现、换代或三个计时参数变化时自动重建。Vue 的 `getContentEl` 与意图回调读取当前响应式选项，React 读取最近一次已提交选项；浮层内容或普通回调换代都不会取消正在进行的安全三角会话。

直接使用 core 的 `trackHoverIntent()` 时传入创建时已经在场的 `trigger` 元素。该元素是明确的创建快照，订阅期间不得跨 Document 移动；需要换触发器时先调用 cleanup 再重建。浮层 content 可以动态换代，但必须始终与 trigger 属于同一 Document；安全三角会按原离开点和新面板位置重算。多级浮层经 Portal 分离时，用 `getHoverBranches` 显式返回属于同一悬停树的后代区域；它们必须是同一 Document 的原生 `HTMLElement`，不会按全局浮层顺序猜测归属。所有计时器与文档监听都取自 trigger 创建时所属的活动 Window；非法数值、离线 Document、跨 Document content 或 branch 会直接报错。

另有 `useScrollTracker` / `useStickToBottom` / `useTypeahead`，接法相同。`useStickToBottom` 除状态外还返回句柄上的两个动作，回到底部按钮使用的是前者：

```ts
const { state, scrollToBottom } = useStickToBottom({
  config,
  scrollEl: () => viewportRef.value,
  contentEl: () => contentRef.value,
});

// state.value?.atBottom 为假时显示回到底部按钮，点击调用 scrollToBottom()
```

两个 getter 中读取的是 ref 时不必自行 `retarget`：节点更换后这层包装会重新绑定。

需要层栈流程的原语不在这里：消隐层、焦点域、背景失活要按顺序接入多个部分，接错的表现是点击子菜单导致父层关闭这类不报错的异常。该场景直接使用库内的浮层组件；确需自建时按下文各节的顺序接入。

## 层栈

浮层不是孤立的，它们叠成一个栈。`LayerRegistry` 是这个栈的登记表：

```ts
export type LayerKind = "modal" | "popover" | "inline";

export interface Layer {
  readonly id: string;
  readonly kind: LayerKind;
  readonly node: () => HTMLElement | null; // 层的根节点
  readonly branches: () => Element[]; // 逻辑属于本层、DOM 却在别处的节点
  readonly isModal: () => boolean;
  readonly surfaces: () => Element[]; // 点了就该关本层的表面，如遮罩
  readonly visuals?: () => Element[]; // 特殊结构显式声明真正消费 z-index 的宿主
}

export interface LayerRegistry {
  readonly ownerDocument: Document;
  // register / list / top / elementsAbove / subscribe ...
  visualOf: (layer: Layer) => {
    visualIndex: number;
    visualLane: number;
    visualLayer: string;
  };
  sync: (layer: Layer) => void; // isModal 等动态 getter 改值后显式通知
}
```

两个概念需要单独说明：

- `branches`（分支）：嵌套 portal 出去的子层。菜单开在对话框中、子菜单再 portal 到 body，DOM 上它们是兄弟，逻辑上是父子。漏登记分支会使点击子菜单被判定为点击外部，父层随之关闭。
- `surfaces`（表面）：遮罩这类点击即应关闭的元素。它属于本层，但点击它的语义是关闭而不是点击层内。

默认情况下同一 Document 共用一个注册表；自定义注册表也会在创建时固化唯一的 `ownerDocument`，公共记录本身被冻结。不同 Document（iframe、画中画窗口）的注册表不能混用。

视觉层级不再由各组件各自拿静态 `z-index` 猜。注册表按当前 Document 的逻辑栈派生
`visualIndex`，再让 `kind` 与实时 `isModal()` 占用该序号内的 `visualLane`；后登记层的序号
权重大于 lane，所以嵌套 popover 一定高于所属 modal，后来打开的 modal 也能压住更早的
popover。公共绑定把 `visualLayer` 写入私有 `--xh-_layer`，皮肤仍以公开
`--xh-<component>-layer` 为第一优先级，再回落这份私有值和旧全局令牌。动态 modal 通过
`sync(layer)` 发布同一冻结快照，不改写 Layer，也不在适配器保留 `setModal` 空实现。

`list()` 与订阅回调拿到的都是冻结状态快照，Layer 记录本身也被冻结；节点、分支和模态性仍由记录里的 getter 返回当前值。注册与释放会固定这一轮的订阅者名单并通知完所有人，单个订阅者抛错不会截断后续通知，多项异常会按订阅顺序聚合。

登记与释放采用不同提交点。`register()` 的通知失败表示登记失败：注册表先恢复登记前的同一份快照，再向见过临时新状态的同一批订阅者发布补偿通知；中途退订的人仍会收到补偿，中途新增的人不会凭空收到补偿。变更通知和补偿通知都失败时，两阶段异常会一起上抛，失败登记已经分配的 layer id 不会复用。`dispose()` 会先在旧状态上报告非栈顶诊断，再永久移除 Layer、终结 cleanup，并发布通知；即使诊断输出或通知抛错，移除也不会撤销，两个阶段的异常会完整聚合。这样不会把已经释放且上层不再持有 cleanup 的 Layer 复活；重复释放保持幂等。

订阅回调可以读取当前快照、订阅或退订，但不能同步嵌套调用 `register()`，也不能释放仍在注册表里的 Layer。嵌套状态变更会明确抛错，避免外层通知观察到一半又被另一轮变更改写；已经成功终结的 cleanup 仍可重复调用并保持无操作。

注册表还给出 `elementsAbove(layer)`：栈中位于该层之上的各层的全部节点（`node` + `branches` + `surfaces`）。背景失活要用它把上层排除在自己的管辖之外。

单个 Headless 浮层 layer effect 会把“登记 layer → 建消解层 → 建焦点域 → 加滚动锁/背景失活”放在同一初始化事务里。同步步骤与宿主 `flush` 后才执行的背景失活都经过事务守卫；任一步抛错都会把已经取得的资源按逆序全部释放，最后移除 layer。effect 成功后交给机器的也是同一份幂等逆序 cleanup。单项清理失败原样抛出，多项失败则聚合报告，且两者都会继续清完其余项，避免错误层永久占着栈顶。

## 消隐层

```ts
import { createDismissLayer, createEscapeFallback } from "@xihan-ui/core";

const layer = createDismissLayer({
  config, // RuntimeConfig：scope + 层注册表 + 豁免配置
  layer, // 已注册的层
  onDismiss: (reason) => { /* 'escape-key' | 'pointer-down-outside' | 'focus-outside' | 'programmatic' */ },
  onEscapeKeyDown: (e) => { /* preventDefault() 即这次别关 */ },
  onPointerDownOutside: (e) => {},
  onFocusOutside: (e) => {},
  onInteractOutside: (e) => {}, // 上面两者任一发生时也派发一次
});

const fallback = createEscapeFallback({
  config,
  isEnabled: () => sheetOpen,
  onEscape: event => closeSheet(event),
});
```

两条约束：

- 只有栈顶层响应 `Escape`。否则一次按键会关闭整个栈。
- 四个回调都是可取消的表决票。它们收到的是 `cancelable` 的 `CustomEvent`，`preventDefault()` 即否决本次关闭。四种票均通过 `detail.originalEvent` 保留同一原生事件对象：Escape 为 KeyboardEvent，Pointer 为 PointerEvent，Focus 为 FocusEvent，Interact 为 PointerEvent 或 FocusEvent。DOM 监听与选项回调收到同一张可取消票；specific 与 interact 两票送达后统一检查取消结果。这使表单未填完时按 Esc 先弹出确认这类需求不必绕开组件实现。

DismissableLayer 的监听 Document、`CustomEvent`、微任务与动画帧均取自 `config.scope` 的同一个 Window，`config.layerRegistry.ownerDocument` 也必须逐字指向该 Document。传入的 layer 必须已经登记在这份注册表里；动态 `layer.node()` 可以暂时为 `null`，非空时必须是真实 HTMLElement 且属于该 Document。从其他窗口返回节点会立即报错，不会把一张文档里的交互票派到另一张文档。所属 Window 缺少 `CustomEvent`、`queueMicrotask` 或动画帧能力时创建即失败，不借 ambient 全局。

同一 Document 的 DismissableLayer 与 EscapeFallback 共用一套 Hub；每一份显式 LayerRegistry 按对象身份形成独立 lane，不同应用或子树的自定义层栈互不干扰。同一 lane 的同一 Layer 只能有一个消解参与者，重复创建会明确失败。首个租约同步事务化安装四个监听：keydown capture、pointerdown capture、focusin capture、keydown bubble；最后一个租约释放时按 keydown bubble、focus、pointer、keydown capture 的严格逆序完整卸载。DismissableLayer 参与者仍延后一枚所属 Window 的微任务武装，以避开打开浮层的同一次 pointerdown；EscapeFallback 注册后同步生效。派发处理期间最后一个租约离场时，Hub 把卸载延到当前处理阶段的 `finally`，回调里同步建立的新租约会复用原 Hub，不会出现两套 Document 监听。

pointer 与 focus 先为本次事件冻结一份 composed path，并在执行任何业务回调前冻结所有 lane 的 LayerRegistry snapshot。每条 lane 从事件开始时的真实栈顶向下生成纯计划：命中层内部即停；命中 surface 时计划关闭该层后停止；没有 DismissableLayer 参与者、参与者尚未武装或节点尚未在场时都是屏障。计划阶段每次读取 node、branches 或 surfaces 后都会复核原 snapshot；getter 改变层栈时整条 lane 当场作废，不再读取更低层 getter。执行每个候选前都会确认当前栈严格等于原计划对应的前缀、候选确为真实栈顶、参与者 token 与动态节点仍相同；DOM 表决、选项表决与 interact 表决之后逐阶段复核。票被否决、回调改变 snapshot/node、动态 branch 把原目标纳入层内，都会停止该 lane；动态 surface 命中会关闭其所属层，随后停止，不继续触碰更低层。

`onDismiss` 完整返回后，只有候选 Layer 确实退栈、当前栈严格变成下一段计划前缀时，pointer/focus 才继续处理下一层。受控组件只发关闭意图却未退栈、关闭开关让 `onDismiss` 原地返回、额外移除旧层或登记新层都会形成屏障。正常逐层退栈产生的新冻结 snapshot 会成为下一候选的 stage token；成功变更后再恢复相同内容仍不能冒充原 snapshot，失败登记由 LayerRegistry 补偿回原对象则保持有效。Escape 每条 lane 只处理事件开始时的原始栈顶，一次按键不会沿栈连续关闭。

`createEscapeFallback()` 给同一 lane 的空层栈提供 Escape 后备出口，适合覆盖侧栏这类不登记为 Layer 的界面。keydown capture 会在任何 Layer getter、表决或业务回调前冻结全部 lane 的 registry snapshot 与 fallback token snapshot；当时只要 lane 存在任意 Layer，该 lane 的本次按键就已消费，即使 Layer 没有消解参与者、尚未武装、否决关闭或同步退栈，bubble 也不会接着调用 fallback。空栈 lane 从最新 token 反向查找第一个 `isEnabled()` 为真的出口，最新出口已启用后不会再读取更早 getter。

原生事件到达 Document bubble 且在进入 Hub 前尚未 `defaultPrevented` 时，Hub 才复核 capture 计划。registry 必须仍是原来的空快照，fallback 列表、所选 token 以及为选出它而读过的启用状态也必须逐项相同；capture 后新注册或新启用出口、dispose 后重建、Layer 空栈成功经历非空再回空，都会让旧计划失效。失败 Layer 登记补偿回同一 snapshot 则保持有效。同一 lane 每次只调最新的一个出口；它不释放时会持续占位，释放发生在 capture 之后时本键也不会降级到旧出口。不同 registry lane 各自执行一个，某个 fallback 收到同一原生 `KeyboardEvent` 后调用 `preventDefault()` 不会反向否决其他 lane。目标节点在事件到达 Document bubble 前调用 `preventDefault()` 或阻止传播，则全部 fallback 都不执行。

触摸在 pointerdown 时只建立关闭候选，不立即派发层外票；匹配 pointerup 仅标记触摸完成，随后同目标的 click 才提交原计划。鼠标与笔仍在 pointerdown 时处理。触摸提交的 `detail.originalEvent` 仍为最初的 PointerEvent，click 只作为内部完成证据。

滚动、指针取消、长按菜单、新指针、窗口失焦、文档可见性变化或新的键盘交互会取消候选。参与者、节点或 Layer 快照失效也不会提交；等待期间焦点事件不抢先关闭浮层。这条路径没有固定超时或 pointerup 自动关闭，某一 registry lane 校验抛错只剔除该 lane，其余有效 lane 仍可完成 click。

Hub 在每个 capture 或 bubble 处理阶段持有重入锁，getter、表决、关闭或 fallback 回调同步派出的事件不会嵌套进入该阶段；原事件的 target 阶段仍按浏览器传播模型正常运行。某条 registry lane 的 getter、表决或关闭回调抛错时，其他 lane 仍照常执行；末尾单错原样抛出，多错按 lane 与清理的发生顺序聚合，首错保留为 `cause`。Hub 的 add、queue、动画帧和 remove 都使用所属 Window/Document，并遵守先终态、LIFO、全量尝试的清理规则。

## 焦点域

```ts
import { createFocusScope } from "@xihan-ui/core";

const scope = createFocusScope({
  config,
  layer,
  container: () => contentEl,
  trapped: () => isModal, // 焦点不得逃逸，生命周期内可变
  loop: true, // Tab 到边界回绕，与 trapped 正交
  branches: () => nestedPortals,
  initialFocus: () => firstInputEl,
  restoreFocus: () => true, // 卸载时把焦点归还给创建前的元素，默认开启
  onMountAutoFocus: (e) => {}, // 可 preventDefault 接管首次聚焦
  onUnmountAutoFocus: (e) => {},
});
```

`trapped` 与 `loop` 是两件事：陷住（逃不出去）和回绕（Tab 到末尾回到开头）。模态对话框两者都要；非模态气泡通常只要回绕。

容器上的 `xh.focusScope.mountAutoFocus` / `xh.focusScope.unmountAutoFocus` DOM 事件与两个选项回调收到同一个 `cancelable` `CustomEvent`。成功绑定容器后，每个生命周期只派发一次，DOM 监听器先执行，选项回调随后执行；两条通道都会收到通知。任一通道调用 `preventDefault()`，FocusScope 都不再执行对应的默认聚焦或焦点归还。scope 从未取得容器时不会伪造 body 事件。

`restoreFocus: () => false` 或同一 Document 中更新的焦点域仍在场时，unmount 通知仍会发出，只跳过默认归还。不同 Document 的焦点域互不抑制；跨窗口交接若不应归还，调用方必须用 `preventDefault()` 或 `restoreFocus: () => false` 明确表达。回调抛错会直接暴露；挂载回调抛错时，FocusScope 会先撤销监听、哨兵和层订阅，不留下拿不到句柄的半成品。

挂载回调是同步表决点；要让 FocusScope 在 DOM 稳定后聚焦指定节点，使用 `initialFocus`，它会沿既定帧预算重试。回调取消后自行安排异步焦点时，调度与目标有效性由调用方负责。

非栈顶的焦点域自动暂停：上方新开一层时，下层不再争抢焦点。

`focusSafely` 与 `focusFirst` 按候选节点所属的 Document/ShadowRoot 判断焦点是否真正落下；可选中文本控件通过严格 HTMLElement 身份与 HTML 节点名识别，不依赖可能因 `adoptNode` 改变的 owner realm 构造器。Shadow DOM 中 `document.activeElement` 只指向 host，不能拿它判断内部候选失败或重复聚焦。

陷焦点域会精确观察最后一个域内焦点的 DOM/ShadowRoot 祖先路径。该路径被移除后，FocusScope 等到所属 Window 的下一动画帧再确认最终焦点；只有域仍在场、仍为活动层、`trapped` 仍开启且业务没有把焦点交给其他有效节点时，才恢复到重新插回的原节点、主容器首个有效项或容器。暂停中的域保留待复核资格，重新取得同一 Document 的焦点所有权后再继续；每次尝试候选后都会重新仲裁，候选的 focus 回调同步打开新层时不会再触碰后续节点。动态 `branches`、closed ShadowRoot 与容器替换走同一判据，普通 DOM 删除不会触发补焦。

公开 `FocusableElement` 统一表示 `Element & HTMLOrSVGElement`，即具备浏览器原生焦点能力的 Element。`getTabbables`、`focusSafely`、`focusFirst`、`focusItem`、Scope 活动元素和 FocusScope 的显式焦点目标都使用这份合同；带 `tabindex` 的 SVG/MathML 不会再被类型系统遗漏。

## 滚动锁

```ts
import { acquireScrollLock } from "@xihan-ui/core";

const lock = acquireScrollLock({ config });
lock.dispose();
```

锁是引用计数的：叠加三层浮层即加锁三次，全部释放后才真正解锁并还原滚动位置。

锁定的元素由 `config.scrollRoot()` 明确决定。返回 `null`、`body`、`documentElement` 或 `scrollingElement` 都锁定页面；返回其他节点则锁定该容器，节点必须是所属 Scope Document 内已连接的原生 HTMLElement。内容容器承担滚动时应显式返回它，滚动锁不扫描页面猜测目标。

同一 Document 的并行锁共享同一个规范化目标，混用不同目标会明确失败；最后一把锁释放后，下一次获取可以使用新目标。每轮保存双轴滚动位置、内联样式值与优先级及原 gutter 变量。初始化失败逆序回滚，最终释放先终结状态再尝试全部恢复；业务期间主动改写的样式不会被旧锁覆盖。页面位置按 instant 行为恢复，避免受 smooth 滚动影响。

加锁期间让出来的滚动条宽度写在文档根的 `--xh-scroll-lock-gutter` 上，供 `fixed` 定位的元素让位：

```css
.my-fixed-header {
  padding-inline-end: var(--xh-scroll-lock-gutter, 0px);
}
```

浮层内部需要滚动的场景不依赖白名单：锁修改的是滚动容器本身，浮层是 portal 出去的独立子树，其内部滚动不受影响。

## 背景失活

```ts
import { hideOutside } from "@xihan-ui/core";

const restore = hideOutside(() => [
  contentEl,
  ...branches,
  ...config.layerRegistry.elementsAbove(layer),
], config, {
  exemptSelectors: [".my-portal-root"],
});
```

给 `body` 下除目标与豁免节点外的直接子元素加 `inert`，背景内容对读屏与键盘一并消失。

第一个参数是函数而不是数组：施加 `inert` 的时机横跨整个展开期（`MutationObserver` 观察后续新增到 `body` 的节点），晚于调用时刻挂载的节点也必须能计入目标。目标必须包含全部分支节点，以及栈中位于自己之上的层（`config.layerRegistry.elementsAbove(layer)`），漏传会把 portal 出去的嵌套浮层一起设为 inert：可见但无法操作。

第二个参数必须同时提供 Scope 和计算 `elementsAbove` 的同一份 `LayerRegistry`，通常直接传 `RuntimeConfig`。`hideOutside` 只订阅该实例的层栈变化，并校验注册表的 `ownerDocument` 与 Scope Document 相同；自定义注册表、iframe 与画中画窗口都不再暗中切换到按 Document 获取的默认注册表。

带 `data-xh-inert-exempt` 的元素默认豁免。

`hideOutside` 的目标、`body`、层栈、`MutationObserver` 与 inert 引用计数严格属于 Scope 的同一 Document。iframe 与画中画窗口中的后挂节点会由各自 Window 的观察器重新计算；从其他窗口 adopt 进来的豁免节点也按当前所属 Document 生效。注册表或目标来自其他 Document、Document 没有活动 Window 或宿主缺少 `MutationObserver` 时会明确报错，初始化失败不会留下半施加的 inert 状态。

## 进出场

退场动画与何时可以从 DOM 移除是一对常见问题。`presence` 用租约解决：

```ts
export interface PresenceHandle {
  readonly open: boolean; // 逻辑状态：该开着吗
  readonly rendered: boolean; // 渲染状态：DOM 还该留着吗
  readonly state: "open" | "closed"; // 直接绑到 data-state

  claimExit: (reason: string) => ExitLease;
  onBeforeExit: (fn: () => void) => Cleanup;
  onExitComplete: (fn: () => void) => Cleanup;
  update: (open: boolean) => void;
}
```

关闭时先同步触发 `onBeforeExit`，动画探测器在此申领租约；所有租约归还之前 `rendered` 保持 `true`，DOM 不移除。退场中途又被打开则取消旧租约，不卸载。租约不设猜测时限：CSS 观察器等待浏览器实际创建的有限动画对象完成或取消，同名的多个动画也分别计入；没有实际动画对象时不等待，无限装饰动画不阻塞退出。减弱动效下退场关键帧去掉位移、只剩 120ms 淡出，租约照样等它播完。自定义动画租约由创建方明确完成或取消。

Dialog 与共用其机器的 Drawer 在逻辑关闭时立即给内容设置 `inert` 和 `aria-hidden`，保持浮层登记、滚动锁与背景失活直到内容及遮罩完成退场，然后通知 `onExitComplete`（Vue/Web Components 为 `exit-complete`）。退场中重开保留原资源，旧完成不影响新状态；必要时通过原焦点域的 `reactivate()` 恢复域内焦点，不重复派发挂载自动聚焦通知。卸载立即释放资源，不等 CSS。

适配器必须在 `data-state` 已提交到 DOM 之后才调用 `update(open)`：先改属性再让 CSS 过渡开始，顺序颠倒时动画不会播放。

## 集合导航

列表型组件（菜单、列表框、组合框、树、标签页）共用一套条目导航：

```ts
import { focusItem, navigateItems, navIntentFromKey, queryItems } from "@xihan-ui/core";

const items = queryItems(rootEl, { scope: "menu", part: "item" });
const intent = navIntentFromKey(event, { axis: "vertical", dir: "ltr" });
if (intent) {
  event.preventDefault();
  focusItem(navigateItems(items, currentValue, intent, { loop: true }));
}
```

`navIntentFromKey` 把按键翻译为方向意图（`next` / `prev` / `first` / `last`），并处理两件容易出错的事：轴向（垂直列表不响应左右键）与书写方向（RTL 下左右键语义互换）。不属于导航的按键返回 `null`，此时不得 `preventDefault`，否则会拦截输入法、快捷键和浏览器默认行为。

条目的禁用与身份通过统一的 `data` 标记读取，因此判定逻辑对所有组件一致。

## Typeahead

```ts
import { createTypeahead } from "@xihan-ui/core";

const typeahead = createTypeahead({ timeout: 350 });
const query = typeahead.push(event.key); // 不参与检索的键返回 null
typeahead.clear(); // 收起浮层、切换焦点组时丢弃缓冲
```

连续按键在超时窗口内累积成查询串，超时后重新开始。空格只在缓冲区非空时参与检索，否则会拦截空格选中。

## 贴底

流式输出的消息列表需要新内容到达时自动滚到底部，用户向上翻阅后不再争抢：

```ts
import { createStickToBottom } from "@xihan-ui/core";

const stick = createStickToBottom({
  config,
  scrollEl: () => viewportEl,
  contentEl: () => contentEl, // 尺寸变化的观察目标
  threshold: 64, // 距底部多少 px 视为在底部
  onChange: (state) => {},
});

stick.scrollToBottom(); // 减弱动态效果开启时自动改为 'instant'
stick.retarget(); // 节点更换后解绑重绑
```

会话线程组件使用的就是它。

## 其他

| 导出 | 用途 |
| --- | --- |
| `prefersReducedMotion()` / `onReducedMotionChange()` | 读取与订阅减弱动态效果的系统偏好 |
| `easing` | 一组具名缓动函数 |
| `applySelection()` / `toggleSelectAll()` / `rangeBetween()` | 选中集合运算：带锚点的范围选、全选与切换，不涉及 DOM |
| `getTabbables()` / `focusFirst()` / `focusSafely()` | 可聚焦元素查询与安全聚焦 |

## 相关

- [浮层定位](./position)：坐标的计算方式
- [状态机运行时](./machine)：这些原语在 effects 中装配

- [无障碍与键盘规格](./a11y)：焦点与按键的规格出处

---

来源：https://ui.docs.xihanfun.com/guide/connect

# connect 与属性产出

`connect` 是无头内核的出口：输入是服务与归一化器，输出是一组 props-getter。它把状态机的当前状态翻译为 DOM 此刻应有的属性。

```ts
export function connectAccordion<T extends PropTypes>(
  service: Service<AccordionSchema>,
  normalize: NormalizeProps<T>,
): AccordionApi<T>;
```

`connect` 中没有任何 DOM 写操作，也没有任何框架 API。它是一个纯函数：同样的服务状态，产出同样的属性字典。

## api 的成员

以手风琴为例：

```ts
export interface AccordionApi<T extends PropTypes = PropTypes> {
  // 状态与操作
  value: string[];
  setValue: (next: string[]) => void;
  isOpen: (value: string) => boolean;

  // 每个部件一个 getter
  getRootProps: () => T["element"];
  getItemProps: (props: AccordionItemProps) => T["element"];
  getHeaderProps: (props: AccordionItemProps) => T["element"];
  getTriggerProps: (props: AccordionItemProps) => T["button"];
  getContentProps: (props: AccordionItemProps) => T["element"];
  getIndicatorProps: (props: AccordionItemProps) => T["element"];
}
```

两类成员：

- 状态与操作：当前值、判定函数、命令式方法，供模板外使用；
- props-getter：每个部件一个，名字固定为 `get` + 部件名的大驼峰 + `Props`。

部件本身有身份的（条目、标签页面板等），getter 接收一个描述该条目的参数；单例部件的 getter 不接收参数。

## getter 的内容

```ts
getTriggerProps: item => normalize.button({
  ...parts.trigger.attrs, // data-scope + data-part
  [ITEM_VALUE_ATTR]: item.value, // 集合导航用的身份标记
  "id": triggerId(item.value), // 由 scope 派生，同页多实例不冲突
  "type": "button",
  "aria-controls": contentId(item.value), // 与 content 的 id 对上
  "aria-expanded": isOpen(item.value) ? "true" : "false",
  "aria-disabled": item.disabled ? "true" : "false",
  "data-state": stateAttr(item), // 皮肤钩子
  "data-disabled": dataAttr(item.disabled),
  "onClick": () => { /* send({ type: 'ITEM.TOGGLE', … }) */ },
  "onKeydown": onTriggerKeydown(item),
});
```

五类内容，缺一不可：

| 类别 | 例子 | 消费方 |
| --- | --- | --- |
| 结构标识 | `data-scope` `data-part` | 皮肤、测试、诊断 |
| 无障碍语义 | `role` `aria-expanded` `aria-controls` | 读屏 |
| 状态钩子 | `data-state` `data-disabled` | 皮肤 |
| id 关联 | `id` `aria-labelledby` | 读屏；id 由 `scope.partId()` 派生 |
| 事件处理器 | `onClick` `onKeydown` | 适配器绑到 DOM |

id 一律由 `scope` 派生而不是随意生成，这样同一页面挂载多个实例时 `aria-controls` 指向的仍是自身的内容。跨适配器一致性测试会抹除 id 的具体值、把 IDREF 属性翻译为 `@part(...)` 再比对：各适配器的关联结构必须完全一致。

## 归一化器

`normalize` 按元素类型分为若干 getter：`element` / `button` / `input` / `label` / `output` / `select` / `textarea` / `img`。`connect` 按部件实际渲染的标签选择对应的 getter，适配器即可针对性地转换。

```ts
// 无头场景：恒等归一化，原样获得属性字典
import { normalizeProps } from "@xihan-ui/core";

const api = connectAccordion(service, normalizeProps);
api.getTriggerProps({ value: "a" });
// { 'data-scope': 'accordion', 'data-part': 'trigger', 'aria-expanded': 'false', … }
```

Vue 适配器传入 `vueNormalize`（把 `onKeydown` 一类的键改写为 Vue 识别的形态），Web Components 适配器传入 `wcNormalize`。接入新框架时实现一份 `NormalizeProps` 即可，`connect` 不需修改。

## 无障碍属性上的刻意选择

`connect` 中对 ARIA 的处理有一批经过明确权衡，阅读组件源码时会反复见到：

- 使用 `aria-disabled` 而非 `disabled`，当禁用项仍需可聚焦时（手风琴的禁用条目、加载中的按钮）。原生 `disabled` 会使元素失去焦点，读屏用户无法 Tab 到它，也读不到不可用的原因。
- 不输出 `tabindex` 的组件是刻意的。手风琴不做 roving tabindex，每个触发器都是独立的 Tab 停靠点：这是 APG 对该模式的规定，不是遗漏。
- `hidden` 使用 `!open || undefined`，使属性在展开时彻底消失而不是 `hidden="false"`。
- 纯装饰部件设置 `aria-hidden="true"`，例如指示箭头。

## 直接使用 api 渲染

三种宿主都可以直接使用 `connect`，不必经过现成组件。

Vue 中使用组合式函数：

```vue
<script setup lang="ts">
import { useAccordion } from "@xihan-ui/vue";

const { api } = useAccordion({ multiple: true, defaultValue: ["a"] });
</script>

<template>
  <section v-bind="api.getRootProps()">
    <!-- 自行决定渲染标签 -->
  </section>
</template>
```

完全脱离框架时自行创建服务：

```ts
import { createCounterIdGenerator, createScope, createService, normalizeProps } from "@xihan-ui/core";
import { createVanillaRuntime } from "@xihan-ui/core/vanilla";
import { accordionMachine, connectAccordion } from "@xihan-ui/headless";

const runtime = createVanillaRuntime();
const scope = createScope(rootEl, createCounterIdGenerator());
const service = createService(accordionMachine, {
  props: () => ({ multiple: true }),
  runtime,
  scope,
});
runtime.start();

const api = connectAccordion(service, normalizeProps);
runtime.subscribe(() => {
  // 任一格子变化即重读 api，把属性写到 DOM 上
});
```

## 相关

- [解剖与部件契约](./anatomy)：`data-scope` / `data-part` 的来源
- [状态机运行时](./machine)：`service` 的来源

- [无障碍与键盘规格](./a11y)：这些 ARIA 属性对应的规格出处

---

来源：https://ui.docs.xihanfun.com/guide/date

# 日期与时间

`@xihan-ui/core/date` 提供不带时区的日期值、公历运算、时区换算、按地区划分的周与格式化。日期族的 8 个组件（日期字段、时间字段、日期选择器、日期范围选择器、日历选择器、日历范围选择器、时间选择器、时间范围选择器）都建立在它之上。自研实现，零运行时依赖，整个子入口压缩后 6.52 kB。

命名、取值范围与越界规则沿用 Temporal：`PlainDate` / `PlainTime` / `PlainDateTime` 与 `Temporal.PlainDate` 等同名同义，运行环境普遍提供 Temporal 之后，调用点可以逐个换成原生对象。

## 存在的原因

组件对外的值一律是 ISO 串（`2026-09-26`、`14:05`、`2026-09-26T14:05`）。把串换成可运算的值时，以下细节写错一处，症状就是边界日期错位：

- 月份加减要夹住日号。1 月 31 日加一个月是 2 月 28 日（闰年 29 日），不是 3 月 3 日。
- `Date` 表示时刻而不是日期。以 `Date` 做日期运算时，运行环境所在的时区隐式参与，跨越夏令时的那一天会多出或少掉一小时；`Date.UTC` 还会把 0–99 年映射到 1900 年代。
- 一周从星期几开始由地区决定：美国、日本从星期日开始，中国、欧洲多数国家从星期一开始，埃及从星期六开始。月历的首列与行数都随之变化。
- ISO 周固定从星期一开始，跨年的那一周归星期四所在的年：2027-01-01 属于 2026 年的第 53 周。
- 墙上时间在某些时区里不唯一：夏令时开始时有一段时间不存在，结束时有一段时间出现两次，换成时刻前必须决定取哪一刻。

## 用法

```ts
import { PlainDate, today } from "@xihan-ui/core/date";

PlainDate.from("2026-01-31").add({ months: 1 }).toString(); // '2026-02-28'
today("Asia/Shanghai").toString(); // 上海此刻的日期
```

组件内部已经接入，日常使用不涉及这一层。需要在组件之外计算日期（快捷预设、查询参数、min / max）时直接使用。

## 值类型

| 类型 | 字段 | 字符串形态 |
| --- | --- | --- |
| `PlainDate` | `year` `month` `day` | `YYYY-MM-DD`；0–9999 以外的年份写成 `±YYYYYY-MM-DD` |
| `PlainTime` | `hour` `minute` `second` `millisecond` | `HH`、`HH:mm`、`HH:mm:ss`、`HH:mm:ss.SSS`，可带前缀 `T` |
| `PlainDateTime` | 以上全部 | `YYYY-MM-DD`（时间取 00:00）或 `YYYY-MM-DDTHH[:mm[:ss[.SSS]]]`，分隔符可以是 `T` 或空格 |

三种值都不可变，实例冻结，所有运算返回新值。月份从 1 起算，星期几按 ISO 8601 编号：1 = 星期一 … 7 = 星期日。日期范围与 Temporal 相同：-271821-04-19 至 +275760-09-13。

字符串解析是严格的：`2026-02-29`、`2026-1-1`、带时区偏移的串（`...Z`、`...+08:00`）都抛 `RangeError`。组件内部把解析失败当作「没有值」处理，不会抛给使用者。

### 构造与越界

构造函数只接受合法字段，越界抛 `RangeError`。`from(fields)` 与 `with(fields)` 缺省把越界的字段夹到最近的合法值，传 `{ overflow: 'reject' }` 改为抛错：

```ts
import { PlainDate } from "@xihan-ui/core/date";

PlainDate.from({ year: 2026, month: 2, day: 31 }).toString(); // '2026-02-28'
PlainDate.from("2026-01-31").with({ month: 2 }).toString(); // '2026-02-28'
PlainDate.from({ year: 2026, month: 2, day: 31 }, { overflow: "reject" }); // RangeError
```

### 运算

| 方法 | 说明 |
| --- | --- |
| `add(duration)` / `subtract(duration)` | 先加年月并夹住日号，再加周与日。`PlainDateTime` 先加时间部分、满一天进位，再按同样规则加日期部分。`PlainTime` 跨过午夜时绕回 |
| `with(fields)` | 换掉部分字段 |
| `until(other, { largestUnit })` / `since(other, ...)` | 两者之差，`since` 是 `until` 的相反数。`largestUnit` 缺省为天；取月或年时，月数取「不越过终点」的最大值，起点加上结果恰好落在终点 |
| `round({ smallestUnit, roundingIncrement, roundingMode })` | `PlainTime` 与 `PlainDateTime` 按单位与步长取整。步长须整除上一级单位，例如按 15 分钟取整；取整方式与 Temporal 相同的九种 |
| `compare(a, b)` / `equals(other)` | 先后比较与相等判断 |

值对象不能直接比大小或做算术：`a < b`、`a + 1` 会抛 `TypeError`，比较一律用 `compare`。`toString()` 与 `toJSON()` 输出 ISO 串，放进模板字符串与 `JSON.stringify` 都得到 ISO 串。

`PlainDate` 与 `PlainDateTime` 另有只读字段 `dayOfWeek`、`dayOfYear`、`weekOfYear`、`yearOfWeek`、`daysInMonth`、`daysInYear`、`inLeapYear`。其中 `weekOfYear` 与 `yearOfWeek` 按 ISO 周计算。

## 时区

值对象不带时区。与时刻互换时显式给出时区，不给时取运行环境所在的时区：

| 导出 | 说明 |
| --- | --- |
| `today(timeZone?)` / `now(timeZone?)` | 某个时区里的今天与此刻 |
| `PlainDate.fromDate(instant, timeZone?)` / `PlainDateTime.fromDate(...)` | 时刻（`Date` 或毫秒数）在某个时区里的日期与日期时间 |
| `plainDate.toDate(timeZone?)` | 这一天在某个时区里开始的时刻 |
| `plainDateTime.toDate(timeZone?, { disambiguation })` | 墙上时间在某个时区里对应的时刻 |
| `getLocalTimeZone()` | 运行环境所在时区的 IANA 名 |
| `getTimeZoneOffset(instant, timeZone?)` | 该时刻的偏移量，毫秒，东正西负 |
| `isValidTimeZone(timeZone)` | 运行环境是否认得这个时区名 |

偏移量向 `Intl` 询问，库里不带时区数据库。墙上时间不唯一时按 `disambiguation` 取舍：

| 取值 | 夏令时跳过的时间 | 夏令时重复的时间 |
| --- | --- | --- |
| `compatible`（缺省） | 跳过之后的那一刻 | 较早的一次 |
| `earlier` | 跳过之前的那一刻 | 较早的一次 |
| `later` | 跳过之后的那一刻 | 较晚的一次 |
| `reject` | 抛 `RangeError` | 抛 `RangeError` |

零点被夏令时跳过的日子（例如智利），`plainDate.toDate()` 取当天第一个存在的时刻。

日期类组件的 `timeZone` prop 只决定「今天」是哪一天（聚焦日的兜底、今天的标记、快捷预设）与日期字段的 `valueAsDate`。格式化只由日期字段决定，与时区无关。

## 周与地区

```ts
import { getWeekInfo, PlainDate, startOfWeek, weeksInMonth } from "@xihan-ui/core/date";

getWeekInfo("en-US"); // { firstDay: 7, weekend: [6, 7] }
startOfWeek(PlainDate.from("2026-09-26"), "zh-CN").toString(); // '2026-09-21'
weeksInMonth(PlainDate.from("2026-08-01"), "en-US"); // 6
```

| 导出 | 说明 |
| --- | --- |
| `getWeekInfo(locale)` | 周首日与周末 |
| `startOfWeek(date, weekStart)` / `endOfWeek(date, weekStart)` | 所在那一周的第一天与最后一天 |
| `dayOfWeekIn(date, weekStart)` | 在那一周里排第几，0 即周首日 |
| `weeksInMonth(date, weekStart)` | 所在月份在月历上占几行（4–6） |
| `isWeekend(date, locale)` | 是否周末 |

`weekStart` 可以是 locale，也可以直接给出星期几（`1` 即 ISO 周的周一起算）。周规则取自 Unicode CLDR 48 的 weekData，按地区查表；只写语言时按语言推断地区（`zh` 按中国、`ar` 按埃及）。认 `-u-fw-`（`en-US-u-fw-mon`）、`-u-ca-iso8601`（周一起）与 `-u-rg-`（`en-US-u-rg-gbzzzz` 按英国）三种扩展。

不向 `Intl.Locale#getWeekInfo` 询问：各浏览器对它的支持与数据版本不一，同一个 locale 会排出不同的月历。

## 月、季度与年

| 导出 | 说明 |
| --- | --- |
| `startOfMonth` / `endOfMonth` | 月初与月末 |
| `startOfQuarter` / `endOfQuarter` / `quarterOf` | 季初、季末与第几季度 |
| `startOfYear` / `endOfYear` | 年初与年末 |
| `fromIsoWeek(yearOfWeek, week, dayOfWeek?)` | ISO 周年的第几周、星期几是哪一天 |
| `isoWeeksInYear(year)` | 一个 ISO 周年有 52 周还是 53 周 |
| `isLeapYear` / `daysInMonth` / `daysInYear` | 按年份与月份的公历常识 |

边界函数对 `PlainDateTime` 只挪日期，保留时间部分。

## 格式化

```ts
import { createDateFormatter, PlainDate } from "@xihan-ui/core/date";

const heading = createDateFormatter("zh-CN", { year: "numeric", month: "long" });
heading.format(PlainDate.from("2026-02-01")); // '2026年2月'
```

`createDateFormatter(locales, options)` 建一个可复用的格式化器，提供 `format`、`formatToParts`、`formatRange`、`formatRangeToParts` 与 `resolvedOptions`，参数同 `Intl.DateTimeFormat`，不含时区。值对象上的 `toLocaleString(locales, options)` 做同样的事。

值本身不带时区，格式化按字段原样呈现，结果与运行环境所在的时区无关。没有给任何日期或时间字段时，日期按年月日、时间按时分秒、日期时间两者都输出。`Intl.DateTimeFormat` 的构造开销较大，同一组参数只构造一次。

## 与 Temporal 的差异

| 方面 | 本模块 | Temporal |
| --- | --- | --- |
| 精度 | 毫秒 | 纳秒 |
| 历法 | 只有 ISO 8601 推及历 | 支持多种历法 |
| 字符串解析 | 只认上文列出的扩展格式，不收时区偏移与时区注记 | 另收基本格式、偏移与注记 |
| 带时区的值 | 与 `Date` 互换（`toDate` / `fromDate`） | `ZonedDateTime` |
| 时长 | 冻结的普通对象 | `Temporal.Duration` |
| 周与季度 | 另有按地区的周规则、季度与边界函数 | 无 |

---

来源：https://ui.docs.xihanfun.com/guide/diagnostics

# 诊断通道

组件在运行期发现契约问题时不直接 `console.warn`，而是向诊断通道投递一条结构化记录。宿主订阅后自行决定打印、收集还是上报。

## 不直接打日志的原因

契约违约需要被处理，不只是被看见。`wc.missing-part` 这类问题在开发时应明显报出，在测试中应使用例失败，在生产环境应静默：同一条记录，三种归宿。写死 `console.warn` 只满足第一种。

## 记录的形状

```ts
interface DiagnosticRecord {
  code: string; // 稳定标识，如 'wc.missing-part'
  level: "error" | "warn";
  message: string; // 面向开发者的说明，文案可变
  scope?: string; // 组件名，取解剖名
  instanceId?: string; // 区分同一组件的多个实例
  part?: string;
  node?: Element;
  detail?: Record<string, unknown>;
}
```

`code` 稳定，`message` 不稳定。订阅方按码分流，不匹配文案。

## 现有的码

```ts
export const DIAGNOSTIC_CODES = {
  invariant: "core.invariant", // 断言不成立
  warn: "core.warn", // 条件告警
  layerDisposeNotTop: "core.layer.dispose-not-top", // dispose 的层不是栈顶
  machineError: "machine.error", // 机器抛出 MachineError
  wcMissingPart: "wc.missing-part", // 作者未渲染必需的角色节点
  wcUnknownPart: "wc.unknown-part", // 角色节点的 part 名不在组件解剖内
  wcWrongPartTag: "wc.wrong-part-tag", // 角色节点的标签不满足要求，原生语义会静默失效
  matrixCodeLogoDamage: "matrix-code.logo-damage", // 中心 logo 挖掉的码字超出纠错级别能恢复的量
  matrixCodeOptionIgnored: "matrix-code.option-ignored", // 二维码收到一个对当前码制没有意义的选项，按没给处理
  barCodeOptionIgnored: "bar-code.option-ignored", // 条形码收到一个对当前码制没有意义的选项，按没给处理
  stylesMissingSkin: "styles.missing-skin", // 页面上出现了组件，但它那份皮肤没被引入
  versionMismatch: "core.version-mismatch", // 适配器与 core 的版本不一致，锁步发版被打破
  ignoredSlot: "core.ignored-slot", // 作者给了默认插槽，但该组件不渲染插槽内容
  overlayStackingTrap: "overlay.stacking-trap", // 浮层的祖先建了层叠上下文，浮层的层号被困在其中
  scrollbarMissingScrollable: "scrollbar.missing-scrollable", // 滚动条挂载时找不到它要管的滚动容器
  overlayMissingAnchor: "overlay.missing-anchor", // 浮层展开了却没有锚点，位置无从算起
  chartMissingName: "chart.missing-name", // 图表没有可及名：caption 部件、aria-label、aria-labelledby 都没有
  chartUnknownField: "chart.unknown-field", // 系列引用的字段在数据里不存在
  chartDuplicateSeries: "chart.duplicate-series", // 两个系列的 id 相同
  chartTooManySeries: "chart.too-many-series", // 分类系列超过 8 个：没有第 9 色
  chartMixedColorRoles: "chart.mixed-color-roles", // 同一张图混用分类色与语气色
  chartInvalidSlot: "chart.invalid-slot", // 固定色槽越界，或两个系列固定到同一槽
  chartStackOffsetConflict: "chart.stack-offset-conflict", // 同一堆叠组的 stackOffset 不一致
  chartLogDomain: "chart.log-domain", // 对数轴的定义域含 0 或跨越正负
  chartBarBaseline: "chart.bar-baseline", // 柱系列所在的值轴不含 0
  chartNegativeShare: "chart.negative-share", // 占比类图表出现负值
};
```

这份清单与 `@xihan-ui/core` 中的码表逐条对账，不会遗漏，可以直接据此编写分流。

`machine.error` 的 `detail.machineCode` 是状态机错误码。机器崩溃或正常停机清理失败时，`detail.reason` 保留实际上报的原始或聚合异常对象；同时发生 cleanup 与 exit 异常时，它与调用方捕获的 `AggregateError` 是同一个对象，可以继续读取 `errors` 与 `cause`。

状态机实现引用属于执行前置条件。`UNKNOWN_ACTION`、`UNKNOWN_GUARD`、`UNKNOWN_EFFECT` 在创建机器时拒绝静态缺项；动态列表或实现内部引用缺项时使用 `MISSING_ACTION`、`MISSING_GUARD`、`MISSING_EFFECT`。后三种错误在开发与生产都会先投递 `machine.error`；没有其他停机异常时，其 `detail.reason` 与随后抛出的 `MachineError` 是同一个对象，存在其他停机异常时则由后续崩溃记录携带聚合结果。服务同时进入 `Stopped`。诊断阈值只控制记录是否送达，不会把错误改成继续执行、guard 的 `false` 或部分 effect。

三条 `wc.*` 是 Web Components 适配器的部件契约校验，也是日常最常遇到的三条：手写 DOM 时遗漏一个 `data-xh-part` 或写错名字，通道会明确指出节点与部件。

## 用法

```ts
import { onDiagnostic, setDiagnosticsConsoleOutput, setDiagnosticsLevel } from "@xihan-ui/core";

// 订阅
const off = onDiagnostic((record) => {
  if (record.code === "wc.missing-part")
    reportToSentry(record);
});

// 调阈值：'error' | 'warn' | 'silent'
setDiagnosticsLevel("warn");

// 关闭内建 console 输出，只使用自己的订阅
setDiagnosticsConsoleOutput(false);
```

其余可用的接口：

| 函数 | 作用 |
| --- | --- |
| `getDiagnostics()` | 获取通道对象本身 |
| `reportDiagnostic(record)` | 投递一条（自定义组件中使用） |
| `setDiagnosticsDedupe(on)` | 同一 `code + scope + instanceId + part + message` 是否只报一次 |
| `resetDiagnostics()` | 清空订阅者、去重记录与全部开关 |

## 默认行为

| 环境 | 阈值 | console 输出 | 去重 |
| --- | --- | --- | --- |
| 开发 | `warn` | 开 | 开 |
| 生产 | `silent` | 关 | 开 |

生产默认 `silent`，投递直接被丢弃，不产生任何开销。需要在生产收集时，显式调用 `setDiagnosticsLevel('error')` 并挂载自己的订阅。

去重键包含 message：同一个码下不同文案是不同的问题，只有逐帧重复的同一条才应被压缩。去重集有容量上限，超出即整体清空，长时间运行的进程不会无界增长。

## 隔离性

- 通道挂在全局，同一页面中多份 `@xihan-ui/core` 副本共用一条通道；
- 订阅方抛错不会回流进组件：上报逻辑出错不影响界面。

## 在测试中使用

把阈值调到 `warn` 并订阅，即可把契约违约变为用例失败：

```ts
import { onDiagnostic, resetDiagnostics, setDiagnosticsLevel } from "@xihan-ui/core";

beforeEach(() => {
  resetDiagnostics();
  setDiagnosticsLevel("warn");
});

it("不应有契约违约", () => {
  const records: DiagnosticRecord[] = [];
  onDiagnostic(r => records.push(r));
  render();
  expect(records).toEqual([]);
});
```

## 相关

- [解剖与部件契约](./anatomy)：部件契约校验的内容
- [Web Components 适配器](../adapters/web-components)：三条 `wc.*` 码的来源
- [版本与兼容性政策](./versioning)：名字的变更与移除规则

---

来源：https://ui.docs.xihanfun.com/guide/forms

# 表单参与与重置

复合控件的值保存在自己的状态机中，浏览器不可见。要让它随 `<form>` 一起提交、一起重置，依靠两件事：一份表单影子（把值映射为原生输入）和一条重置事件（把宿主表单的 `reset` 转换进状态机）。

## 表单影子

提供 `name` 才生成影子，未提供时整个组件不参与提交，既有 DOM 不变。

```vue
<XhSwitch name="notify" default-checked />
```

提交结果是 `notify=on`。值可以更换：`<XhSwitch name="theme" value="dark" />` 提交 `theme=dark`。

三种形态，按组件的值形状划分：

| 形态 | 使用者 | 说明 |
| --- | --- | --- |
| 单个 `hidden-input` | color-picker、combobox、tree-select、checkbox、switch、rating 等 | 多值按逗号拼接为一串 |
| 一值一个影子输入 | checkbox-group、radio-group | 与原生 checkbox / radio 同构，依靠 `checked` 表达选中 |
| 隐藏 `<select>` | select | 多选直接开启原生 `multiple` |

勾选类控件的语义与原生一致：未勾选时整个字段不进入 `FormData`，不是提交空值。checkbox 的半选（`indeterminate`）按未勾选处理，原生中它也只是外观，是否提交由 `checked` 决定。

影子在各适配器中的来源不同：

- Vue：单体控件（checkbox、switch）由组件自行渲染，提供 `name` 后才有该节点；有子部件的组件由作者写出对应部件，例如 `<XhComboboxHiddenInput />`。
- Web Components：一律由作者编写 `data-xh-part="hidden-input"` 的原生节点，元素只负责写入属性。

::: tip 为什么 `type=hidden` 可以放进 `<button>`
checkbox 与 switch 的根是 `<button>`，HTML 的内容模型禁止 button 含有交互内容后代。`<input type="hidden">` 不在此列：规范中 input 的条目写明“type 属性不处于 Hidden 状态时”才算交互内容，因此这种嵌套是合法的。
:::

## 表单重置

带 `name` 的组件都响应表单重置。点击 `<button type="reset">`（或调用 `form.reset()`）时，它们各自回到自己的默认值，与旁边的原生输入框一致。

重置桥按事件目标的原生 HTMLElement 品牌与 `form` 节点名识别表单，不依赖顶层 `HTMLFormElement` 构造器。因此组件与表单位于 iframe 中，或表单从另一 Window adopt 到当前 Document 后，仍会跟随所属表单重置；普通元素派发的同名事件不会冒充表单。

对于正式提供 `form` 属性的组件，重置桥优先按该 ID 查找组件所属 Document 或 ShadowRoot 中的表单；未提供时才关联最近的祖先表单。空 ID、目标不存在或目标不是表单时均不关联其他表单。关联在重置发生时读取，因此目标表单延后创建或属性变更不需要重新挂载组件；取消原生 `reset` 事件仍会取消组件重置。此规则不使未声明 `form` 的组件自动获得该公共属性。

```vue
<form>
  <XhRadioGroupRoot name="plan" default-value="standard">…</XhRadioGroupRoot>
  <XhRatingRoot name="score" :default-value="3">…</XhRatingRoot>
  <button type="reset">重置</button>
</form>
```

几条要点：

- 落点按当前的 props 重新计算，不是挂载时冻结的值。宿主更换 `defaultValue`（例如切换到编辑另一条记录）后，重置回到新的默认值，与原生 `reset()` 回到当前 default 一致。
- 受控组件只发出意图。组件不自行修改状态，只调用一次 `onValueChange`（或 `onCheckedChange`），由宿主写回。

::: warning 受控组件要响应重置，必须显式传 `defaultValue`
这是本库与“受控 reset 是空操作”的分歧点，也是最容易出错的一条。

组件内部的 `?? 兜底` 把宿主声明的默认值和组件的空值写在同一个表达式中（radio-group 是 `null`、rating 是 `0`、tags-input 是空数组）。受控且未写 `defaultValue` 时，组件不做任何动作、不发出任何意图；否则该空值会被当作默认值发给宿主，重置就变成了清空数据。
:::

- 重置被拦截时不动作。表单侧 `event.preventDefault()` 之后，同表单的原生控件也未还原，组件单方面还原会产生半份默认值。
- 归属在事件发生时计算。监听挂在组件所在的根节点上而不是 `<form>` 上（表单会被条件渲染替换、组件也会被移动），用 `closest('form')` 比对，因此嵌套表单不会误伤。

不在任何表单内、无 DOM 的服务端、作者未写影子输入，三种情形都不需要特别处理：归属判定不命中、服务端不挂载副作用、锚点是组件根节点而不是影子输入。

## 控件在薄封装内

`XhFieldControl` 默认把接线属性（`id` 与各条 `aria-*`）合并到它唯一的子节点上。子节点是组件时，合并到的是组件的根，而薄封装的根往往是 `div`。

标签的 `for` 只对可标注元素生效（`input` / `select` / `textarea` / `button` 等），指向 `div` 时没有任何效果，且不报错。

点击标题这一半由库处理：`for` 未落到实处时，字段会把焦点送给控件内第一个可 tab 的节点，无论封装是库内的还是自行编写的。读屏能否读出名称是另一半，取决于以下两种写法。

一、控件的根就是可聚焦元素：不需要额外处理，默认路径正确：

```vue
<XhFieldControl>
  <input type="email" />
</XhFieldControl>
```

二、控件位于封装内：关闭 `asChild`，让封装内部自行获取：

```vue
<XhFieldControl :as-child="false">
  <MyInput />
</XhFieldControl>
```

```ts
// MyInput 内部
import { useFieldControl } from "@xihan-ui/vue";

const controlProps = useFieldControl();
// 绑定到真正可聚焦的节点上
```

`useFieldControl` 在字段外调用返回空对象，封装仍可单独使用。不关闭 `asChild` 时属性会被合并两次，一次在封装根、一次在真控件，页面上会出现两个相同的 `id`。

库自身的控件不需要处理这一层。select、text-field、date-picker 等封装内部已经把两份接线取到真正可聚焦的部件上：说明与校验状态一份，字段的标签一份。直接放入 `XhFieldControl` 即可，`asChild` 保持默认。

标签那份是并入而不是覆盖：字段的标签排在最前，控件自己的部分（下拉的当前值等）跟在后面，两者都能读出。控件自带的 `aria-labelledby` 指向它自己的 `label` 部件，使用字段的标签时该部件未渲染，只保留它会形成悬空引用：按 accname 规则跳过，名称又无法回退到 `for`（`for` 指向封装根的 `div`），焦点所在的控件就没有名称。

## 参与的组件

34 个：checkbox、cascader、checkbox-group、color-field、color-picker、color-slider、color-swatch-picker、combobox、date-field、date-picker、date-range-picker、editable、field-array、file-upload、image-cropper、mention、number-field、password-input、pin-input、radio-group、rating、segmented、select、signature-pad、slider、switch、tags-input、text-field、time-field、time-picker、time-range-picker、toggle-group、transfer、tree-select。

新增的表单组件未接入重置会被门禁拦截：判据的分母从源码扫描得出（`types` 的 props 中有 `name?:` 即表单字段，字段名可以是标量字符串或 `FormPath`），不是手写名单。

---

来源：https://ui.docs.xihanfun.com/guide/i18n

# 国际化

默认行为：组件内建的文本是英文，其余全部跟随 `locale`，`locale` 未提供时跟随宿主浏览器。

具体为四条：

- 内建文案（关闭按钮的读屏名称、分页的翻页说明、上传区的提示、色阶两端的 `Less` / `More` 等）一律英文，切换语言经 `translations`。
- 日期时间类组件的月份名、星期名、段位顺序、周首日与默认格式串全部由 `locale` 决定，不写死。
- `locale` 的解析链是实例 props → 全局配置 → 宿主的 `navigator.language` → `en-US`，`calendar` / `date-picker` / `date-field` / `heatmap` / `time` 都使用它。因此中文浏览器中不做任何配置也显示中文日期；服务端渲染期或显式 Scope 没有活动 Window 时读不到宿主语言，使用 `en-US`，不借用其他页面的 Window。
- 例外一处：`time-picker` / `time-field` 的小时制不从宿主推断。`hourCycle` 与 `locale` 都未提供时始终为 24 小时制，需要 12 小时制时提供其中之一。

服务端渲染的应用应在服务端与客户端显式注入同一个 `locale`。如果服务端依赖无 DOM 时的 `en-US`、客户端又依赖 `navigator.language`，两端可能生成不同的月份、星期与段位顺序，形成水合差异。

::: warning 周首日跟随 locale
一周从周日还是周一开始由 `locale` 决定：`en-US` 周日起，`zh-CN` 与多数欧洲语言周一起。
未配置 `locale` 时它跟随读者的浏览器变化，同一份代码在两台机器上排出的月历首列不同。
要固定为一种排法，显式传入 `locale`（实例上传入，或全局配置一次），不依赖默认值。
:::

各适配器都有一处全局出口，语义一致：Vue 侧是 `provideXhConfig`（走 provide/inject，可按子树覆盖），自定义元素侧是 `setXhConfig`（模块级，整个文档一份）。

## 全局注入一次

```ts
import { provideXhConfig } from "@xihan-ui/vue";

// 应用根组件的 setup 中
provideXhConfig({
  locale: "zh-CN",
  translations: {
    breadcrumb: { root: "面包屑" },
    pagination: { root: "分页", prevTrigger: "上一页", nextTrigger: "下一页" },
    dialog: { close: "关闭" },
    toast: { close: "关闭" },
  },
});
```

取值优先级从高到低：实例 props → 全局注入 → 组件内建默认（文案为英文，`locale` 再向宿主浏览器读取一次）。`translations` 按键合并：全局提供整包，个别实例只覆盖需要修改的键。

## 运行时切语言

传入 ref 或 getter，切换时使用这些文案的组件随之重渲染：

```ts
import { provideXhConfig } from "@xihan-ui/vue";
import { computed, ref } from "vue";
import { enUS, zhCN } from "./locales";

const lang = ref<"zh" | "en">("zh");
provideXhConfig(computed(() => (lang.value === "zh" ? zhCN : enUS)));
```

语言包是一个普通对象（`XhConfig` 类型），按组件名收纳各自的 `Translations`；每个组件页的 Props 表列有它的文案键。

## 接受 locale 的组件

`locale` 一律接受 BCP 47 语言标记（如 `zh-CN`、`en-US`），供以下组件使用：

| 组件 | `locale` 决定的内容 | 未提供时 |
| --- | --- | --- |
| `calendar` / `date-picker` | 月份名、星期名、周首日、标题中年月的顺序 | 宿主语言，再退 `en-US` |
| `date-field` | 年月日三段的顺序、上午 / 下午的写法 | 宿主语言，再退 `en-US` |
| `heatmap` | 月份名、星期名 | 宿主语言，再退 `en-US` |
| `time` | 用词（`zh` 开头使用中文，其余英文）与默认格式串 | 宿主语言，再退 `en-US` |
| `time-picker` / `time-field` | 上午 / 下午的写法、推断小时制 | 不读取宿主：小时制固定 24，上午 / 下午写 AM/PM |

实例上显式提供 `locale` 的不受全局影响。

## 作用域与边界

- 注入走 Vue 的 provide/inject：在应用根 provide 即全应用默认，也可以只在某个子树 provide 以局部切换语言。
- `createToastService` / `createDialogService` 自带宿主应用，无法接入组件树中的注入。它们的按钮文案使用各自创建时的选项（`okText` 默认 `OK`、`cancelText` 默认 `Cancel`、`translations`），需要整个服务与应用同语言时通过 `config` 传入：

  ```ts
  const dialog = createDialogService({
    config: { locale: "zh-CN", translations: { dialog: { close: "关闭" } } },
    okText: "确定",
    cancelText: "取消",
  });
  ```

  `config` 是一份普通的 `XhConfig`，服务会在自己的子树中 `provideXhConfig` 一次；未提供时使用内建默认。
- 不注入时组件按原路径运行，没有额外开销。
- 自定义元素无法接入 Vue 的注入，使用它自己的全局出口，见下文。

::: tip 文档站的示例为什么逐实例传入
每条示例都是孤立片段，没有应用根可以注入，因此一律写成 `:translations="{ … }"`。
真实应用按上文全局配置一次即可，实例上只保留需要单独覆盖的键。
:::

## 自定义元素侧

自定义元素无法获取 Vue 的 provide/inject，文案是对象，只能通过 property 而不能通过 attribute 设置，因此逐实例设置是原有的唯一路径。`setXhConfig` 提供一处全局出口：

```ts
import { setXhConfig } from "@xihan-ui/web-components";
import { defineXhElements } from "@xihan-ui/web-components/define";

defineXhElements();
setXhConfig({
  locale: "zh-CN",
  translations: {
    dialog: { close: "关闭" },
    pagination: { root: "分页", prevTrigger: "上一页", nextTrigger: "下一页" },
  },
});
```

取值优先级与 Vue 侧一致：元素上的 property → `setXhConfig` 的全局值 → 组件内建默认（文案为英文，`locale` 再向宿主浏览器读取一次），`translations` 逐键合并。切换语言时再次调用，已挂载的元素随之重渲染：

```ts
setXhConfig({ locale: "en-US", translations: enUS });
```

两处差别：

- `setXhConfig` 是整份替换，不做深合并；修改一处需要传入整份配置。Vue 侧语义相同。
- 它是模块级的，整个文档一份，没有 Vue 那种只在某棵子树切换语言的能力。需要分区时，把该部分渲染为 Vue 组件，或逐实例设置 `.translations`。

---

来源：https://ui.docs.xihanfun.com/guide/icons

# 图标集

`@xihan-ui/icons` 是一套结构化数据，不是 SVG 字符串，也不是字体。每枚图标是一条 `IconRecord`：名字、`viewBox`、若干节点，节点带标签与属性。

```ts
import { ArrowDownIcon } from "@xihan-ui/icons";

// { name: 'arrow-down', viewBox: '0 0 24 24', nodes: [{ tag: 'path', attrs: { d: '…' } }] }
```

渲染端逐节点创建元素，运行期不经任何解析，因此不存在把外来字符串写入 `innerHTML` 的路径。这份数据框架无关，Vue、React、Web Components 适配器与不使用框架的场景消费同一份数据。

首方集覆盖中后台界面的常用语义，逐枚手绘、统一 24 网格与 2 粗描边：方向与布局、文件与文档、文本编辑、媒体与设备、通信、状态与安全、数据与图表、系统与账户、商业场景。

它不打算成为穷尽的图标库。图标审美与授权属于使用者：使用 Lucide、Tabler、Bootstrap Icons 或自绘的图标集，把 SVG 目录交给下文的转换器即可。集合大小不影响产物：打包器逐枚判定未被引用并摇掉，只引用一枚就只承担一枚的体积。

## 组件自带的兜底字形

作者未向部件写入内容时，皮肤会绘制一个默认字形：多选框的勾、下拉框的箭头、清空按钮的叉、表头的排序方向、树的展开把手、数字框的加减号。这些图形不是字符，而是图标包中对应的 SVG：令牌 `--xh-glyph-mark-*` 的取值是 `url("data:image/svg+xml,…")`，皮肤把它用作 `mask-image`、以 `currentColor` 着色，因此随语气、悬停、禁用自动变色，与使用 `<XhIcon>` 绘制的结果一致。

| 令牌 | 取自 | 用途 |
| --- | --- | --- |
| `--xh-glyph-mark-check` | `check` | 各列表族的条目勾、多选框、树、穿梭框、表格勾选把手、步骤条已完成 |
| `--xh-glyph-mark-minus` | `minus` | 半选横杠；number-field 的减号 |
| `--xh-glyph-mark-plus` | `plus` | number-field 的加号、悬浮按钮 |
| `--xh-glyph-mark-close` | `x` | 清空钮、关闭钮、标签与文件条目的删除钮 |
| `--xh-glyph-mark-chevron-down` · `-up` · `-left` · `-right` | `chevron-*` | 展开箭头、树与侧栏的分支把手、轮播与穿梭框的翻页、回到顶部 |
| `--xh-glyph-mark-sort` · `-sort-asc` · `-sort-desc` | `arrow-up-down` / `arrow-up` / `arrow-down` | table 的排序方向 |
| `--xh-glyph-mark-info` · `-warning` | `info` / `triangle-alert` | 命令式 dialog / notification 的类型徽记，以及 toast 的状态字形 |
| `--xh-glyph-mark-zoom-in` · `-zoom-out` · `-rotate-left` · `-rotate-right` · `-flip-horizontal` · `-flip-vertical` | 同名图标 | image-viewer 的工具条 |
| `--xh-glyph-mark-required` | `'*'` | field · fieldset 的必填星号（这是文字，不是图标） |

### 替换方式

通道一：修改令牌。全局修改写在 `:root` 上，只改一块区域就写在该区域的容器上：它是普通的自定义属性，随 DOM 继承。取值是任意一张 SVG 的 `url()`，着色同样使用 `currentColor`：

```css
:root {
  --xh-glyph-mark-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E…%3C/svg%3E");
}

/* 只有这张表里的排序箭头换成实心三角 */
.report-table {
  --xh-glyph-mark-sort-asc: url("/icons/caret-up.svg");
  --xh-glyph-mark-sort-desc: url("/icons/caret-down.svg");
}
```

遮罩只读取图形的不透明度，颜色由部件的 `color` 决定，因此 SVG 中的 `fill` / `stroke` 取值不影响结果。

通道二：自行放置节点。向该部件写入内容后，皮肤规则不再命中：它带有 `:empty` 守卫：

```vue
<XhSelectItemIndicator>
  <XhIcon :icon="CheckIcon" />
</XhSelectItemIndicator>
```

```html
<span data-xh-part="item-indicator"><svg data-xh-part="root">…</svg></span>
```

`:empty` 对空白文本同样敏感：HTML 中要写成 `<span data-xh-part="item-indicator"></span>`，标签之间不留换行。

有几处部件本身已有其他内容，`:empty` 恒不命中，只能使用通道一：checkbox-group 与 transfer 的全选格、field 与 fieldset 的必填星号。

json-viewer 键名后的冒号不在这一族中：它是 JSON 数据格式的语法字符，不是视觉标记。Kbd 的 `⌘` `⇧` 键名由 JS 渲染为文本，使用它自己的 `translations`。


## 把任意 SVG 目录转成图标集

包里带一个 `xihan-icons` 命令：

```bash
npx xihan-icons ./node_modules/lucide-static/icons --out src/icons.mjs --dts
```

产出一份运行期模块，每枚图标一个顶层 `export const`，可摇树；`--dts` 一并产出类型声明。之后照常使用：

```ts
import { ArrowDownIcon } from "./icons.mjs";
```

命令行参数：

| 参数 | 说明 |
| --- | --- |
| `<svg 目录>` | 必填。扫描该目录下的 `*.svg`，不递归 |
| `--out <文件>` | 产物路径，默认 `icons.mjs` |
| `--dts` | 一并产出同名 `.d.mts` |
| `--quiet` | 跳过的图标只列前 5 条 |

需要接入自己的构建脚本时使用 `@xihan-ui/icons/codegen`：

```js
import { ingestIconDir, renderModule } from "@xihan-ui/icons/codegen";

const { icons, skipped } = await ingestIconDir("./svg");
await writeFile("icons.mjs", renderModule(icons));
```

`ingestIconDir` 不中断：无法转换的图标收进 `skipped`（带文件名与原因）后继续，由调用方决定报告还是视为失败。

## 转换时丢弃的内容

图标名由文件名归一而来：小写、连字符分段。数字开头的（Bootstrap Icons 的 `0-circle`）会派生出不合法的导出标识符，前缀一个 `n` 归为 `n0-circle` → `N0CircleIcon`。重名的后来者被跳过而不是覆盖。

非 24 网格的源会就地归一到 `0 0 24 24`：坐标、描边宽度、半径一并按比例换算，不是只修改 `viewBox`。

外部图标集普遍带有与图标本身无关的内容，这些会被丢弃并逐条记入 `notes`：

- 根上的 `width` / `height` / `xmlns` / `version` / `xml:space` 等
- 任何节点上的 `class`（样式归皮肤）、`style`、`onclick` 等内联事件属性
- 白名单外的属性、取值不合规的属性
- `<title>` / `<desc>` / 许可注释

内联事件属性走同一条丢弃路径，源中的任何脚本都不会进入产物。

丢弃它们正是预期行为：尺寸由使用处决定，颜色使用 `currentColor`，无障碍名字由 `XhIcon` 的 `label` 提供。

## 无法转换时明确报错

属性层可以宽松，标签层不可以。宽松模式下以下几类仍然报错：

- `<use>`：外观依赖记录无法表达的外部引用
- `<text>` / `<tspan>` / 任何文本内容：记录没有文本变体，字体缺席时无法绘制
- `<style>` / `<image>` / `<script>`：使图标外观依赖记录之外的内容

接收这些会产出一枚绘制错误的图标，而绘制错误比缺少一枚更难发现，因此报错。CLI 逐条打印跳过的图标：静默缺少图标时使用者只会以为名字写错。

另一类会报错：源不是 24 网格且节点带 `transform`。正确归一需要先把变换乘入坐标，管线不做这件事，直接报告。

按三套真实图标集实测：

| 图标集 | 转成 | 跳过 |
| --- | --- | --- |
| Lucide 1.31.0 | 2025 / 2025 | 0 |
| Tabler 3.46.0（outline） | 5130 / 5130 | 0 |
| Bootstrap Icons 1.13.1 | 2077 / 2078 | 1（16 网格 + `transform`） |

## 首方集使用严格模式

本仓库 `src/svg` 下的图标由 `buildIconSet` 构建，任何属性不合规都直接失败：首方集的每一枚都由库自行绘制，不设宽松接收的余地。这条路径与上文的摄取管线共用同一套白名单与变换，只是不开启宽松开关。

---

来源：https://ui.docs.xihanfun.com/guide/machine

# 状态机运行时

`@xihan-ui/core` 中的状态机是一台轻量的有限状态机运行时：零第三方运行时依赖。组件的全部行为写在这里，因此它必须与框架无关：响应式由宿主框架经 `ReactiveRuntime` 接口注入。

## 状态机的形态

```ts
import type { AccordionSchema } from "./accordion.types";
import { setup } from "@xihan-ui/core";

const { createMachine } = setup<AccordionSchema>();

export const accordionMachine = createMachine({
  name: "accordion",
  context: ({ prop, cell }) => ({
    value: cell<string[]>(() => ({
      value: prop("value"),
      defaultValue: prop("defaultValue") ?? [],
      onChange: value => prop("onValueChange")?.({ value }),
    })),
  }),
  initialState: () => "idle",
  states: {
    idle: {
      on: {
        "ITEM.TOGGLE": { actions: ["toggleItem"] },
        "VALUE.SET": { actions: ["setValue"] },
      },
    },
  },
  implementations: {
    actions: {
      toggleItem: ({ context, prop, event }) => { /* … */ },
      setValue: ({ context, prop, event }) => { /* … */ },
    },
  },
});
```

`setup<Schema>()` 是类型锚：一次绑定 schema，之后 `prop()` / `context.get()` / 事件类型全部自动推断，不需要在每处重复写泛型。它同时给出 `guards`，即 `and` / `or` / `not` 三个组合子。

## 配置的各个面

| 字段 | 作用 |
| --- | --- |
| `context` | 状态机自身的状态。用 `cell()` 声明的格子自带受控语义 |
| `refs` | 不参与响应式的引用（DOM 取值器、宿主注入的配置、层注册器等） |
| `computed` | 由 context / props 派生的只读值 |
| `props` | 宿主传入的属性，经 `prop('x')` 读取 |
| `initialState` | 初始状态，可读 props 决定 |
| `states` | 状态节点：`on` 转移表、`entry` / `exit` 动作、`effects` 副作用、`tags` |
| `watch` | 追踪外部值变化并触发动作，受控回写走这里 |
| `implementations` | `actions` / `guards` / `effects` 的具名实现 |

具名实现是硬约束。`states` 中只能出现动作名、守卫名、副作用名的字符串；裸内联函数会在 `createMachine` 时直接抛出 `MachineError`（守卫只放行 `and` / `or` / `not` 组合子的产物）。`createMachine` 在开发与生产模式都会检查静态列表并递归审计组合 guard：转移表中引用了 `implementations` 中不存在的名字同样报错。实现必须是对应分组自身的数据属性函数；原型链成员、访问器和非函数值都不构成实现，审计也不会为了检查而调用 getter。这条约束的收益是状态图成为可静态分析的数据，测试可以计算转移覆盖率，而不是一组闭包。

函数形态的 `entry`、`exit`、`effects` 以及实现内部调用的 `action()`、`guard()` 只能在运行时得知名字。运行时会先解析整份 action 或 effect 列表，再通过自有数据属性一次取得全部函数快照，之后才执行 action 或初始化 effect；任一名字缺失都会用 `MISSING_ACTION`、`MISSING_GUARD` 或 `MISSING_EFFECT` 上报、停止服务并抛出原错误，开发与生产行为一致。缺失 guard 不会按 `false` 继续选择分支，缺失 action 不会被跳过，列表后部缺失 effect 也不会让前部 effect 先取得资源。缺项发生在 effect 初始化中且 cleanup 也失败时，抛出的 `AggregateError` 同时保留缺项错误与全部回滚异常。

`inspect` 只观察这些运行事件，不参与错误决策；观察器自身抛错会被隔离，不能遮蔽 `MISSING_*`、阻止停机或替换诊断中的原错误对象。

## 受控与非受控：`cell`

值类组件的取值语义统一在 `cell` 一处，不由各组件自行判断：

```ts
value: cell<string[]>(() => ({
  value: prop("value"), // 传了就是受控
  defaultValue: prop("defaultValue") ?? [], // 只传它就是非受控
  onChange: value => prop("onValueChange")?.({ value }),
}));
```

规则：

- `value !== undefined` → 受控。`context.set()` 不修改内部值，只调用 `onChange` 通知宿主；实际值始终从 `prop('value')` 读取。
- `value === undefined` → 非受控。内部持有值，变更时同样调用 `onChange`。
- 从受控变回 `undefined` 表示转为非受控，不会强制复位。

浮层类组件的开关不经过 `cell`，而是采用意图与回写两段式，因为状态本身就是状态机的状态节点：

<!-- eslint-skip -->

```ts
'OPEN': [
  { guard: 'isOpenControlled', actions: ['invokeOnOpen'] }, // 受控：只发意图
  { target: 'open', actions: ['invokeOnOpen'] }, // 非受控：直接转移
],
'CONTROLLED.OPEN': { target: 'open' }, // 宿主写回 open 后由 watch 派发
```

`watch` 追踪 `prop('open')`，宿主写回新值时才派发 `CONTROLLED.OPEN` / `CONTROLLED.CLOSE`。受控组件因此不会自行变更状态。

## 转移表的匹配顺序

一个事件可以配置一组转移，按书写顺序取第一条守卫通过的：

<!-- eslint-skip -->

```ts
'OPEN': [
  { guard: 'isOpenControlled', actions: ['invokeOnOpen'] },
  { target: 'open', actions: ['invokeOnOpen'] }, // 无 guard = 兜底
]
```

没有任何一条匹配时事件被丢弃，不报错。

## 副作用

`effects` 声明在状态节点上，进入该状态时启动、离开时清理。对话框的遮罩装配就是一个 effect：

<!-- eslint-skip -->

```ts
states: {
  open: {
    effects: ['trackOverlay'], // 装配消隐层 → 焦点域 → 滚动锁 → 背景失活
  },
}
```

副作用可以获取 `refs`（宿主注入的 DOM 取值器与运行时配置）、`send`、`flush`，返回一个清理函数。`setTimeoutEffect` / `setIntervalEffect` 是两个现成的定时器 effect 工厂。

同一状态节点的一批 effect 在执行前会先建立在途路径登记，整批成功后才保留为活动批次。如果后一项初始化抛错或挂载期间丢失路径所有权，在途登记会被摘除，本批已取得的 cleanup 会立即按资源取得逆序全部回滚；某项 cleanup 抛错不会阻断其余回滚。无回滚异常时保留原初初始化异常；回滚也失败时通过 `AggregateError` 同时携带初始化异常和全部回滚异常。最外层的 `MachineError` 会把这份原始异常链保留在 `cause` 中。

事务只能回滚 effect 已经返回给服务的 cleanup。单个 effect 如果在返回前已取得多项资源，它自身必须在内部初始化抛错时逆序回滚；服务无法释放从未交出的句柄。

成功挂载的 cleanup 同样按资源取得逆序执行。每条状态路径只能存在一份活动 effect 登记，返回 `void` 的 effect 也会占用该路径；重复挂载会抛出 `DUPLICATE_EFFECT_PATH` 不变式错误，而不是把两批 cleanup 隐式合并。退出状态时，服务会先从清理表摘除该路径，再调用 cleanup，因此 cleanup 抛错也不会在崩溃停机时被重复执行。

停机一开始就进入 `Stopped`、关闭事件入口并清空待处理事件与 tracker，然后继续清完所有 effect 并运行 machine exit。清理、exit 与原始崩溃同时抛错时，抛出和诊断通道都收到同一份完整聚合异常；正常停机只有 cleanup 或 exit 失败时也遵守同一规则。cleanup 或 exit 里同步调用 `send` 不会再推进机器；服务停止后宿主重复触发 mount 也不会把它复活。

effect 执行前路径就已处于“挂载中”。setup 里同步重入宿主 mount 会在服务边界命中 `DUPLICATE_SERVICE_MOUNT`，并按崩溃停机释放当前全部资源；同一状态路径在机器内部非法重复挂载时才报告 `DUPLICATE_EFFECT_PATH`。setup 里同步停机后，该 effect 迟到返回的 cleanup 会当场按逆序释放，当次 choreography 立即终止，不会再运行后续 entry 或根 effect；这次紧急清理的异常仍会暴露。

首次 mount 的完整 choreography 是一个不可重入的初始化边界，顺序固定为 state effect → machine entry → state entry → 根 effect：根 effect 是整个生命周期的资源（层、焦点域、观察器），建起那一刻读到的是进入完毕的初态，初态 entry 挑好的锚点（高亮项、焦点格）对它可见。这四步全部提交前，其中的 `send` 只会按调用顺序进入 FIFO；提交后先处理挂载前累积的 tracker，再统一消费事件队列。初始化失败或停机会清空该队列，不会用半提交的状态继续转移。初始化来源和根 effect 使用与用户状态路径不相交的内部标识，因此 `__init__` 是合法的用户状态名，也可以与根 effect 同时使用。

状态机允许 JavaScript 抛出任意值。`null`、`undefined` 和其他非 `Error` 值会使用安全格式化的崩溃信息，并在 `MachineError.cause` 中保留原值；即使单个 cleanup 或 exit 抛出 `undefined`，也会被记录为真实异常并向外抛出。抛出值自身无法转为文本时，诊断使用稳定的“无法格式化的异常”文案。

## 服务与响应式运行时

状态机配置是纯数据，运行需要一个服务：

```ts
import { createService } from "@xihan-ui/core";

const service = createService(accordionMachine, {
  props: () => ({ multiple: true, defaultValue: ["a"] }),
  runtime, // ReactiveRuntime，由宿主提供
  scope, // DOM 环境抽象
});
```

`ReactiveRuntime` 是状态机与框架之间唯一的接口，需要实现的成员不多：`cell`（受控格子）、`track`（依赖追踪）、`flush`（微任务冲刷）、`onMount` / `onCleanup`。

| 运行时 | 来源 | 用途 |
| --- | --- | --- |
| Vue | `@xihan-ui/vue` 内部的 `createVueRuntime()` | Vue 适配器 |
| vanilla | `@xihan-ui/core/vanilla` 的 `createVanillaRuntime()` | Web Components 适配器、测试、benchmark |

vanilla 运行时是一个同步 dirty 循环的微 signal 实现，也是这套契约的参考实现：接入新框架时按它实现一份即可。

## 服务的对外接口

`connect` 获得的 `service` 包含以下成员：

| 成员 | 用途 |
| --- | --- |
| `state` | `get()` / `previous()` / `matches(...)` / `hasTag()` |
| `context` | 读写 context 格子 |
| `computed` | 读派生值 |
| `prop` | 读 props |
| `refs` | 读写非响应式引用 |
| `event` | 读当前 / 上一个事件 |
| `send` | 派发事件 |
| `scope` | DOM 环境：`getDoc()` / `getWin()` / `partId()` / `getActiveElement()` 等 |
| `machine` / `getStatus()` | 状态机配置本身与生命周期状态 |

没有直接修改状态的入口。状态只能由事件驱动转移，这条限制使当前状态始终可以由事件序列复现：跨适配器一致性测试正是依靠这一点比对各适配器。

调试时可以给 `createService` 传入 `inspect`，逐条获取转移、动作、副作用与事件：

```ts
createService(dialogMachine, {
  props: () => ({}),
  runtime,
  inspect: e => console.log(e.type, e.state, e.detail),
});
```

## 相关

- [connect 与属性产出](./connect)：从服务到 DOM 属性
- [行为原语](./behavior)：effects 中调用的原语

- [测试与质量门禁](./testing)：转移覆盖率与一致性判据

---

来源：https://ui.docs.xihanfun.com/guide/metadata

# 框架元数据

框架名称、版本、版权与运行时信息的单一事实源在 `@xihan-ui/core` 的 `XIHAN_UI_METADATA` 中，与 [XiHan.Framework](https://github.com/XiHanFun/XiHan.Framework) 的 `XiHanMetadata` 同构：常量集中维护在一份文件中，版本从 package.json 派生，运行时信息由适配器登记。

## 元数据对象

```ts
import { XIHAN_UI_METADATA, XIHAN_UI_VERSION } from "@xihan-ui/core/metadata";

XIHAN_UI_METADATA.name; // 'XiHan.UI'
XIHAN_UI_METADATA.displayName; // '曦寒视图组件'
XIHAN_UI_METADATA.version; // 与 package.json 同源，即整套库的版本
XIHAN_UI_METADATA.majorVersion; // 主版本号（数字）
XIHAN_UI_METADATA.minorVersion; // 次版本号
XIHAN_UI_METADATA.patchVersion; // 修订版本号
XIHAN_UI_METADATA.prerelease; // 预发布标识（如 'alpha.2'），正式版为 null
XIHAN_UI_METADATA.copyright; // 版权信息
XIHAN_UI_METADATA.author; // 作者
XIHAN_UI_METADATA.organization; // 组织与网址
XIHAN_UI_METADATA.repositoryUrl; // 仓库地址
XIHAN_UI_METADATA.documentationUrl; // 文档地址
XIHAN_UI_METADATA.license; // 许可证与地址
XIHAN_UI_METADATA.keywords; // 关键词
XIHAN_UI_METADATA.supportedPlatforms; // 支持的浏览器引擎（Chrome / Edge / Firefox / Safari）
XIHAN_UI_METADATA.adapters; // 渲染适配器（react / vue / web-components）
```

对象与内部数组一律 `Object.freeze`：这是集中维护点，消费方无法修改。

标志与寄语不在这个对象中，是两个独立导出：

```ts
import { XIHAN_UI_LOGO, XIHAN_UI_SEND_WORD } from "@xihan-ui/core/metadata";
```

对象被整体引用时打包器无法摇掉其中的字段，并入这两项会随浏览器产物发送给每个访问者。单独导出后无人引用即整体消失：它们面向开发者，见下文的终端横幅。

版本不在元数据中手写：`version` / `majorVersion` / `minorVersion` / `patchVersion` / `prerelease` 全部由 `XIHAN_UI_VERSION` 从 core 的 package.json 解析而来。修改版本只改 package.json 一处，元数据自动同步。

## 运行时信息

```ts
import { getRuntimeHost, getRuntimeInfo } from "@xihan-ui/core/metadata";

getRuntimeInfo();
// { mode: 'development' | 'production', ssr: boolean, host: { name, version } | null }
```

- `mode` 取 `import.meta.env.DEV`；`ssr` 表示当前是否运行在无 DOM 的环境（服务端渲染 / 纯 Node）。
- `host` 是适配器自行登记的运行时宿主：Vue 适配器在第一个组件创建状态机时登记 `{ name: 'vue', version }`，Web Components 适配器在 `defineXhElements()` 中登记。元数据据此报告组件运行的适配器与版本：这是 Framework 侧 EntryAssembly 概念在浏览器语境下的对应物。

## 输出

与 Framework 的 `GetSummary()` / `GetDetails()` 同款：

```ts
import { getMetadataDetails, getMetadataSummary, printMetadataSummary } from "@xihan-ui/core/metadata";

const summary = getMetadataSummary();
// XiHan.UI 曦寒视图 v<当前版本>
// 快速、轻量、高效、用心的框架无关跨端组件库。
//
// 宿主:vue v<当前版本>

const details = getMetadataDetails(); // 摘要之外再补作者 / 组织 / 仓库 / 文档 / 许可证 / 环境

// dev 中输出到控制台，生产静默
printMetadataSummary();
printMetadataDetails();
```

### 启动横幅：输出到开发者的终端

对齐 [XiHan.Framework](https://github.com/XiHanFun/XiHan.Framework) 的 `XiHanApplicationBase`：应用构造时自动打印 Logo 与摘要。UI 库的等价位置是开发服务器启动的终端，由 `@xihan-ui/core/vite` 子入口负责：

```ts
// vite.config.ts
import { xihanUiBanner } from "@xihan-ui/core/vite";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [xihanUiBanner()] });
```

```text
   _  __ ______  _____    _   __        ← 标志逐字符横向彩虹
  | |/ //  _/ / / /   |  / | / /
  |   / / // /_/ / /| | /  |/ /
 /   |_/ // __  / ___ |/ /|  /
/_/|_/___/_/ /_/_/  |_/_/ |_/

XiHan.UI 曦寒视图 v<当前版本>
快速、轻量、高效、用心的框架无关跨端组件库。
碧落降恩承淑颜，共挚崎缘挽曦寒。
迁般故事终成忆，谨此葳蕤换思短。
              —— 致她
```

同一入口另导出两个与 Vite 无关的函数，任何 Node 脚本都可调用：`getXiHanUiBanner()` 只返回文本，`printXiHanUiBanner()` 输出到 stdout。这一份不从 `index` 再导出，浏览器产物中不包含它。

是否上色的判据与 `picocolors` 逐条对齐：Vite 自身的输出即用它上色，遵循同一判据横幅才与周围输出一致；`NO_COLOR` 与 `--no-color` 一票否决。横幅排在 Vite 打印本地地址之后（打印该段时会清屏），使用 `server.config.logger`，因此受 `--silent` 与 `logLevel` 控制。

### 浏览器控制台：默认不输出

适配器启动时也可以向浏览器控制台输出一次摘要，但默认关闭：控制台是网站访问者也可见的位置，横幅面向开发者。需要输出时显式开启，开关只影响之后的启动，手动 `print` 不受影响：

```ts
import { setMetadataAutoPrint } from "@xihan-ui/core/metadata";

setMetadataAutoPrint(true);
```

开启后 Vue 适配器在第一个组件创建状态机时、Web Components 适配器在 `defineXhElements()` 时各输出一次，整个页面只输出一次，生产构建静默。输出的只有摘要，标志与寄语属于终端横幅。


## 相关

- [版本与兼容性政策](./versioning)：同版发布与版本承诺
- [安装与接入](../installation)：三个适配器的接入方式

---

来源：https://ui.docs.xihanfun.com/guide/motion

# 动效原语

`@xihan-ui/motion` 是动效的基础层：缓动曲线与时长常量、不持有计时器的纯补间、逐帧循环、减弱动效偏好，以及解析解弹簧与 Web Animations 的薄封装。零第三方依赖，`import` 无副作用，SSR 安全。

安装任意一个适配器即自动获得它：`headless` 的数字动画与倒计时、`core` 的缓动表都从这里取值。需要自行编写动画时，它也可以单独安装。

## 缓动

CSS 侧的字符串与 JS 侧的采样函数在这里是同一份来源；取值的真源是令牌层（`@xihan-ui/tokens` 的原语 `ease.*`、`duration.*` 与语义层 `--xh-motion-*`）。门禁 `check-motion-source` 双向比对：令牌里的每条曲线与时长在这里都有同值常量，这里多出的名字须登记理由。

```ts
import { cubicBezier, easing, resolveEasing } from "@xihan-ui/motion";

easing.easeOut; // 'cubic-bezier(0, 0, 0.2, 1)'

// 名字、CSS 缓动函数、函数三种写法统一成函数
resolveEasing("easeOut")(0.5); // 0.84…
resolveEasing("cubic-bezier(0.4, 0, 0.2, 1)")(0.5);
resolveEasing("steps(4)")(0.5); // 0.5
resolveEasing(t => t * t)(0.5); // 0.25
```

十条命名缓动：与令牌原语同值的 `standard` `easeIn` `easeOut` `outStrong` `outFluid` `easeInOut` `outBack` `sineInOut` `emphasized`（表现性进场，语义令牌 `--xh-motion-ease-emphasis`，`@xihan-ui/animations` 的预设使用），以及 CSS 关键字 `linear`。

三档时长（毫秒）：`durations.fast` 120、`durations.normal` 200、`durations.slow` 320。`animate()` 默认取 `durations.normal`，`@xihan-ui/animations` 的配方默认取 `motionDurations.slide`（320ms）。语义层在此之上定义统一点击触感：按下走 `--xh-motion-duration-press`（120ms）与 `--xh-motion-ease-press`，释放走 `--xh-motion-duration-release`（200ms）与 `--xh-motion-ease-release`，见[设计令牌与主题](/guide/theme#点击触感)。

字符串先查命名缓动，查不到再按 CSS 缓动函数的语法解释：`linear`、`ease` / `ease-in` / `ease-out` / `ease-in-out`、`step-start` / `step-end`、`cubic-bezier()`、`steps()`、`linear()`，取值与浏览器一致，所以 `readMotion` 读到样式里改写成任何合法缓动都能换成函数。CSS 关键字 `ease-out` 与命名缓动 `easeOut` 是两条曲线。认不出的写法抛 `TypeError`，消息里列出可用写法：写法可能来自 DOM 特性或后端配置，拼错的名字若悄悄按匀速播放，比报错更难察觉。`cubicBezier` 用牛顿迭代反解参数，导数过小时退回二分。

## 从元素读取令牌

JS 动画与同一元素上的 CSS 过渡保持同步时，不要写死毫秒，从元素读取语义令牌：

```ts
import { readMotion, tweenValueAt } from "@xihan-ui/motion";

const motion = readMotion(el);
const spec = {
  from: 0,
  to: 1,
  duration: motion.duration("move"), // --xh-motion-duration-move 的实际取值（毫秒）
  easing: motion.easing("continuous"), // --xh-motion-ease-continuous 的采样函数
};
```

计算样式里已经算进作者对组件槽的覆盖、容器上的 `data-motion` 与系统的减弱动效偏好，减弱动效下几何类时长读到的就是 1ms。读不到时（服务端、未加载样式的测试环境）取与令牌同值的常量 `motionDurations` / `motionEasings`，按元素判断为减弱时取减弱档的时长。每次调用读一次计算样式，在动画开始前调用即可。

`readMotion` 只读时长与缓动。语义位移与错开步长另有同值常量：`motionDistances`（`sm` / `md` / `lg`，4 / 8 / 16px，减弱动效下令牌归零）与 `motionStaggerStep`（40ms）。

`toLinearEasing` 把任意缓动函数采样为 CSS `linear()` 串，用于把只有 JS 能计算的曲线交回 CSS：

```ts
import { toLinearEasing } from "@xihan-ui/motion";

toLinearEasing(t => t ** 2, 5); // 'linear(0, 0.0625, 0.25, 0.5625, 1)'
```

## 弹簧

弹簧使用解析解，不是逐帧数值积分。给定质量、刚度、阻尼，任意时刻的位移可以 O(1) 直接计算，因此它可以被任意采样、可以离线烘焙为 `linear()` 串交给 CSS，不需要每帧回主线程写样式。

```vue
<script setup lang="ts">
import { animate, createSpring, springToLinearEasing } from "@xihan-ui/motion";
import { computed, onBeforeUnmount, ref, useTemplateRef } from "vue";

const duration = ref(0.5);
const bounce = ref(0.3);

const solver = computed(() => createSpring({ duration: duration.value, bounce: bounce.value }));

// 曲线画在 0..1 的归一化坐标里，y 轴翻过来让 1 在上方
const path = computed(() => {
  const spring = solver.value;
  const seconds = spring.durationMs / 1000;
  const points: string[] = [];
  for (let i = 0; i <= 80; i++) {
    const t = i / 80;
    const value = spring(t * seconds);
    points.push(`${(t * 280).toFixed(1)},${(110 - value * 80).toFixed(1)}`);
  }
  return `M ${points.join(" L ")}`;
});

const box = useTemplateRef<HTMLElement>("box");
let handle: { cancel: () => void } | null = null;

function play() {
  const el = box.value;
  if (!el)
    return;
  handle?.cancel();
  const spring = solver.value;
  handle = animate(
    el,
    [{ translate: "0 0" }, { translate: "180px 0" }],
    { duration: spring.durationMs, easing: springToLinearEasing(spring, 48), fill: "forwards" },
  );
}

onBeforeUnmount(() => handle?.cancel());
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: 100%">
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 20px">
      <label style="display: flex; align-items: center; gap: 8px">
        时长 {{ duration.toFixed(2) }}s
        <input v-model.number="duration" type="range" min="0.15" max="1.2" step="0.05">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        弹性 {{ bounce.toFixed(2) }}
        <input v-model.number="bounce" type="range" min="-0.8" max="0.8" step="0.05">
      </label>
    </div>

    <p style="margin: 0; font-size: 13px; opacity: 0.7">
      阻尼比 {{ solver.dampingRatio.toFixed(3) }} · 沉降 {{ Math.round(solver.durationMs) }}ms · 过冲
      {{ (solver.overshoot * 100).toFixed(1) }}%
    </p>

    <svg viewBox="0 0 280 120" style="width: 100%; height: 120px">
      <line x1="0" y1="30" x2="280" y2="30" stroke="var(--vp-c-divider)" stroke-dasharray="4 4" />
      <line x1="0" y1="110" x2="280" y2="110" stroke="var(--vp-c-divider)" />
      <path :d="path" fill="none" stroke="var(--vp-c-brand-1)" stroke-width="2" />
    </svg>

    <div style="display: flex; align-items: center; gap: 12px">
      <button
        type="button"
        style="
          padding: 6px 14px;
          border: 1px solid var(--vp-c-divider);
          border-radius: 8px;
          background: transparent;
          color: inherit;
          cursor: pointer;
        "
        @click="play"
      >
        播一次
      </button>
      <div
        style="
          position: relative;
          flex: 1;
          height: 40px;
          border: 1px dashed var(--vp-c-divider);
          border-radius: 8px;
        "
      >
        <div
          ref="box"
          style="
            position: absolute;
            top: 4px;
            left: 4px;
            width: 32px;
            height: 32px;
            border-radius: 8px;
            background: var(--vp-c-brand-1);
          "
        />
      </div>
    </div>
  </div>
</template>
```

两种参数写法。直接给物理参数：

```ts
import { createSpring } from "@xihan-ui/motion";

const spring = createSpring({ stiffness: 380, damping: 30, mass: 1 });
spring(0.1); // 0.1 秒时的归一化位移，0 起 1 止，欠阻尼时可越过 1
spring.durationMs; // 沉降到静止阈值要多久
spring.dampingRatio; // <1 欠阻尼、=1 临界阻尼、>1 过阻尼
spring.overshoot; // 最大过冲量，不过冲为 0
```

感知参数更易调整，只描述时长与弹性：

```ts
createSpring({ duration: 0.4, bounce: 0.3 }); // 弹
createSpring({ duration: 0.4, bounce: 0 }); // 临界阻尼，全程单调不过冲
createSpring({ duration: 0.4, bounce: -0.5 }); // 过阻尼，缓慢趋近
```

`bounce` 落在 (−1, 1)：正数减阻尼、负数加阻尼。预设按名字取，取值与令牌 `--xh-motion-spring-<名>-stiffness / -damping` 同源（质量恒为 1）：

| 预设 | 刚度 / 阻尼 | 超调 | 落定 | 用途 |
| --- | --- | ---: | ---: | --- |
| `stiff` | 600 / 42 | 0.5% | 约 195ms | 越界回弹 |
| `smooth` | 300 / 30 | 0.4% | 约 283ms | 手势松手：归位、快甩、面板弹回 |
| `snappy` | 380 / 30 | 2.2% | 约 369ms | 干脆的位移 |
| `gentle` | 170 / 26 | 0 | 约 567ms | 临界阻尼的慢弹簧 |
| `bouncy` | 400 / 18 | 20.4% | 约 581ms | 明显回弹，只供作者使用，核心组件不用 |
| `toggle` | 420 / 26 | 7.5% | — | liquid 档的切换滑块 |
| `lead` / `trail` | 520 / 34、210 / 24 | 2.9%、0.9% | 约 313ms、485ms | liquid 档双沿指示器的前沿与后沿 |
| `merge` | 320 / 24 | 5.8% | — | liquid 档的融合与分离 |

核心组件在 standard 档只用超调不超过 3% 的预设。

沉降时长按阻尼比分三支计算：欠阻尼看包络衰减、临界阻尼求解含 t 的指数方程、过阻尼由较慢的根主导。三支各有断言，并与 dt=0.1ms 的四阶龙格-库塔积分逐点比对。

烘焙给 CSS：

```ts
import { createSpring, springToLinearEasing, supportsLinearEasing } from "@xihan-ui/motion";

const spring = createSpring("bouncy");
if (supportsLinearEasing()) {
  el.style.animationDuration = `${spring.durationMs}ms`;
  el.style.animationTimingFunction = springToLinearEasing(spring, 32);
}
```

### 有状态弹簧

`createSpring` 描述的是一段从 0 到 1 的固定运动。手势需要另外两件事：松手时的速度要接进动画，动画进行中目标还会变。`createSpringValue` 持有当前值、速度与目标，改目标时以当前位移与当前速度为初始条件重新求解，位置与速度都不跳变：

```ts
import { createSpringValue } from "@xihan-ui/motion";

const offset = createSpringValue({
  spring: "smooth",
  value: 0,
  target: sheetElement, // 取它所在的窗口驱动帧循环，并按它的 data-motion 作用域判断减弱动效
  onUpdate: (value) => { sheetElement.style.translate = `0 ${value}px`; },
});

// 拖动中跟手，直接落位
offset.set(dragY);
// 松手：按位移与速度决定关闭还是弹回，速度原样交给弹簧
const result = await offset.to(shouldClose ? sheetHeight : 0, { velocity: releaseVelocity });
// result 是 'rest'（落定）或 'interrupted'（被新的 to()、set()、stop() 打断）
```

- 在目标处带着速度松手也会运动：先被速度带离，再回到目标。
- 每一段运动是时间的闭式解，与帧率无关；帧由 `frameLoop` 驱动。
- 减弱动效下 `to()` 直接落到终态并以 `'rest'` 结算，跟手的 `set()` 不受影响。
- 刚度、阻尼、质量不大于 0，或任何数值不是有限数时立即抛 `TypeError`。

## 减弱动效

系统偏好之上叠加一层应用级 override，最终偏好 = override ?? 系统设置。传入元素时，最近祖先上的 `data-motion`（`reduce` / `default`）再优先一层，与 CSS 令牌的作用域一致。

```ts
import {
  onMotionPreferenceChange,
  resolveMotionPreference,
  setMotionOverride,
} from "@xihan-ui/motion";

resolveMotionPreference(); // 'no-preference' | 'reduce'
resolveMotionPreference(el); // 先看 el 最近祖先的 data-motion，再看 override 与系统设置

// 接到产品自己的“减弱动效”设置项；传 null 交还系统
setMotionOverride("reduce");

const off = onMotionPreferenceChange(preference => console.log(preference));
```

订阅只在最终值变化时回调：override 生效期间系统翻转不会触发，交还系统时才生效。

没有 `matchMedia` 的宿主（SSR、jsdom）一律按不减弱处理：`prefersReducedMotion()` 返回 `false`，`getMotionPreference()` 返回 `'no-preference'`。

JS 侧统一经 `resolveMotionPreference` 读取，并传入动效作用的元素：最近祖先上的 `data-motion` 与 CSS 的作用域一致地生效，其次是应用级 override，最后是系统设置。`@xihan-ui/core` 的贴底与平滑滚动、`headless` 的数字动画与走马灯自动播放、反馈服务的加载弧线与 `backgrounds` 的画面都按此读取，容器上写一次 `data-motion="reduce"`，CSS 与 JS 动效一起停。门禁 `check-reduced-motion-channel` 保证：系统信号 `(prefers-reduced-motion` 只在 motion 包的 `reduced-motion.ts` 与 core 的视觉环境探测 `visual-environment/env.ts` 两处出现，且 `resolveMotionPreference` 处处传参。

### 八轴控制器统一入口

应用根只设置一次视觉环境，解析后的 motion 会同时投影到 DOM，并经显式 sink 驱动 JS 动画与平滑滚动：

```ts
import { setMotionOverride } from "@xihan-ui/motion";
import {
  createMotionOverrideSink,
  createVisualEnvironmentController,
} from "@xihan-ui/tokens/runtime";

const visual = createVisualEnvironmentController({
  root: document.documentElement,
  motionSink: createMotionOverrideSink(setMotionOverride),
  initial: { motion: "system" },
});

visual.setPreference({ motion: "reduce" });
```

`motionSink` 只允许绑定 `documentElement` 根作用域。局部 VisualEnvironment 仍会写 `data-motion="reduce"`，让该子树的 CSS 令牌降级；它不会改全局 JS override，也不会影响兄弟树。需要直接控制全局 JS 且不使用视觉环境时，仍可显式调用 `setMotionOverride`。

## 播放动画

`animate` 是 Web Animations 的薄封装，统一处理三件事：减弱动效降级、宿主缺少 `Element.animate` 时的降级、结束时的结算方式。

```ts
import { animate } from "@xihan-ui/motion";

const handle = animate(el, [{ opacity: "0" }, { opacity: "1" }], {
  duration: 200,
  easing: "easeOut",
});

await handle.finished; // 'finished' | 'cancelled'
handle.cancel();
handle.finish();
```

`finished` 始终 resolve，被打断时也是：它返回结束方式，不抛出异常。调用方不需要为用户中途关闭弹窗编写 catch。

降级时不产生中间帧：按 `fill` 决定是否把末帧样式落到元素上，`finished` 立即以 `'finished'` 结算。降级只影响中间帧是否存在，不影响控制流：回调照常触发，`await` 照常返回。

## 补间与帧

供数值动画使用的纯函数与逐帧胶水。补间本身不感知帧，也不持有计时器，推进由调用方逐帧传入 `elapsed`。

```ts
import { frameLoop, frameNow, isTweenDone, tweenValueAt } from "@xihan-ui/motion";

const spec = { from: 0, to: 1000, duration: 800, easing: "easeOut" } as const;
const start = frameNow(window);

const stop = frameLoop(window, () => {
  const elapsed = frameNow(window) - start;
  render(tweenValueAt(spec, elapsed));
  if (isTweenDone(elapsed, spec.duration))
    stop();
});
```

边界一律收在终点：时长非正时立即满格，`elapsed` 为无效的时钟读数时也按满格，完成时返回终点本身而不是曲线计算的近似值。

## 相关

- [动画层](/guide/animations)：现成的进场与注意动效，构建于这一层之上
- [行为原语](/guide/behavior)：进出场时序、焦点域、滚动观察
- [设计令牌与主题](/guide/theme)：`--xh-motion-*` 时长与缓动令牌

---

来源：https://ui.docs.xihanfun.com/guide/pointer

# 指针原语

`@xihan-ui/pointer` 收纳指针交互中容易出错的公共几何与生命周期。自研实现，零运行时依赖，整包压缩后 2.04 kB，分四层：

| 层 | 内容 |
| --- | --- |
| 指针会话 | 一根指针从按下到抬起的跟手、过滤与收尾 |
| 多指会话与双指几何 | 同时跟住多根指针，以及两指的间距、中点、连线角度与相对起始那一刻的缩放 / 位移 / 转角 |
| 拖放几何 | 排序落点投影、让位位移、激活阈值、边缘自动滚动 |
| 尺寸调整几何 | 八向边推动，带吸附步进、宽高比、上下限与容器夹取 |

后两层是纯函数：不涉及 DOM、不持有状态，输入几何、输出几何，因此可以在无 DOM 的用例中直接断言。

## 存在的原因

跟手交互看似简单，正确实现需要同时满足四点：

- 监听挂在文档上，而不是按下的元素上。挂在元素上时，指针一旦滑出即中断，滑块拖到一半停住、面板中途脱落。
- 必须处理 `pointercancel`。系统随时可能收回指针（移动端被浏览器判定为页面滚动、笔离开数位板、来电打断）。不处理时状态永远停在拖动中，元素持续跟随指针。
- 多指同时按下时，第二根手指不应劫持正在进行的会话。不识别 `pointerId` 时，触屏上双指触碰会使拖拽目标瞬移到另一根手指下。
- 拆卸路径必须完整移除监听。拖动中组件被卸载而监听仍挂在文档上时，后续每次指针移动都在向已销毁的状态机发送事件。

四条中遗漏任何一条，症状都是偶发、只在真机上出现、难以复现。会话一次性正确实现这四条，需要跟手的组件直接调用。

## 用法

```ts
import { createPointerSession, resolveSessionDoc } from "@xihan-ui/pointer";

const session = createPointerSession({
  doc: resolveSessionDoc(trackEl),
  onMove: ({ point }) => {
    // point.clientX / point.clientY
  },
  onEnd: ({ reason }) => {
    // reason: 'pointerup' | 'pointercancel'
  },
});

session.dispose(); // 移除监听，重复调用是安全的
```

日常使用不涉及这一层：需要跟手的组件内部已经接入。

## 选项

| 选项 | 必填 | 说明 |
| --- | --- | --- |
| `doc` | 是 | 会话跟随的文档。传 `null` 时会话退化为空操作，`dispose` 照常可调用 |
| `pointerId` | 否 | 只跟随该指针，其他指针的事件全部过滤。不传则不过滤 |
| `onMove` | 是 | 指针移动。回送坐标、`pointerId`、压感与原始事件 |
| `onEnd` | 是 | 指针抬起或被系统收回。两种情形都只回送一次 |

## 跟随的文档

`resolveSessionDoc` 的解析顺序：元素自身的文档 → 全局 `document` → `null`。

按元素解析而不是直接取全局，是因为组件可能渲染在 iframe 或另一个文档中，跟错文档的表现是指针一移动即中断。元素尚未就位（首帧尚未布局）时退回全局；没有全局（无 DOM 的纯逻辑测试）时返回 `null`，此时会话不做任何事，状态照常转移，只是没有指针可跟随。

## 使用的组件

跟手期间的指针监听统一经过这一层，16 个组件在用：`slider` · `splitter` · `scrollbar` · `color-picker` · `image-cropper` · `floating-panel` · `signature-pad` · `carousel` · `calendar` · `image-viewer` · `sortable` · `resizable` · `table` · `tabs` · `tree`。

在状态机中的接法是把会话挂进拖动态的效应，效应拆卸时 `dispose`：状态一离开拖动态，监听自动移除：

<!-- eslint-skip -->

```ts
effects: {
  trackPointer: ({ send, refs }) => {
    const session = createPointerSession({
      doc: resolveSessionDoc(refs.get('getTrackEl')()),
      onMove: ({ point }) => send({ type: 'DRAG.MOVE', point }),
      onEnd: () => send({ type: 'DRAG.END' }),
    })
    return () => session.dispose()
  },
},
```

`signature-pad` 多传一个 `pointerId`：起笔指针的 id 在效应挂载前已记入 refs，笔画因此不会被第二根手指接管。

## 多指会话与双指几何

`createMultiPointerSession` 同时跟随多根指针：`add()` 记录新按下的指针，`onChange` 在任何一根移动或抬起时回送当前全部触点（按落下先后排序），最后一根离开才触发 `onEnd`。

```ts
import { createMultiPointerSession, pinchChange, pinchSnapshot } from "@xihan-ui/pointer";

const session = createMultiPointerSession({
  doc: resolveSessionDoc(el),
  onChange: (points) => {
    if (points.length < 2)
      return;
    const now = pinchSnapshot(points[0], points[1]);
    const { scale, translate, rotate } = pinchChange(start, now);
  },
  onEnd: ({ reason }) => {
    // reason 为 'pointercancel' 时应恢复原状，'pointerup' 才是落定
  },
});
```

`pinchSnapshot` 记录两指此刻的间距、中点与连线角度；`pinchChange` 由起始快照与当前快照算出相对起始时刻的缩放、位移与转角。相对起始计算而不是相对上一帧，是因为逐帧累乘会累积浮点误差。触点数变化时应重新记录基准：从双指退回单指时不重新记录，剩余手指会沿用上一段的缩放基准继续，画面会跳动。

`onEnd` 的 `reason` 需分开处理：被系统收回时应恢复原状，抬起才是落定提交。会话本身可以重复使用：最后一根手指抬起只是本场结束，不是会话作废，因此可以挂在根级效应上常驻。

`carousel` 与 `image-viewer` 使用这一层：前者只把第一根手指交给会话（单指划动，划动中第二根落下不计入），后者用双指缩放，两指整体平移时只改偏移不改缩放。

## 拖放几何

四个纯函数，`sortable` / `table` / `tree` / `tabs` 的重排都建立在其上：

| 导出 | 用途 |
| --- | --- |
| `projectSortable()` | 算出此刻的落点下标与每一项应让开的距离 |
| `sortableOffsets()` | 只取让位位移 |
| `shouldActivate()` / `DEFAULT_ACTIVATION_DISTANCE` | 本次位移是否足以开始拖动（默认 5px） |
| `edgeScrollDelta()` / `DEFAULT_EDGE_THRESHOLD` / `DEFAULT_EDGE_SPEED` | 拖到容器边缘时应滚动的距离，速度随入侵深度线性上升 |
| `moveItem()` | 先移除后插入的下标折算 |

三条判据：

- 落点按被拖项的中心是否越过其他项的中心判定，不按矩形相交。项高不一致时相交判据会在边界反复跳动；沿轴扫描遇到未越过的即停止，落点因此连续，不会从第 0 位跳到第 5 位。
- 几何一律取按下时刻的快照。让位之后布局已变化，用变形后的几何再计算会自激振荡。拖动中版面滚动产生的漂移由调用方换算回快照坐标。
- 激活阈值用直线距离而不是分轴比较。斜向拖动 4px + 4px 的实际位移是 5.7px，分轴比较会判定为未移动。

## 尺寸调整几何

`resizeRect()` 计算推动某条边之后的矩形，`clampSize` / `snapSize` / `applyAspectRatio` 是它使用的三条约束，也单独导出。`resizable` 与 `table` 的列宽、`floating-panel` 的尺寸调整都使用它。

两条硬规则：

- 西边与北边移动的是矩形的起点，因此位置随之变化；尺寸先经过约束，起点再按实际收缩量回算：顶到下限之后对边才不会继续漂移。
- 约束次序是吸附 → 宽高比 → 上下限 → 容器，夹取优先于比例。顶到容器或上下限时比例会被打破，因为边界是硬约束而比例是意图；反之（保比例、越界）会把矩形推到容器外。

## 本包不负责的部分

- 不涉及 DOM，不改样式，不调用 `setPointerCapture`
- 不换算业务坐标（轨道百分比、裁剪框、面板位置由各组件计算）
- 不做时序类手势识别（轻点、长按、双击都不在这一层）
- 不持有拖动状态：是否在拖、拖的是谁、松手后写回何处，全在组件的状态机中

这些留给调用方，是因为同一段跟手在不同组件中含义完全不同：滑块需要轨道上的比例，面板需要相对起点的位移，签名板需要压感曲线。本包只保证指针当前位置与几何计算两件事正确。

---

来源：https://ui.docs.xihanfun.com/guide/position

# 浮层定位

`@xihan-ui/position` 负责一件事：把浮层放到锚点旁的正确位置，并在页面变化时持续跟随。它是自研实现，零第三方运行时依赖。

默认共享箭头皮肤只作用于 `context-menu`、`hover-card`、`menu`、`menubar`、`popconfirm`、`popover`、`tour`、`tooltip` 自身的 `arrow` 部件。业务或其他组件使用同名 `data-part="arrow"` 不会获得浮层定位、旋转或描边裁剪。

## 端口与实现是分开的

定位能力在 `@xihan-ui/core` 中以端口形式声明，`@xihan-ui/position` 只是它的一个实现：

```ts
export interface PositionEnginePort {
  /** 计算并持续更新浮层位置，返回值调用后停止跟随。 */
  attach: (
    anchor: Anchor,
    floating: HTMLElement,
    options: PositionOptions,
    onResult: (result: PositionResult) => void,
  ) => () => void;
}
```

组件只识别这个端口。需要换用其他定位库时，实现一份 `PositionEnginePort` 注入即可，组件与皮肤不需修改。定位判据本身也是引擎无关的：它只断言浮层最终出现在屏幕的位置，更换实现后同样适用。

## 用法

```ts
import { createPositionEngine } from "@xihan-ui/position";

const engine = createPositionEngine();

const stop = engine.attach(
  triggerEl,
  floatingEl,
  { placement: "bottom-start", offset: 8, flip: true, shift: true, strategy: "absolute" },
  ({ x, y, placement, hidden }) => {
    floatingEl.style.left = `${x}px`;
    floatingEl.style.top = `${y}px`;
  },
);

stop(); // 停止跟随
```

日常使用不涉及这一层：浮层组件内部已经接入，只需传 `placement` / `offset` 等 props。

## 选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `placement` | `'bottom'` | 12 种：四个方向 × `start` / `center` / `end` |
| `offset` | `8` | 与锚点的间距（px） |
| `flip` | `true` | 主轴空间不足时翻到对面 |
| `shift` | `true` | 交叉轴溢出时沿边推回，贴边留 4px 余量 |
| `strategy` | `'absolute'` | 坐标系，见下 |

回传的 `PositionResult` 除坐标外，还有最终采用的 `placement`（翻面后可能与请求的不同，皮肤依靠 `data-side` / `data-align` 绘制箭头）与 `hidden`（锚点已被裁剪，浮层应隐藏）。

## 两套坐标系

这是浮层最容易出错的位置：

| strategy | 坐标基准 | 被谁裁 |
| --- | --- | --- |
| `absolute` | 包含块的布局坐标 | 任何 `overflow` 祖先 |
| `fixed` | 视口坐标 | 只受改变其包含块的祖先（`transform` / `filter` / `contain` 等）约束 |

引擎对两者的处理不只是切换基准：`fixed` 时会把裁剪祖先链截断到改变包含块的祖先为止。不截断时，浮层会离开裁剪区却仍在躲避一条已不存在的边界，表现为异常翻面或被推回。

::: warning 坐标系必须三处一致
状态机传给引擎的 `strategy`、`connect` 产出的内联 `position`、皮肤中 `positioner` 规则的 `position`，三处必须写同一个值。任意一处不一致，引擎按一套坐标计算、CSS 按另一套渲染，整族浮层会整体偏移一个 `scrollY`，且没有任何报错。

仓库中有一道门禁（`check-overlay-strategy.mjs`）专门检查这三处。新增使用引擎坐标的浮层组件时，必须把它登记进该名单，否则不受保护。
:::

## 虚拟锚点

右键菜单、文本选区这类没有实体元素的锚点，给一个能返回矩形的对象即可：

```ts
const virtual = {
  getBoundingClientRect: () => ({ x: event.clientX, y: event.clientY, width: 0, height: 0 }),
};
engine.attach(virtual, floatingEl, { placement: "bottom-start" }, apply);
```

计算的第一步即把元素锚点与虚拟锚点统一为矩形，之后没有任何区别。

## 落位后显示

浮层的坐标依赖自身尺寸，而尺寸要等元素进入 DOM 参与排版后才能测量：无法先定位再展开，
顺序只能是渲染、测量、定位。展开的前几帧坐标仍是兜底的 0，不处理时浮层会先在视口左上角闪现一帧：
快机器上这一帧在绘制前闭合，慢机器或开启 devtools 时会被绘制。

因此定位层有一条生命周期契约，落在皮肤基线与连接层两处：

- `reset.css` 给所有 `[data-part='positioner']` 默认 `visibility: hidden`，只有带 `data-positioned` 的才显示。
  使用 visibility 而不是 display：`display: none` 会让浮层退出排版，引擎无法测量其尺寸。
- 连接层在引擎回报坐标后写入 `data-positioned`（使用引擎坐标的经 `overlayPositioned(position)`；
  由皮肤 inset 直接摆放的对话框、抽屉、图片查看器恒带，它们没有尚未测量完成的窗口）。
- 判据与展开态无关：收起中的浮层保留坐标播完退场；重开前由各状态机的 `trackPosition` 先清除坐标，
  因此再次落位前同样隐藏。`(0, 0)` 是合法坐标，判据只判断 `x` 是否存在。
- 锚点被滚出可视区时引擎置 `hidden`，这是另一个信号 `data-hidden`，各皮肤据此隐藏。

未接线的新浮层只会不显示，不会闪现：`check-overlay-positioned` 门禁在构建前即报出。

多面板共用一份坐标的组件（菜单栏、侧栏的折叠弹出）还要逐面板记录：切换时共享份立即归新面板所有，
正在收起的面板若从共享份取坐标会当场归零。菜单栏此外遵循原生菜单栏的惯例：首开有进场、
末收有退场，相邻切换瞬时切换；且新面板落位前上一面板保持显示（`data-instant` 与交接），
否则两者之间的空档快速掠过会形成频闪。

## 跟随

`attach` 之后引擎会持续更新位置，覆盖这些情况：

- 页面滚动、容器滚动
- 视口尺寸变化
- 锚点或浮层自身尺寸变化
- 祖先链上的 `transform` / 缩放容器

静置时不空转，`stop()` 之后不再有任何回调。这两条与十二种 placement 的贴边对齐、翻面与避让（各配一条关闭后应当溢出的对照）、缩放容器、裁剪后的 `hidden` 一起，构成在浏览器中运行的定位契约判据。

## 相关

- [组件参考](../components/)：带 `positioner` 部件的组件
- [行为原语](./behavior)：定位之外的层栈、消隐与焦点
- [测试与质量门禁](./testing)：定位契约的验证方式

---

来源：https://ui.docs.xihanfun.com/guide/sound

# 声音层

`@xihan-ui/sound` 是一层纯 Web Audio 的程序化 UI 音效：零音频文件、零第三方依赖、框架无关。点击、成功、报错等提示音不是加载 MP3，而是在播放瞬间用振荡器与噪声实时合成：整个包比一个音频文件更小。

它是独立的：不依赖任何适配器，任何框架（或无框架）都可直接安装使用。

下面的示例会实际发声，建议先调低音量。

```vue
<script setup lang="ts">
import type { SoundTheme } from "@xihan-ui/sound";
import {
  BUILTIN_SOUND_NAMES,
  createSoundPlayer,
  defaultSoundTheme,
  minimalSoundTheme,
  softSoundTheme,
} from "@xihan-ui/sound";
import { XhButton, XhRadioGroupRoot, XhSwitch } from "@xihan-ui/vue";
import { onBeforeUnmount, ref, watch } from "vue";

const themes: Record<string, SoundTheme> = {
  default: defaultSoundTheme,
  minimal: minimalSoundTheme,
  soft: softSoundTheme,
};

const options = [
  { value: "default", label: "default 清亮" },
  { value: "minimal", label: "minimal 极简" },
  { value: "soft", label: "soft 柔和" },
];

// 建播放器不碰音频上下文，等第一次真的发声才建，放 setup 里是安全的
const player = createSoundPlayer();
const theme = ref("default");
const volume = ref(0.5);
const enabled = ref(true);

watch(theme, name => player.setTheme(themes[name] ?? defaultSoundTheme));
watch(volume, value => player.setVolume(value));
watch(enabled, on => player.setEnabled(on));

onBeforeUnmount(() => player.dispose());
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: 100%">
    <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 20px">
      <XhRadioGroupRoot
        v-model:value="theme"
        :collection="options"
        label="主题"
        name="sound-theme"
      />
      <label style="display: flex; align-items: center; gap: 8px">
        音量
        <input v-model.number="volume" type="range" min="0" max="1" step="0.05">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        出声
        <XhSwitch v-model:checked="enabled" />
      </label>
    </div>

    <div style="display: flex; flex-wrap: wrap; gap: 8px">
      <XhButton
        v-for="name in BUILTIN_SOUND_NAMES"
        :key="name"
        variant="outline"
        size="sm"
        @click="player.play(name)"
      >
        {{ name }}
      </XhButton>
    </div>
  </div>
</template>
```

## 声音是配方，不是文件

一段声音是一份可 JSON 序列化的声明式配方（`SoundSpec`）：若干并行发声层，每层一条增益包络，可带音高包络、滤波与混响送出。

```ts
import type { SoundSpec } from "@xihan-ui/sound";

const ding: SoundSpec = {
  layers: [
    {
      kind: "oscillator",
      wave: "sine",
      frequency: [{ time: 0, value: 1046.5 }], // C6
      gain: [
        { time: 0, value: 0 },
        { time: 0.01, value: 0.25 }, // 10ms 起音，避免爆音
        { time: 0.3, value: 0, curve: "exp" }, // 指数衰减
      ],
    },
  ],
  space: 0.2, // 混响送出量
};
```

配方是纯数据，这带来三点：主题可以整套替换、用户配置可以持久化再回放、调音界面可以直接编辑它，例如：

```vue
<script setup lang="ts">
import type { OscillatorLayer, SoundSpec } from "@xihan-ui/sound";
import { createSoundPlayer, glide, strike } from "@xihan-ui/sound";
import { XhButton, XhRadioGroupRoot } from "@xihan-ui/vue";
import { computed, onBeforeUnmount, ref } from "vue";

const waves = [
  { value: "sine", label: "sine" },
  { value: "triangle", label: "triangle" },
  { value: "square", label: "square" },
  { value: "sawtooth", label: "sawtooth" },
];

const wave = ref<OscillatorLayer["wave"]>("triangle");
const from = ref(880);
const to = ref(1320);
const attack = ref(5);
const decay = ref(180);
const peak = ref(0.3);
const space = ref(0.15);

const seconds = computed(() => Math.max(0.01, decay.value / 1000));

const spec = computed<SoundSpec>(() => ({
  layers: [
    {
      kind: "oscillator",
      wave: wave.value,
      frequency: glide(from.value, to.value, seconds.value),
      gain: strike(peak.value, attack.value / 1000, seconds.value),
    },
  ],
  space: space.value,
}));

const code = computed(
  () => `sound.play({
  layers: [
    {
      kind: 'oscillator',
      wave: '${wave.value}',
      frequency: glide(${from.value}, ${to.value}, ${seconds.value.toFixed(3)}),
      gain: strike(${peak.value}, ${(attack.value / 1000).toFixed(3)}, ${seconds.value.toFixed(3)}),
    },
  ],
  space: ${space.value},
})`,
);

const player = createSoundPlayer();
onBeforeUnmount(() => player.dispose());
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; width: 100%">
    <XhRadioGroupRoot v-model:value="wave" :collection="waves" label="波形" name="sound-wave" />

    <div
      style="
        display: grid;
        grid-template-columns: repeat(auto-fit, minmax(190px, 1fr));
        gap: 10px 20px;
      "
    >
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">起始 {{ from }}Hz</span>
        <input v-model.number="from" type="range" min="80" max="2400" step="10">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">终止 {{ to }}Hz</span>
        <input v-model.number="to" type="range" min="80" max="2400" step="10">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">起音 {{ attack }}ms</span>
        <input v-model.number="attack" type="range" min="1" max="80" step="1">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">衰减 {{ decay }}ms</span>
        <input v-model.number="decay" type="range" min="20" max="900" step="10">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">峰值 {{ peak }}</span>
        <input v-model.number="peak" type="range" min="0.05" max="0.6" step="0.05">
      </label>
      <label style="display: flex; align-items: center; gap: 8px">
        <span style="width: 76px">空间 {{ space }}</span>
        <input v-model.number="space" type="range" min="0" max="0.6" step="0.05">
      </label>
    </div>

    <div>
      <XhButton variant="solid" @click="player.play(spec)">试听</XhButton>
    </div>

    <pre
      data-xh-scroll
      style="
        margin: 0;
        padding: 12px 14px;
        border-radius: 8px;
        background: var(--vp-c-bg-soft);
        font-size: 12px;
        line-height: 1.6;
        overflow-x: auto;
      "
    >{{ code }}</pre>
  </div>
</template>
```

播放前配方一律经过一道钳制（`clampSpec`）：越界钳住、类型不符回落、未知形态丢弃，异常数据不会导致播放失败，也不会产出刺耳或超长的声音。

## 语义名与主题

主题把语义名映射到配方。内置 14 个语义名：

`click` `tap` `toggle-on` `toggle-off` `open` `close` `success` `error` `warning` `info` `notification` `send` `receive` `complete`

内置三套主题，每套都覆盖全部语义名：

| 主题 | 性格 |
| --- | --- |
| `defaultSoundTheme` | 清亮乐音系：C 大调琶音、高频短敲、适度混响 |
| `minimalSoundTheme` | 短促干净、无混响，整段不超过 0.3 秒，只标记事件不渲染情绪 |
| `softSoundTheme` | 低音区正弦、慢起音、厚混响，提示可被听见但不惊扰 |

自定义主题即普通对象展开：

```ts
import { defaultSoundTheme, defineSoundTheme } from "@xihan-ui/sound";

const mine = defineSoundTheme({
  ...defaultSoundTheme,
  click: ding, // 替换一个，其余沿用
});
```

## 基础用法

```ts
import { createSoundPlayer, softSoundTheme } from "@xihan-ui/sound";

const sound = createSoundPlayer({
  volume: 0.5, // 主音量 0..1
  enabled: true, // 接入用户偏好，不替最终用户决定
  throttle: 50, // 同名声音的最小重触发间隔（毫秒）
});

sound.play("success");
sound.play("click", { volume: 0.5 }); // 单次音量系数
sound.play(ding); // 配方对象直接播放，不经过主题

sound.setTheme(softSoundTheme);
sound.setVolume(0.3);
sound.setEnabled(false);
sound.dispose();
```

音频上下文惰性创建：首次实际播放时才创建，从不发声的页面不为它付出任何代价。SSR 或没有 Web Audio 的环境中所有调用静默退化为空操作，不需要条件守卫。

## 在 Vue 中使用

Vue 侧的适配放在单独的子入口 `@xihan-ui/vue/sound`，两种用法：给命令式反馈服务配声，或给单个元素配声。

### 给通知与确认框配声

`withToastSound` / `withDialogSound` 包装现有的服务，调用点不需修改：

```ts
import { createSoundPlayer, softSoundTheme } from "@xihan-ui/sound";
import { createDialogService, createToastService } from "@xihan-ui/vue";
import { setSoundPlayer, withDialogSound, withToastSound } from "@xihan-ui/vue/sound";

// 更换主题、接入用户偏好；不设置时使用默认播放器
setSoundPlayer(createSoundPlayer({ theme: softSoundTheme, enabled: userPrefs.sound }));

export const toast = withToastSound(createToastService());
export const dialog = withDialogSound(createDialogService());

toast.success("已保存"); // 视觉 + 听觉，返回值与原服务完全一致
await dialog.confirm({ title: "删除这条记录？" });
```

```vue
<script setup lang="ts">
import type { ToastService } from "@xihan-ui/vue";
import { createToastService, XhButton } from "@xihan-ui/vue";
import { withToastSound } from "@xihan-ui/vue/sound";
import { onBeforeUnmount } from "vue";

// 惰性建单例：服务要 document，等到第一次调用（必然在客户端）再建
let toast: ToastService | undefined;
function use(): ToastService {
  toast ??= withToastSound(createToastService({ placement: "top" }));
  return toast;
}
onBeforeUnmount(() => toast?.dispose());

function upload(): void {
  const id = use().loading("上传中");
  setTimeout(() => use().update(id, { loading: false, tone: "success", title: "上传完成" }), 1200);
}
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px">
    <XhButton variant="solid" @click="upload()">上传（静默转成功才响）</XhButton>
    <XhButton variant="outline" @click="use().success('已保存')">success</XhButton>
    <XhButton variant="outline" @click="use().warning('磁盘快满了')">warning</XhButton>
    <XhButton variant="outline" @click="use().danger('同步失败，稍后自动重试')">
      danger
    </XhButton>
  </div>
</template>
```

默认映射：

| 调用 | 声音 |
| --- | --- |
| `toast.info/success/warning/danger` | 同名语义声（`danger` 对应 `error`） |
| `toast.loading` | 不发声（加载中只是过渡态） |
| `toast.update(id, { tone })` | 新语气的声音，`loading: true` 仍开启时除外：上传完成时应发声，修改文案不应发声 |
| `dialog.confirm` | `open` |
| `dialog.info/success/warning/error` | 同名语义声 |
| 关闭、消失 | 不发声 |

逐项改写，传 `null` 即该类静音：

```ts
withToastSound(createToastService(), {
  sounds: { success: "complete", danger: null },
});
```

这两个服务挂在 body 下的独立应用中，无法获取组件树的注入：音效开关要么使用 `setSoundPlayer` 设置的播放器，要么通过 `options.player` 单独传入。

服务默认在首次用户手势时解锁音频上下文（`autoUnlock`），因为通知常来自请求拦截器或推送等非手势场景，不解锁则无法发声。

### 给单个元素配声

```vue
<script setup lang="ts">
import { XhButton } from "@xihan-ui/vue";
import { vSound } from "@xihan-ui/vue/sound";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 8px">
    <XhButton v-sound variant="solid">默认 click</XhButton>
    <XhButton v-sound="'send'" variant="outline">发送</XhButton>
    <XhButton v-sound="{ sound: 'toggle-on', volume: 0.6 }" variant="outline">
      指定音量
    </XhButton>
    <XhButton v-sound disabled variant="outline">禁用不响</XhButton>
  </div>
</template>
```

指令挂在 `click` 上而不是 `pointerdown`：键盘按 Enter / Space 激活也应发声，按下后拖开取消的不应发声。带 `disabled` / `aria-disabled` / `data-disabled` 的元素不发声。

`@xihan-ui/sound` 是可选 peer：不安装时主入口不引用它，应用中不会多出音频引擎。

## 在 React 中使用

React 侧的适配同样放在单独的子入口 `@xihan-ui/react/sound`。服务层与 Vue 完全同名同形：

```ts
import { createDialogService, createToastService } from "@xihan-ui/react";
import { setSoundPlayer, withDialogSound, withToastSound } from "@xihan-ui/react/sound";
import { createSoundPlayer, softSoundTheme } from "@xihan-ui/sound";

// 更换主题、接入用户偏好；不设置时使用默认播放器
setSoundPlayer(createSoundPlayer({ theme: softSoundTheme, enabled: userPrefs.sound }));

export const toast = withToastSound(createToastService());
export const dialog = withDialogSound(createDialogService());

toast.success("已保存"); // 视觉 + 听觉，返回值与原服务完全一致
await dialog.confirm({ title: "删除这条记录？" });
```

默认映射、逐项改写与 `autoUnlock` 的口径与上表一致：两侧包装的是同一份语义。

给单个元素配声的方式不同：指令是 Vue 独有的介质，React 侧对应的是 `useSoundOnPress`，返回一个挂到元素 `ref` 上的回调：

```tsx
import { useSoundOnPress } from "@xihan-ui/react/sound";

<>
  <button ref={useSoundOnPress()}>提交</button>
  <button ref={useSoundOnPress("send")}>发送</button>
  <div ref={useSoundOnPress({ sound: "toggle-on", volume: 0.6 })} />
</>;
```

监听同样挂在 `click` 上而不是 `pointerdown`：键盘按 Enter / Space 激活也应发声，按下后拖开取消的不应发声。带 `disabled` / `aria-disabled` / `data-disabled` 的元素不发声。

传入的值每次渲染时读取：更换语义名、音量、播放器都不必解绑重绑，按下时取当前值。ref 回调本身常驻，React 不会因重渲染反复解绑重绑。

给库内组件配声时，把回调挂到它转发的 ref 上；组件不转发 ref 时，包一层自己的元素，声音随该次点击的冒泡触发。

## 自动播放策略

浏览器要求用户先与页面交互，音频上下文才允许发声。播放器的处理：

- 点击、切换这类手势触发的声音天然合规：手势本身已解锁上下文；
- 上下文仍被挂起时，只保留最近一声待发，恢复后补发该声，不会把积压的提示音一次全部播放；
- 通知这类非手势的声音需要发声时，需在任意一次用户手势中先调用 `sound.unlock()` 提前解锁。

```ts
// 应用入口处：首次交互解锁，之后 SignalR 推送的通知即可发声
window.addEventListener("pointerdown", () => sound.unlock(), { once: true });
```

声音默认是打扰。把 `enabled` 与音量接入用户偏好并持久化，优先提供关闭入口：这是应用的责任，播放器只负责让开关随时生效。

## 调音

三个包络工厂简化常用形状：

```ts
import { flat, glide, strike } from "@xihan-ui/sound";

strike(0.3, 0.005, 0.2); // 敲击：5ms 起音到 0.3，再 200ms 指数衰减
flat(880); // 恒定值（音高 880Hz）
glide(440, 880, 0.12); // 滑音：120ms 从 440 滑到 880
```

层可以叠加：琶音是几层错开 `delay` 的正弦，风声是一层扫频 lowpass 的噪声，按键是一层三角波加少量 highpass 白噪。配方可用的原料：振荡器四种波形、白噪与粉噪、双二阶滤波五型（`lowpass` `highpass` `bandpass` `notch` `peaking`）、共享混响总线，整包不到 5 kB。

## 相关

- [背景层](./backgrounds)：同为 `features/` 组的可选能力层，视觉对偶

---

来源：https://ui.docs.xihanfun.com/guide/styling

# 皮肤与样式分层

`@xihan-ui/styles` 是纯 CSS 包：不依赖任何 JS 包，也不被任何 JS 包依赖。它可以脱离 JS 层单独使用，也可以整体替换为自定义皮肤。

## 层序

CSS 的级联顺序由 `@layer` 声明的首次出现顺序决定，与 `@import` 顺序无关。层序声明单独放在一个文件中：

```css
/* layers.css */
@layer xihan.reset, xihan.tokens, xihan.motion, xihan.components, xihan.overrides;
```

| 层 | 内容 |
| --- | --- |
| `xihan.reset` | 库自身的基线，只作用于带 `data-scope` 的节点 |
| `xihan.tokens` | 令牌声明（来自 `@xihan-ui/tokens/tokens.css`） |
| `xihan.motion` | 关键帧动画 |
| `xihan.components` | 组件皮肤 |
| `xihan.overrides` | 留给使用者，优先级高于以上全部 |

令牌产物 `tokens.css` 由生成器携带一份逐字相同的层序副本，先引入令牌的项目层序同样成立；两份不允许漂移，由 `check-layer-order` 门禁保证。

按组件引入样式时必须先引入 `layers.css` 或 `tokens.css` 之一，否则层序不成立，级联顺序会退化为引入顺序。

::: warning 本站示例使用无层版本
主入口 `index.css` 与 `index.unlayered.css` 都是从同一份源序生成的扁平文件：家族配方在四份公共层之后只内联一次、排在一切组件皮肤之前，各皮肤随后按源序内联并去掉自带的家族 `@import`。文档站引入的是 `index.unlayered.css`（VitePress 自带无层的 `button` 重置，见[安装与接入](../installation#宿主有无层-reset-时改用无层版)）。层壳移除后，本页描述的层序在本站示例中不生效，规则按特异性竞争。层序相关的表现请在自己的项目中引入 `index.css` 后验证。
:::

## reset 只作用于库节点

```css
@layer xihan.reset {
  :where([data-scope]) {
    box-sizing: border-box;
  }

  :where([data-scope])::before,
  :where([data-scope])::after {
    box-sizing: border-box;
  }

  :where([data-scope]):where(button, input, optgroup, select, textarea) {
    font: inherit;
    letter-spacing: inherit;
  }
}
```

没有全局 reset，不影响宿主页面的任何元素。与现有页面共存不需要隔离。

reset 层的每条选择器都由 `:where()` 包住，特指度为 (0,0,0)（伪元素自身的 (0,0,1) 无法再低）。有层版本里这一点无关紧要，层序已经保证皮肤压得住 reset；无层版本 `index.unlayered.css` 只按特指度竞争：Family Recipe 的根规则在产物里由 `[data-scope]` 前缀抬到 (0,2,0)（源文件仍是 `[data-xh-action-control]` 一类的 (0,1,0)），与皮肤选择器同档，并在四份公共层之后、先于全部组件皮肤与 reset 内联一次——同档只剩源序竞争，皮肤对配方物理属性的直接覆盖只有配方先出现才成立，与有层版本里皮肤高一级即胜等价；reset 只有低一档才不会靠源序把配方的字号压掉。代价是无层模式下宿主页面的元素选择器（`div { visibility: hidden }` 这类 (0,0,1)）可以压过 reset——这是无层模式「按特指度竞争」既有取舍的延伸，宿主有这类规则时请自行提高 reset 覆盖的特指度或改用有层版本。

## 组件内滚动

组件内的滚动条形态只有两档，按滚动面的身份固定：

| 档 | 适用面 | 表达 |
| --- | --- | --- |
| 自绘条 | Overlay 家族 positioner 下的 content / list / column，以及定高小列表（Listbox、Transfer、时间列、Cascader column） | Scrollbar 组件接线，`type` 默认 `scroll-hover`，浮层 4px、页内 6px，壳上 `--xh-scrollbar-track-bg: transparent` |
| 原生细条 | 页内结构容器（Table、Tree、Virtualizer viewport、Dialog / Drawer body、Layout sider、Log / MessageFeed 视口、Typography `pre`……）与作者自建滚动容器 | reset 层统一给：`scrollbar-width: thin` + `scrollbar-color: var(--xh-fg-scrollbar-thumb) var(--xh-bg-scrollbar-track)` |

原生细条住在 reset 层，选择器是 `:where([data-scope][data-part], [data-xh-scroll], [data-scope='typography'][data-part='prose'] pre)`。库节点自动命中；作者自己的滚动容器与文档示例加 `data-xh-scroll` 即得同一套细条，不必引任何组件：

```html
<div data-xh-scroll style="max-block-size: 240px; overflow: auto">
  <!-- 长内容 -->
</div>
```

`data-xh-scroll` 只挂样式，不进任何组件契约；它不是 Web Components 的角色声明，角色声明只有 `data-xh-part`。

皮肤不得手写 `scrollbar-width` / `scrollbar-color`（stylelint 判红），要藏原生条（挂了自绘条时）只能写 `scrollbar-width: none`。两条边界属性同样按身份给：`overscroll-behavior: contain` 只给浮层滚动面、模态 body 与粘底视口，页内结构容器保持 `auto`；`scrollbar-gutter: stable` 只给内容高度动态变化的容器（Log、MessageFeed、Dialog / Drawer body），并带 `:not([data-xh-scrollbar])` 守卫——挂了自绘条的容器原生条已是零宽，空道对它没有布局作用。每一处滚动面都登记在 `tooling/scripts/scroll-surface-registry.json`，由 `check-scrollbar-hosts` 逐面核对。

## 皮肤的写法

选择器只使用 `data-*`，不使用类名：

```css
@layer xihan.components {
  [data-scope='toggle'][data-part='root'] {
    /* 私有槽带组件名：组件令牌 → 语义令牌两级回退 */
    --xh-_toggle-bg-on: var(--xh-toggle-bg-on, var(--xh-bg-brand-subtle));
    --xh-_toggle-fg-on: var(--xh-toggle-fg-on, var(--xh-fg-on-brand-subtle));

    /* 家族配方画面：公开槽桥接到形态矩阵之前，使用者槽 → 矩阵（data-xh-action-variant）→ 家族缺省 */
    --xh-action-bg-rest: var(--xh-toggle-bg, var(--xh-_action-variant-bg-rest));
    --xh-action-fg-rest: var(--xh-toggle-fg, var(--xh-_action-variant-fg-rest));
    --xh-action-radius: var(--xh-toggle-radius, var(--xh-shape-control));
  }

  /* 状态只改槽，不重写整条规则 */
  [data-scope='toggle'][data-part='root'][data-state='on'] {
    --xh-action-bg-rest: var(--xh-_toggle-bg-on);
    --xh-action-fg-rest: var(--xh-_toggle-fg-on);
  }

  /* 禁用同时降级前景与表面，不只降低 opacity；手型与状态选择器由配方给 */
  [data-scope='toggle'][data-part='root'][data-state='on'] {
    --xh-action-bg-disabled: var(--xh-_toggle-bg-on-disabled);
    --xh-action-fg-disabled: var(--xh-_toggle-fg-on-disabled);
  }
}
```

三层变量各司其职：

| 形式 | 名称 | 由谁设置 |
| --- | --- | --- |
| 组件覆盖槽 | `--xh-button-bg` | 使用者：修改该组件的背景 |
| 语义令牌 | `--xh-bg-subtle` | 令牌产物：修改后影响全库 |
| 皮肤私有槽 | `--xh-_toggle-bg-on` | 皮肤内部：状态只改它，规则不重复 |

带下划线前缀的私有槽不是公开接口，不在外部设置。

## 覆盖样式的三种粒度

```css
/* 1. 改语义令牌：影响所有直接消费它的规则 */
:root {
  --xh-shape-control: var(--xh-radius-md);
}

/* 2. 改组件覆盖槽：只影响这一类组件 */
:root {
  --xh-button-h: 40px;
  --xh-dialog-max-w: 40rem;
}

/* 3. 直接写规则：放进 overrides 层 */
@layer xihan.overrides {
  [data-scope='button'][data-part='root'] {
    text-transform: uppercase;
  }
}
```

优先使用前两种。直接写死的规则会绕开令牌体系，深色模式与密度切换随之失效。

## 输入类控件的缺省宽度与最小宽度

下拉、日期、文本框等单行字段不传尺寸时一律同宽：根上带 `inline-size: var(--xh-control-w)`，默认值 `16rem`（约 256px），宽度不随内容走——选中一条很长的选项，触发器不会跟着变宽，文字在盒内截断。要撑满表单列就在根上写 `inline-size: 100%`，或改槽：

```css
/* 全局：所有字段一起改 */
:root {
  --xh-control-w: 20rem;
}

/* 单类：只改下拉，其余不变 */
:root {
  --xh-select-control-w: 20rem;
}
```

19 份皮肤消费缺省宽令牌。日期范围选择器是登记过的例外：起止两组按日的段位、分隔符与日历钮排在一行，内容本身就比 16rem 宽，钉成缺省宽会裁掉终点的段位，所以它缺省按内容撑开、只拿缺省宽作地板（按年、按月时不比别的字段窄），`--xh-date-range-picker-control-w` 仍可钉宽。分格输入的宽由格数与格宽决定，对话输入条铺满宿主，表单字段（Field）的控件铺满表单列：这三类不吃缺省宽。

缺省宽之外还有一条底线 `min-inline-size: var(--xh-control-min-w)`，默认值 `12rem`（约 192px）。字段放进 flex 或 grid 中会被压缩，压缩到只剩箭头时无法使用，底线挡住这一步；容器比底线还窄时整件收成容器那么宽，不越出去。

20 份皮肤消费这条令牌（其中 file-upload 用它作为条目内文件名的下限，不是控件宽度）。窄栏场景（两列表单、抽屉内的设置项、表格上方的筛选行）要让字段收得更小时放开它：

```css
/* 全局：所有消费这条令牌的控件一起改 */
:root {
  --xh-control-min-w: 0;
}

/* 单类：只改下拉，其余不变 */
:root {
  --xh-select-control-min-w: 8rem;
}
```

槽名是 `--xh-<组件名>-control-w` 与 `--xh-<组件名>-control-min-w`；`mention` 的盒是输入框自己，两条槽叫 `--xh-mention-input-w` 与 `--xh-mention-input-min-w`。完整列表见各组件页的“CSS 变量”。

## 在自定义节点上使用语气

语气轴（`data-tone`）不限于库内组件。在自定义节点上写 `data-tone`，该节点内即可取到整族颜色：六族语气、深浅两态、切换品牌色后的取值都随之变化：

```css
.my-status-card {
  background: var(--xh-tone-subtle);
  border: 1px solid var(--xh-tone-border);
  color: var(--xh-tone-fg);
}
```

```html
<div class="my-status-card" data-tone="danger">…</div>
```

| 令牌 | 含义 |
| --- | --- |
| `--xh-tone-solid` | 实心底 |
| `--xh-tone-solid-hover` / `--xh-tone-solid-active` | 实心底的悬停与按下 |
| `--xh-tone-on` | 实心底上的前景色 |
| `--xh-tone-subtle` | 淡底 |
| `--xh-tone-subtle-hover` / `--xh-tone-subtle-active` | 淡底的悬停与按下 |
| `--xh-tone-fg` | 普通背景上表达该语气的文字色 |
| `--xh-tone-border` | 描边 |
| `--xh-tone-border-control` | 可操作区的边界，对面 3:1 |
| `--xh-tone-soft` | 色条、指示条等装饰性强调，对画布 3:1 |

这一族只在写了 `data-tone` 的节点及其后代内有取值；`data-tone` 是它们的开关，不是可选修饰。

对比度已按 WCAG 逐族验证：实心底与 `--xh-tone-on`、淡底三态与 `--xh-tone-fg` 都是 4.5:1，两条非文字档是 3:1。自定义配色时，文字与底色按上表成对取用，不把 `--xh-tone-fg` 放在 `--xh-tone-solid` 上。

## 聚焦环与实心面

键盘焦点的环由公共皮肤 `focus.css` 统一绘制，组件不需要自行写 `outline`：

```css
[data-scope][data-part]:focus-visible {
  outline: var(--xh-ring-width) solid var(--xh-_ring-color, var(--xh-ring-focus));
  outline-offset: var(--xh-ring-offset);
}
```

偏移是负的一个环宽：环向元素内收，外沿与元素边框外沿重合，聚焦前后占位一致。因此环内侧紧邻的是元素自己的面。面为实心的档位上，环色与面同族，对比度最低可到 1.00:1。这些档位把环色槽设为 `currentColor`，环改取该面配对的前景色：

```css
[data-scope='tag'][data-part='root'][data-variant='solid'] {
  background: var(--xh-tag-bg, var(--xh-bg-brand));
  color: var(--xh-tag-fg, var(--xh-fg-on-brand));
}

[data-scope='tag'][data-part='root'][data-variant='solid']:focus-visible {
  --xh-_ring-color: currentColor;
}
```

环不随语气变化。`currentColor` 取的是该面配对的前景色（实心底上是 `--xh-tone-on`），不是语气色本体：语气色本体作为环色时，warning 对白底只有 2.70:1、success 3.04:1，达不到 3:1。没有实心面的档位一律使用 `--xh-ring-focus`。判据是环压着的面，不是组件的语气。

达标的面不为统一而改环色。淡底、透空等非实心档一律使用默认环；一条改环色的规则覆盖到非实心档（同一部件的另一形态、失效档、只读档）时门禁判红，应把选择器收窄到实心档，而不是登记豁免。

改环色按求值判定，不按写法判定。门禁检查三条声明的求值结果：`--xh-_ring-color`、`outline-color`、键盘聚焦规则中的 `outline` 简写。沿皮肤中的槽展开、再沿令牌链解到颜色，在任一主题 × 语气下与库的两支环（`--xh-ring-focus`、`--xh-ring-invalid`）都不相等即视为改环色；解不出的值（`currentColor`、使用者传入的色值、没有兜底的使用者令牌）同样视为改环色。以下写法与写 `currentColor` 受同一套判据约束：

```css
/* 与面配对的前景色令牌：开关选中的轨道是 <button>、皮肤没有给它 color，只能这样写 */
[data-scope='switch'][data-part='root'][data-state='checked']:focus-visible {
  --xh-_ring-color: var(--xh-_tone-on, var(--xh-fg-on-brand));
}

/* 不经槽、直接写长属性：同样视为改环色 */
[data-scope='x'][data-part='y']:focus-visible {
  outline-color: var(--xh-fg-default);
}

/* 包进 @supports：块内条件按成立处理 */
@supports (color: red) {
  [data-scope='x'][data-part='y']:focus-visible {
    --xh-_ring-color: currentColor;
  }
}

/* 包进 @media screen / @container：静态无法判断何时不成立，按成立处理 */
@media screen {
  [data-scope='x'][data-part='y']:focus-visible {
    --xh-_ring-color: currentColor;
  }
}

/* 写在裸 :focus 里的 outline 简写：:focus 包含键盘聚焦；未写颜色时等于 currentColor */
[data-scope='x'][data-part='y']:focus {
  outline: var(--xh-ring-width) solid var(--xh-fg-default);
}

/* 没有兜底的使用者令牌：值由使用者决定，无法解出 */
[data-scope='x'][data-part='y']:focus-visible {
  --xh-_ring-color: var(--xh-tag-fg);
}
```

显式写回 `var(--xh-ring-focus)`、校验失败时换 `var(--xh-ring-invalid)` 不算改环色。`@media` 只有打印、高对比、减弱动效、粗指针、断点这几种真实媒体条件才算条件块。用 `[data-variant]` / `[data-state]` 等属性存在式选择器一次覆盖多个形态时，每个形态各算一档，覆盖到的非实心档逐档判红：规则写了但档位未写取值的属性，存在式一律视为覆盖；写了取值的（`[data-state='on']`）按是否有兄弟档认领判定。库的两支环令牌与它们解析链上经过的名称（如 `--xh-color-brand-500`）在皮肤内一律不允许赋值。浏览器测试 `focus-ring-inset-grpring` 按同一定义从样式表读出改环色的规则，逐条测量落焦对比度是否达到 3:1；静态放行的别名色（例如在实心底上写同族的 `var(--xh-color-brand-600)`）在那里测量为 1:1。

自行编写皮肤时，改环色前核对三件事：

1. 面画在哪个节点上。画在祖先上时（透空的关闭按钮位于标签的实心底上），规则写成后代选择器，槽仍然设在获得焦点的节点上。
2. 部件是否有 `color`。圆点、滑块等没有文字的部件先补一支与面配对的前景色；否则 `currentColor` 会取到继承的正文色或原生控件的 UA 前景色。只有一档需要更换时把该色直接写进槽，不经过 `currentColor`。
3. 面被替换的档位要退出。失效档把面换成置灰底、前景换成置灰色甚至透明（`color: transparent` 会让整条环一起透明），中性轻档把实心底换成灰底。收窄选择器退回默认值，或把槽显式写回 `var(--xh-ring-focus)`。

## 切换品牌色

品牌色的唯一真源是原语梯度 `--xh-color-brand-50…950`：语义令牌（`--xh-bg-brand` 等）与语气层（`data-tone='brand'`）都从它取值。切换品牌色要替换整套原语，而不是只改 `--xh-bg-brand`：后者只影响未写 `data-tone` 的默认路径，写了 `data-tone='brand'` 的组件（实心按钮、开关、进度条等）不会随之变化。

提供一枚种子色即可，运行时派生整套梯度：

```ts
import { brandId, createVisualEnvironmentController, registerBrand } from "@xihan-ui/tokens";

// 注册：从种子色派生 11 档原语，注入 [data-brand='acme'] 取值块
registerBrand("acme", "#16a34a");

// 切换：品牌是八轴视觉环境之一
const visual = createVisualEnvironmentController({ root: document.documentElement });
visual.setPreference({ brand: brandId("acme") });
```

派生只取种子的色相与彩度，明度曲线沿用基线，库内所有建立在明度上的对比度保证（如实心底白字 4.5:1）对任何种子色都继续成立。种子会被锚定到 600 档（实心底与强调文字的档位），因此种子必须完全不透明；透明品牌色依赖宿主背景，运行时会拒绝。

需要逐档手动调整时，把整套梯度直接交给 `registerBrand('acme', { 50: '...', ..., 950: '...' })`。SSR 场景用 `brandScaleCss(id, seed)` 获得取值块字符串，随首屏 HTML 下发，客户端不需要再注册。

## 透明颜色与对比度

颜色运行时把 alpha 作为 `Oklch.a` 的必填通道保留。`compositeColors(foreground, backdrop)` 按 CSS source-over 在 sRGB 编码通道合成；WCAG 相对亮度在得到最终像素后再线性化。

```ts
import { compositeColors, contrastRatio } from "@xihan-ui/tokens";

const page = "oklch(0.97 0.01 250)";
const frosted = "oklch(0.98 0.01 250 / 88%)";
const renderedFrosted = compositeColors(frosted, page);

// 背景本身透明时，第三个参数必须给出最终底色。
const ratio = contrastRatio("oklch(0.2 0.02 250)", frosted, page);
```

`relativeLuminance(transparentColor)` 和缺少最终底色的 `contrastRatio(foreground, transparentBackground)` 会直接抛错，不假设白底。磨砂面位于图片、品牌色或多层 surface 上时，应分别传入实际像素或逐层合成；平均色不能证明每一处文字都满足对比度。

`pickOnColor` 与 `pickAwayColor` 可通过 `{ backdrop: actualBackdrop }` 处理半透明背景，并比较自定义 light/dark 候选的真实对比度。没有最终底色时同样抛错，运行时不推测页面背景。

## 动画与进出场

进出场动画挂在 `data-state` 上：

```css
[data-scope='dialog'][data-part='backdrop'][data-state='open'] {
  animation: xh-fade-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
}

[data-scope='dialog'][data-part='backdrop'][data-state='closed'] {
  animation: xh-fade-out var(--xh-motion-duration-exit) var(--xh-motion-ease-exit);
}
```

关闭时 DOM 不会立即消失：[进出场原语](./behavior#进出场)会等待动画结束（或超时）后才允许卸载，因此 `[data-state='closed']` 的动画可以完整播放。

跨皮肤共用的关键帧只定义一次，住在 `family/motion.css`，子入口是 `@xihan-ui/styles/motion.css`：浮层进出场 `xh-overlay-slide-in / out`、`xh-overlay-pop-in`、`xh-pop-in / out`，面板 `xh-sheet-in / out`，整幅滑入 `xh-slide-in / out`，淡变与页内显现 `xh-fade-in / out`、`xh-rise-in`、`xh-drop-in`，列表条目 `xh-item-in`，披露 `xh-disclosure-expand / collapse`，循环 `xh-spin`、`xh-shimmer`，倒计时 `xh-countdown`。引用它们的皮肤各自 `@import` 这份文件，所以单独引入某一份皮肤时关键帧仍会到场，全量入口按物理文件去重。同一段动画全库只有一个名字；只属于一个组件的关键帧（`xh-toast-in`、`xh-skeleton-shimmer` 一类）仍写在各自皮肤里。

要替换某段动画，在 `xihan.overrides` 层重定义同名关键帧即可，不必逐皮肤覆盖。共享关键帧的重定义会作用到所有引用它的组件；只想换一个组件时，改写该组件部件上的 `animation-name`，指向自己定义的关键帧。

## 升级前的形态

自定义元素在 JS 到达之前不会升级，这段时间 `data-scope` / `data-part` 尚未写入，浮层的内容会以裸文本出现在页面流中，被搜索引擎与读屏视为正文。SSR / SSG 直出时这段窗口尤其长。

`undefined.css` 处理这种情况，按作者写的 `data-xh-part` 选中（升级前唯一存在的标记）：

```css
@layer xihan.components {
  :where(xh-dialog, xh-popover, xh-select /* … */):not(:defined)
    :where([data-xh-part='backdrop'], [data-xh-part='content'],
           [data-xh-part='positioner'], [data-xh-part='viewport']) {
    display: none;
  }
}
```

## 门禁

皮肤由多道门禁约束（`pnpm gate`）：

| 门禁 | 拦截内容 |
| --- | --- |
| `check-token-refs` | 皮肤引用了令牌产物中不存在的令牌名。孤儿引用不报错也不降级，整条声明在计算值阶段静默失效 |
| `check-shared-slots` | 同一个字面量在两个以上组件中作为默认值。这是一条未命名的设计决策，应先建立语义令牌 |
| `check-disabled-contrast` | 禁用态的前景色令牌上又叠加 `opacity`。两种手段同时使用会把对比度压到无法阅读 |
| `check-focus-ring-surface` | 可聚焦部件的面对环的对比度不到 3:1，该档位却没有规则更换环色（`--xh-_ring-color` / `outline-color` / 聚焦规则中的 `outline` 简写求值后仍是库环）。反之改环色的规则覆盖到非实心档、`:focus-visible` 中关闭环（`outline: none` / `outline-width: 0`）却未登记由谁绘制、绘制实心面却不接焦点也未登记的部件，同样判红；聚焦规则把环色写成透明直接判红，失效档只豁免对比度，环不允许消失。`@supports` 块内的规则按条件成立处理，`@media` 只认几种真实媒体条件为条件块，其余条件块与 `@container` 一律按成立处理；皮肤中给库环令牌链上的名称赋值直接判红 |
| `check-focus-outline-reset` | 皮肤在 `:focus:not(:focus-visible)` 下复位 `outline`（含 `outline-style` / `outline-width` / `outline-color`）。UA 只在 `:focus-visible` 绘制环，这条复位是死代码，而 `outline` 简写会把 `outline-color` 复位成 `currentColor`，描边色一旦进过渡，焦点离开时就闪出一圈近黑描边 |
| `check-overlay-strategy` | 浮层的坐标系在状态机、`connect`、皮肤三处不一致 |
| `check-part-wiring` | 解剖中声明、`connect` 中产出、适配器却未接线的部件。皮肤为它写了规则却匹配不到任何元素 |
| `check-scrollbar-hosts` | 自绘条三端接线不齐、壳缺定位上下文或轨道底色、浮层没把壳记进层分支；皮肤里的滚动面没有登记进 `scroll-surface-registry.json`（或登记过期）、自绘面的轴与浮层 4px 档没接齐、`overscroll-behavior` / `scrollbar-gutter` 写在不该写的面上或该写的面上没写、原生面自己写 `scrollbar-width`、不是壳的部件声明 `--xh-scrollbar-track-bg` |
| stylelint | 常规 CSS 规范，含皮肤不得手写 `scrollbar-width`（`none` 除外）/ `scrollbar-color` |
| 家族门禁（`check-surface-edge` / `check-elevation-role` / `check-selection-marker` / `check-state-ladder` / `check-shape-scale` / `check-press-feedback` / `check-text-role` / `check-family-parity`） | 根面 `border` 颜色位落 `--xh-border-subtle` / `--xh-border-strong`、淡底面带影、ghost 档画边底影、raised 没登记或没带 `--xh-border-default` 描边；选中与当前态没按浮层集合 / 页内集合 / 导航 / 格状 / 开关的唯一标记走；hover / pressed 的底不从语义面派生或阶梯与承载面不符、焦点边不是 `--xh-border-control-focus`；取 circle / pill 的部件没在身份表登记、正方盒用 pill 冒充圆；铺满一行的部件登记成缩放、缩放不换底、集合行零反馈；标签 / 说明 / 标题 / 图标没按角色取令牌；同族成员不同值。存量登在 `tooling/scripts/family-backlog.json`，按门禁分段、一条一句理由，命中即放行、不命中判过期；`check-family-backlog` 用快照与 CEILING 钉住每段条目数，键集合只减不增——迁走一个组件 = 删条目 + 重录快照 + 下调 CEILING |

## 完全自定义皮肤

移除 `@xihan-ui/styles`，只保留令牌（或连令牌一起移除），组件行为不受影响。需要了解的全部接口是：

1. `data-scope` + `data-part`：结构标识，见[组件参考](../components/)中每个组件的解剖；
2. `data-state` / `data-disabled` / `data-readonly` / `data-invalid` / `data-orientation` / `data-highlighted` / `data-side` / `data-align`：状态钩子；
3. 组件自身的语义属性，如 `data-variant`、`data-position`。

两条贯穿全库的取值约定，写全局规则时可以依赖：

- 开合一律编码为 `data-state='open'|'closed'`，与元素上的 `aria-expanded` 同步。
- `role='option'` 的条目一律编码为 `data-state='checked'|'unchecked'`，与 `aria-selected` 同步，条目上不再发出 `data-selected`。
- `data-selected` 只用于结构性选中：树节点、表格行等既非 option、选中态又与展开 / 高亮各自独立的角色。
- 布尔状态为真时属性存在且值为空串，为假时属性缺席，因此选择器写 `[data-disabled]` 即可，不必写 `[data-disabled='true']`。

`data-xh-*` 前缀的属性是内部标记（层栈、集合项、焦点哨兵），不承诺稳定，不要选择它们。

## 相关

- [设计令牌与主题](./theme)：令牌的来源与形状、材质、动效的语义阶梯
- [解剖与部件契约](./anatomy)：`data-scope` / `data-part` 的约定

---

来源：https://ui.docs.xihanfun.com/guide/testing

# 测试与质量门禁

框架无关的组件库最常见的问题是各适配器逐渐偏离。行为写在同一个内核中不代表各端表现一致：写入属性的时机、事件的派发形态、焦点的落点都可能不同。

XiHan.UI 的测试体系首先针对这一点。

## 三套判据

| 入口 | 回答的问题 | 运行环境 |
| --- | --- | --- |
| `@xihan-ui/testing` | 适配器的实现是否符合规格 | jsdom |
| `@xihan-ui/testing/a11y` | 渲染结果是否存在无障碍违规 | 真实 Chromium |
| `@xihan-ui/testing/position` | 浮层最终是否落在屏幕上正确的位置 | 真实 Chromium |

后两套必须在真实浏览器中运行：jsdom 没有布局，无法验证对比度、目标尺寸、翻面与避让。

```bash
pnpm test         # 第一套
pnpm test:browser # 后两套（先 pnpm exec playwright install chromium）
```

在 Windows / macOS 宿主上，`pnpm test:browser` 固定有一条失败：像素基线文件受字体守卫拦截，整文件判失败、40 条用例全部 skipped。这是预期结果，不是环境故障；本地验证像素改动的方式见下文「像素基线」。

### 按分类运行浏览器态

`pnpm test:browser` 由 `ui/tooling/scripts/test-browser.mjs` 执行：先构建各包的依赖，再逐包串行运行（Vue → React → Web Components → 其余），每个包的 worker 数缺省为 `min(8, 核数 - 1)`。每个包各起一套 Chromium，同时运行多个包会在多核机器上拉起上百个页面，占满内存与 CPU。

```bash
pnpm test:browser                    # 全部包、全部用例
pnpm test:browser form overlay       # 只跑这几类（跨包）
pnpm test:browser --list             # 各分类在每个包里的用例数
pnpm test:browser --pkg=vue,react    # 只跑点名的包
pnpm test:browser --workers=4        # 调整每个包的 worker 数
pnpm test:browser --no-build         # 跳过依赖构建
pnpm test:browser overlay -- -t Esc  # -- 之后的参数原样交给 vitest
```

分类与组件总览一致（`ui/scripts/component-docs.manifest.json`）：`general`、`layout`、`navigation`、`form`、`data-display`、`feedback`、`overlay`、`ai`。用例文件名以某个组件名开头（取最长匹配）即归入该组件的分类；浮层主题的跨组件用例（`overlay-*`、各类 Portal、position 引擎）归 `overlay`；其余跨组件用例（全量无障碍、计算样式快照、像素基线、焦点环对账等）归 `shared`。某个包失败不中断其余包，全部跑完后汇总。

### Vue 浏览器态的三个项目

同一个 worker 里的用例文件共用一张页面，仿真状态会从上一个文件带到下一个文件。`vitest.browser.config.ts` 因此把 Vue 浏览器态分成三个项目，按 `sequence.groupOrder` 先后运行：

| 项目 | 收哪些文件 | 为什么单独放 |
| --- | --- | --- |
| `vue-browser` | 其余全部 | 并行主池 |
| `vue-browser-touch` | 调用过 `Emulation.setTouchEmulationEnabled` 或 `coarsePointer()` 的文件，配置加载时自动扫出 | Linux 无头 Chromium 上，一张页面只要关过一次触屏仿真，`(pointer)` 与 `(hover)` 就永久变为 `none`，没有 CDP 入口改回来。挂在 `@media (hover: hover)` 下的悬停规则随之失效，同一 worker 里后续文件的悬停断言与像素基线会随机判红。Windows 上不走这条恢复路径，本机复现不出来 |
| `vue-browser-serial` | `overlay-open-budget.spec.ts` | 量主线程耗时，与整套并行时量到的是别的用例抢走的 CPU，放到最后单独串行 |

媒介仿真（print、forced-colors 等）由 `tests/browser/setup.ts` 在每个文件开跑前复位；触屏仿真不能这样复位，复位本身就会让页面失去悬停能力。

## 一致性：一份规格驱动各适配器

规格（`ConformanceSuite`）声明组件的解剖部件、键盘表与用例；适配器各实现一个 `AdapterHarness`（挂载 fixture 树、获取事件、卸载）。运行器把同一份规格交给不同的 harness，逐帧采集归一化后的 `DomSnapshot` 并断言。

fixture 是框架无关的树：

```ts
interface FixtureNode {
  part?: string; // 解剖 part 名，与 data-part 逐字相同
  tag?: string;
  text?: string;
  attrs?: Record<string, string>; // 业务属性，不含 aria- / data-scope / data-part
  children?: FixtureNode[];
}
```

快照也是归一化的：

```ts
interface DomSnapshot {
  parts: Record<string, PartSnapshot[]>; // part 名 → 全部实例（文档序）
  order: string[]; // 文档序，集合项带下标：['trigger', 'content', 'item[0]']
  activeElement: ActiveElementRef | null; // 焦点落在哪个 part、是否恰为该元素本身
  events: AdapterEvent[]; // 自上一帧起适配器对外派发的事件
  strayParts: string[]; // 带 data-scope 却不属于任何声明 part 的元素
}
```

### 五条契约不变量

这套判据依赖五条约束：

1. 规格零框架：套件只从 `@xihan-ui/core` / `@xihan-ui/headless` 取纯数据（解剖、键盘表、类型），不 import 任何框架；
2. 只断言归一化快照：断言对象只能是 `DomSnapshot`，不接触组件实例、内部 ref、`shadowRoot`；
3. 快照适配器无关：id 的具体值、`data-v-*` 等适配器痕迹在采集阶段抹除，IDREF 属性翻译为 `@part(...)`。无法抹除的差异即抽象泄漏；
4. 单实例文档：同一时刻文档内只有一个 harness 的一个挂载实例，卸载后该 scope 不得残留节点；
5. 状态断言归纯逻辑层：harness 不暴露当前状态机状态，`settle` 只等待可观察的 DOM 事实。

第 3 条是关键：适配器之间的差异无法在归一化中抹除，说明抽象存在泄漏，应修改的是库而不是测试。

### 分母外化

键盘规格表是可达性的分母。用例通过 `covers` 字段反查行 id，缺一行即套件失败。

键盘测试只能通过补充用例通过，不能修改分母。

## 无障碍

把一致性套件的 fixture 挂载到真实 Chromium，对初始态与各用例终态运行 axe，终态按形态签名去重。

存量违规登记在 `tooling/testing/src/a11y/known.ts`：命中已登记的规则不判失败，但一条都不再命中时判定登记过期：修复后必须从表中删除，不保留已不成立的豁免。当前登记的清单见[无障碍与键盘规格](./a11y#存量违规登记表)。

## 浮层定位

`runPositionEngine(engine, hooks, name)` 是一份引擎无关的契约：判据只认浮层最终出现在屏幕的位置，两个矩形都取视口坐标，因此不关心包含块关系与中间的 transform 层数。更换定位引擎实现后同样适用。

覆盖：十二种 placement 的贴边与对齐、offset、翻面与交叉轴避让（各配一条关闭后应当溢出的对照）、虚拟锚点、缩放与 transform 容器、文档滚动、容器滚动跟随、裁剪后的 `hidden`、尺寸变化重算、静置不空转、停止跟随后不再回调。

## 像素基线

计算样式不一致会被令牌快照拦截，结构错位会被一致性套件拦截，但值全部正确、外观仍然不同这一档没有其他判据覆盖：层叠顺序、私有槽的覆盖时机、两条规则的先后，只在最终位图上显现。像素基线负责这一档。

受管范围是母组件 `button` / `text-field` / `select` / `menu` / `popover` / `dialog` / `drawer` / `toast`，每件在五组轴上各出一张：`light×comfortable`、`dark×comfortable`、`light×compact`、`dark×compact`、`dark×more`。前四格是主题与密度的笛卡尔积；第五格是层叠最脆弱的一格：两块 `contrast` 取值块必须排在两个 `mode` 块之后，顺序错误即静默回归。`motion=reduce` 不在其中：静止帧与默认档没有差别，该轴由令牌快照与 `check-infinite-motion` 承担。

基线文件在 `packages/adapters/vue/tests/browser/__screenshots__/` 下，具体数量以该目录为准。

### 必须在容器中生成的原因

基线比对的是逐像素的位图。字体、字形栅格化与子像素平滑在 Windows 与 Linux 上不同，同一份 CSS 在两边渲染出的位图不同：在开发机上生成的基线，CI 上无法匹配。

字体是最大的不确定性：全库皮肤写的是 `font-family: inherit`，没有 sans 字体令牌，字体最终取文档根上的值。截图用例因此把根上的字体族按名字固定为 `DejaVu Sans`，不交给环境默认的 `sans-serif` 解析。因此基线的成立条件不止 Linux，还包括 `DejaVu Sans` 这个名字可以解析到，即安装了 `fonts-dejavu-core`：CI 的 `browser` job 中有一步专门安装它，删除该步骤基线会整体判红。

反过来，环境中多安装字体不影响基线：字体族按名字确定，默认 `sans-serif` 落到 Noto Sans 或其他字体，画面不变。核对字体时核对的是这个名字（`fc-match 'DejaVu Sans'`），不是默认 `sans-serif`。

```bash
pnpm visual:baseline            # 校验：与库里的基线逐像素比对
pnpm visual:baseline --update   # 生成 / 更新基线并写回库里
```

两条都在 `mcr.microsoft.com/playwright:v1.62.0-noble` 中运行，与 CI 使用同一套渲染栈。首次运行前先 `docker pull` 该镜像；镜像版本必须与 `pnpm-workspace.yaml` 中 `playwright` 的版本一致，浏览器二进制才配套。

运行器把仓库同步到容器内的工作副本再安装依赖，不使用宿主的 `node_modules`：宿主安装的是 win32-x64 原生二进制，容器内无法运行，而在容器内安装会覆盖宿主的副本。pnpm store 与工作副本都落在一个命名卷上，重复运行不重复安装。

校验模式下基线目录不挂载进容器，容器无法写入。修改基线只能显式使用 `--update`。

比对失败时，实际截图与差异图输出到 `packages/adapters/vue/.vitest-attachments/`（不入库）。CI 上同一批文件作为 `visual-diffs` artifact 输出，可下载逐张查看。

### 本地运行方式与固定失败项

`pnpm visual:baseline` 是本地唯一有效的入口，不使用宿主的渲染栈：源码同步进容器、依赖在容器内安装、用例在容器内运行，因此 Windows 与 macOS 上的结果与 CI 逐像素一致。前置条件只有 `docker pull`。

直接运行 `pnpm test:browser` 时，像素基线文件整文件判红：字体守卫在 `beforeAll` 中抛错，40 条用例全部 skipped，不生成任何位图，也不会在 `__screenshots__/` 下留下带 `-win32` 后缀的文件。在宿主上安装 DejaVu 无法解决：字体只是差异之一，字形栅格化与子像素平滑仍与 Linux 不同，比对结果没有意义。这条失败是预期结果，同一批浏览器态用例中的无障碍与浮层定位在宿主上照常通过。

修改皮肤的工作方式：

- 本地 `pnpm visual:baseline` 查看本次改动影响的截图，差异图在 `.vitest-attachments/` 下逐张打开；
- PR 的判据是 CI 的 `browser` job，本地 `pnpm test:browser` 的固定失败项可以忽略；
- CI 失败时先下载 `visual-diffs` artifact 查看，确认是有意的视觉改动，再 `pnpm visual:baseline --update` 重新生成基线并提交。

字体族名、安装它的 apt 包、容器镜像与运行命令分散在用例、容器脚本、CI 与本页中，任何一处不一致都只表现为四十张整体判红。`check-visual-baseline-env` 把四处对齐，并核对镜像版本与 `pnpm-workspace.yaml` 中 `playwright` 的版本一致、CI 的 `browser` job 中安装字体的步骤排在运行用例之前。

### 基线变更必须经人工审阅

基线的更新是无声的：`git diff` 只显示二进制文件变化，看不出变成了什么。任何人都可以 `--update`，把一次真实的视觉回归记录为新基线。

因此规则是：PR 中凡有 `__screenshots__/` 下的改动，作者必须逐张说明变更原因，审阅者必须打开图片查看。改动张数与改动理由不一致的 PR 不合并。

基线文件名带浏览器与平台后缀（`…-chromium-linux.png`），入库的只有 `linux` 一套。带其他平台后缀的文件不应出现（字体守卫会在生成之前拦截用例），出现时直接删除，不提交。

## 视觉样板性能预算

`pnpm visual:performance` 在与像素基线相同的 Playwright Linux 镜像中运行真实 Chromium，并把报告写到
`ui/packages/adapters/vue/.vitest-attachments/visual-performance.json`。这条用例不另建展示页：它直接复用
`visual-baseline.spec.ts` 的 Dialog `variant="blur"` 夹具与 800×520 视口，在对话框后方逐帧移动固定渐变背景，
让 `backdrop-filter` 参与真实合成。默认透明与 `data-transparency="reduce"` 交替采样，避免先后顺序把机器热态集中到某一档。

设备档固定为 `mcr.microsoft.com/playwright:v1.62.0-noble`、Chromium、800×520@1x、2 CPU、2 GiB，
并通过 CDP 对渲染进程施加 4× CPU throttle。每档先预热 30 帧，再采 120 帧，重复三轮。预算真源是
`tooling/scripts/visual-performance-budget.json`；容器镜像版本继续与 `pnpm-workspace.yaml` 的 Playwright catalog 对齐。

报告与门禁包含：

- `requestAnimationFrame` 相邻回调的 p50 / p95 / 最大间隔；每帧都会改变背景绘制位置，这个间隔包含该帧排队、样式、绘制与合成对下一帧的影响，不把纯 JS 计时冒充 GPU 时间；
- W3C Long Tasks `PerformanceObserver` 给出的长任务数量、最大值与合计时长；
- 每个可见且计算样式含 `blur(...)` 的 `backdrop-filter` 元素，在视口内裁切后的面积之和。重叠材质逐层计数，因为每一层都要独立取样；`reduce` 档必须严格为 0；
- 10 次交替挂载/卸载后，强制 GC 前后的 CDP `Memory.getDOMCounters` 差值，作为 documents / DOM nodes / JS listeners 的资源留存代理。

这里不输出伪内存数。浏览器目前没有稳定的标准轨页面内存 API；候选
`measureUserAgentSpecificMemory()` 仍是 WICG 草案，且要求跨源隔离。测试页不为获取一个数字而伪造隔离条件，
报告如实记录候选 API 与 `crossOriginIsolated` 状态，并用上述 DOM 资源留存代理监测泄漏。长任务定义见
[W3C Long Tasks](https://www.w3.org/TR/longtasks-1/)，内存候选 API 的标准状态见
[WICG Measure Memory](https://wicg.github.io/performance-measure-memory/)。

第一次建立或有意重定预算时，必须先运行：

```bash
pnpm visual:performance --record
```

`--record` 只写真实报告、不判断 `limits`。至少检查一份完整报告后，才按实测值与明确余量修改预算真源；常规
`pnpm visual:performance` 执行红线。CI 运行后者。像素基线仍由 `pnpm visual:baseline` 守护，本项不自动更新任何 PNG。

包体积不在性能 JSON 里复制数字：JavaScript / 发布产物继续由 `.size-limit.json` 与 `pnpm size` 守护，逐皮肤 CSS
继续由 `.size-limit.css.json` 与 `check-skin-size` 守护。性能预算门禁反查这两份真源；修改本项不得提高既有阈值。

## 结构门禁

结构检查按职责分成十个模块，脚本放在 `ui/tooling/scripts/<模块>/` 下，执行顺序由 `ui/tooling/scripts/gate.modules.mjs` 决定。每一步都是独立子进程，串行执行：

```bash
pnpm gate                    # 全部模块，遇到第一处失败即停（CI 运行这一条）
pnpm gate overlay motion     # 只跑点名的模块
pnpm gate --list             # 列出模块、中文名与步数
pnpm gate --keep-going       # 失败不停，跑完汇总失败的步骤；可与模块名同用
```

| 模块 | 管什么 |
| --- | --- |
| `package` | 运行时依赖、版本锁步、包清单与角色、子路径导出、发布产物 |
| `tokens` | 令牌产物、令牌引用、字面量与兜底、语气层、层序与层号 |
| `skin` | 皮肤入口与标记、解剖对齐、收起态、视觉轴、打印 / 高对比 / 安全区等环境档 |
| `visual` | 形状、间距、描边、字号、海拔、交互阶梯、控件与面板尺寸、字形、家族配方与按压反馈 |
| `overlay` | 浮层坐标系、可用空间、定位层、遮罩、箭头、落点与自绘滚动条 |
| `motion` | 关键帧、时长与缓动、幅度、减弱动效、动效覆盖面 |
| `a11y` | 聚焦环、焦点复位与上报、ARIA 写法、按键重复与键盘套件 |
| `adapter` | 部件接线、状态与部件词汇、插槽与翻译、全局配置、三端计算样式一致、组件落点 |
| `docs` | 示例的多框架对齐、令牌与动效、文档数字与导入、组件总览 |
| `repo` | changeset、提交 scope、发版标签、PR 模板、类型检查覆盖面、文件头、脚本接线 |

改了哪一块先跑对应模块，提交前再跑一次全量。

`pnpm gate` 运行 128 项结构检查，它们检查的是判据无法覆盖的问题：静默失效、悬空承诺、未被命名的决策：

| 门禁 | 拦截内容 |
| --- | --- |
| `check-runtime-deps` | 库包的运行时依赖引入了未登记的第三方 |
| `check-exact-pins` | 库包依赖内联了版本号（只允许 `catalog:` / `workspace:`） |
| `check-tokens-dist` | 令牌产物未入库 |
| `check-overlay-strategy` | 浮层坐标系在机器 / `connect` / 皮肤三处不一致 |
| `check-token-refs` | 皮肤引用了不存在的令牌名（整条声明会静默失效） |
| `check-tone-tokens` | 语气轴对外的 `--xh-tone-*` 没声明在语气层的 `[data-tone]` 上，或与私有槽的取值分叉 |
| `check-chart-palette` | 图表数据色在亮色或暗色下不过色板检查：分类色的明度带、对比度、相邻与任意两色的色差、色觉障碍分离、色相分散与离开告警色，以及有序、顺序、发散、涨跌色阶的结构 |
| `check-shared-slots` | 同一字面量在多个组件中作为默认值，却未建立语义令牌 |
| `check-motion-easing` | 皮肤的缓动下探到 `--xh-ease-*` 原语、手写 `cubic-bezier()`，或使用了未登记的字面曲线 |
| `check-motion-amplitude` | 位移与缩放的幅度写成字面量（减弱动效档把 `--xh-motion-distance-*` 压成 `0px`、`--xh-motion-scale-*` 压成 `1`，写死的位置无法压缩）；居中用的百分比与 `0` / `1` 是几何，不在此列 |
| `check-disabled-contrast` | 禁用态前景色令牌上叠加 `opacity`，对比度被压到无法阅读 |
| `check-color-literals` | 颜色写死在 `background` 简写、`box-shadow` 颜色位或 `--xh-*` 槽赋值中：stylelint 的六个长属性白名单不覆盖这些位置 |
| `check-print-surface` | 浮层定位层 / 遮罩 / 滚动条 / 固定在视口上的节点在打印时未收起，或投影未由令牌层取消 |
| `check-placeholder-fg` | 占位文字两条通道（`::placeholder` 与 `[data-placeholder]`）取了不同的默认前景，或用 `opacity` 表达深浅 |
| `check-autofill` | 渲染原生表单控件的输入框未写自动填充规则，或两种手段 / 两个引擎的选择器缺一 |
| `check-part-wiring` | 解剖声明、`connect` 产出、适配器却未接线的部件 |
| `check-dead-state-attr` | `connect` 发出的 `data-*` 在本组件的作用域中没有任何规则消费：其他组件的同名规则不计入，该规则永远无法选中它。信息钩子逐条登记，登记项过期同样判失败 |
| `check-skin-parts` | 皮肤选择器中的 `[data-part]` 不在所属 scope 的解剖中：部件退役后遗留的规则永远无法选中节点，`surface:update` 还会把它的覆盖槽收回公开面。scope 按选择器计算（逐分支、逐复合：写在 `[data-part]` 前后的 `[data-scope]` 都约束这一节，未写的沿用左侧最近一节，`:is()` / `:where()` 中一致的 scope 带回外层，`:not()` / `:has()` 中各自计算），解剖外的名字逐条登记，登记项过期同样判失败；`data-scope` / `data-part` 的属性选择器无法读取的（转义、匹配符不是全等）同样判失败 |
| `check-breakpoints` | 皮肤 `@media` 中的断点字面量不在令牌清单中（自定义属性在媒体条件中不生效，只能写字面量）；查询用了 `max-width` / `max-height` 上界写法：它在断点值上与 `min-width` 同时成立，窄档专属规则写补集 `not all and (min-width: …)` |
| `check-focus-ring` | 聚焦环的粗细、颜色、偏移写了字面量而不是令牌，主题与全局调整对它无效 |
| `check-focus-ring-surface` | 可聚焦部件的面与环的对比度不足 3:1（按计算结果，不按形态推断），该档却未把 `--xh-_ring-color` 设为 `currentColor`：键盘焦点在该面上等于未绘制。`currentColor` 覆盖到非实心档、`:focus-visible` 中关闭环（`outline: none` / `outline-width: 0`）却未登记环由谁绘制、绘制实心面却不接焦点也未登记的部件，同样判红；聚焦规则把环色写成透明的直接判红，没有登记表 |
| `check-focus-outline-reset` | 皮肤在 `:focus:not(:focus-visible)` 下复位 `outline`（含 `outline-style` / `outline-width` / `outline-color`）。UA 只在 `:focus-visible` 绘制环，这条复位是死代码，而 `outline` 简写会把 `outline-color` 复位成 `currentColor`，描边色一旦进过渡，焦点离开时就闪出一圈近黑描边 |
| `check-exports` | 已实现却未从包级入口导出，包外无法获取，而构建与类型检查照常通过 |
| `check-package-roles` | 包所在的角色组与其 `package.json` 中的依赖声明不一致 |
| `check-public-surface` | 公开面基线中有而当前没有的名字：被删除或改名 |
| `check-visual-performance-budget` | 固定设备、默认/reduce 场景、真实浏览器入口与既有 JS/CSS 体积真源任一脱节 |
| `check-material-scope` | liquid 落在没登记的部件上：连接层投影 `data-xh-liquid` 的部件、皮肤里与 `[data-xh-liquid]` 写在同一个复合选择器上的部件，都必须是登记过的导航层（浮动钮、媒体控制、悬浮栏），每条写明它浮在什么之上；过期的登记同样判失败 |
| `check-changeset-packages` | changeset 头部写了 `.changeset/config.json` ignore 表里的私有包（如 `@xihan-ui/testing`）或不在工作区的包：前者与发布包混写时 `changeset version` 直接报 Mixed changesets，只写它时整份被丢掉、正文进不了 CHANGELOG；后者报 not in the workspace。不依赖 git 基线，头部读不成「包名: 档位」也判红 |
| `check-surface-edge` / `check-selection-marker` / `check-state-ladder` / `check-text-role` 与扩展后的 `check-elevation-role` / `check-shape-scale` / `check-press-feedback` / `check-family-parity` | 七条家族门禁：根面边界三选一、选中与当前态按语义分类、交互态按承载面阶梯、排版与图标按角色、raised 逐部件登记且必带描边、形状身份表、按压几何与换底、同族同值。尚未迁移的存量登在 `tooling/scripts/family-backlog.json`，每条必须真被放行过一次（登记了却没命中判过期），`check-family-backlog`（`gate:family` 里的 `family-backlog.spec.mjs`）把每段条目数钉在快照与 CEILING 上、键集合只许是快照的子集——表只减不增 |

另有分层依赖检查与十二项单独的门禁：

```bash
pnpm boundaries   # 分层依赖 + 禁循环 + styles 不依赖 JS + 库包不引入第三方
pnpm gate:tokens  # 重新运行令牌生成后比对，修改源文件未运行生成会被拦截
pnpm gate:styled  # 重新生成皮肤的无层版产物后比对
pnpm gate:cem     # 重新生成自定义元素清单后比对
pnpm gate:docs    # 重新生成组件文档页后比对
pnpm gate:exports # 重新生成子路径导出后比对 package.json
pnpm gate:surface # 公开面基线：基线中有而当前没有的名字判失败
pnpm gate:demos   # 在真实 Chromium 中运行文档站的自定义元素示例
pnpm gate:demo-types # 文档站 React 示例逐份类型检查（读 icons 的 dist，先 build）
pnpm gate:publish # 逐包运行 publint 与 attw，校验 exports 条件与类型解析
pnpm gate:llms    # 文档站的机读资产：页数、组件数、令牌数与库对账，示例不得保留站点标签
pnpm gate:family  # 逐家族豁免表只减不增（条目数快照 + 键集合子集），并用临时夹具证七条家族门禁会红
```

`gate:llms` 读取文档站的构建产物，运行前先在 `docs/` 下运行一次 `pnpm build`。

文档站是独立工作区，lint 也独立，在 `docs/` 下运行 `pnpm lint`。示例语料的引号与分号与库源码相反，规则固定在 `docs/eslint.config.js` 中：示例供使用者复制，不跟随库源码的写法。

`gate:publish` 按包声明的支持面校验：ESM-only、`engines.node >= 18`，不提供 CJS，也不承诺 node10 的旧式解析。

## 体积棘轮

```bash
pnpm size
```

40 条产物各有上限（gzip 后），超出即失败。预算一律按实测留一成余量。逐条限额的真源是 `ui/.size-limit.json`，具体数字以该文件为准。


## 相关

- [无障碍与键盘规格](./a11y)
- [浮层定位](./position)
- [架构总览](../overview#分层与依赖矩阵)

---

来源：https://ui.docs.xihanfun.com/guide/theme

# 设计令牌与主题

`@xihan-ui/tokens` 提供两部分能力：**设计令牌**（一份 CSS 自定义属性产物）与**主题运行时**（将用户偏好解析为根元素上的属性）。它位于依赖图的第一层，不依赖其他包。

## 令牌的两层

```
primitive  ──►  semantic  ──►  组件私有槽
调色板本身      有语义的角色      单个组件的覆盖点
```

**primitive**：与场景无关的原始值，在任何作用域都不变，只声明一次。

```css
--xh-color-brand-500: oklch(0.623 0.214 258);
--xh-color-neutral-950: oklch(0.145 0.005 258);
--xh-space-4: 16px;
--xh-radius-md: 8px;
```

颜色使用 `oklch` 而不是 `hex` / `hsl`：同一明度的不同色相在感知上亮度一致，深色反转与对比度调整不需要逐色手工修正。

**semantic**：带语义的角色，指向 primitive。皮肤只能消费这一层。

```css
--xh-bg-canvas: var(--xh-color-neutral-0);
--xh-bg-surface: var(--xh-color-neutral-0);
--xh-bg-brand: var(--xh-color-brand-600);
--xh-fg-default: var(--xh-color-neutral-950);
--xh-fg-muted: var(--xh-color-neutral-600);
--xh-border-subtle: var(--xh-color-neutral-100);
--xh-control-h-md: 36px;
--xh-shape-control: var(--xh-radius-sm);
--xh-elevation-floating: var(--xh-shadow-md);
--xh-motion-duration-enter: var(--xh-duration-normal);
--xh-layer-modal: var(--xh-z-modal);
--xh-overlay-max-w: 20rem;
```

语义层按角色分组：`bg-*` 背景、`fg-*` 前景、`border-*` 描边、`control-*` 控件尺寸、`shape-*` 形状、`ring-*` 焦点环、`elevation-*` 海拔、`motion-*` 时长与缓动、`layer-*` 层级、`overlay-*` 浮层尺寸、`text-*` 排版。

令牌源是 DTCG 格式的 JSON（`packages/design/tokens/tokens/`），产物由构建脚本生成，`tokens.css` / `tokens.json` / `src/generated/tokens.ts` 三份都入库。CI 会重新生成并比对产物，源与产物不同步时构建失败。

## 形状阶梯

圆角只有一套语义阶梯，组件不写独立圆角值。

| 令牌 | 值 | 用途 |
| --- | ---: | --- |
| `--xh-shape-inset` | 4px | 嵌在控件里的内层：菜单项、标签内部、微型状态块 |
| `--xh-shape-control` | 4px | 控件本体：Button、Input、Select Trigger、Toggle、分页按钮 |
| `--xh-shape-surface` | 8px | 成面的静态容器：Card、Alert、Panel、列表容器、Segmented 与 Tabs 轨道 |
| `--xh-shape-overlay` | 12px | 脱离文档流的浮层：Popover、Menu、Dialog、Drawer、Toast |
| `--xh-shape-circle` | 50% | 正圆：头像、圆形图标按钮、单选指示器 |
| `--xh-shape-pill` | 9999px | 胶囊：Badge、Tag 等状态 chip，以及轨道、指示条、手柄、滚动条滑块等一维对象 |

普通按钮、字段、卡片与浮层不使用 pill；内层圆角不超过外层圆角减去内边距；相连控件消除相接侧圆角。亮色、暗色与紧凑密度不改变形状身份。正方盒取 circle，不用 pill 冒充圆。

## 点击触感

离散操作控件（Button、Toggle、图标按钮、分页按钮、工具栏按钮）共用一套按压时间线：

| 阶段 | 时长 | 缓动 | 结果 |
| --- | ---: | --- | --- |
| 按下 | `--xh-motion-duration-press`（120ms） | `--xh-motion-ease-press` | scale 1 → `--xh-motion-scale-press`（0.97），背景进入 active |
| 释放 | `--xh-motion-duration-release`（200ms） | `--xh-motion-ease-release` | scale 回到 1，背景回到 hover / rest |

Menu Item、Listbox Item、Tree Node、Table Row 等集合项与 Accordion / Collapsible 等 disclosure trigger 使用同一节奏，但只切换表面，不缩放整条，也不允许零反馈。减少动效时 `--xh-motion-scale-press` 归 1、两段时长归 1ms，颜色反馈保留。

## 组件内滚动

滚动条形态只有两档，按滚动面的身份固定，不按组件各自决定：

| 档 | 适用面 | 令牌 |
| --- | --- | --- |
| 自绘条（Scrollbar 组件接线） | Overlay 家族 positioner 下的 content / list / column；定高小列表（Listbox content、Transfer list、时间列、Cascader column） | `type` 默认 `scroll-hover`；厚度浮层 `--xh-scrollbar-thickness-sm`（4px）、页内 `--xh-scrollbar-thickness-md`（6px）；壳上 `--xh-scrollbar-track-bg: transparent` |
| 原生细条 | 页内结构容器（Table、Tree、Transfer 面板、Virtualizer viewport、Dialog / Drawer / FloatingPanel body、Layout sider / content、SideNav popout、Log / MessageFeed 视口、日历年网格、Typography `pre`）与作者自建滚动容器 | reset 层 `:where([data-scope][data-part], [data-xh-scroll])` 统一给 `scrollbar-width: thin` + `scrollbar-color: var(--xh-fg-scrollbar-thumb) var(--xh-bg-scrollbar-track)` |

滑块色阶维持三级：`--xh-fg-scrollbar-thumb` / `-hover` / `-active` 分别是前景色 15% / 25% / 35%，两档共用。作者自己的滚动容器加 `data-xh-scroll` 即得同一套细条，写法与边界见[皮肤与样式分层](./styling#组件内滚动)。

边界行为按身份给：`overscroll-behavior: contain` 只给浮层滚动面、模态 body 与粘底视口，页内结构容器保持 `auto`；`scrollbar-gutter: stable` 只给内容高度动态变化的容器（Log、MessageFeed、Dialog / Drawer body），并带 `:not([data-xh-scrollbar])` 守卫；边缘渐隐只在 ScrollArea 的 fade 变体与 Marquee 提供。文档站页面滚动条与组件滚动条同一 `type`，不另写覆写。

## 排版角色

`text-*` 排版令牌按角色取用，层级由字号、字重、行高和间距共同表达，不能只调颜色：

| 角色 | 字号 / 字重 / 颜色 | 与相邻元素的间距 |
| --- | --- | --- |
| 字段标签（单字段与 Slider、Rating、Signature、Color* 等复合单字段） | `--xh-text-label-size` 14 / `--xh-text-label-weight` 500 / `--xh-fg-default` | 贴控件 `--xh-space-1` |
| 集合标题（RadioGroup、CheckboxGroup、Listbox、Tree、TagGroup、Descriptions） | 14 / 500 / `--xh-fg-muted` | 与集合 `--xh-space-2` |
| 说明 / helper | `--xh-text-secondary-size` 13 / `--xh-fg-muted` / `--xh-leading-normal` | 与控件 `--xh-space-1` |
| 错误文案 | 13 / `--xh-fg-danger` | 与控件 `--xh-space-1` |
| Surface / Feedback / 浮层内标题 | 14 / `--xh-font-weight-semibold` | — |
| 页面级面板标题（Dialog、Drawer、Tour） | heading-3（`--xh-text-heading-3-*`） | — |
| 次级标注（计数、快捷键、时间戳、序号） | `--xh-text-caption-size` 12 | — |

必填星号与错误文案是公共层规则：`--xh-glyph-mark-required` + `--xh-space-1` + `--xh-fg-danger`，自带标签的字段不各画一套；禁用标签色统一 `--xh-fg-subtle`，单行标签 `--xh-leading-none`。控件内图标随 size 档取 `--xh-glyph-size-sm / md / lg`（16 / 20 / 24）；`--xh-glyph-size-text`（随文 1em）只给 Tag、Kbd、Breadcrumb、Typography、Highlight 这类纯行内文字组件。

## 八轴视觉环境运行时

`VisualEnvironmentController` 是 mode、brand、density、dir、contrast、motion、transparency、material 的唯一状态与 DOM 投影入口。一次 `setPreference` 同步提交同一 scope 的完整八轴：

```ts
import { setMotionOverride } from "@xihan-ui/motion";
import {
  brandId,
  createMotionOverrideSink,
  createVisualEnvironmentController,
} from "@xihan-ui/tokens/runtime";

const visual = createVisualEnvironmentController({
  root: document.documentElement,
  storageKey: "app-visual-environment",
  onStorageError: detail => reportStorageFailure(detail),
  motionSink: createMotionOverrideSink(setMotionOverride),
  initial: {
    mode: "system",
    brand: brandId("xihan"),
    density: "comfortable",
    dir: "ltr",
    contrast: "system",
    motion: "system",
    transparency: "system",
    material: "standard",
  },
});

visual.setPreference({ mode: "dark", density: "compact" });
visual.getState();
visual.subscribe(state => console.log(state));
visual.dispose();
```

启用 `storageKey` 必须同时给 `onStorageError`。解析失败、隐私模式或配额不足会明确回调；控制器继续维护内存状态，但不会把持久化失败伪装成成功。

根控制器的 `motionSink` 是显式依赖注入：它把解析后的 motion 同步到 Presence、平滑滚动和 JS 动画。只有 `documentElement` 根作用域允许传；局部控制器只改当前 DOM scope，不能隐式污染全局 JS override。

八轴状态会投影成 Portal 可桥接的完整属性面：

```html
<html data-theme="dark" data-brand="xihan" data-density="compact" data-contrast="more" data-motion="reduce" data-transparency="reduce" data-material="liquid" dir="rtl">
```

## 偏好、状态与系统轴

| | `VisualEnvironmentPreference` | `VisualEnvironmentState` |
| --- | --- | --- |
| 含义 | 用户或服务端提交的意图 | 已完全定型的事实 |
| `undefined` | 清除本层覆盖，继承父控制器 | 不存在，八轴全部非空 |
| `'system'` | 仅 mode / contrast / motion / transparency 合法 | 不存在，已解析成具体值 |

brand、density、dir、material 没有平台媒体查询，因此不接受伪造的 `system`。其余四轴分别读取 `prefers-color-scheme`、`prefers-contrast`、`prefers-reduced-motion`、`prefers-reduced-transparency`。没有 `window` / `matchMedia` 的 SSR 环境使用浅色、默认对比度、默认动效和默认透明度，不猜测客户端偏好。

基线八轴为 light、xihan、comfortable、ltr、default、default、default、standard。`contrast='default'` 是显式恢复常规对比度的正式值；旧的 `base` 不再接受。

| DOM 轴 | 说明 |
| --- | --- |
| `data-theme` | 明暗两值各有整套语义取值 |
| `data-brand` | 注册品牌梯度后切换品牌色 |
| `data-density='compact'` | 收紧控件高度、内距与间隙，不缩字号和字形 |
| `dir` | 由逻辑属性驱动 LTR / RTL 布局 |
| `data-contrast` | `more` 加强边界；`default` 显式回到常规档 |
| `data-motion` | `reduce` 触发局部 CSS 动效降级 |
| `data-transparency` | `reduce` 把磨砂材质切成实体配方 |
| `data-material` | `liquid` 让浮在内容之上的导航层部件（浮动钮、媒体控制、吸顶顶栏）换成液态面；`standard` 保持原材质，最近的祖先生效 |

## 父作用域、Portal 与回收

局部控制器通过 `parent` 明确继承。父状态变化时，子控制器只重算没有本地偏好的轴；`setPreference({ motion: undefined })` 会删除本层覆盖，立即恢复继承。dispose 会退订父作用域和系统媒体，并把根元素八个属性精确还原到接管前。

```ts
const page = createVisualEnvironmentController({
  root: document.documentElement,
  initial: { mode: "dark", motion: "system" },
});
const editor = createVisualEnvironmentController({
  root: document.querySelector("#editor")!,
  parent: page,
  initial: { density: "compact", transparency: "reduce" },
});
```

React / Vue 的 `XhConfigProvider` / `provideXhConfig` 通过 `config.visualEnvironment` 接受带显式 root 的控制器选项；嵌套 Provider 自动接父控制器。Web Components 的 `<xh-config>` 自身就是局部 scope，可直接设置 `mode`、`brand`、`density`、`direction`、`contrast`、`motion`、`transparency`、`material`。物理 Portal 仍由 Core 的 VisualBridge 桥接已解析八轴，适配器不另存一份视觉状态。

## 五轴旧视图

`createThemeController`、`resolveTheme` 与 `applyThemeAttrs` 继续存在，但只是新控制器的明确五轴视图：没有独立 resolver、媒体查询或持久化实现。新代码应使用八轴控制器；独立的 `applyThemeAttrs` 只写五轴，控制器则始终维护完整八轴 DOM 合同。

`color-scheme` 声明写在深色取值块里，所以嵌套深色区域的原生控件也会跟随。SSR 首屏应直接输出八个已解析属性，避免客户端接管前闪烁。

## 材质配方

令牌配方五档，每档都提供同名九项令牌：`bg`、`backdrop`、`border`、`highlight`、`shadow`、`separator`、`fg`、`fg-muted`、`focus-surface`；M5 liquid 另有五项专用令牌。透明的磨砂面只允许用于瞬态浮层；不提供玻璃材质，也不提供任何兼容别名。另有 raised / floating 两个由海拔令牌组成的叠加档：它们没有 `--xh-material-*` 令牌，只能写成 solid 描边 + solid 底 + 对应海拔的组合。

| 编号 | 令牌 | 用途 | 光学 |
| --- | --- | --- | --- |
| M0 solid | `--xh-material-solid-*` | 静态内容面缺省：border-default 描边 + surface 底 + 无影；字段静息同为描边式 | 实体底色，无高光、无投影 |
| M1 soft | `--xh-material-soft-*` | Button soft、Tag、Popconfirm 动作等次级操作；不用于 Card 与字段 | 实体底色，细微顶光与两段接触投影，无背景模糊 |
| M2 frosted | `--xh-material-frosted-*` | 短列表、菜单、tooltip、气泡等需要透景的锚定瞬态浮层；含网格或多列的锚定面板改用 solid + border-default + `--xh-elevation-floating` | 0.88 不透明度，16px 模糊，108% 饱和度，1px 可见边界 |
| M4 elevated | `--xh-material-elevated-*` | Dialog、Drawer、Command、Tour、Toast、Notification 等模态与强反馈面（sheet），必有 1px 描边 | 完全不透明，无背景模糊，三层高层投影 |
| M5 liquid | `--xh-material-liquid-*` | 只在 `data-material="liquid"` 下出现：浮在内容之上的导航层——浮动钮（FloatButton、BackTop、MessageFeed / Log 的回到底部）、媒体控制（Carousel 控制钮与分页条、ImageViewer 控制层）、吸顶的 Layout 顶栏 | 可读下限浅 0.48 / 深 0.61 不透明度，8px 模糊，140% 饱和度，墨色细线 + 1px 边缘光，Chromium 下边缘折射 |
| raised（叠加档） | solid 描边 + solid 底 + `--xh-elevation-raised` | Card 与可抬起 / 可拖起部件（Segmented、Tabs segment 的滑块，静止的滑杆拇指等），逐部件登记；描边必须在，影只是加成，只有可交互时允许 hover 抬升 | 实体底色，一层低海拔投影 |
| floating（叠加档） | solid 底 + `--xh-border-default` + `--xh-elevation-floating` | 含网格或多列的锚定面板：NavigationMenu content、Date / Time / DateRange / TimeRange picker content | 实体底色，不透景，中海拔投影 |

| 后缀 | 用途 |
| --- | --- |
| `bg` / `backdrop` | 底色 / 背景滤镜 |
| `border` / `highlight` / `shadow` | 外边界、顶部高光与投影 |
| `separator` | 内部分段线 |
| `fg` / `fg-muted` | 正文与次要文字，始终不透明 |
| `focus-surface` | 键盘聚焦时铺在焦点环内侧的实体隔离底 |

M2 frosted 在库里只有一份实现：材质家族配方 `@xihan-ui/styles/material.css`。组件在部件上投影 `data-xh-material="frosted"`，锚定浮层的内容面由配方画描边、底、1px 顶光、前景、投影与背景滤镜；浮动钮的面归 Action Control，由配方给交互阶梯（悬停 / 按下换不透明淡底一档、二档，键盘聚焦铺 `focus-surface`）。自定义的浮层面写同一个属性即可接入，用 `--xh-frosted-bg`、`--xh-frosted-border`、`--xh-frosted-fg`、`--xh-frosted-shadow`、`--xh-frosted-backdrop`、`--xh-frosted-highlight` 覆盖。

Card 只有三档形态：`outline`（缺省，solid 描边 + surface 底 + `--xh-elevation-raised`）、`subtle`（`--xh-bg-subtle` + 透明占位边 + 无影）、`ghost`（不写边、底与影，只允许分隔线）。边界只由描边承担，阴影与淡底都不作为边界。

环境轴在同一令牌名上原位降级：高对比档提高不透明度并加强边界；减少透明度与打印改为实体底并关闭背景滤镜；强制色改由 `Canvas` / `CanvasText` 表达。四档在浅色、深色两套主题下都按黑、白、中灰、页面与品牌背景验证正文至少 4.5:1、焦点环对隔离底至少 3:1。

主题与对比度可以分别声明在不同层级：每一层采用最近的 `data-theme` 和 `data-contrast`。子主题不撤销祖先的高对比度，`data-contrast="default"` 可以局部恢复常规档；兄弟区域互不影响。

### 磨砂面的使用范围

- 只用于需要保留背景空间感的瞬态浮层，正文、表单主体、Card、Table、Toast 与 Dialog 主阅读面不使用。
- 不把 `backdrop-filter` 放在页面根、大滚动区或重叠的多层表面，不对模糊半径做动画。
- 焦点环必须搭配 `focus-surface` 对应的实体隔离面。

### 紧凑磨砂

Tooltip 等小型反白表面使用三支 compact 配方组合 M2 的边界、前景与高光：

| 配方 | 常规值 |
| --- | --- |
| `--xh-material-frosted-compact-alpha` | 0.94，按内置反白与六种 tone 在黑、白、灰、页面和品牌底上验证正文对比度 |
| `--xh-material-frosted-compact-backdrop` | 8px 模糊、104% 饱和度 |
| `--xh-material-frosted-compact-shadow` | 明暗独立的两层小投影 |

高对比、强制颜色和打印分别改为不透明、无模糊、无投影；减少透明时保留小投影表达浮层位置。组件只经这三支配方消费光学参数，不直接选择 alpha 或 blur 原语。

### 液态材质

`data-material` 是应用级材质轴，缺省 `standard`，取 `liquid` 时浮在内容之上的导航层部件换成液态面。它写在任意祖先上，最近的一层生效，Portal 视觉桥会把它带到实例壳；standard 档下同一部件保持原材质。用了视觉环境控制器时，经它的 `material` 偏好设置（控制器始终维护根上的这个属性）。

现有的液态部件：FloatButton 触发器与展开的动作、BackTop、MessageFeed / Log 的回到底部、Carousel 的翻页与播放钮和分页条（托在一条液态胶囊上）、ImageViewer 的工具条、计数、翻页与关闭钮，以及 Layout 固定时的顶栏。瞬态浮层、模态、Toast / Notification、Card、Table、表单与正文容器不用液态，由门禁 `check-material-scope` 守住。

```html
<html data-material="liquid">
  <!-- 图片、视频、画布这类读不到颜色的区域，由作者声明下层的明暗 -->
  <section data-xh-backdrop="dark" data-xh-backdrop-busy>…</section>
</html>
```

作者只写这一个属性。组件挂载后由 `@xihan-ui/core/visual-environment` 的液态面接管，同一文档的部件共用一套监听，不需要额外安装或调用：

- 按部件下层的计算底色与作者声明选色调：下层亮取浅色调、下层暗取深色调，部件随之成为黑墨或白墨域（相对亮度 0.179 ± 0.04 滞回，内容滚过分界附近不来回闪）。
- 下层均匀且色调已知时换通透档（浅 0.24 / 深 0.34）；下层有文字、渐变、图片、视频、画布或读不到时留在可读下限，标签在任何下层上至少 4.5:1。模态打开、背景被设为 inert 而命中不到时同样按读不到处理。
- 滚动、窗口缩放、图片加载完、过渡或动画播完、状态机驱动的平移落定（轮播翻页、看图惯性）时重读下层。
- 细指针移动时 1px 边缘光转向指针；粗指针、无指针与减弱动效下固定左上（RTL 右上）。
- Chromium 内核下距边缘 18px 以内折射下层；其余引擎、尺寸超过 640 × 120 或同一视口超过 3 个时只模糊不折射。

| 专用令牌 | 用途 |
| --- | --- |
| `--xh-material-liquid-tint` | 通透档的着色 |
| `--xh-material-liquid-alpha-clear` / `-alpha-floor` | 通透档与可读下限的不透明度 |
| `--xh-material-liquid-rim-far` | 背光一侧的弱亮边 |
| `--xh-material-liquid-bezel` | 折射带宽度 |

服务端与挂载前输出静态形态：色调随主题，不透明度取可读下限。减少透明、打印时不透明度 1 且无背景滤镜与折射，高对比档不透明度 1，强制色改由系统色表达。

## 直接取用令牌

```ts
import type { TokenName } from "@xihan-ui/tokens";
// TypeScript 侧带类型的令牌名
import { tokens } from "@xihan-ui/tokens";

// 机读产物：生成 Figma 变量、Tailwind 主题、设计稿标注都可以用
import tokens from "@xihan-ui/tokens/tokens.json" with { type: "json" };
```

## 相关

- [皮肤与样式分层](./styling)：皮肤怎么消费这些令牌
- [安装与接入](../installation)：令牌与皮肤的引入顺序

---

来源：https://ui.docs.xihanfun.com/guide/versioning

# 版本与兼容性政策

本页回答一个问题：升级到下一个 `1.x` 小版本时，已依赖的公开面是否会变化。

XiHan.UI 的公开面横跨五种介质：替换自带皮肤、手写 Light DOM 结构都是 [皮肤与样式分层](./styling) 与 [解剖与部件契约](./anatomy) 公开说明的用法：

| 介质 | 使用者写在哪里 | 例子 |
| --- | --- | --- |
| JS / TS 导出 | 自己的源码 | `import { XhSelectRoot } from '@xihan-ui/vue'` |
| 解剖属性 | CSS 选择器 | `[data-scope='select'][data-part='trigger']` |
| `data-*` 状态属性 | CSS 选择器 | `[data-state='open']`、`[data-tone='danger']` |
| CSS 自定义属性与 `@layer` 名 | 自己的样式表 | `--xh-bg-brand`、`@layer xihan.overrides` |
| 自定义元素标签与 attribute | 自己的 HTML | `<xh-dialog modal="true">`、`data-xh-part="content"` |

破坏其中任何一种都不会产生编译错误、运行时异常或降级，只会表现为样式丢失或控件不响应。因此本页对五种介质逐类给出结论。

## 三个档位

| 档位 | 含义 |
| --- | --- |
| **受约束** | 改名、删除、收窄语义 = major。新增同类成员 = minor。 |
| **只增不减** | 只保证已有成员不消失、不改名。新增字段与条目不算破坏。 |
| **排除** | 明确不在承诺内，任何版本都可能改。使用者不应依赖。 |

版本号采用语义化版本 `major.minor.patch`：受约束的成员变更走 major，新增走 minor，只修正行为不改名字走 patch。

## 18 个包必须同版本安装

18 个包锁步发布：任何一个包发新版本，全部 18 个包一起发同一个号。

```
@xihan-ui/core     @xihan-ui/position       @xihan-ui/tokens
@xihan-ui/styles   @xihan-ui/headless       @xihan-ui/icons
@xihan-ui/vue      @xihan-ui/web-components @xihan-ui/chat-stream
@xihan-ui/markdown @xihan-ui/code-highlight @xihan-ui/backgrounds
@xihan-ui/sound    @xihan-ui/motion         @xihan-ui/animations
@xihan-ui/pointer  @xihan-ui/viz
```

两条后果：

- 某个包的 major 可能不含任何针对它自身的变更。`@xihan-ui/markdown` 升到 `2.0.0` 可能只是因为 `@xihan-ui/vue` 修改了一个 prop。判断某次 major 是否影响当前项目，以 [更新日志](../changelog) 的分类条目为准，不以版本号跨度为准。
- 不混装版本。`@xihan-ui/vue` 与 `@xihan-ui/headless` 版本不一致时类型无法对齐；`@xihan-ui/web-components` 更严格：同一个 `xh-` 标签被两个版本注册会直接抛错。适配器与其兄弟包目前是普通 `dependencies`，包管理器不会阻止这种组合，需要使用方自行保证（见[尚无门禁的条款](#尚无门禁的条款)）。

---

## 一、JS / TS 导出面

18 个包中 18 个出 JS 或类型入口，共 36 个带类型的入口。

### 受约束

| 类别 | 数量 | 说明 |
| --- | --- | --- |
| 包名 | 18 | 把代码从一个包移到另一个包 = major |
| `exports` 子路径 | 36 个 JS 入口 | 如 `@xihan-ui/vue/backgrounds`、`@xihan-ui/web-components/define`、`@xihan-ui/core/metadata`。没有 `./*` 通配，深路径引用（`.../dist/xxx.js`）会被 Node 与打包器拒绝，这些路径不是 API |
| Vue 组件导出 `Xh*` | 1056（136 个家族） | `XhButton`、`XhSelectRoot`、`XhSelectItemIndicator` |
| Vue 组合式函数 `use<家族>` | 104 | `useSelect`、`useCombobox`。不使用库内部件、自行编写标记时的唯一入口 |
| Vue 指令 | 2 | `vBackground`（`@xihan-ui/vue/backgrounds`）、`vSound`（`@xihan-ui/vue/sound`），两个子入口各依赖一个可选 peer |
| 无头内核 `connect*` | 136 | `connectAccordion` 及其参数顺序、返回的 getter 名 |
| 无头内核 `*Machine` | 80 | 机器 schema 的形状 |
| 类型 `*Props` / `*Api` / `*ChangeDetails` / `*Schema` | 145 / 120 / 103 / 80 | 删字段、改字段名、把可选改必填都是 major |
| Vue prop 名与未传入语义 | 373 个不同名字 / 1335 处声明 | 见下方说明 |
| Vue emit 名集合 | 67 个不同名字 / 243 处 | 名字受约束（列在 `emits` 中的事件不经 `$attrs` 透传，删除名字会静默改变行为） |
| Vue 插槽名 | 12 | `default`、`item`、`label`、`trigger`、`panel`、`content`、`empty`、`indicator`、`mark`、`cell`、`split`、`tooltip` |

::: tip Vue prop 的未传入语义也是契约
`disabled` 声明为裸 `Boolean`（未传入恒为 `false`）还是 `{ type: Boolean, default: undefined }`（未传入交由底层状态机决定），在类型上几乎没有差别，但决定了不传该 prop 时组件的表现。仓库中 202 处裸 `Boolean`、180 处三态、12 处 `default: true`、1 处显式 `default: false`。把某个 prop 从一种改为另一种是 major，即使名字和类型都未变。
:::

### 只增不减

| 类别 | 数量 | 说明 |
| --- | --- | --- |
| Vue 上下文类型 `*Context` / `*Callbacks` | 108 | 用于给透传的 `api` 标注类型。只保证可读，不保证可构造：新增可选字段不算破坏，因此不要写 `const c: SelectContext = { … }` 这类字面量赋值 |
| `custom-elements.json`（CEM） | 1 份 / 138 个元素 | 已经进过清单的 `tagName` / `attribute` / `event` 条目不会消失；`cssProperties`（皮肤覆盖槽）与 `events` 的 `type`（detail 类型）由 `scripts/enrich-cem.mjs` 从皮肤与元素源码生成，`gate:cem` 校验同步。字段结构细节仍不承诺，补充算 minor |

### 排除

| 类别 | 数量 | 排除原因 |
| --- | --- | --- |
| `@xihan-ui/headless` 的内部算子与常量 | 625 | `clampRating`、`buildMonthGrid`、`colorHexToRgba`、`CAROUSEL_AUTOPLAY_INTERVAL` 等。它们是内核实现的一部分，实现变化时签名随之变化。所需默认值应从组件 props 的文档默认值读取，不应 import 常量再自行比对 |
| `@xihan-ui/headless` 的内部伴生类型 | 564 | `*Refs`（机器持有的 DOM 引用袋，46 个）、`ColorHsva`、`CascaderLevel` 等，是上述函数的参数与返回类型 |
| `xxxAnatomy` / `xxxMeta` / `xxxKeyboard` 三组导出对象 | 各 136 | 它们描述的 part 名单受约束（见第二节），但这三个对象本身的组织方式不受约束。部件名单以组件文档页的解剖表为准，不应 import 这些对象 |
| Vue 的 `provide*` / `use*Context` 函数 | 115 | [Vue 适配器](../adapters/vue) 已写明父子组件之间的 provide / inject 是内部实现，不对外开放。需要下探时使用 `use<家族>()` |
| Vue 的 `useTimelineItem` | 1 | 名字形似组合式函数，实际是 inject 管道，与上一行同类 |
| 适配器运行时底座 | Vue 3 个、WC 8 个 | `createVueRuntime` / `createVueIdGenerator` / `vueNormalize`；`createLitRuntime` / `createSpreader` / `defineElement` / `discoverParts` / `wcNormalize` / `MachineController` 等。这些是适配器与内核之间的接缝，签名依赖的类型未从同一个包导出，无法构造调用 |
| WC 的元素类导出 `Xh*Element` | 110 | 仅用于 `instanceof` 与手动 `customElements.define`，不支持 `extends`（基类不导出、`wire()` 是 protected abstract）。获取元素使用 `document.querySelector` |
| WC 元素上的 `static partContract` | 136 | 部件校验的输入数据，实现细节 |
| `dist/` 内部文件名 | — | `element-Bx4xCiT2.js` 这类打包 chunk 每次构建都可能变化，不得 deep import |
| `.d.ts` 的文件布局 | — | 类型从包入口获取，不引用具体 `.d.ts` 路径 |
| `ui/tooling/`、`ui/apps/playground-*` | — | 不发布 |

---

## 二、解剖属性（`data-scope` / `data-part`）

这是更换皮肤时最核心的一组名字，也是 Web Components 使用者手写 HTML 时书写的字符串。

| 类别 | 数量 | 档位 |
| --- | --- | --- |
| `data-scope` 取值（组件身份） | 136 | **受约束**（新增第 137 个组件是 minor） |
| `data-part` 取值（部件名） | 290 个不同名字 / 1103 条「组件 × 部件」配对 | **受约束** |
| `data-xh-part`（WC 作者书写的角色声明） | 属性名 1 个，取值即上面 290 个 | **受约束** |
| `meta.requiredParts`（必备部件） | 300 条 | **受约束**（加条目 = major），方向见下 |

`data-scope` 的取值与三处完全同名，不做任何转换：headless 目录名、自定义元素标签 `xh-<scope>`、皮肤文件 `<scope>.css`。改动一处即四处同时破坏。

::: warning `data-xh-part`、`data-xh-scroll`、墨色域与液态下层的声明是 `data-xh-` 前缀里仅有的例外
其余 `data-xh-*` 属性（`data-xh-scrollbar`、`data-xh-focus-guard`、`data-xh-inert-exempt` 等 53 个）是库自用标记，排除在承诺之外。例外都由作者书写：`data-xh-part` 是 Web Components 适配器唯一的作者输入 API；`data-xh-scroll` 只承诺「作者容器取得 reset 层的原生细条」（见[皮肤与样式分层](./styling#组件内滚动)），不进任何组件契约，删除或改名同样按公开面破坏处理；`data-xh-ink` 与 `data-xh-ink-margin` 写在作者自己的彩色区块上，声明底色极性与余量（见[色彩 · 彩色面与墨色域](/design/colors#彩色面与墨色域)），取值与语义按公开面承诺；`data-xh-backdrop` 与 `data-xh-backdrop-busy` 写在作者自己的图片、视频、画布区域上，声明液态面下层的明暗与杂乱（见[设计令牌与主题 · 液态材质](./theme#液态材质)），同样按公开面承诺。作者书写 `data-xh-part="trigger"` 是声明，元素接线后在同一节点写入 `data-scope` + `data-part` 是事实。皮肤匹配后者，后者不应手写。
:::

### requiredParts 的方向是反的

向 `requiredParts` 新增一条是收紧：原本可运行的 Light DOM 开始在 [诊断通道](./diagnostics) 报 `wc.missing-part`。规则：

- 删条目：任何版本都可以。
- 加条目：属于破坏性变更，只出现在 major，并且落地即按 `error` 报告。缺少必需角色节点恒发 `error`，没有先以 `warn` 过渡一个版本的档位。

---

## 三、`data-*` 状态属性

`connect` 一共产出 237 个不同的 `data-*` 属性名、1662 条「组件 × 属性」配对。分两类。

### 受约束

行为契约。这些不是样式钩子，删除会使功能静默失效：

| 属性 | 作用 |
| --- | --- |
| `data-value` | 集合型组件的条目值。行为层按它反查节点执行方向键导航，Web Components 使用者需手写在 `item` 节点上。删除后所有集合型组件的键盘导航静默失效 |
| `data-name` | 表单字段名（`form`） |
| `data-index` | 条目序号（0 基） |

样式钩子。自带皮肤消费了 183 个属性名 / 793 条「皮肤 × 属性」配对（不含解剖的 `data-scope` / `data-part`），第三方皮肤参照的就是这一组：

| 属性 | 选中它的皮肤份数 |
| --- | --- |
| `data-size` | 79 |
| `data-state` | 64 |
| `data-disabled` | 58 |
| `data-variant` | 32 |
| `data-invalid` | 27 |
| `data-orientation` / `data-readonly` | 各 26 |
| `data-placement` | 22 |
| `data-highlighted` | 20 |
| `data-hidden` / `data-motion` | 各 18 |
| `data-dragging` | 13 |
| `data-tone` | 10 |
| `data-current` / `data-placeholder` / `data-empty` / `data-clearable` … | 其余 |
| `data-cols-sm` / `-md` / `-lg` / `-xl` | 仅 `grid`，断点分档名受约束 |

份数低不等于使用少：`data-tone` 的规则集中在 `tone.css` 一份文件中，浮层的 `data-placement`
同样集中在定位块中，逐份皮肤只在需要额外微调时才单独选中它们。属性名与取值的约束不按份数区分。

取值同样受约束。属性名变更会破坏皮肤，取值变更同样破坏且更隐蔽：`[data-state='open']` 在取值改为 `expanded` 之后仍是合法 CSS，只是永远不匹配。自带皮肤当前用到的 34 个 `data-state` 取值全部受约束：

```
open  closed  checked  unchecked  indeterminate  on
active  current  incomplete  visible  hidden  ready  empty  invalid  error
completed  preparing  finishing  dismissing  picking  copying
```

取值的真源是 `tooling/scripts/state-vocabulary.json`，按族登记了 7 个族共 38 个取值：同族互斥，一个部件同一时刻只取其中一个。上面 21 个是皮肤当前选中的取值，其余只在 DOM 上出现，尚无对应的皮肤规则。`check-state-vocabulary` 双向校验：`connect` 发出词汇表外的值报错，皮肤选中词汇表中不存在的值同样报错。

三条视觉轴的取值同理。`data-tone` 的合法值是 6 个，唯一真源是 `tone.css`：

```
brand  neutral  success  warning  danger  info
```

### 排除

其余 45 个 `data-*`（`data-lane`、`data-one-way`、`data-checked-count`、`data-sticking`、`data-file-size`、`data-modules` 等）：自带皮肤未选中它们，组件文档页也未记载。`check-state-vocabulary` 每次都会列出这批发射但零引用的属性名（连同上面 `data-value` / `data-index` 两个数据载体，共 47 个）。它们在 DOM 上存在，但不承诺稳定，随时可能改名或消失。需要依赖它们编写样式时，先提交 issue。

---

## 四、CSS 自定义属性与 `@layer`

### 受约束

| 类别 | 数量 | 说明 |
| --- | --- | --- |
| `@layer` 名与声明顺序 | 5 | `xihan.reset` → `xihan.tokens` → `xihan.motion` → `xihan.components` → `xihan.overrides`。改名、调序、增删中间层均为 major。`xihan.overrides` 刻意留空，专供使用方覆盖，不会作为未使用的层被清理 |
| 全局令牌 · 原语层 | 115 | `--xh-color-brand-500`、`--xh-space-4`、`--xh-radius-md`。皮肤中不应直接使用它们，但接入品牌轴必须写 `--xh-color-brand-*`，因此它们是公开的 |
| 全局令牌 · 语义层 | 302 | `--xh-bg-brand`、`--xh-fg-on-brand`、`--xh-control-h-md`、`--xh-shape-control`。主题定制的正门，见 [设计令牌与主题](./theme) |
| 组件覆盖槽 | 4088（覆盖 135 个组件） | `--xh-button-bg`、`--xh-button-h`、`--xh-dialog-max-w`。全部写成 `var(--xh-x-y, 默认值)` 形态，在 `:root` 中设置即可修改该组件 |
| 语气轴槽 | 12 | `--xh-_tone`、`--xh-_tone-on`、`--xh-_tone-hover`、`--xh-_tone-subtle`、`--xh-_tone-border` 等。这是自定义语气的唯一机制：写入 `[data-tone='premium'] { --xh-_tone: gold; --xh-_tone-on: #000 }`，读取这批槽的 58 份皮肤随之生效。虽然带下划线前缀，但按受约束处理 |
| 关键帧名 | 40 | `xh-pop-in`、`xh-fade-out`、`xh-spin`。共享关键帧住在 `family/motion.css`（子入口 `@xihan-ui/styles/motion.css`），皮肤 `@import` 它；组件专属关键帧仍在各皮肤。在 `xihan.overrides` 层中重定义同名关键帧即可替换该段动画（关键帧名因此是公开面），所以改名与删名同样是 major |
| 跨包内联属性 | 4 | `--xh-_truncate-lines`、`--xh-_float-button-offset`、`--xh-_tour-spotlight-radius`、`--xh-_carousel-autoplay-duration`。由 headless 写入内联 `style`，皮肤必须读取。整套更换皮肤时若不读取这些值，文本截断、浮动按钮贴边、引导目标圆角或轮播进度会失效，且不报任何错误 |
| `@xihan-ui/styles` 的 CSS 子路径 | 160 | `.`、`./index.css`、`./index.unlayered.css`，家族文件 `./action-control.css`、`./chart.css`、`./collection-item.css`、`./field-chrome.css`、`./swatch.css`、`./material.css`、`./motion.css`，与 148 条 `.css`：136 份组件皮肤加 `./layers.css`、`./tone.css`、`./reset.css`、`./overlay-arrow.css`、`./visually-hidden.css`、`./undefined.css`、`./focus.css`、`./label.css`、`./description.css`、`./pointer.css`、`./forced-colors.css` |
| `@xihan-ui/tokens` 的 CSS 子路径 | 2 | `./tokens.css`、`./tokens.json` |

### 排除

| 类别 | 数量 | 排除原因 |
| --- | --- | --- |
| 其余 `--xh-_` 私有槽 | 465 | 皮肤内部的回退中转（`--xh-_bg`、`--xh-_bg-hover`、`--xh-_mention-py` 等），变体只改槽位、不重写规则依赖它。不应在外部设置它们 |
| 令牌的取值 | — | `--xh-color-brand-500` 这个名字受约束，其对应的 `oklch()` 值不受约束。调色板随视觉迭代变化，这正是令牌存在的意义 |
| `index.css` 的内部结构 | — | 它是生成的扁平文件：家族配方只内联一次、排在皮肤之前，皮肤段的顺序即源序。段标记注释（`/* styles/xxx.css */`）只作阅读定位，不是承诺 |
| `index.unlayered.css` 的内部结构 | — | 它是同一源序的扁平镜像，不带 `@layer`。使用该入口时没有 `xihan.overrides` 覆盖槽位，层名承诺不适用 |

::: warning 命名前缀不能反推归属
`--xh-field-py` 形似 `field` 组件的覆盖槽，实际是全局语义令牌，`field.css` 本身并不使用它。同理 `--xh-text-*`（13 个全局文本令牌）与 `text-field` 的 48 条组件槽同前缀，`--xh-color-*`（43 个原语调色板令牌）与 `color-picker` 的 70 条组件槽同前缀。判断一条属性属于哪一档，看它在不在上表列的那 660 个全局令牌里，不按前缀推断。
:::

---

## 五、自定义元素与 attribute

| 类别 | 数量 | 档位 |
| --- | --- | --- |
| 自定义元素标签 `xh-*` | 139（`defineXhElements()` 注册 138 + `xh-background`） | **受约束** |
| 注册函数 | 2（`defineXhElements`、`defineXhBackground`） | **受约束** |
| observed attribute | 1357 条声明 / 393 个不同名字 | **受约束**（具体元素上的具体属性名） |
| attribute 名词汇表本身 | 393 | **只增不减**（新组件复用 `size` / `tone` / `dir` 不算破坏） |
| `CustomEvent` 名 | 96 个名字 / 210 条「元素 × 事件」 | **受约束** |
| 事件传播语义 | `bubbles: true, composed: true`（195 处中 193 处） | **受约束**。取消冒泡会使祖先节点上的事件委托静默失效。例外是名为 `submit` 的事件（`xh-prompt-input` / `xh-question-flow`）：与原生表单提交同名，一律不冒泡，避免被祖先 `<form>` 视为自身的提交 |
| 事件 `detail` 形状 | 188 个 `*Details` 类型 | **受约束**，等同于 headless 的同名类型 |
| `attribute: false` 的 JS 字段 | 223 条（涉及 76 个字段名） | **受约束**。`collection`、`translations`、`validate`、`filter` 等只能通过 JS 赋值，HTML 中无法表达：不是每个 property 都有对应 attribute |
| 命令式方法 | 97（分布在 50 个元素） | **受约束**，含参数与返回类型 |

命令式方法全清单：

| 元素 | 方法 |
| --- | --- |
| `xh-form` | `setFieldValue` `setFieldError` `clearErrors` `submit` `reset` `getFieldId` `getFieldValue` `getFieldError` |
| `xh-notification` | `create` `updateItem` `dismiss` `dismissAll` `getItemsByPlacement` |
| `xh-file-upload` | `openFilePicker` `setFiles` `addFiles` `deleteFile` `clear` |
| `xh-timer` | `start` `pause` `resume` `reset` |
| `xh-virtualizer` | `scrollToIndex` `measureElement` `measure` |
| `xh-signature-pad` | `clear` `toSvg` |
| `xh-log` | `scrollToBottom` |
| `xh-tour` | `remeasure` |

::: tip 布尔 attribute 是三态的
`modal="false"` 表示关闭，不写表示交由组件决定，这与原生 HTML 布尔属性（写出即为真）不同。把三态转换器换回原生语义是不改名字的语义收窄，按 major 处理。
:::

以下与包结构有关的事实同样在承诺内：

- 元素在 `@xihan-ui/web-components/define`，不在包主入口。`defineXhElements()` 是全量注册：调用即注册全部 138 个元素，没有逐个的 `defineXhButton()`。（补充细粒度 define 是 minor；补充后 `defineXhElements` 的全量语义即成为承诺。）
- `xh-background` 单独在 `@xihan-ui/web-components/backgrounds`，因为它依赖可选 peer。把它移入 `./define` 会强制所有使用方安装 WebGL 引擎，属于破坏性变更。
- 元素全部是 Light DOM，没有 shadow root，`::part()` 不生效。CEM 中的 `cssParts` 条目在本包读作 `data-xh-part`，不是 shadow part。

---

## 六、什么算破坏性变更

正例（major）与反例（minor / patch）对照，按介质各举数条。

### JS 导出

| 算破坏 | 不算破坏 |
| --- | --- |
| 删除或改名任一 `Xh*` 组件（含 `XhTreeSelectBranchIndicator` 等低频部件） | 新增组件、新增部件 |
| `connectAccordion` 的返回值把 `getRootProps` 改成 `getProps` | 给 `connectAccordion` 加一个新的 getter |
| `SelectProps` 新增一个必填字段，或把可选字段改为必填 | `SelectProps` 新增可选字段 |
| `SelectApi` 删除一个 getter | `SelectContext` 新增一个可选字段 |
| 把 `useSelect()` 的返回从 `ComputedRef<Api>` 换成其他容器 | 新增 `useXxx` |
| 把某个 prop 从裸 `Boolean` 改成 `default: undefined` | 给某个 prop 补文档 |
| 从某个组件的 `emits` 数组中删除一个名字 | 向 `emits` 新增一个名字 |

### 解剖与 `data-*`

| 算破坏 | 不算破坏 |
| --- | --- |
| `data-part` 从 `indicator` 改成 `marker` | 给某个组件新增一个可选部件 |
| 把 `item-text` 改成 `itemText`（分词/大小写变化） | 皮肤内部改用其他选择器组合实现同样的视觉 |
| 某个组件不再输出 `data-size` / `data-tone` | 给某个组件补上原本没有的 `data-tone` |
| `data-state` 的取值从 `open` 改成 `expanded` | 新增一个 `data-state` 取值 |
| 把 `data-disabled` 从「存在即禁用」改成 `data-disabled="true"` | — |
| 删除 `data-value` | 删除 `data-lane`（在排除清单中） |

### CSS

| 算破坏 | 不算破坏 |
| --- | --- |
| `--xh-button-h` 改名成 `--xh-button-block-size` | 新增 `--xh-button-letter-spacing` |
| 删除 `--xh-radius-xl`（即使库内部未使用） | 调整 `--xh-color-brand-500` 的 `oklch()` 值 |
| 把 `var(--xh-alert-px, …)` 改为直接写语义令牌（等于取消该覆盖点） | 给某条规则补充 `@supports` 兜底 |
| 调整 `@layer` 声明顺序 | 在 `xihan.components` 里加规则 |
| 删除 `./tone.css` 子路径 | 新增 `./<新组件>.css` 子路径 |

### 自定义元素

| 算破坏 | 不算破坏 |
| --- | --- |
| `xh-empty-state` 改名成 `xh-empty` | 新增 `xh-xxx` 元素 |
| 某元素的 `observedAttributes` 减少一条 | 给某元素新增 attribute |
| 把 `read-only` 改写成 `readonly` | 把某个 `attribute: false` 的字段反向暴露成 attribute |
| 事件名 `value-change` 改成 `change` | 新增事件名 |
| 把某个事件的 `bubbles` 改成 `false` | 补 `HTMLElementEventMap` 类型增强 |
| `xh-notification.create()` 从返回 `string` 改成返回对象 | 给 `xh-form` 新增一个方法 |
| 把某个可选 part 提升为 `requiredParts` | 新增一个可选 part |

### 支持面

| 算破坏 | 不算破坏 |
| --- | --- |
| 抬高 Node 下限 | 降低 Node 下限 |
| 抬高浏览器硬底线（使用一个无兜底的新 CSS 特性） | 新增一个带退化路径的增强特性 |
| 收窄 `vue` peer 区间（加上限、抬下限） | 放宽 peer 区间 |
| 撤销 ESM 导出条件 | 增加 CJS 导出条件 |

---

## 七、移除流程

本库不设废弃期，也不保留兼容层。改名直接改，删除直接删：不为旧写法保留别名、不把旧名放入兜底链、不在源码中标注 `@deprecated` 延长存续。在一个 major 中读到的名字就是当时唯一存在的名字。

移除动作集中在 major，一律出现在更新日志顶部、单列一节，逐条写明旧名与替换写法，这是唯一的迁移材料。

四种介质需要单独说明：`data-*`、CSS 自定义属性、`@layer` 名、元素 attribute 没有 IDE 提示，改名之后对应选择器只会静默失配，不报错也不降级。它们唯一的告知渠道是更新日志，因此每次移除都在 changeset 中逐条列出旧名与替换写法，使用方可据此在自己的代码库中全文搜索。

---

## 八、支持面

收窄支持面按破坏性变更处理，放宽随时可以。

### 运行时

| 项 | 值 | 变更规则 |
| --- | --- | --- |
| Node（安装并运行本库） | **≥ 18** | 抬高 = major。产物实际用到的最高特性是 `Object.hasOwn`（Node 16.9），`>=18` 留了余量 |
| Node（开发本仓库） | ≥ 24，pnpm ≥ 11 | 与上一行无关，随时可变 |
| 模块格式 | **ESM only** | 无 CJS、无 node10 解析条件。包中 `main` / `module` 字段存在但指向 ESM 文件，是给旧式 bundler 的别名，不代表可以 `require` |
| 包管理器 | 无要求 | — |

### 浏览器

硬底线由三个无兜底的 CSS 特性决定：`@layer`（125/125 个样式文件使用，不识别它的解析器会丢弃整块）、`oklch()`（`tokens.css` 中 63 处，是唯一颜色来源）、`color-mix()`。

| 浏览器 | 硬底线 | 完整保真 |
| --- | --- | --- |
| Chrome / Edge | **111** | 111 |
| Firefox | **113** | 121（`:has()`） |
| Safari | **16.2** | 16.4 |

测试承诺：当前正式版，外加 Chromium 与 Safari 各向前两个大版本、Firefox ESR。硬底线只在 major 中抬高。

低于硬底线不会降级，而是无样式：皮肤中刻意不写兜底值，令牌缺席是缺陷而不是降级。

高于硬底线又无从兜底的特性，皮肤一律不用，由 `check-css-floor` 的拒绝名单拦截（`@scope`、`@starting-style`、嵌套选择器等）。其中容易误写的一条：

| 特性 | 最早完整支持 | 底线内的引擎不认时 | 皮肤的写法 |
| --- | --- | --- | --- |
| 媒体查询区间写法 `(width < 768px)` | Chrome 104 / Firefox 63 / Safari 16.4 | Safari 16.2 / 16.3 把整条查询判作不成立，块内规则静默丢失 | 断点只写 `(min-width: …)`，窄档专属规则写它的补集 `not all and (min-width: …)` |

可选增强层（不支持时按下表退化；新增增强特性不算破坏，前提是同时提供退化路径）：

| 特性 | Chrome | Firefox | Safari | 不支持时 |
| --- | --- | --- | --- | --- |
| `:has()` | 105 | 121 | 15.4 | 少量间距/gutter 微调失效 |
| `scrollbar-gutter` | 94 | 97 | 18.2 | 滚动条出现时轻微位移 |
| `dvh` / `svh` / `lvh` | 108 | 101 | 15.4 | 回落到 `vh` |
| `text-wrap: balance` | 114 | 121 | 17.5 | 标题按默认换行 |
| `light-dark()` | 123 | 120 | 17.5 | 代码块语法色退化成单色 |
| `field-sizing` | 123 | 152 | 26.2 | `prompt-input` 输入框退化成固定行数 |

Web Components 侧不构成额外约束：全部 Light DOM，不使用 shadow DOM、`ElementInternals`、`adoptedStyleSheets`，平台要求只到 Custom Elements v1。

### 宿主框架

| 包 | peer | 规则 |
| --- | --- | --- |
| `@xihan-ui/vue` | `vue: ^3.5.0` | 下限由 `useId` 决定（Vue 3.5 引入）。收窄为 major，放宽为 minor |
| `@xihan-ui/vue`、`@xihan-ui/web-components` | `@xihan-ui/backgrounds`（optional） | 不使用背景效果时无需安装 |
| `@xihan-ui/vue` | `@xihan-ui/sound`（optional） | 不使用音效时无需安装 |
| `@xihan-ui/web-components` | 无框架 peer | 原生自定义元素，不要求任何框架 |
| 其余 15 个包 | 无 | — |

---

## 九、包的稳定性分级

锁步发版意味着版本号不反映稳定性，因此单独列表。

下面两张表覆盖全部 18 个包，每个包必在其中一张中；门禁比对两张表的包名与 `packages/` 下的公开包，新增包未定级即构建失败。

### 稳定

破坏性变更只出现在 major，移除按上文流程执行。

| 包 | 说明 |
| --- | --- |
| `@xihan-ui/vue` | 1056 个组件、104 个组合式函数 |
| `@xihan-ui/react` | 组件与 hooks（铺开中，公开面随批次增长） |
| `@xihan-ui/web-components` | 139 个自定义元素 |
| `@xihan-ui/headless` | `connect*` / `*Machine` / 各类公开类型；内部算子在排除清单里 |
| `@xihan-ui/styles` | 136 份组件皮肤、5 个层名 |
| `@xihan-ui/tokens` | 660 个令牌名，外加 `./runtime` 的主题控制器与种子色 API |
| `@xihan-ui/icons` | 图标集 |
| `@xihan-ui/core` | 只有被适配器与 headless 公开消费的那部分（`createAnatomy`、`createNormalizer`、归一化规则、状态机公开面），含 `data-value` 这条集合导航契约；另有 `./date` 子入口的全部导出（`PlainDate` / `PlainTime` / `PlainDateTime`、时区换算、周规则、边界函数与格式化器） |
| `@xihan-ui/position` | `createPositionEngine` 与它的选项；其余 9 个导出是内部算子 |
| `@xihan-ui/motion` | 缓动名、时长常量、`animate`、补间与弹簧算子。三值与令牌层同源（`check-motion-source` 比对），`core` / `headless` 与各适配器均建立在它之上，改名会先破坏库自身 |
| `@xihan-ui/pointer` | `createPointerSession` / `createMultiPointerSession` 与四层几何纯函数。`headless` 与各适配器的拖拽、缩放、划动全部经由它，同上 |

### 实验

这七个包的破坏性变更可以出现在 minor 中，不适合用于不易升级的生产代码。

| 包 | 仍在变化的原因 |
| --- | --- |
| `@xihan-ui/viz` | 图表组件按期接入，比例尺、形状、场景与过渡的签名随组件落地仍会调整 |
| `@xihan-ui/code-highlight` | 承诺面是 `HighlighterPort` 端口，自研分词器（`tokenizeCode`、`langSpecOf`、`LangSpec`）随时可能整体替换 |
| `@xihan-ui/markdown` | 公开面是 `createStreamRenderer` 与它的三个类型，外加 `blockKind` / `fenceLang` / `isFenceClosed` / `LIVE_BLOCK_KEY` 四个切块算子；解析、切块、缓存的中间件随时可能变化 |
| `@xihan-ui/chat-stream` | AI 会话协议类型（`UIMessage`、`TextPart` 等）跟随上游生态演进 |
| `@xihan-ui/backgrounds` | 效果参数与点云 API 仍在调整；通用短名（`bool` / `num` / `str` / `rgb`）不是公开 API |
| `@xihan-ui/animations` | 公开面是 `MotionSpec` 的字段与 `BUILTIN_MOTION_NAMES` 里的预设名。预设表随组件接入继续调整，预设改名没有门禁拦截：它不是导出名，删除不会被报告 |
| `@xihan-ui/sound` | 同上：`SoundSpec` 的层与包络字段、三套主题、`BUILTIN_SOUND_NAMES` 中的预设名仍在调整 |

---

## 门禁覆盖范围

### 已由门禁保证

六种介质的改名即 major 已有门禁保证。`pnpm gate:surface` 运行的 `check-public-surface`
以入库基线（`ui/tooling/public-surface.json`，16366 个名字）比对当前状态：
基线中有而当前没有，即为删除或改名，构建失败。新增一律放行，因为新增是 minor。

覆盖：包名与 198 条子入口、8513 个导出名、136 个 `data-scope` 与 1103 条部件配对、
136 个组件的 1763 个 prop 名、239 种 `data-*`、34 个 `data-state` 取值、660 个令牌、
5 个 `@layer` 名、4088 个组件覆盖槽、138 个自定义元素及其 attribute 与事件。

prop 名一维是后补的：在它加入之前，修改一个 prop 名（实测 `transfer` 的 `items` 改
`collection`、`splitter` 的 `size` 改 `sizes`）其余门禁全程沉默。它的事实源是无头内核的
`<组件>Schema['props']`，各适配器的 props 均按它展开。

它的必要性可以复现：把 `switch` 的 `thumb` 改名 `knob`，其余门禁全部通过，
只有这一道拦截；把 `switch` 的 `checked` 改名 `isChecked`，同样只有它报出
「组件 prop switch: checked」。删除一个语义令牌、修改一个组件覆盖槽名同理。

确需破坏性变更时，运行 `pnpm surface:update` 更新基线并在 changeset 中说明：
门禁拦截的是无意删除，不是有意的 major。

::: warning 基线锁定的名字比本页承诺的范围宽
基线是所有可写出名字的机械快照，不区分档位：本页归入排除的成员同样在内，包括
headless 的 625 个内部算子与常量、564 个伴生类型、`*Anatomy` / `*Meta` / `*Keyboard` 三组导出对象，
以及六个实验包的全部导出。政策允许随时删改它们，但删除仍会触发门禁。
行使这份删除权时先运行 `pnpm surface:update` 更新基线，这不是破坏性变更，
changeset 按 patch / minor 记录即可：更新基线这一动作本身不代表 major。
:::

另有三道门禁把原本依赖自觉的条款转为机器检查。`check-css-floor` 保证浏览器硬底线：
`.browserslistrc` 记录底线，拒绝名单拦截 `@scope`、媒体查询区间写法等无兜底的抬底线特性，
`light-dark()` / `dvh` / `lh` 必须带级联兜底。`check-version-lock` 保证 18 包锁步：任何一个
package.json 的 version 与其余不同，门禁直接失败。`check-wiring` 保证检查系统自身：新增的
check 脚本未接入 `pnpm gate` 等同于未编写，死引用同样被拦截。

三条视觉轴已收敛为联合类型，`tone` / `size` / `variant` 不再是裸 `string`，
写错取值在编译期报错。Vue 事件载荷已有类型，101 个组件的 `emits` 全是对象式，
产物 `.d.ts` 中不再出现 `(...args: any[]) => any`。

### 尚无门禁的条款

以下条款目前没有门禁。

| 条款 | 现状 | 计划补充的机制 |
| --- | --- | --- |
| Vue 作用域插槽载荷 | 带载荷的插槽已声明 `slots:` 选项，由 `check-slot-types` 门禁的四条判据保证（缺声明 / 键非可选 / 值非函数 / 声明未用）。仅渲染无载荷插槽的部件仍不声明，消费方写错 slot 名不会报错 | 无载荷插槽也补充声明，或明确只有带载荷的插槽进入契约 |
| 移除提示（CSS / `data-*` / attribute / 层名） | 这四种介质没有 IDE 提示：名字移除之后，消费方的声明只是静默失配，既不报错也不降级。唯一的告知渠道是更新日志，因此每次移除都在 changeset 中逐条列出旧名与替换写法，供使用方在自己的代码库中全文搜索 | 无 |
| 浏览器硬底线 | 已落地：`.browserslistrc` 记录硬底线，`check-css-floor` 门禁拒绝抬底线的无兜底特性（`@scope`、媒体查询区间写法等），并校验 `light-dark()` / `dvh` / `lh` 的级联兜底 | 拒绝名单改动时联动本页支持面表格的提醒 |
| 「18 个包必须同版本」 | `check-version-lock` 门禁保证 18 个 package.json 同版本。运行期一侧只在 dev 有提示：三个适配器启动时调用 `checkLockstepVersion`，自身版本与 core 不一致时经诊断通道发出一条 `warn`；生产构建中跳过，且只比对适配器与 core 两个版本，不是全部 18 个 | 提升为 peer，或把运行期比对扩展到全部包 |

本页内容与实际行为不符时按缺陷处理，请提交 issue。

---

来源：https://ui.docs.xihanfun.com/runtime/code-highlight

# 代码着色

`@xihan-ui/code-highlight` 是 `HighlighterPort` 的自研实现：粗粒度词法着色，零第三方依赖。

```ts
import { createHighlighter } from "@xihan-ui/code-highlight";

const highlighter = createHighlighter();
```

把它交给[代码视图](../components/code-view)组件的 `highlighter` prop 即可。组件本身不识别任何具体的着色器，只识别这个端口。

## 是否安装

它是各适配器的可选 peer，不随适配器一起安装：

```bash
pnpm add @xihan-ui/code-highlight
```

安装后，[代码视图](../components/code-view)自动着色，不需要写 `highlighter` prop；不安装时代码视图渲染纯文本，不报错。换成其他实现（典型是接入 Shiki）同样通过 `highlighter` prop。

## 区分范围

只区分五类：注释、字符串、数字、关键字、标点。

类型名、函数名、属性名这类需要语法树才能区分的内容一概不分：那属于 TextMate 语法一档的工作，本实现不追求。因此同一段代码在这里与在编辑器中的显示不会完全相同，这是预期内的。

无法识别的语言、超长代码一律返回 `null`，由调用方原样渲染纯文本。没有着色不等于故障，这是设计上的降级路径。

## 更高精度时更换实现

`highlighter` 是一个端口，不是一个实现。把 Shiki、Prism 或其他着色器包装成同一个形状接入，组件侧不需修改：

```ts
interface HighlighterPort {
  highlight: (code: string, lang: string) => readonly CodeToken[] | null;
}
```

这条端口存在的理由：库不替使用方决定是否为语法高亮付出几百 kB 的体积。默认提供一个够用且无额外代价的实现，需要升级时随时更换。

## 不直接内置 Shiki 的原因

Shiki 需要携带 TextMate 语法与主题数据，体积在几百 kB 量级，且需要异步加载。对文档中偶尔出现一段代码的场景，这个代价不成比例。而对实际构建代码编辑器的使用方，粗粒度着色又不足够：两侧都不应由库代为决定。端口是唯一能同时满足两侧的形态。

## 支持的语言

`langSpecOf(lang)` 可识别的语言即受支持的语言。传入无法识别的标注返回 `null`，代码原样渲染。

流式场景需配合 `complete` 使用：未闭合的代码随时会变，着色是纯计算但有开销，等闭合后再执行一次更合理。[代码视图](../components/code-view)组件的 `highlightWhileStreaming` 即为该开关。

## 长度上限

超过 `HIGHLIGHT_MAX_LENGTH` 的代码直接返回 `null`。着色是同步的，超长输入会阻塞主线程，与其卡顿不如不着色。这个常量是导出的，可读但不可修改：处理超长代码本应在 worker 中进行。

---

来源：https://ui.docs.xihanfun.com/runtime/config

# 全局配置

组件的内建文案默认是英文，日期时间类组件另接受 `locale`，尺寸档默认为 `md`，浮层默认挂在 portal 落点上。这些配置逐个实例传入既冗长又容易遗漏，`provideXhConfig` 支持在应用根注入一次。

```ts
import { provideXhConfig } from "@xihan-ui/vue";

provideXhConfig({
  locale: "zh-CN",
  size: "sm",
  translations: {
    "dialog": { close: "关闭" },
    "file-upload": { dropzone: "把文件拖到这里" },
  },
});
```

取值优先级只有一条：实例 props > 最近一层注入 > 外层注入 > 组件内建默认（英文）。不注入时组件按原路径运行，零开销。

## 五个字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `locale` | `string` | BCP 47 语言标记，供日期时间类组件（`calendar` / `date-*` / `time-*`）使用。它只决定这些组件的日期时间格式，不切换文案。 |
| `translations` | `XhTranslationOverrides` | 按组件 id 分组的文案覆盖。每个组件的可覆盖键即其 `<Pascal>Translations` 中的字段，组件页的 Props 表可以查到。 |
| `size` | `'sm' \| 'md' \| 'lg'` | 尺寸档的默认值，作用于每个声明了三档 `size` 的组件，包括运行状态机与不运行状态机的（按钮、徽标、空状态等）。它与 `data-density` 是两条独立的轴：`size` 切换控件高度与字号档，密度只收紧间距。`floating-panel` 的 `size` 是一对像素数、同名不同义，不受它影响。 |
| `portalContainer` | `() => Element \| null` | 指定同一 Document 内的浮层目标，未配置时由运行时提供默认 Portal。现有组件通常允许返回 `null` 使用默认目标；Vue DatePicker 的严格规则见下文。它不负责切换 Scope，跨 Document 目标会失败。Vue 与 React 可配置；Web Components 暂不公开该配置，Menu 子菜单使用所属 Document 的运行时 Portal 根。 |
| `scrollRoot` | `() => HTMLElement \| null` | 实际滚动的元素。宿主把滚动移进内容容器（`body` 本身不滚动）时必须提供，否则模态浮层的滚动锁是空操作。返回 `null` 明确锁定页面，不自动探测后代滚动容器；同一 Document 的并行锁必须指向同一规范化目标。 |

方向不在这里。`dir` 走 DOM：写在 `<html dir="rtl">` 或任意祖先上即可，行为层从计算样式读取，皮肤中的 `[dir='rtl']` 规则也随之生效。在这份配置中再加 JS 侧的 `dir` 只会多一条不一致的通道。

Vue `DatePicker` 从实际渲染出的根节点建立运行时 Scope：整棵应用挂在 iframe 内时，即使不配置
`portalContainer`，浮层、LayerRegistry、定位与滚动条也都留在该 iframe Document。显式容器必须属于同一
Document；该组件需要默认落点时应省略字段，显式 getter 返回 `null` 或其他非 Element 值会失败。组件不会
为了迁就无效目标改绑来源 Scope，也不会回落主页面的全局 `document`。目标 getter 只会在真实根和同轮
渲染树中的兄弟 ref 都已提交、浮层真正选择 Portal 落点时读取。初始展开的服务端输出与客户端 hydration
首帧都先保留来源内结构，运行时就绪后再执行同 Document 搬运。

## 运行期切语言

传入 ref 或 getter，不传裸对象：注入的是 `MaybeRefOrGetter<XhConfig>`，提供响应式来源后，切换语言时组件随之重渲染。

```ts
import { provideXhConfig } from "@xihan-ui/vue";
import { computed } from "vue";

const locale = ref<"zh-CN" | "en-US">("zh-CN");

provideXhConfig(() => ({
  locale: locale.value,
  translations: locale.value === "zh-CN" ? zhTranslations : {},
}));
```

传裸对象也可以使用，但从此固定，这是最常见的误用。

## 文案的合并方式

`translations` 按键合并而不是整块替换：全局提供 `{ close: '关闭', open: '展开' }`、实例提供 `{ close: '收起' }`，组件最终得到 `{ close: '收起', open: '展开' }`。因此全局只需要写需要修改的条目，不必抄全一个组件的文案。

## 作用域：全局与局部

它就是 Vue 的 provide/inject，因此按组件树作用域生效，不是全局单例。同一个应用中可以在不同子树注入不同配置：整站中文，某个内嵌的第三方面板保持英文，各自注入即可。

嵌套注入逐键合并，不整份遮蔽：内层只写 `translations` 时，外层的 `locale` 与 `size` 仍然生效；同一个组件下的文案也按键合并，内层只覆盖它写了的条目。键缺席与写成 `undefined` 都视为该层未声明。

```ts
// 应用根
provideXhConfig({ locale: "zh-CN", size: "sm" });

// 某个子树中：只改文案，locale 与 size 仍从外层继承
provideXhConfig({ translations: { dialog: { close: "Close" } } });
```

## 自定义元素侧

两条出口，语义与 Vue 侧一一对应：`setXhConfig` 管理整页，`<xh-config>` 管理一棵子树。前者是模块级单例，后者沿 DOM 祖先链解析：Vue 侧查找组件树，这里查找 DOM 树，合并规则完全一致。

```html
<script type="module">
  import { setXhConfig } from '@xihan-ui/web-components'

  setXhConfig({ locale: 'zh-CN', size: 'sm' })
</script>

<!-- 这一小块保持英文，size 仍从全局继承 -->
<xh-config id="panel">
  <xh-dialog>…</xh-dialog>
</xh-config>

<script type="module">
  document.getElementById('panel').translations = { dialog: { close: 'Close' } }
</script>
```

`locale` 与 `size` 两条属性写在标签上即可；`translations` 是对象、`scrollRoot` 是函数，只能通过 property 设置。子树中每个元素都沿祖先链解析，运行状态机与不运行状态机的组件一致；`scrollRoot` 由 `xh-dialog` / `xh-drawer` / `xh-image-viewer` / `xh-command` 开启模态时读取，修改后下一次打开生效。`<xh-config>` 自身不渲染任何内容，也不接线任何角色节点：它是 `display: contents`，布局上完全让开。

`setXhConfig` 是整份替换（不深合并），修改一处需要传入整份配置；`<xh-config>` 之间以及它与全局配置之间才是逐键合并。

运行状态机的元素把沿祖先链解析到的那份结果缓存起来：状态机每读一个 prop 都要经过这一步，而解析一次要逐层往上找配置作用域。缓存在全局那份改了、任一 `<xh-config>` 改了或进出文档时整体作废，元素自己被搬到另一棵子树时随断开重连作废。因此**改配置要走 `setXhConfig` 或 `<xh-config>` 的 property**，就地改写已经交出去的那个配置对象不会被看见——这一条本来就成立（子树里已挂载的元素也不会因此重渲），缓存只是让它更明显。

## 与其他库的对应关系

| 其他库 | 本库 |
| --- | --- |
| Element Plus `<el-config-provider>` | `provideXhConfig()` / `<xh-config>` |
| Ant Design `<ConfigProvider>` | `provideXhConfig()` / `<xh-config>`（`componentSize` 即这里的 `size`） |
| Naive UI `<n-config-provider>` | `provideXhConfig()`（主题部分见[设计令牌与主题](../guide/theme)） |
| Semi Design `<LocaleProvider>` | `provideXhConfig()` 的 `locale` 与 `translations` |

主题不在这里。上述库的 ConfigProvider 同时管理主题，本库的主题属于 CSS 令牌层：切换主题是修改 CSS 自定义属性、切换 `data-theme` 等属性，随 DOM 继承，局部主题天然可嵌套，与这份配置无关。

Vue 与 React 的浮层搬到 Portal 时，每个实例会把逻辑来源最近声明的 `data-theme`、`data-brand`、`data-density`、`data-contrast`、`data-motion`、`data-transparency` 和 `dir` 投影到自己的无盒壳，并复制来源解析出的 CSS 自定义属性；共享 Portal 根不带这些属性。同一落点里的两个局部主题因此互不覆盖。来源没有声明的轴与变量继续继承显式 `portalContainer`，普通计算样式不会被复制。

Web Components 的普通声明式浮层仍在 Light DOM 原位。多级 Menu 是明确例外：展开的 submenu positioner 会进入所属 Document 的运行时 Portal，以免父菜单的磨砂采样建立 fixed 包含块；它同样使用独占无盒壳桥接上述视觉轴，关闭或断连后恢复作者原位置。

`shape` 是组件自身形态，不是主题环境轴。系统 `prefers-reduced-transparency` 媒体路径在同一浏览器中天然同时作用于来源与 Portal；`data-transparency="reduce"` 是同源的显式视觉轴，令牌层会在该局部范围将材质实体化并由实例壳继承，业务皮肤也可消费它扩展自己的非材质降级。

---

来源：https://ui.docs.xihanfun.com/runtime/

# 服务与运行时

组件册收录有解剖、有部件、可放置在页面上的组件。另有一类能力不是组件，却同样由本库对外提供：应用级配置、一次调用即弹出的对话框、把流式文本转换为节点的内核。它们没有 `data-part`，因此不进入组件册，本册收录这些能力。

| 本册 | 内容 | 对应的包 |
| --- | --- | --- |
| [全局配置](./config) | 应用级注入一次，语言与内建文案的默认值 | `@xihan-ui/vue` |
| [命令式服务](./services) | `confirm()` / `toast.success()` 这类一次调用即出结果的入口 | `@xihan-ui/vue` |
| [流式 Markdown](./markdown) | 传入截至当前的全文，返回一组带稳定 key 的已渲染块 | `@xihan-ui/markdown` |
| [代码着色](./code-highlight) | 零依赖的粗粒度词法着色，也是一个可替换的端口 | `@xihan-ui/code-highlight` |

## 不在组件册中的原因

组件册每一页固定给出解剖、部件、状态机、connect API 与键盘规格，因为组件的契约即这几项。本册四项均不适用：全局配置是一个 provide 函数，命令式服务返回一个对象，Markdown 渲染器产出数据而不是 DOM。放入组件册只会使该册的页内结构失去意义。

但能力清单应当完整。按其他组件库的习惯查找对应能力时（Element Plus 的 `ElMessageBox`、Ant Design 的 `App.useApp()`、Naive UI 的 `useDialog`、Semi Design 的 Markdown 渲染器），它们在本册，不在组件册。

---

来源：https://ui.docs.xihanfun.com/runtime/markdown

# 流式 Markdown

`@xihan-ui/markdown` 解决一个具体问题：AI 逐 token 输出 Markdown，需要边接收边渲染，且不能每帧重建整段 DOM：重建一次，用户的选区和滚动位置即丢失。

对外只有一个工厂。

```ts
import { createStreamRenderer } from "@xihan-ui/markdown";

const renderer = createStreamRenderer();

// 每收到一批增量，把截至当前的全文整份传入
const blocks = renderer.render(fullTextSoFar);

// 流结束时告诉它
const final = renderer.render(fullText, { ended: true });

renderer.dispose();
```

## 产出的是块，不是一整串 HTML

```ts
interface RenderedBlock {
  readonly key: string; // 稳定 key
  readonly kind: "markdown" | "code" | "math" | "html";
  readonly html: string; // 已消毒，可直接插进 DOM
  readonly complete: boolean; // 该块是否已闭合
  readonly lang?: string; // 围栏语言标注，仅 code 块有
  readonly source?: string; // 块正文的原始文本，仅 code 与 math 两种块有
}
```

三点需要单独说明：

`key` 是稳定的。生长中的块恒为 `LIVE_BLOCK_KEY`，定型块由下标与内容摘要拼成。框架据此复用同一份 DOM 只改文本，而不是整段重建。`v-for` 中必须用它作为 key，使用下标会失去这一保证。

`render` 是幂等的。传同一份全文调用多少次结果都相同，内部按块 memo，已定型的块不会重渲染。因此不需要自行做增量 diff，每帧整份传入即可。

`complete` 用于决策。未闭合的块随时会变，昂贵的渲染（如[代码着色](./code-highlight)）等它闭合后再执行。[代码视图](../components/code-view)组件的 `complete` 与 `highlightWhileStreaming` 两个 prop 即为此保留。

## 未传 `ended` 的后果

不传等同于仍在生长：最后一块按未闭合处理，key 为 `LIVE_BLOCK_KEY`。流结束时必须传 `{ ended: true }`，否则最后一段永远停在生长态，key 也无法确定。

## 这是一个子集，不是 CommonMark 实现

当前对官方 652 条用例的一致率是 489/652（75.0%），逐节数字在包内的 `tests/commonmark-baseline.json`。

这个数字不是目标，是事实的记录。本包服务于 AI 聊天输出，不是通用 Markdown 渲染，因此不追求满分。

### 按设计不通过的

| 节 | 条数 | 原因 |
| --- | --- | --- |
| HTML blocks | 0/44 | 原生 HTML 块不透传 |
| Raw HTML | 7/20 | 行内原生 HTML 不透传 |

消毒位于解析器内部（`html: false` 加协议白名单），而不是渲染后再清洗一次。不透传 HTML 是这条安全约束的代价，也是本包最重要的一条约束，不会为了通过率修改。把这两节摘掉之后的一致率是 482/588（82.0%）。

内容来源可信且确实需要透传 HTML 时，本包不适用：换用通用 Markdown 渲染器并自行接入消毒。

### 已知缺口

| 缺口 | 波及 | 说明 |
| --- | --- | --- |
| 列表项内容缩进的判定 | `List items` 35/48、`Lists` 19/26 | 延续行要缩进到标记后内容起始列才属于该项；当前按剥除最多 N 个空格近似，相差一列无法区分。目前最大的缺口 |
| 标题中的换行 | `Link reference definitions` 19/27 | 跨行标题的换行被丢弃，规范要求原样保留在 `title` 属性中 |
| 制表符在列表与引用中的展开 | `Tabs` 6/11 | 行首缩进已按 4 列制表位计算，列表项内容缩进与引用标记后的制表符尚未使用同一套换算 |

## 不暴露解析中间态的原因

解析、切块、冻结缓存一概不对外。中间态暴露后，消费方迟早会绕过缓存直接修改块，增量渲染的保证随之失效。定制渲染在块这一层进行：`kind` 与 `complete` 足以决定每一块交给谁渲染。

## 与组件的配合

它产出数据，不产出 DOM，因此框架无关。一条助手消息的正文即它的块列表，典型接法是配合[消息流](../components/message-feed)：

```vue
<XhMessageFeedItem :item-id="message.id" :item-index="index" item-role="assistant">
  <div v-for="block in blocks" :key="block.key" v-html="block.html" />
</XhMessageFeedItem>
```

不分条、只向下追加的输出（命令回显、构建日志）配合[日志](../components/log)，贴底机制相同。

`v-html` 在这里是安全的：`html` 字段已经消毒，这正是消毒位于解析器内部的意义。

代码块的 `html` 是一份降级产物：渲染好的 `<pre><code>`，语言标注在 `lang` 上。原始代码文本另存于 `source`，因此换成组件形态只需一次转交：`source` 交给[代码视图](../components/code-view)的 `code`，`lang` 与 `complete` 原样传入，行号、指定行高亮、超长折叠与闭合后着色都由它负责。


```vue
<XhCodeViewRoot :code="block.source" :lang="block.lang" :complete="block.complete" line-numbers>
  <XhCodeViewPre><XhCodeViewCode /></XhCodeViewPre>
</XhCodeViewRoot>
```

---

来源：https://ui.docs.xihanfun.com/runtime/services

# 命令式服务

部分反馈不适合写成模板：删除前确认、保存后提示，这类反馈没有挂载位置的问题，适合一次调用弹出。库提供四个服务工厂：对话框、轻提示、通知与顶部进度条。

四者都自建宿主容器、自行管理挂载与卸载，用完后需调用 `dispose()`。

工厂返回即可接收命令，与宿主何时渲染无关：在组件的挂载回调（Vue 的 `onMounted`、React 的 `useEffect`、自定义元素的 `connectedCallback`）里懒建服务并紧接着发第一条命令，与在模块作用域调用一样成立，不需要等一帧。

## 对话框服务

```ts
import { createDialogService } from "@xihan-ui/vue";

const dialog = createDialogService({ okText: "确定", cancelText: "取消" });

const ok = await dialog.confirm({
  title: "删除这条记录？",
  content: "删除后不可恢复。",
  tone: "danger",
  okText: "删除",
});
if (ok) {
  // 用户已确认，且 onOk（如提供）已执行完成
}

dialog.dispose();
```

| 方法 | 返回 | 说明 |
| --- | --- | --- |
| `confirm(options)` | `Promise<boolean>` | 确认走完 `onOk` 后 resolve `true`；取消或 Escape resolve `false` |
| `info` / `success` / `warning` / `error` | `Promise<void>` | 单按钮告知框，没有取消按钮，徽记由预设档决定 |
| `prompt(options)` | `Promise<T \| null>` | 取值型弹窗：确认后返回一份值，取消 resolve `null` |
| `setConfig(next)` | — | 更换全局配置源 |
| `dispose()` | — | 卸载宿主应用并移除容器 |

`ConfirmOptions` 的字段：`title`（必填）、`content`、`tone`（确认按钮语气，危险操作传 `danger`）、`badge`（标题旁的类型徽记）、`okText` / `cancelText`、`onOk`。

### 异步确认

`onOk` 返回 Promise 时，确认按钮自动进入 pending 并阻止关闭；失败时保持打开，用户可以重试或取消。这是它相对于自行编写 `<XhDialog>` 的主要便利。

```ts
await dialog.confirm({
  title: "发布这个版本？",
  onOk: () => api.publish(id), // 拒绝时对话框不关闭，用户可以再次确认
});
```

### 正文内容

`content` 接受字符串与渲染函数。字符串经 `XhDialogDescription` 渲染（读屏的 `aria-describedby` 指向它），函数则整块渲染在正文位：

```ts
await dialog.confirm({
  title: "导入这份数据？",
  content: () => h(XhAlertRoot, { tone: "warning" }, () => "已存在的记录会被覆盖"),
});
```

不接受裸 VNode：服务宿主常驻，忙态切换时整棵重渲染，同一个 VNode 实例被复用时的行为未定义。

### 取值型弹窗

`prompt` 负责在弹窗中填写内容并把值带回。每次打开创建一份初值，`body` 与 `onOk` 拿到的是同一份可写代理：

```ts
const next = await dialog.prompt({
  title: "改邮箱",
  initialValue: { email: "", password: "" },
  body: value => [
    h(XhTextFieldRoot, { "value": value.email, "onUpdate:value": (v: string) => (value.email = v) }, () => h(XhTextFieldInput)),
    h(XhTextFieldRoot, { "type": "password", "value": value.password, "onUpdate:value": (v: string) => (value.password = v) }, () => h(XhTextFieldInput)),
  ],
  initialFocus: "[data-scope=text-field][data-part=input]",
  onOk: value => value.email.includes("@"), // 返回 false 表示校验未通过，弹窗不关闭
});
// next 是 { email, password } 的普通对象快照；取消 / Escape 得到 null
```

`prompt` 的 `onOk` 返回 `false` 表示不放行。`confirm` 的 `onOk` 不适用这条：它的返回值不参与判定，只有拒绝才阻止关闭。

### 同一时刻只有一个

后续调用排队顺次弹出，避免多层模态叠加。当前项的内容与遮罩全部完成有限退场动画后，队列才放出下一项；无动画或减弱动效时不额外等待固定时间。

## 轻提示服务

```ts
import { createToastService } from "@xihan-ui/vue";

const toast = createToastService({ placement: "top", max: 5 });

toast.success("已保存");
toast.danger("保存失败，请重试", { duration: 8000 });
```

| 方法 | 返回 | 说明 |
| --- | --- | --- |
| `create(options)` | `string`（id） | 入队；同 id 已存在则就地改写 |
| `update(id, options)` | — | 改写正在显示的条目 |
| `dismiss(id)` / `dismissAll()` | — | 手动关闭 |
| `info` / `success` / `warning` / `danger` | `string`（id） | 语气快捷方法，第一个参数是正文 |
| `loading(message, options)` | `string`（id） | 以 `loading` 态弹出一条并返回 id，之后用 `update` 收尾 |
| `promise(input, options)` | `Promise<T>` | 先弹出 loading，落定后就地改写为成功 / 失败 |
| `pauseAll()` / `resumeAll()` | — | 整组暂停计时、再恢复 |
| `setConfig(next)` | — | 更换全局配置源（切换语言用） |
| `dispose()` | — | 卸载宿主应用并移除容器 |

### 在途 → 完成

`loading` 与 `update` 是一条完整的链，不连发两条：

```ts
const id = toast.loading("正在上传…");
try {
  await upload(file);
  toast.update(id, { loading: false, tone: "success", title: "上传完成" });
}
catch {
  toast.update(id, { loading: false, tone: "danger", title: "上传失败" });
}
```

同一条链有封装写法，结果与拒绝都原样返回：

```ts
const url = await toast.promise(upload(file), {
  loading: "正在上传…",
  success: result => `上传完成：${result.name}`,
  error: reason => `上传失败：${(reason as Error).message}`,
});
```

### 行内动作

提供 `actionLabel` 才渲染动作按钮，按下的行为写在 `onAction` 中：

```ts
toast.info("已删除 3 条记录", { duration: 8000, actionLabel: "撤销", onAction: () => restore() });
```

文案进入队列记录，回调保存在服务中：记录只存放可整份替换、序列化、比对的纯数据。

### 重复与优先级

同一句错误连续发出多次时，`dedupe: 'content'` 把它们合并为一条并在标题后追加计数：

```ts
const toast = createToastService({ dedupe: "content" });
toast.danger("同步失败");
toast.danger("同步失败"); // 界面上是「同步失败 ×2」
```

超出 `max` 时先移除低优先级的条目，同级中移除最旧的。未指定优先级时按语气派生（`danger` 最高、
`warning` 次之、其余持平），也可以逐条写 `priority`：一条报错不应被随后的多条提示挤出。

服务档的默认落位是 `top`，最多同时留 5 条，超出时移除最旧的。落位是整个服务的口径：
一次操作的反馈不应逐条分散到不同位置，在 `createToastService({ placement })` 中一次确定。

默认不显示关闭按钮。一条轻提示是一枚状态字形加一句话的小条，到时自行消失；
多一个关闭按钮就多一次是否点击的判断。确需保留出口（如 `duration: 0` 的常驻提示）时显式开启：

```ts
toast.danger("导出失败，请重试", { duration: 0, closable: true });
```

## 通知服务

```ts
import { createNotificationService } from "@xihan-ui/vue";

const notify = createNotificationService({ placement: "bottom-end", max: 5 });

notify.info("有新的审批", { description: "张三提交了一份请假单" });
notify.danger("同步失败", { description: "网络中断，稍后自动重试", duration: 0 });
```

| 方法 | 返回 | 说明 |
| --- | --- | --- |
| `create(options)` | `string`（id） | 入队；同 id 已存在则就地改写 |
| `update(id, options)` | — | 改写正在显示的条目 |
| `dismiss(id)` / `dismissAll()` | — | 手动关闭 |
| `info` / `success` / `warning` / `danger` | `string`（id） | 语气快捷方法，第一个参数是标题，正文写在 `options.description` |
| `pauseAll()` / `resumeAll()` | — | 当前卡片整组暂停计时、再恢复 |
| `setConfig(next)` | — | 更换全局配置源（切换语言用） |
| `dispose()` | — | 卸载宿主应用并移除容器 |

行内动作、`dedupe` 与 `priority` 与轻提示同形：两者运行同一台队列状态机，上限、移除与
合并计数只有一份实现。

与轻提示的两处不同：条目有标题与正文两层，且单条可以用 `options.placement` 覆盖落位：
消息各有轻重，逐条决定位置是合理的。`duration: 0` 即常驻不消失，由用户手动关闭。

队列需要位于页面结构中（通知中心一栏自行排版）时改用组件形态的
[通知](../components/notification)，两者不共享队列。

## 顶部进度条服务

路由守卫与请求拦截器都在组件树之外，需要命令式入口：

```ts
import { createLoadingBarService } from "@xihan-ui/vue";

const bar = createLoadingBarService();

router.beforeEach(() => { bar.start(); });
router.afterEach(() => { bar.finish(); });

http.interceptors.request.use((cfg) => { bar.start(); return cfg; });
http.interceptors.response.use(
  (res) => { bar.finish(); return res; },
  (err) => { bar.error(); return Promise.reject(err); },
);
```

| 方法 | 说明 |
| --- | --- |
| `start()` | 在途计数 +1；从 0 起跳即开始爬升 |
| `finish()` | 在途计数 −1（下限为 0，多次调用不会变负）；归零才收起 |
| `error()` | 强制归零并以 `errorTone`（默认 `danger`）收起 |
| `finishAll()` | 无论剩余多少在途请求一律收起 |
| `set(value)` | 切换为确定进度；再次 `start()` 回到不确定 |
| `setConfig(next)` | 更换全局配置源 |
| `dispose()` | 卸载宿主应用并移除容器 |

在途计数是这层封装的要点。写成布尔开关时，三个并发请求中第一个返回就会收起进度条，其余两个仍在进行：进度条比请求先结束。

## 切换语言（Vue 侧）

Vue 的四个服务都自建宿主应用，无法接入组件树中的 `provideXhConfig`，因此配置从 `config` 选项提供。传入 ref 或 getter，不传一次性的对象：传对象时文案只在创建服务时求值一次，之后应用切换语言，服务子树中的按钮与读屏名不随之更新；队列中排队的对话框也会跨过这次切换。

```ts
const dialog = createDialogService({
  config: () => ({ locale: app.locale.value, translations: myOverrides[app.locale.value] }),
  okText: () => t("common.ok"),
  cancelText: () => t("common.cancel"),
});

// 没有响应式源时也可以命令式推送
dialog.setConfig({ locale: "en-US" });
```

取值优先级：调用点 > 服务选项 > `config.translations.<组件>` > 组件内建默认。

## Web Components 侧

同样四个工厂，从 `@xihan-ui/web-components/services` 取，句柄的方法与 Vue 侧同名同形：

```ts
import { createToastService } from "@xihan-ui/web-components/services";

const toast = createToastService({ placement: "top", max: 5 });
toast.success("已保存");
```

服务自行生成真实的自定义元素与角色节点（`<xh-toast>`、`<xh-notification>`、`<xh-dialog>`、
`<xh-loading-bar>`），得到的仍是一棵可查询、可选中的 DOM；用到的元素在服务创建时按需注册，
不必先 `import '@xihan-ui/web-components/define'`。

与 Vue 侧的两处不同都来自这一侧的身份：

- 没有 `config` 入参，也没有 `setConfig`。全局配置沿 DOM 祖先链解析，服务的宿主容器挂在
  文档中，语言、尺寸、浮层落点由 `setXhConfig` 与外层 `<xh-config>` 决定。
- 对话框的正文渲染函数接收节点：`content: (body) => { … }` 拿到正文角色节点后自行写入，
  没有 `prompt`：取值型弹窗需要放表单时直接写 `<xh-dialog>`。

## 不适合使用服务的场景

- 确认可撤销的操作：直接执行，然后发一条带撤销按钮的轻提示。事前确认对用户是额外的一道关卡，撤销才是有效的兜底。
- 提示内容较长或需要用户处理：轻提示会自行消失，用[警告提示](../components/alert)常驻，或用[通知](../components/notification)分标题与正文两层。
- 对话框中需要放表单：用组件形态的[对话框](../components/dialog)，服务档只提供标题、正文与按钮行。

## 一个应用创建几个

各创建一个，挂在应用启动处，全局共用。每个页面各创建一个会产生多个宿主容器，多组提示互相遮盖。

服务不经 provide/inject，因此在组件外（路由守卫、拦截器、store）也能调用，这正是命令式的意义。但也因此它无法获取 [全局配置](./config) 注入的文案：服务的文案在 `createDialogService` / `createToastService` / `createNotificationService` 的入参中单独提供。

## 与其他库的对应关系

| 其他库 | 本库 |
| --- | --- |
| Element Plus `ElMessageBox.confirm` | `dialog.confirm` |
| Element Plus `ElMessage` / `ElNotification` | `toast.*` / [通知](../components/notification) |
| Ant Design `Modal.confirm` / `message` / `notification` | `dialog.confirm` / `toast.*` / [通知](../components/notification) |
| Naive UI `useDialog` / `useMessage` | `createDialogService` / `createToastService` |
| Semi Design `Modal.confirm` / `Toast` | `dialog.confirm` / `toast.*` |

轻提示与通知按发起方分工。轻提示是用户刚才操作的结果，一句话、自行消失；[通知](../components/notification)是系统或他人主动推送的消息，有标题与正文两层、可以常驻。两者都有服务档（`createToastService` / `createNotificationService`），队列各自独立；通知另有组件形态 `XhNotificationRoot`，队列需要位于页面结构中（通知中心一栏自行排版）时使用。轻提示没有容器组件：反馈落位是整个服务的口径。