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

package/dist/define.d.ts

@@ -1,7 +1,9 @@
+import { r as PropertyValues } from "./types-BvWWqMd_.js";
 import { t as XhReactiveElement } from "./element-DRoFjrYO.js";
-import { t as Spreader } from "./spread-Ch8ZXZDC.js";
+import { l as Spreader, n as XhConfigScope, t as XhConfig } from "./config-Cz16-P4i.js";
+import { AccordionNode, AlertSchema, AnchorTranslations, BadgeVariant, BreadcrumbTranslations, CalendarDay, CalendarSelectionMode, CalendarView, CalendarWeekDay, CalendarWeekdayFormat, CarouselTranslations, CascaderExpandTrigger, CascaderNode, CascaderSchema, CascaderValue, CheckboxCheckedState, CheckboxGroupNode, ColorPickerFormat, ColorPickerTranslations, ComboboxInputBehavior, ComboboxNode, ComboboxSchema, ComponentMeta, ComposerRunStatus, ComposerTranslations, ContextMenuNode, ContextMenuSchema, DateFieldTranslations, DateGranularity, DatePickerPreset, DatePickerSchema, DateSegmentSet, DateSegmentType, DownloadTriggerData, DrawerSchema, EditableActivationMode, EditableSubmitMode, EmptyStateLive, FieldsetTranslations, FileUploadRemoteFile, FileUploadSchema, FileUploadTranslations, FloatingPanelPosition, FloatingPanelSchema, FloatingPanelSize, FloatingPanelStage, FormErrorPatch, FormSchema, FormValidateOn, FormValues, HeatmapAxisInput, HeatmapGrid, HeatmapMatrixGrid, HeatmapMonthGrid, HeatmapPalette, HeatmapTranslations, HeatmapValue, HeatmapVariant, HotkeysPlatform, HotkeysTarget, HotkeysTranslations, IconWeight, ImageCropperRect, ImageCropperSchema, ImageCropperShape, ImageViewerItem, ImageViewerTranslations, JsonViewerTranslations, ListboxNode, ListboxSelectionMode, LoadingBarTranslations, MasonryColumns, MasonryProps, MenuNode, MenubarNode, NavigationMenuNode, NavigationMenuTranslations, NumberFieldSchema, PaginationTranslations, PasswordInputTranslations, PinInputTranslations, PinInputType, PopoverTranslations, ProgressGapPosition, ProgressVariant, RadioGroupNode, ResolvedToast, ScrollAreaOrientation, ScrollbarSchema, ScrollbarType, SegmentedNode, SelectNode, SelectSchema, SideNavNode, SideNavSchema, SideNavTranslations, SignaturePadDrawingOptions, SignaturePadTranslations, SkeletonVariant, SliderSchema, SliderValueTextDetails, SpaceProps, SpinnerTranslations, SplitterPanelProps, TableColumnDef, TableRowDef, TableSelection, TableSelectionMode, TableSortDescriptor, TabsActivationMode, TabsNode, TabsVariant, TagSchema, TagVariant, TagsInputBlurBehavior, TextFieldSchema, TextFieldType, ThreadStatus, ThreadTranslations, TimeFieldSchema, TimeGranularity, TimeHourCycle, TimePickerPreset, TimePickerSchema, TimerSchema, ToastOptions, ToastPlacement, ToastRecord, ToastTranslations, ToastType, ToasterTranslations, ToggleGroupNode, TourStep, TourTranslations, TransferFilter, TransferItem, TreeNode, TreeSchema, TreeSelectSchema, TreeSelectionMode, VirtualizerAlign, VirtualizerItemState, XhTranslationOverrides } from "@xihan-ui/headless";
+import { MotionPreference } from "@xihan-ui/motion";
 import { ActionVariant, ControlVariant, Direction, HighlighterPort, IconRecord, Orientation, Placement, Size, Tone } from "@xihan-ui/kernel";
-import { AccordionNode, AlertSchema, AnchorTranslations, BadgeVariant, BreadcrumbTranslations, CalendarDay, CalendarSelectionMode, CalendarWeekDay, CalendarWeekdayFormat, CarouselTranslations, CascaderExpandTrigger, CascaderNode, CascaderSchema, CascaderValue, CheckboxCheckedState, CheckboxGroupNode, ColorPickerFormat, ColorPickerTranslations, ComboboxInputBehavior, ComboboxNode, ComponentMeta, ComposerRunStatus, ComposerTranslations, ContextMenuNode, ContextMenuSchema, DateGranularity, DatePickerSchema, DateSegmentType, DrawerSchema, EditableActivationMode, EditableSubmitMode, EmptyStateLive, FileUploadRemoteFile, FileUploadSchema, FileUploadTranslations, FormErrorPatch, FormSchema, FormValidateOn, FormValues, IconWeight, ImageViewerItem, ImageViewerTranslations, ListboxNode, ListboxSelectionMode, LoadingBarTranslations, MenuNode, MenubarNode, NavigationMenuNode, NavigationMenuTranslations, PaginationTranslations, PinInputTranslations, PinInputType, PopoverTranslations, ProgressGapPosition, ProgressVariant, RadioGroupNode, ResolvedToast, ScrollAreaOrientation, ScrollAreaType, SelectNode, SelectSchema, SideNavNode, SideNavSchema, SideNavTranslations, SkeletonVariant, SliderSchema, SliderValueTextDetails, SpinnerTranslations, SplitterPanelProps, TableColumnDef, TableRowDef, TableSelection, TableSelectionMode, TableSortDescriptor, TabsActivationMode, TabsNode, TabsVariant, TagsInputBlurBehavior, TextFieldSchema, ThreadStatus, ThreadTranslations, TimeGranularity, TimeHourCycle, ToastOptions, ToastPlacement, ToastRecord, ToastTranslations, ToastType, ToasterTranslations, ToggleGroupNode, TourStep, TourTranslations, TransferFilter, TransferItem, TreeNode, TreeSchema, TreeSelectSchema, TreeSelectionMode, VirtualizerAlign, VirtualizerItemState } from "@xihan-ui/headless";
 //#region src/dom/part-contract.d.ts
 /** 只取校验用得上的两项，避免把 `Anatomy<具体 part 联合>` 收窄成 `Anatomy<string>` 时不可赋值。 */
 interface PartContract {
@@ -54,6 +56,12 @@ declare abstract class XhElement extends XhReactiveElement {
    */
   protected onPartsReleased(_nodes: readonly HTMLElement[]): void;
   connectedCallback(): void;
+  private stopConfigWatch;
+  /**
+   * 把沿祖先链解析到的全局配置并进这份 props：translations 按组件名分桶合并，
+   * locale 与 size 在元素上没给时取配置里的。不跑机器的元素在 wire() 里用它包一层。
+   */
+  protected configured<T extends object>(component: string, props: T): T;
   /** 已排了断开后的交还，还没跑到。 */
   private releaseScheduled;
   disconnectedCallback(): void;
@@ -67,6 +75,13 @@ declare abstract class XhElement extends XhReactiveElement {
    * 宿主离场后没有观察器再触发更新，refreshParts 那条交还路径够不着，没摘的监听器会经节点钉住整台宿主。
    */
   private releaseAllParts;
+  /** 层叠上下文那条诊断已经查过。 */
+  private stackingChecked;
+  /**
+   * 浮层首次展开后查一次祖先链有没有建层叠上下文，命中即投诊断。
+   * 每个实例只查一次，重定位与后续展开不再重复。
+   */
+  private checkStackingTrap;
   /** 标记 wire() 正在写属性。 */
   private wiring;
   /**
@@ -102,8 +117,13 @@ declare abstract class XhElement extends XhReactiveElement {
  * @csspart indicator - 展开方向指示符
  */
 declare class XhAccordionElement extends XhElement {
+  private readonly exits;
+  private readonly exitIdGen;
+  private readonly exitScope;
+  private exitConfig;
+  private ensureExitConfig;
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "indicator" | "item" | "trigger" | "content">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "header" | "trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -232,7 +252,7 @@ declare class XhAlertElement extends XhElement {
  */
 declare class XhAnchorElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "list" | "link">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "indicator" | "list" | "link">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -360,6 +380,11 @@ declare class XhAvatarElement extends XhElement {
  * @attr {'solid'|'subtle'|'outline'} variant - 视觉变体
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @attr {number} count - 计数：给了它徽标就自己出数字，超过 max 写成「max+」；节点已有内容时以内容为准
+ * @attr {number} max - 计数上限，默认 99
+ * @attr {boolean} show-zero - 计数为 0 时也显示，默认不显示
+ * @attr {boolean} dot - 只出一个点，不出数字
+ * @attr {string} label - 读屏怎么念这枚徽标，例如「3 条未读」
  * @csspart root - 承载 data-scope/data-part/data-* 的展示节点
  */
 declare class XhBadgeElement extends XhElement {
@@ -383,10 +408,37 @@ declare class XhBadgeElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    count: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    max: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    showZero: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    dot: {
+      type: BooleanConstructor;
+    };
+    label: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
   };
   variant?: BadgeVariant;
   tone?: Tone;
   size?: Size;
+  count?: number;
+  max?: number;
+  showZero?: boolean;
+  dot?: boolean;
+  label?: string;
   protected wire(): void;
 }
 //#endregion
@@ -448,6 +500,8 @@ declare class XhBreadcrumbElement extends XhElement {
  * @customElement xh-button
  * @attr {'button'|'submit'|'reset'} type - 原生按钮类型，默认 button
  * @attr {boolean} disabled - 禁用（原生 disabled，丢焦点）
+ * @attr {boolean} icon-only - 只有图标：左右内距清零、宽高相等；作者须自行给可及名
+ * @attr {boolean} full-width - 撑满行宽
  * @attr {boolean} loading - 加载中（aria-disabled，保留焦点并拦截点击）
  * @attr {'solid'|'subtle'|'outline'|'ghost'} variant - 视觉变体
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
@@ -464,6 +518,14 @@ declare class XhButtonElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    iconOnly: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    fullWidth: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
     loading: {
       type: BooleanConstructor;
     };
@@ -473,6 +535,8 @@ declare class XhButtonElement extends XhElement {
   };
   type?: 'button' | 'submit' | 'reset';
   disabled?: boolean;
+  iconOnly?: boolean;
+  fullWidth?: boolean;
   loading?: boolean;
   variant?: ActionVariant;
   tone?: Tone;
@@ -497,30 +561,41 @@ declare class XhButtonElement extends XhElement {
  * @attr {string} default-focused-value - 非受控初始聚焦日；缺省时退回首个选中值，再退回今天
  * @attr {string} min - 可选范围下界（含当天），界外的日子转 aria-disabled 但仍可聚焦
  * @attr {string} max - 可选范围上界（含当天）
- * @attr {string} locale - 决定周首日与文案，默认 zh-CN
+ * @attr {string} locale - 决定周首日与文案；不给按宿主语言，宿主也没有时按 en-US
  * @attr {string} time-zone - 判定今天与格式化用的时区，默认宿主本地时区
  * @attr {boolean} disabled - 整张禁用：翻月按钮转原生 disabled，格子全转 aria-disabled
  * @attr {boolean} read-only - 只读：翻月与移动焦点照常，只是选不动值
  * @attr {'narrow'|'short'} weekday-format - 表头缩写粒度，默认 short
  * @attr {boolean} fixed-weeks - 恒渲染六行
+ * @attr {'day'|'month'|'quarter'|'year'} view - 挑的粒度，默认 day；这一档也是「点一格即选中」的那一档
+ * @attr {'day'|'month'|'quarter'|'year'} active-view - 受控：面板此刻钻到了哪一层；缺省跟着 view
+ * @attr {'day'|'month'|'quarter'|'year'} default-active-view - 非受控初值，缺省同 view
+ * @attr {boolean} week-selection - 周选：点任意一天选中它所在的整周（view=day 且区间模式下生效）
+ * @attr {number} visible-count - 并排展示几页
  * @fires value-change - 选中集合变化；detail 为 `{ value: string[] }`
  * @fires focused-value-change - 聚焦日变化；detail 为 `{ focusedValue: string }`
+ * @fires active-view-change - 钻到了另一层；detail 为 `{ activeView: 'day'|'month'|'quarter'|'year' }`
  * @csspart root - 组件根容器
  * @csspart header - 标题栏外壳
+ * @csspart prev-year-trigger - 快速往前翻一大步（日视图一年、粗粒度十页）；可选
  * @csspart prev-trigger - 上一月；越过 min 时转原生 disabled
  * @csspart next-trigger - 下一月；越过 max 时转原生 disabled
+ * @csspart next-year-trigger - 快速往后翻一大步；可选
  * @csspart heading - 展示月标题（grid 的 aria-labelledby 目标）
+ * @csspart heading-year-trigger - 标题里年那一截，点它钻到十年格；文字由元素填。年视图下已到顶，转原生 disabled；可选
+ * @csspart heading-month-trigger - 标题里月那一截，点它钻到月格；只有日视图有这一截，其余层带 hidden；可选
  * @csspart grid - role=grid 容器，键盘在此收口
  * @csspart grid-head - role=rowgroup 表头组，里面套一个 week-row
  * @csspart week-day - role=columnheader 列头，须自带 value 属性标明列序 0-6
  * @csspart grid-body - role=rowgroup 日期组
  * @csspart week-row - role=row 周行，表头与日期行共用
+ * @csspart week-number - 行首的周序号格（role=rowheader），须自带 value 属性（行首那天）；可选
  * @csspart cell - role=gridcell 日期格，承载 aria-selected；须自带 value 属性（ISO 串）标明是哪一天
  * @csspart cell-trigger - 可点可聚焦层，承载 aria-disabled 与 roving tabindex
  */
 declare class XhCalendarElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "grid" | "heading" | "prev-trigger" | "next-trigger" | "grid-head" | "week-day" | "grid-body" | "week-row" | "cell" | "cell-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "grid" | "heading" | "prev-trigger" | "next-trigger" | "prev-year-trigger" | "next-year-trigger" | "heading-year-trigger" | "heading-month-trigger" | "grid-head" | "week-day" | "grid-body" | "week-row" | "week-number" | "cell" | "cell-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -591,6 +666,35 @@ declare class XhCalendarElement extends XhElement {
       type: BooleanConstructor;
       attribute: string;
     };
+    view: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    activeView: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    defaultActiveView: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    weekSelection: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    visibleCount: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
     isDateUnavailable: {
       attribute: boolean;
     };
@@ -608,9 +712,15 @@ declare class XhCalendarElement extends XhElement {
   disabled?: boolean;
   readOnly?: boolean;
   fixedWeeks?: boolean;
+  view?: CalendarView;
+  activeView?: CalendarView;
+  defaultActiveView?: CalendarView;
+  weekSelection?: boolean;
+  visibleCount?: number;
   isDateUnavailable?: (value: string) => boolean;
   private readonly notifyValue;
   private readonly notifyFocus;
+  private readonly notifyActiveView;
   private readonly ctrl;
   private machineProps;
   /** 当前展示月的日期矩阵，作者照它重画网格。机器尚未建起时给空数组。 */
@@ -656,7 +766,7 @@ declare class XhCalendarElement extends XhElement {
  */
 declare class XhCarouselElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "prev-trigger" | "next-trigger" | "viewport" | "item-group" | "indicator-group">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "viewport" | "indicator" | "prev-trigger" | "next-trigger" | "item-group" | "indicator-group">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -786,10 +896,11 @@ declare class XhCarouselElement extends XhElement {
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly/data-invalid）
  * @csspart label - 标题（aria-labelledby 目标）
+ * @csspart control - 触发按钮与清空按钮的收纳容器：描边、底色与聚焦环都落在这一层
  * @csspart trigger - role=combobox 的触发按钮，同时是定位锚点，须是原生 button
  * @csspart value-text - 整条路径的显示位；留空即由元素填入，作者写了内容则归作者
  * @csspart indicator - 展开指示符（aria-hidden，data-state 随开合）
- * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，可及名字取 translations.clearTrigger
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - 浮层壳（焦点域与消解层的根节点），键盘在此收口，收起时带 hidden；根列没有条目时带 data-empty
  * @csspart input - 搜索框（content 顶部）；没开 searchable 时带 hidden。上下键走候选、Enter 选中、Escape 先清词
@@ -803,7 +914,7 @@ declare class XhCarouselElement extends XhElement {
  */
 declare class XhCascaderElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "content" | "label" | "positioner" | "item-text" | "item-indicator" | "input" | "empty" | "clear-trigger" | "value-text" | "column" | "search-list" | "search-item">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "control" | "positioner" | "clear-trigger" | "item-text" | "item-indicator" | "input" | "empty" | "column" | "value-text" | "search-list" | "search-item">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -944,6 +1055,8 @@ declare class XhCascaderElement extends XhElement {
   private readonly cascaderScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   /** value-text 是否归元素填：首次见到该节点时定，之后不再回读（回读到的会是自己写的字）。 */
   private readonly ownsValueText;
   /** 空态占位的文案是否归元素填，判定同 ownsValueText。 */
@@ -990,6 +1103,9 @@ declare class XhCascaderElement extends XhElement {
  * @attr {boolean|'indeterminate'} checked - 受控选中；写 indeterminate 为半选，缺省该属性即非受控
  * @attr {boolean|'indeterminate'} default-checked - 非受控初值
  * @attr {boolean} disabled - 禁用
+ * @attr {boolean} read-only - 只读：勾不动，但仍可聚焦、仍参与提交
+ * @attr {boolean} invalid - 校验失败态
+ * @attr {boolean} required - 必填
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
  * @fires checked-change - checked 状态变化；detail 为 `{ checked: boolean }`
@@ -997,10 +1113,12 @@ declare class XhCascaderElement extends XhElement {
  * @csspart indicator - 选中标记
  * @attr {string} name - 表单字段名；给了 hidden-input 才参与提交
  * @csspart hidden-input - type=hidden 的表单出口，省略该节点即不参与表单
+ * @csspart label - 可选：包住 root 与 text 的 <label>，点文字即切换
+ * @csspart text - 可选：控件旁的文字
  */
 declare class XhCheckboxElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "hidden-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "label" | "text" | "hidden-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1018,6 +1136,16 @@ declare class XhCheckboxElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    readOnly: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    invalid: {
+      type: BooleanConstructor;
+    };
+    required: {
+      type: BooleanConstructor;
+    };
     name: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -1034,6 +1162,9 @@ declare class XhCheckboxElement extends XhElement {
   checked?: CheckboxCheckedState;
   defaultChecked?: CheckboxCheckedState;
   disabled?: boolean;
+  readOnly?: boolean;
+  invalid?: boolean;
+  required?: boolean;
   name?: string;
   value?: string;
   tone?: Tone;
@@ -1072,7 +1203,7 @@ declare class XhCheckboxElement extends XhElement {
  */
 declare class XhCheckboxGroupElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "label" | "item-text" | "hidden-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "indicator" | "trigger" | "label" | "item-text" | "hidden-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1171,7 +1302,7 @@ declare class XhCheckboxGroupElement extends XhElement {
  */
 declare class XhClipboardElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "trigger" | "label" | "input" | "control">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "trigger" | "label" | "control" | "input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1204,6 +1335,7 @@ declare class XhClipboardElement extends XhElement {
  * @customElement xh-code-block
  * @attr {string} code - 代码原文，只用于数行数预撑高度
  * @attr {string} code-lang - 围栏语言标注，空白时按 plaintext 处理
+ * @attr {boolean} wrap - 长行自动换行，默认关（长行横向滚动）
  * @attr {boolean} complete - 代码块是否已闭合
  * @csspart root - 外壳，承载 data-lang / data-complete
  * @csspart lang-label - 语言角标，纯装饰且对读屏隐藏
@@ -1229,6 +1361,9 @@ declare class XhCodeBlockElement extends XhElement {
       };
       attribute: string;
     };
+    wrap: {
+      type: BooleanConstructor;
+    };
     complete: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -1243,6 +1378,7 @@ declare class XhCodeBlockElement extends XhElement {
   };
   code?: string;
   codeLang?: string;
+  wrap?: boolean;
   complete?: boolean;
   highlightWhileStreaming?: boolean;
   /** 换一个着色实现（典型是接 Shiki）；置 null 关掉着色。只走 property，属性表达不了对象。 */
@@ -1266,8 +1402,13 @@ declare class XhCodeBlockElement extends XhElement {
  * @csspart content - 可折叠内容（收起时隐藏）
  */
 declare class XhCollapsibleElement extends XhElement {
+  private exit;
+  private readonly idGen;
+  private readonly collapsibleScope;
+  private config;
+  private ensureConfig;
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1326,6 +1467,7 @@ declare class XhCollapsibleElement extends XhElement {
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly）
  * @csspart label - 组标题（触发器 aria-labelledby 的目标之一）
+ * @csspart control - 触发按钮的收纳容器：描边、底色与聚焦环都落在这一层
  * @csspart trigger - 触发按钮，须是原生 button；同时是浮层的定位锚点
  * @csspart value-text - 当前值串的显示位；留空即由元素填入，作者写了内容则归作者
  * @csspart swatch - 当前颜色的色块（aria-hidden，背景由连接层写成内联样式）
@@ -1344,7 +1486,7 @@ declare class XhCollapsibleElement extends XhElement {
  */
 declare class XhColorPickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content" | "label" | "positioner" | "value-text" | "hidden-input" | "area" | "swatch" | "area-thumb" | "channel-slider" | "channel-slider-track" | "channel-slider-thumb" | "channel-input" | "eye-dropper-trigger" | "swatch-group" | "swatch-item">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "control" | "positioner" | "value-text" | "hidden-input" | "area" | "swatch" | "area-thumb" | "channel-slider" | "channel-slider-track" | "channel-slider-thumb" | "channel-input" | "eye-dropper-trigger" | "swatch-group" | "swatch-item">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1437,6 +1579,8 @@ declare class XhColorPickerElement extends XhElement {
   private readonly pickerScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyValue;
   private readonly notifyOpen;
   private readonly ctrl;
@@ -1496,7 +1640,7 @@ declare class XhColorPickerElement extends XhElement {
  * @csspart control - 输入行容器，同时是浮层的定位锚点
  * @csspart input - 输入框，整个组合框唯一的 Tab 停靠点；写 input 时带 role=combobox，写 textarea 时保留它自带的 textbox 角色
  * @csspart trigger - 展开/收起按钮，须是原生 button；不占 Tab 位，可及名字由作者给
- * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，读屏按 aria-label 找到它
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - role=listbox 容器（消解层的根节点），收起时带 hidden
  * @csspart item - role=option 候选，须自带 value 属性标识身份；禁用写 aria-disabled="true"
@@ -1510,13 +1654,16 @@ declare class XhColorPickerElement extends XhElement {
  */
 declare class XhComboboxElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "content" | "label" | "item-group" | "positioner" | "item-text" | "item-indicator" | "input" | "empty" | "clear-trigger" | "hidden-input" | "control" | "item-group-label">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "label" | "item-group" | "control" | "positioner" | "clear-trigger" | "item-text" | "item-indicator" | "input" | "empty" | "hidden-input" | "item-group-label">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
     collection: {
       attribute: boolean;
     };
+    translations: {
+      attribute: boolean;
+    };
     name: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -1622,6 +1769,7 @@ declare class XhComboboxElement extends XhElement {
     };
   };
   collection?: ComboboxNode[];
+  translations?: ComboboxSchema['props']['translations'];
   value?: string | string[];
   defaultValue?: string | string[];
   inputValue?: string;
@@ -1647,6 +1795,8 @@ declare class XhComboboxElement extends XhElement {
   private readonly comboboxScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyValue;
   private readonly notifyInputValue;
   private readonly notifyOpen;
@@ -1741,6 +1891,65 @@ declare class XhComposerElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/config.d.ts
+/**
+ * `<xh-config>` —— 配置作用域。包住一棵子树，里面的元素解析 locale / size / translations
+ * 时先看最近的这一层，再往外层与全局那份回落。
+ *
+ * 它不渲染任何东西、不接线任何角色节点：作者写的子节点原样留在 Light DOM 里，
+ * 这个元素只是 DOM 树上的一个记号。皮肤里没有它的规则，布局上它是 display: contents。
+ *
+ * 与 Vue 适配器的 `provideXhConfig` 是同一件事的两种写法：那边沿组件树找，这边沿 DOM 祖先链找。
+ * 逐键合并，本层只覆盖自己写了的那几项——只想改文案的子树不会把外层的 locale 一并抹掉。
+ *
+ * `translations` 与 `scrollRoot` 是对象与函数，只能走 property；`locale` / `size` / `motion` 属性与 property 都行。
+ * `motion` 写了就调 setMotionOverride（应用级、不分子树）；CSS 侧的 data-motion 钩子由作者自己打。
+ *
+ * @customElement xh-config
+ * @attr {string} locale - BCP 47 语言标记，喂给日期时间系组件
+ * @attr {'sm'|'md'|'lg'} size - 尺寸档的默认值，落到子树里每个声明了三轴 size 的组件上
+ * @attr {'reduce'|'no-preference'} motion - 应用级动效偏好，写了就覆盖系统的 prefers-reduced-motion
+ * @prop {XhTranslationOverrides} translations - 各组件内建文案的覆盖（对象只走 property）
+ * @prop {() => HTMLElement | null} scrollRoot - 真正在滚的那个元素，交给滚动锁（函数只走 property）
+ */
+declare class XhConfigElement extends XhReactiveElement implements XhConfigScope {
+  static properties: {
+    locale: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    motion: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+    scrollRoot: {
+      attribute: boolean;
+    };
+  };
+  locale?: string;
+  size?: Size;
+  motion?: MotionPreference;
+  translations?: XhTranslationOverrides;
+  scrollRoot?: () => HTMLElement | null;
+  /** 本层声明的那几项；解析器沿祖先链读它，缺席的键交给外层。 */
+  get xhConfig(): XhConfig;
+  protected createRenderRoot(): HTMLElement | DocumentFragment;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  /** 改了任一项都要让子树里已挂载的元素重算一遍。 */
+  protected updated(changed: PropertyValues): void;
+}
+//#endregion
 //#region src/elements/context-menu.d.ts
 /**
  * `<xh-context-menu>` —— Light-DOM 行为宿主：作者写 root/trigger/positioner/content 与若干
@@ -1779,7 +1988,7 @@ declare class XhComposerElement extends XhElement {
  */
 declare class XhContextMenuElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "content" | "separator" | "positioner" | "item-text" | "item-indicator" | "group" | "group-label" | "arrow">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "separator" | "positioner" | "item-text" | "item-indicator" | "group" | "group-label" | "arrow">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1858,6 +2067,8 @@ declare class XhContextMenuElement extends XhElement {
   private readonly menuScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyOpen;
   private readonly notifySelect;
   private readonly ctrl;
@@ -1888,13 +2099,16 @@ declare class XhContextMenuElement extends XhElement {
 //#region src/elements/date-field.d.ts
 type SegmentTexts = { readonly [K in DateSegmentType]?: string; };
 /**
- * `<xh-date-field>` —— Light-DOM 行为宿主：作者写 root/label/control/segment（多个）/hidden-input
+ * `<xh-date-field>` —— Light-DOM 行为宿主：作者写 root/label/control/segment-group/segment（多个）/hidden-input
  * 角色节点，元素跑 date-field 机器并把 connect 产出打上去。
  *
  * 每一段是一个 role=spinbutton 的可聚焦节点：上下键加减并在段区间里回绕、左右键与 Home/End 换段、
- * 数字键直填且敲满自动跳下一段、Backspace 清掉本段。是哪一段由 locale（zh-CN 年月日、
- * en-US 月日年）与 granularity 算出来，作者只声明下标，不声明段名——同一份标记换个 locale
- * 就换一副面孔。精度用不上的段带 hidden 留在文档里，不卸载作者节点。
+ * 数字键直填且敲满自动跳下一段、Backspace 清掉本段；可选的 clear-trigger 一键清空全部段。
+ *
+ * 是哪一段有两种写法：只声明下标（`index`，或按文档序），是哪一段由 locale（zh-CN 年月日、
+ * en-US 月日年）与段集算出来——同一份标记换个 locale 就换一副面孔；或按段名写死
+ * （`segment="quarter"`），段集里没有这一块时那一格收起。用不上的段带 hidden 留在文档里，
+ * 不卸载作者节点。
  *
  * 段位没填齐时整份值是 null；填齐了才拼出 ISO 串，由 hidden-input 随表单提交。
  *
@@ -1906,9 +2120,12 @@ type SegmentTexts = { readonly [K in DateSegmentType]?: string; };
  * @attr {string} default-value - 非受控初值，同样是 ISO 串
  * @attr {string} min - 下界 ISO 串，参与各段区间的收窄
  * @attr {string} max - 上界 ISO 串
- * @attr {string} locale - BCP 47 语言标记，决定年月日三段的先后，默认 en-US
+ * @attr {string} locale - BCP 47 语言标记，决定年月日三段的先后；不给按宿主语言，宿主也没有时按 en-US
  * @attr {string} time-zone - IANA 时区名，只用来取"今天"（空段按上下键时的起点）
  * @attr {'day'|'hour'|'minute'|'second'} granularity - 精度，决定一共几段，默认 day
+ * @attr {string} segments - 段集，逗号分隔的段名（`year,quarter`）；给了它 granularity 让路。
+ *   可选的九块：year / quarter / month / week / day / hour / minute / second / dayPeriod。
+ *   季度与月、周与日两两互斥，都写时留细的那个
  * @attr {boolean} disabled - 禁用：整组退出 Tab 序，隐藏输入不参与提交
  * @attr {boolean} read-only - 只读：可聚焦、可换段，但改不动
  * @attr {boolean} invalid - 校验失败标注
@@ -1921,12 +2138,15 @@ type SegmentTexts = { readonly [K in DateSegmentType]?: string; };
  * @csspart root - 最外层，承载 data-disabled / data-invalid / data-complete / data-out-of-range
  * @csspart label - 标题；点它把焦点送进首段
  * @csspart control - role=group 的分段容器
- * @csspart segment - 一段一个的 spinbutton 节点，可自带 index 属性声明下标，缺省按文档序
+ * @csspart segment-group - 段位与分隔符的外壳，占满盒里剩下的宽度
+ * @csspart segment - 一段一个的 spinbutton 节点。可自带 segment 属性按段名认领（segment="quarter"），
+ *   或自带 index 属性声明下标，两者都没写按文档序
+ * @csspart clear-trigger - 清空钮，不占 Tab 位；没值或不可编辑时收起，点完焦点回到首段
  * @csspart hidden-input - type=hidden 的表单出口，值是 ISO 串
  */
 declare class XhDateFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "segment">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "clear-trigger" | "hidden-input" | "segment-group" | "segment">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1967,6 +2187,11 @@ declare class XhDateFieldElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    segments: {
+      converter: {
+        fromAttribute: (v: string | null) => DateSegmentSet | undefined;
+      };
+    };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -2022,13 +2247,14 @@ declare class XhDateFieldElement extends XhElement {
   locale?: string;
   timeZone?: string;
   granularity?: DateGranularity;
+  segments?: DateSegmentSet;
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
   required?: boolean;
   name?: string;
   placeholder?: SegmentTexts;
-  translations?: SegmentTexts;
+  translations?: DateFieldTranslations;
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
@@ -2040,7 +2266,7 @@ declare class XhDateFieldElement extends XhElement {
 //#endregion
 //#region src/elements/date-picker.d.ts
 /**
- * `<xh-date-picker>` —— Light-DOM 行为宿主：作者写 root/label/control/input/segment/trigger/
+ * `<xh-date-picker>` —— Light-DOM 行为宿主：作者写 root/label/control/segment-group/segment/trigger/
  * clear-trigger/positioner/content/calendar 角色节点，calendar 之内再照日历那套写
  * header/prev-trigger/next-trigger/heading/grid/grid-head/week-day/grid-body/week-row/cell/cell-trigger。
  *
@@ -2050,12 +2276,13 @@ declare class XhDateFieldElement extends XhElement {
  * 网格由作者渲染，元素不生成节点：读 `weeks` / `weekDays` / `headingLabel` 三个只读属性，
  * 听 `focused-value-change` 重画。日期身份取 cell 节点上的 `value`（ISO 串），
  * cell-trigger 跟随所在 cell；表头列取 week-day 上的 `value`（列序 0-6）；
- * 段位可自带 `index` 属性声明下标，缺省按所在 input 之内的文档序。
+ * 段位可自带 `segment` 属性按段名认领（`segment="quarter"`），或自带 `index` 属性声明下标，
+ * 两者都没写按所在 segment-group 之内的文档序。
  *
- * 区间模式（selection-mode="range"）下 input 写两个：文档序在前的是起点、在后的是终点，
- * 各自内部写一整套段位。段位与 hidden-input 按所在 input 归组，方向键不跨组；
- * hidden-input 写在 input 之外（如与 control 平级）时按文档序对应起止两端。
- * 其余模式只认第一个 input。
+ * 区间模式（selection-mode="range"）下 segment-group 写两个：文档序在前的是起点、在后的是终点，
+ * 各自内部写一整套段位。段位与 hidden-input 按所在 segment-group 归组，方向键不跨组；
+ * hidden-input 写在 segment-group 之外（如与 control 平级）时按文档序对应起止两端。
+ * 其余模式只认第一个 segment-group。
  *
  * @customElement xh-date-picker
  * @attr {string} value - 受控选中值（单选简写，ISO 串）；缺省该属性即非受控，区间/多选请用 property 传数组
@@ -2064,52 +2291,69 @@ declare class XhDateFieldElement extends XhElement {
  * @attr {boolean} default-open - 非受控初始为展开
  * @attr {string} min - 可选范围下界（含当天），日历与分段输入共用
  * @attr {string} max - 可选范围上界（含当天）
- * @attr {string} locale - 决定周首日、月份文案与段位先后，默认 zh-CN（段序默认 en-US 由分段输入自定）
+ * @attr {string} locale - 决定周首日、月份文案与段位先后；不给按宿主语言，宿主也没有时按 en-US
  * @attr {string} time-zone - 判定"今天"与格式化用的时区，默认宿主本地时区
  * @attr {'single'|'multiple'|'range'} selection-mode - 选择模式，默认 single
+ * @attr {'day'|'month'|'quarter'|'year'} view - 挑的粒度，默认 day；输入行铺哪几段也跟着它走
+ * @attr {'day'|'month'|'quarter'|'year'} active-view - 受控：面板此刻钻到了哪一层；缺省跟着 view，每次展开都拨回去
+ * @attr {boolean} week-selection - 周选：点任意一天选中它所在的整周（view=day 且区间模式下生效）
+ * @prop {DatePickerPreset[]} presets - 快捷选项（数组只走 property）：给了就在浮层里多出一列
+ * @attr {number} visible-count - 并排展示几页
  * @attr {boolean} disabled - 整个控件禁用：trigger 转原生 disabled，段位退出 Tab 序
  * @attr {boolean} read-only - 只读：浮层照常展开、日历照常浏览，但选中值改不动
  * @attr {boolean} invalid - 校验失败标注
  * @attr {boolean} required - 必填标注，落到每段的 aria-required 上
  * @attr {string} name - 表单字段名；给了隐藏输入才带 name。区间模式下是起点那一份
  * @attr {string} end-name - 区间终点那份隐藏输入的表单字段名；不给即终点不参与提交
+ * @attr {'outline'|'subtle'|'ghost'} variant - 视觉变体
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
  * @attr {string} placement - 首选放置位，默认 bottom-start；避让后的实际位写在 data-placement 上
  * @attr {number} offset - 浮层与锚点的间距（px）
  * @attr {boolean} close-on-select - 选完即收起，默认 true；写 close-on-select="false" 关掉
  * @fires value-change - 选中集合变化；detail 为 `{ value: string[] }`
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @fires focused-value-change - 聚焦日变化（意味着展示月可能换了）；detail 为 `{ focusedValue: string }`，作者据此重画网格
+ * @fires active-view-change - 钻到了另一层（点标题钻上、点格子钻下）；detail 为 `{ activeView: 'day'|'month'|'quarter'|'year' }`，作者据此重画网格
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly/data-invalid）
  * @csspart label - 标题；点它把焦点送进首段。刻意不是原生 label（段位是 div，标不了）
  * @csspart control - 输入行容器，同时是浮层的定位锚点
- * @csspart input - role=group 的分段容器，段位挂在它里面；区间模式下有起止两个，data-index 区分
- * @csspart segment - 一段一个的 spinbutton 节点（data-scope="date-field"），可自带 index 属性；下标在所属 input 组内数
+ * @csspart segment-group - role=group 的分段容器，段位挂在它里面；区间模式下有起止两个，data-index 区分
+ * @csspart segment - 一段一个的 spinbutton 节点（data-scope="date-field"）。可自带 segment 属性按段名认领
+ *   （segment="quarter"），或自带 index 属性声明下标（在所属 segment-group 组内数），两者都没写按文档序
  * @csspart trigger - 展开日历的按钮，须是原生 button
- * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，名字取 translations.clearTrigger
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - role=dialog 浮层（消解层的根节点），收起时带 hidden
+ * @csspart presets - 快捷选项列（role=listbox）；没给 presets 时带 hidden
+ * @csspart preset - 一条快捷选项（role=option），须自带 value 属性（与 presets 数据里的 value 逐字对上）
  * @csspart calendar - 内嵌日历的挂载点，同时充当日历的根节点
  * @csspart time-column - showTime 的时间列，须自带 unit 属性（hour/minute/second）；没开时带 hidden
  * @csspart time-item - 时间选项，须自带 value 属性（两位补零串）；点按把该单位写进值
  * @csspart confirm-trigger - showTime 的收口按钮；没开时带 hidden
  * @csspart header - 日历标题栏外壳（data-scope="calendar"）
+ * @csspart prev-year-trigger - 快速往前翻一大步（日视图一年、粗粒度十页）；可选
  * @csspart prev-trigger - 上一月；越过 min 时转原生 disabled
  * @csspart next-trigger - 下一月；越过 max 时转原生 disabled
+ * @csspart next-year-trigger - 快速往后翻一大步；可选
  * @csspart heading - 展示月标题（grid 的 aria-labelledby 目标）
+ * @csspart heading-year-trigger - 标题里年那一截，点它钻到十年格；可选
+ * @csspart heading-month-trigger - 标题里月那一截，点它钻到月格；只有日视图有这一截；可选
  * @csspart grid - role=grid 容器，网格键盘在此收口
  * @csspart grid-head - role=rowgroup 表头组，里面套一个 week-row
  * @csspart week-day - role=columnheader 列头，须自带 value 属性标明列序 0-6
  * @csspart grid-body - role=rowgroup 日期组
  * @csspart week-row - role=row 周行，表头与日期行共用
+ * @csspart week-number - 行首的周序号格（role=rowheader），须自带 value 属性（行首那天）；可选
  * @csspart cell - role=gridcell 日期格，承载 aria-selected；须自带 value 属性（ISO 串）
  * @csspart cell-trigger - 真正可点可聚焦的那一层，承载 aria-disabled 与 roving tabindex
  * @csspart hidden-input - type=hidden 的表单出口，值是 ISO 串；区间模式下起止各一份
  */
 declare class XhDatePickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content" | "label" | "positioner" | "input" | "clear-trigger" | "control" | "confirm-trigger" | "calendar" | "time-column" | "time-item">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "control" | "positioner" | "clear-trigger" | "segment-group" | "confirm-trigger" | "preset" | "presets" | "calendar" | "time-column" | "time-item">;
     meta: import("@xihan-ui/headless").ComponentMeta;
-    delegates: (import("@xihan-ui/kernel").Anatomy<"root" | "header" | "grid" | "heading" | "prev-trigger" | "next-trigger" | "grid-head" | "week-day" | "grid-body" | "week-row" | "cell" | "cell-trigger"> | import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "segment">)[];
+    delegates: (import("@xihan-ui/kernel").Anatomy<"root" | "header" | "grid" | "heading" | "prev-trigger" | "next-trigger" | "prev-year-trigger" | "next-year-trigger" | "heading-year-trigger" | "heading-month-trigger" | "grid-head" | "week-day" | "grid-body" | "week-row" | "week-number" | "cell" | "cell-trigger"> | import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "clear-trigger" | "hidden-input" | "segment-group" | "segment">)[];
   };
   static properties: {
     value: {
@@ -2159,6 +2403,35 @@ declare class XhDatePickerElement extends XhElement {
       };
       attribute: string;
     };
+    view: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    activeView: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    segments: {
+      attribute: boolean;
+    };
+    weekSelection: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    presets: {
+      attribute: boolean;
+    };
+    visibleCount: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -2194,6 +2467,21 @@ declare class XhDatePickerElement extends XhElement {
     translations: {
       attribute: boolean;
     };
+    variant: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     placement: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -2235,6 +2523,12 @@ declare class XhDatePickerElement extends XhElement {
   locale?: string;
   timeZone?: string;
   selectionMode?: CalendarSelectionMode;
+  view?: CalendarView;
+  activeView?: CalendarView;
+  segments?: DateSegmentSet;
+  weekSelection?: boolean;
+  presets?: DatePickerPreset[];
+  visibleCount?: number;
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
@@ -2242,6 +2536,9 @@ declare class XhDatePickerElement extends XhElement {
   name?: string;
   endName?: string;
   translations?: DatePickerSchema['props']['translations'];
+  variant?: ControlVariant;
+  tone?: Tone;
+  size?: Size;
   placement?: Placement;
   offset?: number;
   closeOnSelect?: boolean;
@@ -2252,8 +2549,11 @@ declare class XhDatePickerElement extends XhElement {
   private readonly pickerScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyValue;
   private readonly notifyOpen;
+  private readonly notifyActiveView;
   private readonly notifyFocus;
   private readonly rootCtrl;
   private readonly calendarCtrl;
@@ -2275,8 +2575,8 @@ declare class XhDatePickerElement extends XhElement {
   /** 取 owner 子树内指定名字的角色节点。 */
   private partsIn;
   /**
-   * 把隐藏输入分到起止两端：写在某个 input 之内的归那一组，
-   * 写在全部 input 之外的按自己的文档序对号入座。多出来的一律不接线。
+   * 把隐藏输入分到起止两端：写在某个 segment-group 之内的归那一组，
+   * 写在全部 segment-group 之外的按自己的文档序对号入座。多出来的一律不接线。
    */
   private hiddenInputGroups;
   /** 打一组段位：下标在组内从 0 数起，段位文字与收起态一并落。 */
@@ -2297,6 +2597,7 @@ declare class XhDatePickerElement extends XhElement {
  * @attr {'dialog'|'alertdialog'} role - 语义角色，默认 dialog
  * @attr {boolean} close-on-escape - Esc 关闭，默认 true
  * @attr {boolean} restore-focus - 关闭后把焦点归还触发元素，默认 true
+ * @attr {string} initial-focus - 展开后先聚焦到 content 内匹配此选择器的元素
  * @attr {'sm'|'md'|'lg'} size - 尺寸：只换 content 的最大宽度，落在 content 上
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @csspart trigger - 触发按钮
@@ -2309,7 +2610,7 @@ declare class XhDatePickerElement extends XhElement {
  */
 declare class XhDialogElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"trigger" | "content" | "title" | "description" | "close-trigger" | "positioner" | "backdrop">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"content" | "trigger" | "title" | "description" | "close-trigger" | "positioner" | "backdrop">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2339,6 +2640,12 @@ declare class XhDialogElement extends XhElement {
       };
       attribute: string;
     };
+    initialFocus: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     size: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -2350,22 +2657,84 @@ declare class XhDialogElement extends XhElement {
   modal?: boolean;
   closeOnEscape?: boolean;
   restoreFocus?: boolean;
+  initialFocus?: string;
   size?: Size;
   private readonly idGen;
   private readonly dialogScope;
   private config;
   private contentNode;
+  private exit;
   private backdropNode;
   private readonly notify;
   private readonly ctrl;
   private machineProps;
   private ensureConfig;
+  /** 退场闸门建一次；presence 不是响应式 cell，退场结束要显式排一次更新才轮得到收起。 */
+  private ensureExit;
   private readonly registerLayer;
   private injectRefs;
   protected wire(): void;
   disconnectedCallback(): void;
 }
 //#endregion
+//#region src/elements/download-trigger.d.ts
+/**
+ * `<xh-download-trigger>` —— Light-DOM 行为宿主，跑 download-trigger 机器并把 connect 产出打到 root 角色节点。
+ *
+ * 下载走临时地址加一次隐藏链接点击：点下去先进 preparing，数据交给浏览器后回 idle 并派
+ * `download-complete`，取数失败同样回 idle 并派 `download-error`。
+ *
+ * Blob 与取数函数只能走 property（`el.data = blob`）：HTML 属性只装得下一个字符串。
+ *
+ * @customElement xh-download-trigger
+ * @attr {string} data - 要下载的文本；Blob 与取数函数只能经 property 交进来
+ * @attr {string} file-name - 写出的文件名；缺省或空串退回内建名 download
+ * @attr {string} mime-type - 内容类型；给了它就以它为准，连 Blob 自带的类型也照它重包
+ * @attr {boolean} disabled - 禁用，按钮不可聚焦也点不动
+ * @fires download-complete - 数据已交给浏览器；detail 为 `{ fileName }`
+ * @fires download-error - 取数失败或造不出下载；detail 为 `{ error, fileName }`，此刻状态已经回到 idle
+ * @csspart root - 触发下载的按钮，须是原生 `<button>`（承载 data-state / aria-busy）
+ */
+declare class XhDownloadTriggerElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    data: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    fileName: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    mimeType: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+  };
+  data?: DownloadTriggerData;
+  fileName?: string;
+  mimeType?: string;
+  disabled?: boolean;
+  private readonly notifyComplete;
+  private readonly notifyError;
+  private readonly ctrl;
+  private machineProps;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/drawer.d.ts
 /**
  * `<xh-drawer>` —— Light-DOM 行为宿主，跑 drawer 机器并把 connect 产出打到角色节点上，
@@ -2377,6 +2746,8 @@ declare class XhDialogElement extends XhElement {
  * @attr {boolean} open - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-open - 非受控初始为打开
  * @attr {boolean} modal - 模态（陷焦点、锁滚动、遮罩交互外关闭），默认 true
+ * @attr {boolean} contained - 局部抽屉：遮罩与定位层从 fixed 换成 absolute，只罩住最近的定位祖先而不是盖满整屏。
+ *   本元素是 Light DOM、作者写在哪浮层就在哪，所以「挂到哪个容器」这件事本身不需要属性——写上它是为了让皮肤按容器画
  * @attr {'top'|'right'|'bottom'|'left'} side - 从哪条边滑出，默认 right
  * @attr {'dialog'|'alertdialog'} role - 语义角色，默认 dialog
  * @attr {boolean} close-on-escape - Esc 关闭，默认 true
@@ -2395,7 +2766,7 @@ declare class XhDialogElement extends XhElement {
  */
 declare class XhDrawerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content" | "title" | "description" | "close-trigger" | "positioner" | "backdrop">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "title" | "description" | "close-trigger" | "positioner" | "backdrop">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2413,6 +2784,11 @@ declare class XhDrawerElement extends XhElement {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
+    contained: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
     side: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -2448,6 +2824,7 @@ declare class XhDrawerElement extends XhElement {
   open?: boolean;
   defaultOpen?: boolean;
   modal?: boolean;
+  contained?: boolean;
   side?: DrawerSchema['props']['side'];
   closeOnEscape?: boolean;
   closeOnInteractOutside?: boolean;
@@ -2458,11 +2835,14 @@ declare class XhDrawerElement extends XhElement {
   private readonly drawerScope;
   private config;
   private contentNode;
+  private exit;
   private backdropNode;
   private readonly notify;
   private readonly ctrl;
   private machineProps;
   private ensureConfig;
+  /** 退场闸门建一次；presence 不是响应式 cell，退场结束要显式排一次更新才轮得到收起。 */
+  private ensureExit;
   private readonly registerLayer;
   private injectRefs;
   protected wire(): void;
@@ -2514,7 +2894,7 @@ declare class XhDrawerElement extends XhElement {
  */
 declare class XhEditableElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "input" | "control" | "area" | "submit-trigger" | "cancel-trigger" | "preview" | "edit-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "input" | "area" | "submit-trigger" | "cancel-trigger" | "preview" | "edit-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2724,6 +3104,63 @@ declare class XhFieldElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/fieldset.d.ts
+/**
+ * `<xh-fieldset>` —— Light-DOM 行为宿主，无状态机，把 connectFieldset 产出的属性打到
+ * root/legend/helper-text/error-text 角色节点上：说明与错误文案的 id 自动接进 root 的描述链。
+ *
+ * root 必须是原生 `<fieldset>`、legend 必须是原生 `<legend>` 且写成 root 的首个子节点——
+ * 整组禁用连坐组内控件与"legend 即组名"都是浏览器给的，写成 div 两样都静默失效。
+ *
+ * 每个实例自带一份 scope 派生 part id，同页多个字段集各出各的 id。
+ *
+ * @customElement xh-fieldset
+ * @attr {boolean} disabled - 整组禁用：root 落原生 disabled，组内表单控件一并停掉
+ * @attr {boolean} invalid - 校验失败态：错误文案接入描述链并显出
+ * @attr {boolean} required - 必填标记，只落 data-required 供皮肤给组标题加星号
+ * @csspart root - 原生 `<fieldset>`，承载原生 disabled 与 data-disabled/data-invalid/data-required
+ * @csspart legend - 原生 `<legend>`，这一组的名字；须是 root 的首个子节点
+ * @csspart helper-text - 常驻说明文案，恒在 root 的描述链里
+ * @csspart error-text - 错误文案（role=alert）；非 invalid 时带 hidden 收起，节点不卸载
+ */
+declare class XhFieldsetElement extends XhElement {
+  #private;
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "error-text" | "legend" | "helper-text">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+    tags: {
+      root: string[];
+      legend: string[];
+    };
+  };
+  static properties: {
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    invalid: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    required: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  disabled?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  translations?: Partial<FieldsetTranslations>;
+  private readonly fieldsetScope;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/file-upload.d.ts
 /**
  * `<xh-file-upload>` —— Light-DOM 行为宿主：作者写 root/label/dropzone/trigger/hidden-input
@@ -2767,11 +3204,11 @@ declare class XhFieldElement extends XhElement {
  * @csspart item-name - 文件名（元素代填）
  * @csspart item-size-text - 人读的文件大小（元素代填）
  * @csspart item-delete-trigger - 删掉这一条
- * @csspart clear-trigger - 清空整份列表；列表为空时带原生 disabled
+ * @csspart clear-trigger - 清空整份列表；列表为空时打 data-empty，按钮照常在位可聚焦
  */
 declare class XhFileUploadElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "label" | "item-group" | "clear-trigger" | "hidden-input" | "dropzone" | "item-name" | "item-size-text" | "item-preview" | "item-delete-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "label" | "item-group" | "clear-trigger" | "hidden-input" | "item-delete-trigger" | "dropzone" | "item-name" | "item-size-text" | "item-preview">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2886,7 +3323,8 @@ declare class XhFileUploadElement extends XhElement {
   addFiles(files: File[]): void;
   /** 按引用剔除某一个。 */
   deleteFile(file: File): void;
-  clearFiles(): void;
+  /** 清空整份列表（本地与远程一起）。 */
+  clear(): void;
   /** 文本是否归元素填：节点非空即判为作者自定义渲染。首次见到时定死，之后不再回读——回读分不出内容是作者写的还是上一帧自己写的。 */
   private readonly ownsText;
   private fillText;
@@ -2899,20 +3337,176 @@ declare class XhFileUploadElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
-//#region src/elements/form.d.ts
+//#region src/elements/floating-panel.d.ts
 /**
- * `<xh-form>` —— Light-DOM 行为宿主：作者写 root（必须是原生 `<form>`）与
- * field-group / error-summary / error-summary-item / submit-trigger / reset-trigger 角色节点，
- * 元素跑 form 机器并把 connect 产出打上去。
+ * `<xh-floating-panel>` —— Light-DOM 行为宿主：作者写 root / positioner / content 等角色节点，
+ * 元素跑 floating-panel 机器并把 connect 产出打上去。
  *
- * 提交只有一条路：`<form>` 自己的 submit 事件。回车的隐式提交、`type=submit` 按钮、
- * 以及命令式的 `submit()` 全部汇到那里，连接层一律 preventDefault——页面永不刷新，
- * 校验与回调都由组件收口。
+ * 面板的落位与尺寸由元素每帧写进 positioner 的内联样式（position/left/top/width/height），
+ * 作者的样式表不要再碰这五个属性。收起态用内联 display 收住 positioner，正文收拢时同样收住。
  *
- * 值与错误都是「表」：元素不去收割原生控件里的值（那要替作者猜 checkbox / 多选 / 数字的类型），
- * 而是由作者经 `values` 属性或 `setFieldValue()` 写进来。校验函数同样由作者给。
+ * 改尺把手要在节点上写明守哪条边（`edge="se"`），形态按钮要写明切到哪个形态（`stage="minimized"`），
+ * 与 Vue 侧的 `:edge` / `:stage` 是同一份声明。
  *
- * 每个字段用一个 field-group 包住并用 `value` 属性自报字段名：错误摘要的链接指向它，
+ * 位置与尺寸的属性形式是逗号分隔的一对数（`default-position="24,24"`、`default-size="360,240"`）；
+ * 也可以直接喂 property（`el.position = { x: 24, y: 24 }`）。
+ *
+ * @customElement xh-floating-panel
+ * @attr {boolean} open - 受控开合；缺省该属性即非受控
+ * @attr {boolean} default-open - 非受控初始为展开
+ * @attr {string} position - 受控落点，写成 "x,y"（px，相对视口）
+ * @attr {string} default-position - 非受控初始落点，默认 "24,24"
+ * @attr {string} size - 受控尺寸，写成 "宽,高"（px）
+ * @attr {string} default-size - 非受控初始尺寸，默认 "360,240"
+ * @attr {string} min-size - 尺寸下限，默认 "160,120"
+ * @attr {string} max-size - 尺寸上限，不写即不封顶
+ * @attr {'default'|'minimized'|'maximized'} stage - 受控形态
+ * @attr {'default'|'minimized'|'maximized'} default-stage - 非受控初始形态，默认 default
+ * @attr {boolean} panel-draggable - 允不允许搬动面板，默认开启；铺满形态下恒不可搬。不叫 draggable：那是 HTML 全局属性，写上去宿主会变成原生拖放源
+ * @attr {boolean} resizable - 允不允许改尺寸，默认开启；只有常规形态下才改得动
+ * @attr {boolean} disabled - 禁用：搬不动、改不了尺寸、切不了形态；开合与关闭不受影响
+ * @fires open-change - 展开态变化；detail 为 `{ open: boolean }`
+ * @fires position-change - 落点变化（拖动途中会连发）；detail 为 `{ position: { x, y } }`
+ * @fires size-change - 尺寸变化（改尺途中会连发）；detail 为 `{ size: { width, height } }`
+ * @fires stage-change - 形态变化；detail 为 `{ stage: 'default' | 'minimized' | 'maximized' }`
+ * @csspart root - 面板与触发器共同的容器
+ * @csspart trigger - 打开面板的按钮
+ * @csspart positioner - 承载落位与尺寸的定位容器，收起时被内联 display 收住
+ * @csspart content - role=dialog 的面板本体（Esc 收口所在）
+ * @csspart header - 标题栏：标题、拖拽把手与几个按钮排在这里
+ * @csspart title - 标题（aria-labelledby 目标）
+ * @csspart drag-trigger - 拖拽把手，须是原生 `<button>`
+ * @csspart resize-trigger - 改尺把手，自带 edge 属性；接线后是 `role="separator"`，别写成 `<button>`
+ * @csspart stage-trigger - 形态按钮，须是原生 `<button>` 并自带 stage 属性
+ * @csspart close-trigger - 关闭按钮
+ * @csspart body - 正文，收拢时带 hidden
+ */
+declare class XhFloatingPanelElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "header" | "trigger" | "title" | "close-trigger" | "positioner" | "body" | "drag-trigger" | "resize-trigger" | "stage-trigger">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    open: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    defaultOpen: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    position: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelPosition | undefined;
+      };
+    };
+    defaultPosition: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelPosition | undefined;
+      };
+      attribute: string;
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelSize | undefined;
+      };
+    };
+    defaultSize: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelSize | undefined;
+      };
+      attribute: string;
+    };
+    minSize: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelSize | undefined;
+      };
+      attribute: string;
+    };
+    maxSize: {
+      converter: {
+        fromAttribute: (v: string | null) => FloatingPanelSize | undefined;
+      };
+      attribute: string;
+    };
+    stage: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    defaultStage: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    panelDraggable: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    resizable: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  open?: boolean;
+  defaultOpen?: boolean;
+  position?: FloatingPanelPosition;
+  defaultPosition?: FloatingPanelPosition;
+  size?: FloatingPanelSize;
+  defaultSize?: FloatingPanelSize;
+  minSize?: FloatingPanelSize;
+  maxSize?: FloatingPanelSize;
+  stage?: FloatingPanelStage;
+  defaultStage?: FloatingPanelStage;
+  panelDraggable?: boolean;
+  resizable?: boolean;
+  disabled?: boolean;
+  translations?: FloatingPanelSchema['props']['translations'];
+  private readonly idGen;
+  private readonly panelScope;
+  private readonly notifyOpen;
+  private readonly notifyPosition;
+  private readonly notifySize;
+  private readonly notifyStage;
+  private readonly ctrl;
+  private machineProps;
+  private injectRefs;
+  /** 把手自报守的是哪条边；没写或写错时按右下角处理，那是最常见的那一个。 */
+  private edgeOf;
+  /** 形态按钮自报切到哪个形态；没写或写错时按常规处理。 */
+  private stageOf;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/form.d.ts
+/**
+ * `<xh-form>` —— Light-DOM 行为宿主：作者写 root（必须是原生 `<form>`）与
+ * field-group / error-summary / error-summary-item / submit-trigger / reset-trigger 角色节点，
+ * 元素跑 form 机器并把 connect 产出打上去。
+ *
+ * 提交只有一条路：`<form>` 自己的 submit 事件。回车的隐式提交、`type=submit` 按钮、
+ * 以及命令式的 `submit()` 全部汇到那里，连接层一律 preventDefault——页面永不刷新，
+ * 校验与回调都由组件收口。
+ *
+ * 值与错误都是「表」：元素不去收割原生控件里的值（那要替作者猜 checkbox / 多选 / 数字的类型），
+ * 而是由作者经 `values` 属性或 `setFieldValue()` 写进来。校验函数同样由作者给。
+ *
+ * 每个字段用一个 field-group 包住并用 `value` 属性自报字段名：错误摘要的链接指向它，
  * 提交失败后的焦点也落进它——落点按**文档序**取第一个出错的字段，而不是错误表的键序。
  *
  * @customElement xh-form
@@ -3045,6 +3639,245 @@ declare class XhFormElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/heatmap.d.ts
+/**
+ * `<xh-heatmap>` —— Light-DOM 行为宿主：作者写 root、grid、若干 row 与 cell 角色节点，
+ * 元素跑 heatmap 机器并把 connect 产出打上去。
+ *
+ * 网格由作者渲染，元素不生成节点：铺一整年不必手写三百多个格子，读 `grid` / `monthGrid` /
+ * `matrixGrid` 三个只读属性，照推导出来的行、列、月份段循环生成即可（三种形态各读其中一个）。
+ * 每读一次都重算一遍，取一次存下来用。
+ *
+ * 角色节点的身份一律取作者写在节点上的 value 属性，怎么解释由 variant 决定：
+ * 日历形态里 row 与 week-day-label 上是行序 0-6（不写即网格之外那条月份行与它的行首占位）、
+ * cell 上是 ISO 日期、month-label 上是 YYYY-MM；月历形态里 month-block 上是 YYYY-MM、
+ * row 上是月内周序（不写即块内那条星期名坐标轴）；矩阵形态里 row 与 row-label 上是行身份
+ * （不写即表头行与角落占位）、column-label 与 cell 上是列身份，格子的行身份从所在的行取。
+ * legend-item 上是档位、legend-label 上是 low 或 high（两端那两个字，文案读 `legendText`）。
+ *
+ * 数据、行列、档位下界与文案只能走 property（`el.value = [...]`）：HTML 属性装不下数组与函数。
+ *
+ * @customElement xh-heatmap
+ * @attr {'calendar'|'month'|'matrix'} variant - 形态；缺省 calendar
+ * @attr {string} start-date - 区间起点（含），ISO YYYY-MM-DD
+ * @attr {string} end-date - 区间终点（含）
+ * @attr {number} levels - 档数，缺省 5；给了 thresholds 则档数由它定
+ * @attr {number} first-day-of-week - 周首日，0 = 星期日，缺省 1
+ * @attr {string} locale - 月份名与星期名的书写 locale；不给按宿主语言，宿主也没有时按 en-US
+ * @attr {'ltr'|'rtl'} dir - 文字方向；只作显式覆盖，不写时方向从 DOM 现读
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
+ * @attr {'green'|'blue'|'orange'|'purple'|'red'|'gray'} palette - 色板，直接点名色阶满档的颜色；同时写了 tone 时听它的
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires cell-focus - 焦点落到某一格；detail 为 `{ date, row, column, count, level, percent }`
+ * @fires cell-active - 详情该显示哪一格（悬停或聚焦）；收起时 detail 为 null
+ * @csspart root - 承载三轴的最外层节点
+ * @csspart grid - role=grid 的网格容器，键盘在它身上收口
+ * @csspart month-block - 月历形态里的一个自然月块
+ * @csspart row - 一行；写了 value 即数据行，不写即坐标轴那一行
+ * @csspart week-day-label - 星期名，只给眼睛看
+ * @csspart month-label - 月份名
+ * @csspart row-label - 矩阵的行名；不写 value 即表头行行首的角落占位
+ * @csspart column-label - 矩阵的列名
+ * @csspart cell - 一格，身份取写在节点上的 value
+ * @csspart tooltip - 悬停或聚焦时显示的详情条，位置由元素量好写成内联样式
+ * @csspart legend - 色阶对照条
+ * @csspart legend-label - 对照条一端的那个字，value 是 low 或 high
+ * @csspart legend-item - 对照条里的一格，value 是档位
+ */
+declare class XhHeatmapElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "grid" | "cell" | "legend" | "tooltip" | "month-block" | "row" | "week-day-label" | "month-label" | "row-label" | "column-label" | "legend-label" | "legend-item">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    value: {
+      attribute: boolean;
+    };
+    rows: {
+      attribute: boolean;
+    };
+    columns: {
+      attribute: boolean;
+    };
+    thresholds: {
+      attribute: boolean;
+    };
+    translations: {
+      attribute: boolean;
+    };
+    variant: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    startDate: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    endDate: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    levels: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    firstDayOfWeek: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    locale: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    palette: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+  };
+  value?: HeatmapValue[];
+  rows?: HeatmapAxisInput[];
+  columns?: HeatmapAxisInput[];
+  thresholds?: number[];
+  translations?: Partial<HeatmapTranslations>;
+  variant?: HeatmapVariant;
+  startDate?: string;
+  endDate?: string;
+  levels?: number;
+  firstDayOfWeek?: number;
+  locale?: string;
+  direction?: Direction;
+  tone?: Tone;
+  palette?: HeatmapPalette;
+  size?: Size;
+  private readonly notifyFocus;
+  private readonly notifyActive;
+  private readonly ctrl;
+  private machineProps;
+  /**
+   * 日历网格：七行星期 × 若干周列，另带月份段、星期名与档位标尺，作者照它铺节点。
+   * 其余形态下是一张空网格。机器尚未建起时同样给空网格。
+   */
+  get grid(): HeatmapGrid;
+  /** 月历网格：按自然月分块，块里逐周一行；不是 month 形态时为 null。 */
+  get monthGrid(): HeatmapMonthGrid | null;
+  /** 矩阵网格：行列由作者给；不是 matrix 形态时为 null。 */
+  get matrixGrid(): HeatmapMatrixGrid | null;
+  /** 对照条两端要写的那两个字，照它填 legend-label 节点的文字。 */
+  get legendText(): {
+    low: string;
+    high: string;
+  };
+  /** 作者写在行上的身份，按形态翻成连接层认得的那一组坐标。 */
+  private rowProps;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/hotkeys.d.ts
+/**
+ * `<xh-hotkeys>` —— Light-DOM 行为宿主：作者写一个空的行内容器当 root，
+ * 元素把 keys 翻成当前平台的写法铺成一排键帽，并在 document 或父节点上接住这组组合。
+ *
+ * 键帽与连接符出多少枚由 keys 与平台决定，作者写不出来，故 root 的内容整份由本元素接管，
+ * 写在里面的东西会被替换掉。
+ *
+ * `Mod` 在 Mac 上是 ⌘、其余平台是 Ctrl，同一份 keys 两边都对。平台缺省测出来的那个，
+ * 显式写 `platform` 即以它为准。
+ *
+ * 命中后默认拦下浏览器的默认动作；组合里除 Shift 外没有别的修饰键时，
+ * 落在输入框、文本域、可编辑区里的按键一律让给输入。
+ *
+ * @customElement xh-hotkeys
+ * @attr {string} keys - 组合里的各枚键，逗号分隔，如 `Mod,S`；逗号本身这枚主键写不进属性，那种组合走 property 传数组
+ * @attr {'auto'|'mac'|'other'} platform - 按哪个平台的写法显示与解析，缺省测出来的那个
+ * @attr {'document'|'parent'} target - 监听装在哪儿，缺省 document
+ * @attr {boolean} prevent-default - 命中后拦下浏览器的默认动作，默认开启
+ * @attr {boolean} enabled - 监听是否生效，默认开启
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires hot-key - 组合被按出来；detail 为 `{ keys: string[], event: KeyboardEvent }`
+ * @csspart root - 键帽的容器（承载 role=img 与整组组合的名字）
+ * @csspart key - 一枚键帽，由元素铺进 root
+ * @csspart separator - 两枚键帽之间的连接符，由元素铺进 root；Mac 的写法里收起
+ */
+declare class XhHotkeysElement extends XhElement {
+  #private;
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "separator" | "key">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    keys: {
+      converter: {
+        fromAttribute: (v: string | null) => string[] | undefined;
+      };
+    };
+    platform: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    target: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    preventDefault: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    enabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  keys?: string[];
+  platform?: HotkeysPlatform;
+  target?: HotkeysTarget;
+  preventDefault?: boolean;
+  enabled?: boolean;
+  size?: Size;
+  translations?: Partial<HotkeysTranslations>;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/hover-card.d.ts
 /**
  * `<xh-hover-card>` —— Light-DOM 行为宿主：作者写 root/trigger/positioner/content/arrow 角色节点，
@@ -3074,7 +3907,7 @@ declare class XhFormElement extends XhElement {
  */
 declare class XhHoverCardElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content" | "positioner" | "arrow">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "positioner" | "arrow">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -3137,6 +3970,8 @@ declare class XhHoverCardElement extends XhElement {
   private readonly hoverCardScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notify;
   private readonly ctrl;
   private machineProps;
@@ -3240,41 +4075,195 @@ declare class XhImageElement extends XhElement {
   static properties: {
     src: {
       converter: {
-        fromAttribute: (v: string | null) => string | undefined;
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    alt: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    fallbackDelay: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+  };
+  src?: string;
+  alt?: string;
+  fallbackDelay?: number;
+  private readonly notify;
+  private readonly ctrl;
+  private machineProps;
+  /**
+   * 图片早在监听器挂上之前就已就绪时补一次上报：load 已经派发完，机器再也等不到，
+   * 状态会永远停在 loading——图片明明在手边，台前却一直是回退内容。两处会撞上：
+   * 作者把同一个 src 也写进了 img 标记（升级前浏览器就加载完了），
+   * 以及元素在 DOM 中被移动导致机器重建（状态从头走一遍，而 src 没变的 img 不会重新加载）。
+   *
+   * 三个条件缺一不可：complete 排除还在路上的请求；naturalWidth 排除加载失败——失败与
+   * "压根没发起请求"在这里分不开，不去猜，留在 loading 上照样只显示回退内容；
+   * currentSrc 与 src 相等排除换图那一瞬，此刻旧图仍是 complete 的，误报会把旧图当新图显出来。
+   *
+   * 只在 loading 补报：idle 期间补会被随后落地的来源决议一脚踢回 loading。
+   * 报完即进 loaded，下一帧不再命中，不会闭成回路。
+   */
+  private syncSettledImage;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/image-cropper.d.ts
+/**
+ * `<xh-image-cropper>` —— Light-DOM 行为宿主：作者写 root/viewport/image/crop-area
+ * 与可选的 crop-handle、grid、hidden-input 角色节点，元素跑 image-cropper 机器并把 connect 产出打上去。
+ *
+ * 裁切矩形以源图的自然像素记录，坐标换算取 viewport 的矩形——矩形在指针事件发生的那一刻才量，
+ * 连接期一律不碰 DOM；自然尺寸由 image 部件的 load 事件报进来，所以图片必须写成原生 `<img>`。
+ * 视口的尺寸要由图片撑出来（图片铺满视口），裁切框的百分比坐标才对得上。
+ *
+ * 每个把手必须用 position 属性写明自己拉的是哪个方位（`position="se"`），八个合法值是
+ * `nw|n|ne|e|se|s|sw|w`；写不出合法方位的把手不接行为，控制台留一条诊断。
+ * 缩放与旋转同时作用在图片与裁切框上，两者始终贴合。
+ *
+ * @customElement xh-image-cropper
+ * @attr {string} src - 图片地址，原样写到 image 部件上
+ * @attr {string} alt - 图片替代文本，原样写到 image 部件上；不给即落空串，读屏跳过这张图
+ * @attr {string} value - 受控裁切矩形，写成 "x,y,width,height"；缺省该属性即非受控
+ * @attr {string} default-value - 非受控初值，同样是四个逗号分隔的数；缺省时图片加载完取整张图
+ * @attr {number} aspect-ratio - 宽高比（宽 ÷ 高）；不写即不锁比例
+ * @attr {number} min-width - 裁切框最小宽度，自然像素，默认 0
+ * @attr {number} min-height - 裁切框最小高度，自然像素，默认 0
+ * @attr {number} zoom - 受控缩放倍率；缺省该属性即非受控
+ * @attr {number} default-zoom - 非受控初始缩放倍率，默认 1
+ * @attr {number} rotation - 显示旋转角度，单位度，默认 0
+ * @attr {'rect'|'round'} shape - 裁切框外形，默认 rect
+ * @attr {boolean} disabled - 禁用：裁切框与把手退出 Tab 序列、改不动、不参与表单提交
+ * @attr {boolean} read-only - 只读：仍可聚焦与被读屏念出，改不动
+ * @attr {string} name - 表单字段名；给了才参与提交，值序列化成 "x,y,width,height"
+ * @fires value-change - 裁切矩形变化（拖动途中会连发）；detail 为 `{ value: { x, y, width, height } }`
+ * @fires value-change-end - 一次指针拖动松手发一次，一次方向键微调也发一次；detail 为 `{ value: { x, y, width, height } }`
+ * @fires zoom-change - 缩放倍率变化；detail 为 `{ zoom: number }`
+ * @csspart root - 承载 data-disabled / data-readonly / data-dragging / data-resizing / data-shape 的容器
+ * @csspart viewport - 量坐标的那个盒子，图片铺满它、裁切框绝对定位在它里面
+ * @csspart image - 源图，须是原生 `<img>`；自然尺寸与加载完成都由它报出来，src / alt 由宿主写入（作者别自己写，会被覆盖或清掉）
+ * @csspart crop-area - role=application 的裁切框，可聚焦，方向键平移
+ * @csspart crop-handle - 改尺寸的把手，须是原生 `<button>` 并自带 position 属性标识方位
+ * @csspart grid - 裁切框里的构图参考线，纯装饰
+ * @csspart hidden-input - 表单影子（须是原生 input）
+ */
+declare class XhImageCropperElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "viewport" | "image" | "grid" | "hidden-input" | "crop-area" | "crop-handle">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    src: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    alt: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => ImageCropperRect | undefined;
+      };
+    };
+    defaultValue: {
+      converter: {
+        fromAttribute: (v: string | null) => ImageCropperRect | undefined;
+      };
+      attribute: string;
+    };
+    aspectRatio: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    minWidth: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
       };
+      attribute: string;
     };
-    alt: {
+    minHeight: {
       converter: {
-        fromAttribute: (v: string | null) => string | undefined;
+        fromAttribute: (v: string | null) => number | undefined;
       };
+      attribute: string;
     };
-    fallbackDelay: {
+    zoom: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    defaultZoom: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    rotation: {
       converter: {
         fromAttribute: (v: string | null) => number | undefined;
       };
+    };
+    shape: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
       attribute: string;
     };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
   };
   src?: string;
   alt?: string;
-  fallbackDelay?: number;
-  private readonly notify;
+  value?: ImageCropperRect;
+  defaultValue?: ImageCropperRect;
+  aspectRatio?: number;
+  minWidth?: number;
+  minHeight?: number;
+  zoom?: number;
+  defaultZoom?: number;
+  rotation?: number;
+  shape?: ImageCropperShape;
+  disabled?: boolean;
+  readOnly?: boolean;
+  name?: string;
+  translations?: ImageCropperSchema['props']['translations'];
+  private readonly notifyValue;
+  private readonly notifyValueEnd;
+  private readonly notifyZoom;
   private readonly ctrl;
   private machineProps;
+  private injectRefs;
   /**
-   * 图片早在监听器挂上之前就已就绪时补一次上报：load 已经派发完，机器再也等不到，
-   * 状态会永远停在 loading——图片明明在手边，台前却一直是回退内容。两处会撞上：
-   * 作者把同一个 src 也写进了 img 标记（升级前浏览器就加载完了），
-   * 以及元素在 DOM 中被移动导致机器重建（状态从头走一遍，而 src 没变的 img 不会重新加载）。
-   *
-   * 三个条件缺一不可：complete 排除还在路上的请求；naturalWidth 排除加载失败——失败与
-   * "压根没发起请求"在这里分不开，不去猜，留在 loading 上照样只显示回退内容；
-   * currentSrc 与 src 相等排除换图那一瞬，此刻旧图仍是 complete 的，误报会把旧图当新图显出来。
-   *
-   * 只在 loading 补报：idle 期间补会被随后落地的来源决议一脚踢回 loading。
-   * 报完即进 loaded，下一帧不再命中，不会闭成回路。
+   * 把手自报的方位。作者在节点上写 position="se"，与 Vue 侧的 `:position` 是同一份声明；
+   * 写不出合法方位（没写、写错）时返回 null，由调用方决定怎么处理。
    */
-  private syncSettledImage;
+  private handlePosition;
   protected wire(): void;
 }
 //#endregion
@@ -3318,7 +4307,7 @@ declare class XhImageElement extends XhElement {
  */
 declare class XhImageViewerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"trigger" | "content" | "close-trigger" | "image" | "prev-trigger" | "next-trigger" | "viewport" | "positioner" | "backdrop" | "reset-trigger" | "toolbar" | "zoom-in-trigger" | "zoom-out-trigger" | "rotate-left-trigger" | "rotate-right-trigger" | "flip-horizontal-trigger" | "flip-vertical-trigger" | "counter">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"viewport" | "content" | "trigger" | "close-trigger" | "image" | "prev-trigger" | "next-trigger" | "positioner" | "backdrop" | "reset-trigger" | "toolbar" | "zoom-in-trigger" | "zoom-out-trigger" | "rotate-left-trigger" | "rotate-right-trigger" | "flip-horizontal-trigger" | "flip-vertical-trigger" | "counter">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -3409,6 +4398,7 @@ declare class XhImageViewerElement extends XhElement {
   private readonly viewerScope;
   private config;
   private contentNode;
+  private exit;
   private backdropNode;
   /** counter 的文本归属：首帧为空才代填，作者写过内容就不碰。 */
   private counterOwned;
@@ -3417,12 +4407,140 @@ declare class XhImageViewerElement extends XhElement {
   private readonly ctrl;
   private machineProps;
   private ensureConfig;
+  /** 退场闸门建一次；presence 不是响应式 cell，退场结束要显式排一次更新才轮得到收起。 */
+  private ensureExit;
   private readonly registerLayer;
   private injectRefs;
   protected wire(): void;
   disconnectedCallback(): void;
 }
 //#endregion
+//#region src/elements/json-viewer.d.ts
+/**
+ * `<xh-json-viewer>` —— Light-DOM 行为宿主：作者只写一个 root 角色节点，
+ * 元素跑 json-viewer 机器，把 value 摊成的每一行铺进 root 里。
+ *
+ * 行是按数据算出来的，作者写不出也不必写：树容器与每一行由本元素建，
+ * root 的内容整份由本元素接管（写在里面的东西会被替换掉）。
+ *
+ * 收起的分支整棵子层不进 DOM——一份大 JSON 全铺出来会把页面压住。
+ *
+ * 属性里的 value 是一段 JSON 文本（解析不了就当一个字符串值展示）；
+ * 直接喂对象走 property（`el.value = { … }`）。
+ * expandedValue / defaultExpandedValue / translations 没有对应属性，只能走 property。
+ *
+ * @customElement xh-json-viewer
+ * @attr {string} value - 要展示的值，写成一段 JSON 文本；对象与数组走 property
+ * @attr {number} default-expanded-depth - 初始展开到第几层，默认 1（只展开根行）
+ * @attr {number} max-string-length - 字符串值超过这么多字符就截断
+ * @attr {number} max-items - 同一层最多摊出这么多成员，其余收成一行占位
+ * @attr {boolean} sort-keys - 对象键按字典序排列
+ * @attr {boolean} loop - 上下键走到首尾回绕，默认关闭
+ * @attr {'ltr'|'rtl'} dir - 文字方向，只对调左右方向键的展开/收起语义；不写即从 DOM 现读
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires expanded-change - 展开集合变化；detail 为 `{ value: string[] }`
+ * @csspart root - 组件根容器，由作者写出；承载 data-size
+ * @csspart tree - role=tree 的树容器（键盘在此收口，焦点在树外时它兜底占 Tab 位）
+ * @csspart item - 标量行，role=treeitem，带 data-type
+ * @csspart item-key - 标量行的键名
+ * @csspart item-value - 标量行的值
+ * @csspart branch - 对象/数组行，role=treeitem，带 aria-expanded 与 data-state
+ * @csspart branch-control - 分支那一行本身（点它切换展开态）
+ * @csspart branch-trigger - 展开箭头（aria-hidden，不占 Tab 位）
+ * @csspart branch-indicator - 箭头字形，随 data-state 转向
+ * @csspart branch-text - 分支的键名
+ * @csspart preview - 收起摘要（如 `{…} 3`），对读屏隐藏
+ * @csspart branch-content - role=group 的子层容器，只在展开时存在
+ */
+declare class XhJsonViewerElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "preview" | "tree" | "item-key" | "item-value" | "branch" | "branch-control" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => unknown;
+      };
+    };
+    expandedValue: {
+      attribute: boolean;
+    };
+    defaultExpandedValue: {
+      attribute: boolean;
+    };
+    defaultExpandedDepth: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    maxStringLength: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    maxItems: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    sortKeys: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    loop: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  value?: unknown;
+  expandedValue?: string[];
+  defaultExpandedValue?: string[];
+  defaultExpandedDepth?: number;
+  maxStringLength?: number;
+  maxItems?: number;
+  sortKeys?: boolean;
+  loop?: boolean;
+  direction?: Direction;
+  size?: Size;
+  translations?: Partial<JsonViewerTranslations>;
+  private readonly notify;
+  private readonly ctrl;
+  private machineProps;
+  /** 树容器与每一行都归本元素建，按路径留着复用。 */
+  private treeEl;
+  private readonly rows;
+  /**
+   * root 被移出本宿主时，铺在它里面的行也一并离场。浏览器此时不派 focusout，
+   * 机器会一直认为焦点还在树内，行重新铺回来时高亮仍挂在那一行上。
+   * 这里替 DOM 把焦点离场如实上报（锚点留着，重新铺回来时仍落回那一行）。
+   */
+  protected onPartsReleased(nodes: readonly HTMLElement[]): void;
+  private makeRow;
+  private paint;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/listbox.d.ts
 /**
  * `<xh-listbox>` —— Light-DOM 行为宿主：作者写 root/label/content 与若干 item 角色节点，
@@ -3649,9 +4767,73 @@ declare class XhLoadingBarElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/masonry.d.ts
+/**
+ * `<xh-masonry>` —— Light-DOM 行为宿主，无状态机。作者写一个 root、若干 column 空容器，
+ * 以及一批 item；元素量出容器宽度与每一项的高度，算出各项落在第几列，再把项搬进对应的列里。
+ *
+ * 列由作者写，因为元素不生成结构：请按最宽那一档需要的列数写足 column 节点，
+ * 当前档位用不上的那几列会被收起。项写在 root 里即可，写在哪儿都会被搬进列里，
+ * 所以 column 节点必须是空容器，别在里面另放内容。
+ *
+ * 项的先后取「首次见到的顺序」——静态标记就是作者写的顺序；运行期新增的项排在末尾，
+ * 需要精确插到中间时请整块重建这批项。
+ *
+ * 浏览器没有 ResizeObserver 时只在每次接线那一刻量，之后不再跟随尺寸变化。
+ *
+ * @customElement xh-masonry
+ * @attr {number|string} columns - 分几列，不写按三列；写 JSON 对象则逐档给列数（base / sm / md / lg / xl），按容器自身宽度换档
+ * @attr {'xs'|'sm'|'md'|'lg'|'xl'} gap - 列与列、项与项之间的间距档位，逐档对应一个间距令牌
+ * @attr {boolean} sequential - 按文档序逐列填，不写则最短列优先
+ * @csspart root - 排布容器，承载 data-gap / data-sequential
+ * @csspart column - 一列，承载 data-index；须是空容器，项由元素搬进来
+ * @csspart item - 一项，承载 data-index（作者写的原序）与 data-column（落在第几列）
+ */
+declare class XhMasonryElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "column">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    columns: {
+      converter: {
+        fromAttribute: (v: string | null) => number | import("@xihan-ui/headless").MasonryColumnsByBreakpoint | undefined;
+      };
+    };
+    gap: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    sequential: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+  };
+  columns?: MasonryColumns;
+  gap?: MasonryProps['gap'];
+  sequential?: boolean;
+  /** 每一项首次被看到时的序号，重排后 DOM 序等于列序，原序只剩它认得出来。 */
+  private readonly seen;
+  private nextSeq;
+  private observer;
+  /** 当前挂着尺寸观察器的节点，与新一轮比对后才决定要不要重挂。 */
+  private observed;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  /** 按首次见到的先后排好当前在场的项。 */
+  private orderedItems;
+  /** 把项按落格结果搬进各列。位置已经对的节点原地不动，免得每次接线都产生一堆变更记录。 */
+  private place;
+  /** 把尺寸观察器挂到这一批节点上。节点没变就不重挂：重挂会白白多跑一轮回调。 */
+  private observeSizes;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/menu.d.ts
 /**
- * `<xh-menu>` —— Light-DOM 行为宿主：用户写 trigger/positioner/content/item/... 角色节点，
+ * `<xh-menu>` —— Light-DOM 行为宿主：用户写 trigger/positioner/content/item/group/... 角色节点，
  * 元素跑 menu 机器并把 connect 产出打上去。浮层定位引擎在本元素里建好、经 refs 注入机器，
  * 锚点取 trigger、被定位的浮层取 positioner；机器只认端口，不认识具体引擎。
  * 条目身份取用户写在 item 上的 value 属性，禁用由部件自报（aria-disabled）。
@@ -3672,11 +4854,13 @@ declare class XhLoadingBarElement extends XhElement {
  * @csspart content - role=menu 容器（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
  * @csspart item - role=menuitem 条目，须自带 value 属性标识身份；禁用写 aria-disabled="true"
  * @csspart separator - 分隔线（role=separator，不入方向键导航）
+ * @csspart group - role=group 分组容器，须自带 value 属性标识身份
+ * @csspart group-label - 分组标题（本组 aria-labelledby 的目标）
  * @csspart arrow - 指向锚点的箭头（aria-hidden，data-placement 随实际放置位翻转）
  */
 declare class XhMenuElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"item" | "trigger" | "content" | "separator" | "positioner" | "arrow">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"item" | "content" | "trigger" | "separator" | "positioner" | "group" | "group-label" | "arrow">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -3764,6 +4948,8 @@ declare class XhMenuElement extends XhElement {
   private readonly menuScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyOpen;
   private readonly notifySelect;
   private readonly ctrl;
@@ -3786,6 +4972,8 @@ declare class XhMenuElement extends XhElement {
    * 机器就地按当前活条目重挑锚点。
    */
   protected onPartsReleased(nodes: readonly HTMLElement[]): void;
+  /** 落在某个角色节点子树里的同名部件。 */
+  private partsIn;
   protected wire(): void;
   disconnectedCallback(): void;
 }
@@ -3828,8 +5016,12 @@ declare class XhMenuElement extends XhElement {
  * @csspart group-label - 分组标题，靠 id 被同组 group 的 aria-labelledby 指着
  */
 declare class XhMenubarElement extends XhElement {
+  /** 逐个 content 一份退场闸门：一个菜单一份，它们各开各的。 */
+  private readonly exits;
+  /** 闸门只用到 reducedMotion，本元素别处不需要 config，建一份共用即可。 */
+  private exitConfig;
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "content" | "separator" | "positioner" | "item-text" | "item-indicator" | "group" | "group-label">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "separator" | "positioner" | "item-text" | "item-indicator" | "group" | "group-label">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -3963,8 +5155,12 @@ declare class XhMenubarElement extends XhElement {
  * @csspart viewport - 可选的共享面板外壳，放在 root 里；都收起时 hidden
  */
 declare class XhNavigationMenuElement extends XhElement {
+  /** 逐个 content 一份退场闸门：一个菜单一份，它们各开各的。 */
+  private readonly exits;
+  /** 退场闸门与消解层共用一份环境包。 */
+  private config;
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "content" | "list" | "link" | "viewport">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "viewport" | "content" | "indicator" | "trigger" | "list" | "link">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4040,8 +5236,11 @@ declare class XhNavigationMenuElement extends XhElement {
   private readonly notify;
   private readonly ctrl;
   private machineProps;
+  private ensureConfig;
+  private readonly registerLayer;
   private injectRefs;
   protected wire(): void;
+  disconnectedCallback(): void;
 }
 //#endregion
 //#region src/elements/number-field.d.ts
@@ -4069,16 +5268,19 @@ declare class XhNavigationMenuElement extends XhElement {
  * @attr {'outline'|'subtle'|'ghost'} variant - 视觉变体
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @prop {(text: string) => number} parse - 显示串 → 数（千位分隔符、单位后缀这类靠它读回来）；只走 property
+ * @prop {(value: number) => string} format - 数 → 显示串，只在步进/取端点/失焦规范化时用；只走 property
  * @fires value-change - 值变化；detail 为 `{ value: string, valueAsNumber: number }`
  * @csspart root - 承载 data-disabled / data-readonly / data-invalid / data-empty 的容器
  * @csspart label - 标题；`for` 恒写向 input，故须是原生 `<label>` 才点得动
+ * @csspart control - 输入框与加减钮的包裹层；皮肤把视觉盒画在它身上，减在左、加在右、输入框居中
  * @csspart input - role=spinbutton 的输入框，键盘交互全在它身上
  * @csspart increment-trigger - 加一步；贴住 max 时转 disabled
  * @csspart decrement-trigger - 减一步；贴住 min 时转 disabled
  */
 declare class XhNumberFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "input" | "increment-trigger" | "decrement-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "input" | "increment-trigger" | "decrement-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4159,6 +5361,12 @@ declare class XhNumberFieldElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    parse: {
+      attribute: boolean;
+    };
+    format: {
+      attribute: boolean;
+    };
   };
   value?: string;
   defaultValue?: string;
@@ -4176,6 +5384,8 @@ declare class XhNumberFieldElement extends XhElement {
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
+  parse?: NumberFieldSchema['props']['parse'];
+  format?: NumberFieldSchema['props']['format'];
   private readonly notify;
   private readonly ctrl;
   private machineProps;
@@ -4202,53 +5412,191 @@ declare class XhNumberFieldElement extends XhElement {
  * @attr {'ltr'|'rtl'} dir - 文字方向，只影响排版；上一页/下一页的语义不随之翻转
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
- * @fires page-change - 页码变化；detail 为 `{ page: number, pageSize: number }`
- * @csspart root - nav 地标，承载 aria-label 与 data-empty
- * @csspart prev-trigger - 上一页；首页时转原生 disabled
- * @csspart next-trigger - 下一页；末页时转原生 disabled
- * @csspart item - 页码按钮，须自带 value 属性；当前页带 aria-current="page" 与 data-selected
- * @csspart ellipsis - 折叠掉的那几页的占位，对读屏隐藏
+ * @fires page-change - 页码变化；detail 为 `{ page: number, pageSize: number }`
+ * @csspart root - nav 地标，承载 aria-label 与 data-empty
+ * @csspart prev-trigger - 上一页；首页时转原生 disabled
+ * @csspart next-trigger - 下一页；末页时转原生 disabled
+ * @csspart item - 页码按钮，须自带 value 属性；当前页带 aria-current="page" 与 data-current
+ * @csspart ellipsis - 折叠掉的那几页的占位，对读屏隐藏
+ */
+declare class XhPaginationElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "ellipsis" | "prev-trigger" | "next-trigger">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    count: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    pageSize: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    page: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    defaultPage: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    siblingCount: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  count?: number;
+  pageSize?: number;
+  page?: number;
+  defaultPage?: number;
+  siblingCount?: number;
+  direction?: Direction;
+  tone?: Tone;
+  size?: Size;
+  translations?: Partial<PaginationTranslations>;
+  private readonly notify;
+  private readonly ctrl;
+  private machineProps;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/password-input.d.ts
+/**
+ * `<xh-password-input>` —— Light-DOM 行为宿主：作者写 root/label/control/input/
+ * visibility-trigger/caps-lock-indicator 六类角色节点，元素跑 password-input 机器并把 connect 产出打上去。
+ *
+ * label 的 `for` 恒写向 input 的 id，所以 label 角色节点必须是原生 `<label>`、input 角色节点必须是原生
+ * `<input>`；切换钮必须是原生 `<button>`，Enter / Space 的激活由平台负责。
+ *
+ * 明暗只改 input 的 type：隐藏态 password、显示态 text。切换之后焦点留在按钮上，
+ * 框里的光标与选中范围由机器放回原处。
+ *
+ * 大写锁定靠按键事件里的 getModifierState 判定——平台没有"现在查一下修饰键"的接口，
+ * 所以提示要等用户按下第一个键才亮，焦点离开输入框即熄灭。提示节点作者写空壳，
+ * 里面的文字由元素写入。
+ *
+ * @customElement xh-password-input
+ * @attr {string} value - 受控值；缺省该属性即非受控
+ * @attr {string} default-value - 非受控初值
+ * @attr {boolean} visible - 受控的明暗态；缺省该属性即非受控
+ * @attr {boolean} default-visible - 非受控的初始明暗态，缺省隐藏
+ * @attr {boolean} disabled - 禁用：输入与明暗切换都推不动
+ * @attr {boolean} read-only - 只读：值写不进，明暗照切
+ * @attr {boolean} required - 必填标注
+ * @attr {boolean} invalid - 校验失败标注
+ * @attr {string} name - 表单字段名；给了才参与提交
+ * @attr {string} placeholder - 占位文案
+ * @attr {string} auto-complete - 落到 input 上的 autocomplete，缺省 current-password；注册表单要写 new-password
+ * @attr {'outline'|'subtle'|'ghost'} variant - 视觉变体
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires value-change - 值变化；detail 为 `{ value: string }`
+ * @fires visibility-change - 明暗变化；detail 为 `{ visible: boolean }`
+ * @csspart root - 承载三个视觉轴与 data-disabled / data-readonly / data-invalid / data-empty 的容器
+ * @csspart label - 标题；`for` 恒写向 input，故须是原生 `<label>` 才点得动
+ * @csspart control - 视觉盒：描边、底色与聚焦环画在它身上，框内三件都是透明分段
+ * @csspart input - 真正的输入框，须是原生 `<input>`；type 随明暗在 password / text 之间换
+ * @csspart visibility-trigger - 明暗切换钮，须是原生 `<button>`；名字随状态换，里面放图标即可
+ * @csspart caps-lock-indicator - 大写锁定提示；节点留空即可，文字由元素写入，是 role=status 的活区域
  */
-declare class XhPaginationElement extends XhElement {
+declare class XhPasswordInputElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "ellipsis" | "prev-trigger" | "next-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "input" | "visibility-trigger" | "caps-lock-indicator">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
-    count: {
+    value: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => string | undefined;
       };
     };
-    pageSize: {
+    defaultValue: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => string | undefined;
       };
       attribute: string;
     };
-    page: {
+    visible: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
-    defaultPage: {
+    defaultVisible: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => boolean | undefined;
       };
       attribute: string;
     };
-    siblingCount: {
+    disabled: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
       };
       attribute: string;
     };
-    direction: {
+    required: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    invalid: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    placeholder: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    autoComplete: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
       };
       attribute: string;
     };
+    variant: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     tone: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -4263,16 +5611,23 @@ declare class XhPaginationElement extends XhElement {
       attribute: boolean;
     };
   };
-  count?: number;
-  pageSize?: number;
-  page?: number;
-  defaultPage?: number;
-  siblingCount?: number;
-  direction?: Direction;
+  value?: string;
+  defaultValue?: string;
+  visible?: boolean;
+  defaultVisible?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  invalid?: boolean;
+  name?: string;
+  placeholder?: string;
+  autoComplete?: string;
+  variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
-  translations?: Partial<PaginationTranslations>;
-  private readonly notify;
+  translations?: Partial<PasswordInputTranslations>;
+  private readonly notifyValue;
+  private readonly notifyVisibility;
   private readonly ctrl;
   private machineProps;
   protected wire(): void;
@@ -4291,7 +5646,8 @@ declare class XhPaginationElement extends XhElement {
  * @attr {string} value - 受控值，逐字符摊进各格；缺省该属性即非受控
  * @attr {string} default-value - 非受控初值，同样逐字符摊开
  * @attr {number} length - 格数，默认 6
- * @attr {'numeric'|'alphanumeric'|'alphabetic'} type - 接受的字符类别，默认 numeric
+ * @attr {'numeric'|'alphanumeric'|'alphabetic'} type - 接受的字符类别，默认 numeric；同时决定移动端弹哪种键盘
+ * @attr {string} pattern - 自定义准入：一段正则源码，逐个字符整格匹配（自动加锚与 u 标志）。给了它就盖过 type 的准入表；写坏了退回 type
  * @attr {boolean} mask - 遮蔽显示：每格转 type=password
  * @attr {boolean} otp - 一次性验证码：补 autocomplete=one-time-code
  * @attr {string} placeholder - 空格子的占位字符
@@ -4336,6 +5692,11 @@ declare class XhPinInputElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    pattern: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     mask: {
       type: BooleanConstructor;
     };
@@ -4385,6 +5746,7 @@ declare class XhPinInputElement extends XhElement {
   defaultValue?: string[];
   length?: number;
   type?: PinInputType;
+  pattern?: string;
   mask?: boolean;
   otp?: boolean;
   placeholder?: string;
@@ -4429,7 +5791,7 @@ declare class XhPinInputElement extends XhElement {
  */
 declare class XhPopoverElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"trigger" | "content" | "title" | "description" | "close-trigger" | "positioner" | "arrow">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"content" | "trigger" | "title" | "description" | "close-trigger" | "positioner" | "arrow">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4492,6 +5854,8 @@ declare class XhPopoverElement extends XhElement {
   private readonly popoverScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notify;
   private readonly ctrl;
   private machineProps;
@@ -4532,6 +5896,7 @@ declare class XhPopoverElement extends XhElement {
  * @attr {number} stroke-width - 环的线宽（viewBox 单位），默认 6；只对 circle / dashboard 生效
  * @attr {number} gap-degree - 缺口角度，默认 75；只对 dashboard 生效
  * @attr {'top'|'right'|'bottom'|'left'} gap-position - 缺口朝向，默认 bottom；只对 dashboard 生效
+ * @attr {boolean} indeterminate - 进度未知：条子改为往复动画，读屏那侧不报数
  * @attr {string} value-text - 读屏播报的文字，覆盖默认的数值播报
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸：线形改厚度，环形改直径
@@ -4565,6 +5930,9 @@ declare class XhProgressElement extends XhElement {
     gapPosition: {
       attribute: string;
     };
+    indeterminate: {
+      type: BooleanConstructor;
+    };
     valueText: {
       attribute: string;
     };
@@ -4577,6 +5945,7 @@ declare class XhProgressElement extends XhElement {
   strokeWidth?: number;
   gapDegree?: number;
   gapPosition?: ProgressGapPosition;
+  indeterminate?: boolean;
   valueText?: string;
   tone?: Tone;
   size?: Size;
@@ -4594,6 +5963,9 @@ declare class XhProgressElement extends XhElement {
  * @attr {string} value - 受控选中值；缺省该属性即非受控
  * @attr {string} default-value - 非受控初始选中值
  * @attr {boolean} disabled - 整组禁用
+ * @attr {boolean} read-only - 只读：选不动，方向键照常移焦点
+ * @attr {boolean} invalid - 校验失败态
+ * @attr {boolean} required - 必填
  * @attr {'horizontal'|'vertical'} orientation - 视觉排布，默认 vertical
  * @attr {'ltr'|'rtl'} dir - 文字方向，只改写左右方向键语义，默认 ltr
  * @attr {string} name - 表单字段名；给定后隐藏输入才带 name 并参与提交
@@ -4609,7 +5981,7 @@ declare class XhProgressElement extends XhElement {
  */
 declare class XhRadioGroupElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "label" | "item-text" | "hidden-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "indicator" | "label" | "item-text" | "hidden-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4627,6 +5999,16 @@ declare class XhRadioGroupElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    readOnly: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    invalid: {
+      type: BooleanConstructor;
+    };
+    required: {
+      type: BooleanConstructor;
+    };
     orientation: {};
     direction: {
       attribute: string;
@@ -4639,6 +6021,9 @@ declare class XhRadioGroupElement extends XhElement {
   value?: string;
   defaultValue?: string;
   disabled?: boolean;
+  readOnly?: boolean;
+  invalid?: boolean;
+  required?: boolean;
   orientation?: Orientation;
   direction?: Direction;
   name?: string;
@@ -4690,60 +6075,302 @@ declare class XhRadioGroupElement extends XhElement {
  *   点亮看 data-highlighted，半亮看 data-half
  * @csspart hidden-input - 表单影子输入（必须是原生 input）
  */
-declare class XhRatingElement extends XhElement {
+declare class XhRatingElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "control" | "hidden-input">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    defaultValue: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    count: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    allowHalf: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    allowClear: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    required: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+  };
+  value?: number;
+  defaultValue?: number;
+  count?: number;
+  allowHalf?: boolean;
+  allowClear?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  name?: string;
+  direction?: Direction;
+  tone?: Tone;
+  size?: Size;
+  private readonly notifyValue;
+  private readonly notifyHover;
+  private readonly ctrl;
+  private machineProps;
+  /**
+   * 承载焦点的星被移出 DOM 时浏览器不派 focusout，焦点锚点会停在一颗已消失的星上：
+   * 容器判自己"焦点在带内"退出 Tab 序列，又没有条目认领得了这个锚点，
+   * 整条评分带零个 Tab 停靠点，键盘用户再也进不来。这里替 DOM 把焦点离场如实上报。
+   */
+  protected onPartsReleased(nodes: readonly HTMLElement[]): void;
+  /** 条目身份取自作者写的 value 属性；没写就不是一颗合法的星，交给 connect 按非法值处理。 */
+  private itemProps;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/scroll-area.d.ts
+/**
+ * `<xh-scroll-area>` —— Light-DOM 行为宿主：作者写 root/viewport/content 与两条 scrollbar
+ * 角色节点，元素按轴各跑一台 scrollbar 机器并把 connect 产出打上去。
+ *
+ * 滚动区没有自己的机器，它是视口加两条 scrollbar 的组装：scrollbar 角色节点是那条
+ * scrollbar 的挂载点、同时充当它的根，里面照 scrollbar 那套写 track / thumb / corner
+ * （它们戴 data-scope="scrollbar"），两个组件共用同一份滚动条。
+ *
+ * 滚动本身一概不接管：viewport 是真正 overflow:auto 的那层，键盘（PageUp/PageDown、方向键、
+ * Home/End）与滚轮全部走浏览器原生通路，元素只是把原生滚动条藏起来另画一套。
+ * 自绘的滚动条对读屏隐藏——同一件事没必要报两遍。
+ *
+ * 每条滚动条用 orientation 属性写明自己管哪条轴（不写即 vertical），
+ * 轨道与滑块按所在滚动条的轴向取几何，不必另写。这是挂载时的静态声明：运行期要换轴，换节点。
+ *
+ * @customElement xh-scroll-area
+ * @attr {'auto'|'always'|'scroll'|'hover'} type - 滚动条露面的时机，默认 hover
+ * @attr {number} hide-delay - 收起前的等待毫秒（type 为 scroll / hover 时生效），默认 600
+ * @attr {'horizontal'|'vertical'|'both'} orientation - 哪几条轴归本组件管，默认 both
+ * @attr {'sm'|'md'|'lg'} size - 尺寸档，换的是滚动条厚度
+ * @attr {'ltr'|'rtl'} dir - 排版方向，只改写横轴的滚动量正负与指针位移方向
+ * @attr {boolean} force-visible - 触屏（粗指针）上也画自绘滚动条；缺省交给原生滚动
+ * @csspart root - 组件根容器（承载 data-orientation / data-type / data-dragging），定位上下文
+ * @csspart viewport - 真正 overflow:auto 的那层，带 tabindex=0 让键盘用户落得进来；承载 data-lane-vertical / data-lane-horizontal
+ * @csspart content - 内容包裹层，横向溢出靠它撑出宽度
+ * @csspart scrollbar - 某条轴的滚动条挂载点，须用 orientation 属性写明轴向；同时是那条 scrollbar 的根，承载 data-state / data-gutter / data-native
+ * @csspart track - 轨道（data-scope="scrollbar"），点空白处把滑块中心挪过去
+ * @csspart thumb - 滑块（data-scope="scrollbar"），位置与长度由内联逻辑属性给出；按住可拖
+ * @csspart corner - 交叉口补丁（data-scope="scrollbar"），写在竖条的挂载点里；只有两条都在场时显形
+ */
+declare class XhScrollAreaElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "viewport" | "content" | "scrollbar">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+    delegates: import("@xihan-ui/kernel").Anatomy<"root" | "track" | "thumb" | "corner">[];
+  };
+  static properties: {
+    type: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    hideDelay: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    orientation: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    forceVisible: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+  };
+  type?: ScrollbarType;
+  hideDelay?: number;
+  orientation?: ScrollAreaOrientation;
+  size?: Size;
+  direction?: Direction;
+  forceVisible?: boolean;
+  private readonly idGen;
+  private readonly areaScope;
+  private readonly verticalCtrl;
+  private readonly horizontalCtrl;
+  private areaProps;
+  /**
+   * 这条滚动条管哪条轴。作者在节点上写 orientation="horizontal"，与 Vue 侧的同名 prop
+   * 是同一份声明；没写或写不出来即竖向（两个适配器同一个缺省）。
+   */
+  private barOrientation;
+  /** 某条轴的挂载点：按轴现查而不是缓存，作者随时可能增删一条轴的滚动条。 */
+  private barEl;
+  private partsIn;
+  private injectRefs;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/scrollbar.d.ts
+/**
+ * `<xh-scrollbar>` —— Light-DOM 行为宿主：作者写 root/track/thumb 三个角色节点，
+ * 元素跑 scrollbar 机器并把 connect 产出打上去。
+ *
+ * 滚动容器由作者交出来，且**不必**是本元素的后代：写 `controls="内容区的 id"`，
+ * 或者用 JS 把节点赋给 `scrollable` 属性。表格的滚动盒、虚拟滚动的视口、
+ * 随手一个 overflow:auto 的 div 都行。
+ *
+ * 滚动本身一概不接管：键盘（PageUp/PageDown、方向键、Home/End）与滚轮在滚动容器上
+ * 走浏览器原生通路，本元素只是另画一套并接上拖拽与点轨道。滑块缺省不进 Tab 序、
+ * 也对读屏隐藏——同一件事没必要报两遍；要用键盘操作滑块本身时开 `focusable`。
+ *
+ * 滑块的位置与长度按可视区/内容/滚动量算出来后写进内联样式：竖向是
+ * inset-block-start + block-size，横向是 inset-inline-start + inline-size（逻辑属性，RTL 自动换向）。
+ *
+ * @customElement xh-scrollbar
+ * @attr {string} controls - 滚动容器的 id；没设 scrollable 属性时按它查节点，focusable 时同时落到 aria-controls
+ * @attr {'horizontal'|'vertical'} orientation - 这条滚动条管哪条轴，默认 vertical
+ * @attr {'auto'|'always'|'scroll'|'hover'} type - 露面的时机，默认 hover
+ * @attr {number} hide-delay - 收起前的等待毫秒（type 为 scroll / hover 时生效），默认 600
+ * @attr {number} min-thumb-size - 滑块最短多少像素，默认 20
+ * @attr {number} step - 方向键一步滚多少像素，默认 40
+ * @attr {'sm'|'md'|'lg'} size - 尺寸档，换的是滚动条厚度
+ * @attr {boolean} disabled - 不接指针也不接键盘，恒不显形
+ * @attr {boolean} focusable - 滑块进 Tab 序并报 role=scrollbar，默认关
+ * @attr {boolean} gutter - 横竖两条同时摆着时在末端让出交叉口那一格，交叉口由 corner 部件补
+ * @attr {boolean} force-visible - 触屏（粗指针）上也显形；缺省交给原生滚动，整条不画并带 data-native
+ * @attr {'ltr'|'rtl'} dir - 排版方向，只改写横轴的滚动量正负与指针位移方向
+ * @prop {HTMLElement} scrollable - 直接给滚动容器节点（对象只走 property），优先于 controls
+ * @fires scroll-start - 开始滚了；detail 为 `{ offset: number, max: number }`
+ * @fires scroll-end - 一段滚动结束（停手 120ms）；detail 同上
+ * @fires drag-start - 按住滑块；detail 同上
+ * @fires drag-end - 松开滑块；detail 同上
+ * @csspart root - 定位盒与指针热区，承载 data-orientation / data-type / data-state / data-scrolling / data-dragging / data-size / data-gutter / data-native；收起走 data-state=hidden 由皮肤淡出
+ * @csspart track - 量长度的那条轨，点空白处把滑块中心挪过去
+ * @csspart thumb - 滑块，位置与长度由内联逻辑属性给出；按住可拖，focusable 时可聚焦并吃方向键
+ * @csspart corner - 交叉口补丁（可选），写在根里、贴在本条末端之外那一格，跟着本条显隐
+ */
+declare class XhScrollbarElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "hidden-input" | "control">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "track" | "thumb" | "corner">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
-    value: {
+    controls: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => string | undefined;
       };
     };
-    defaultValue: {
+    orientation: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    type: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    hideDelay: {
       converter: {
         fromAttribute: (v: string | null) => number | undefined;
       };
       attribute: string;
     };
-    count: {
+    minThumbSize: {
       converter: {
         fromAttribute: (v: string | null) => number | undefined;
       };
+      attribute: string;
     };
-    allowHalf: {
+    step: {
       converter: {
-        fromAttribute: (v: string | null) => boolean | undefined;
+        fromAttribute: (v: string | null) => number | undefined;
       };
-      attribute: string;
     };
-    allowClear: {
+    size: {
       converter: {
-        fromAttribute: (v: string | null) => boolean | undefined;
+        fromAttribute: (v: string | null) => string | undefined;
       };
-      attribute: string;
     };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
-    readOnly: {
+    focusable: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
-      attribute: string;
     };
-    required: {
+    gutter: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
-    name: {
+    forceVisible: {
       converter: {
-        fromAttribute: (v: string | null) => string | undefined;
+        fromAttribute: (v: string | null) => boolean | undefined;
       };
+      attribute: string;
     };
     direction: {
       converter: {
@@ -4751,89 +6378,117 @@ declare class XhRatingElement extends XhElement {
       };
       attribute: string;
     };
-    tone: {
-      converter: {
-        fromAttribute: (v: string | null) => string | undefined;
-      };
+    scrollable: {
+      attribute: boolean;
     };
-    size: {
-      converter: {
-        fromAttribute: (v: string | null) => string | undefined;
-      };
+    translations: {
+      attribute: boolean;
     };
   };
-  value?: number;
-  defaultValue?: number;
-  count?: number;
-  allowHalf?: boolean;
-  allowClear?: boolean;
+  controls?: string;
+  orientation?: Orientation;
+  type?: ScrollbarType;
+  hideDelay?: number;
+  minThumbSize?: number;
+  step?: number;
+  size?: Size;
   disabled?: boolean;
-  readOnly?: boolean;
-  required?: boolean;
-  name?: string;
+  focusable?: boolean;
+  gutter?: boolean;
+  forceVisible?: boolean;
   direction?: Direction;
-  tone?: Tone;
-  size?: Size;
-  private readonly notifyValue;
-  private readonly notifyHover;
+  scrollable?: HTMLElement | null;
+  translations?: ScrollbarSchema['props']['translations'];
   private readonly ctrl;
   private machineProps;
+  /** 事件名逐个写在调用点：形参名会被清单分析器当成事件名，凑出一个永不派发的条目。 */
+  private fire;
   /**
-   * 承载焦点的星被移出 DOM 时浏览器不派 focusout，焦点锚点会停在一颗已消失的星上：
-   * 容器判自己"焦点在带内"退出 Tab 序列，又没有条目认领得了这个锚点，
-   * 整条评分带零个 Tab 停靠点，键盘用户再也进不来。这里替 DOM 把焦点离场如实上报。
+   * 先认 scrollable 属性给的节点，没有再按 controls 当 id 去查。
+   * 每次调用现查：作者的容器可能是后插进来的，缓存住会永远指向第一次那个（或 null）。
    */
-  protected onPartsReleased(nodes: readonly HTMLElement[]): void;
-  /** 条目身份取自作者写的 value 属性；没写就不是一颗合法的星，交给 connect 按非法值处理。 */
-  private itemProps;
+  private resolveScrollable;
+  private injectRefs;
   protected wire(): void;
 }
 //#endregion
-//#region src/elements/scroll-area.d.ts
+//#region src/elements/segmented.d.ts
 /**
- * `<xh-scroll-area>` —— Light-DOM 行为宿主：作者写 root/viewport/content/scrollbar/thumb/corner
- * 角色节点，元素跑 scroll-area 机器并把 connect 产出打上去。
- *
- * 滚动本身一概不接管：viewport 是真正 overflow:auto 的那层，键盘（PageUp/PageDown、方向键、
- * Home/End）与滚轮全部走浏览器原生通路，元素只是把原生滚动条藏起来另画一套。
- * 自绘的 scrollbar/thumb 对读屏隐藏——同一件事没必要报两遍。
- *
- * 滑块的位置与长度按视口/内容/滚动量算出来后写进内联样式：竖向是 inset-block-start + block-size，
- * 横向是 inset-inline-start + inline-size（逻辑属性，RTL 下自动换向）。
- * 尺寸在机器的效应里量：挂载后推迟一拍量一次，此后跟着 scroll 事件与 ResizeObserver 走。
+ * `<xh-segmented>` —— Light-DOM 行为宿主：作者写 root 与若干 item 角色节点，
+ * 元素跑 segmented 机器并把 connect 产出打上去。段须是原生 `<button>`
+ * （Enter/Space 的激活由平台负责），身份取写在段上的 value 属性，禁用由段自报 aria-disabled。
  *
- * 每条滚动条用 orientation 属性写明自己管哪条轴（不写即 vertical），
- * 滑块按所在滚动条的轴向取几何，不必另写。
+ * 一排互斥选项就是单选组：root 是 radiogroup，每段 role=radio 并显式报 aria-checked。
+ * indicator 是那块会滑动的选中标记，位置由机器量好写成内联样式里的四个私有槽；
+ * 它绝对定位，必须写在段之前，靠文档序让段压在它上面。
  *
- * @customElement xh-scroll-area
- * @attr {'auto'|'always'|'scroll'|'hover'} type - 滚动条露面的时机，默认 hover
- * @attr {number} scroll-hide-delay - 收起前的等待毫秒（type 为 scroll / hover 时生效），默认 600
- * @attr {'horizontal'|'vertical'|'both'} orientation - 哪几条轴归本组件管，默认 both
- * @attr {'ltr'|'rtl'} dir - 排版方向，只改写横轴的滚动量正负与指针位移方向
- * @csspart root - 组件根容器（承载 data-orientation / data-type / data-dragging），指针进出的判据挂在它身上
- * @csspart viewport - 真正 overflow:auto 的那层，带 tabindex=0 让键盘用户落得进来
- * @csspart content - 内容包裹层，横向溢出靠它撑出宽度，尺寸变化也观察它
- * @csspart scrollbar - 自绘滚动条轨道，须用 orientation 属性写明轴向；收起时带 hidden
- * @csspart thumb - 滑块，位置与长度由内联逻辑属性给出；按住可拖
- * @csspart corner - 两条滚动条同时在场时右下角那块补丁；只有一条时带 hidden
+ * @customElement xh-segmented
+ * @attr {string} value - 受控选中值；缺省该属性即非受控
+ * @attr {string} default-value - 非受控的初始选中值
+ * @attr {boolean} disabled - 整组禁用
+ * @attr {boolean} read-only - 只读：选不动，方向键照常移焦点
+ * @attr {boolean} invalid - 校验失败态
+ * @attr {boolean} required - 必填
+ * @attr {string} name - 表单字段名；给定后隐藏输入才带 name 并参与提交
+ * @attr {'horizontal'|'vertical'} orientation - 视觉排布，默认 horizontal；方向键四个恒响应，与它无关
+ * @attr {'ltr'|'rtl'} dir - 文字方向，只改写左右方向键语义与指示器的起始缘；不写即从 DOM 现读祖先链上的方向
+ * @attr {boolean} loop - 方向键走到尽头回绕，默认开启
+ * @attr {boolean} block - 撑满行宽，各段等分剩余空间
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires value-change - 选中值变化；detail 为 `{ value: string | null }`
+ * @csspart root - role=radiogroup 的容器（承载键盘收口与 Tab 兜底位）
+ * @csspart item - 一段，须是原生 `<button>` 并自带 value 属性标识身份
+ * @csspart item-text - 段内文本
+ * @csspart indicator - 会滑动的选中标记，对读屏隐藏；无选中项时收起
+ * @csspart hidden-input - 表单影子输入（必须是原生 input），整组只需一份；给了 name 却没写它，就没有任何东西参与提交
  */
-declare class XhScrollAreaElement extends XhElement {
+declare class XhSegmentedElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "viewport" | "thumb" | "scrollbar" | "corner">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "indicator" | "item-text" | "hidden-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
-    type: {
+    collection: {
+      attribute: boolean;
+    };
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    defaultValue: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
       };
+      attribute: string;
     };
-    scrollHideDelay: {
+    disabled: {
       converter: {
-        fromAttribute: (v: string | null) => number | undefined;
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
       };
       attribute: string;
     };
+    invalid: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    required: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     orientation: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -4845,21 +6500,57 @@ declare class XhScrollAreaElement extends XhElement {
       };
       attribute: string;
     };
+    loop: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    block: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
   };
-  type?: ScrollAreaType;
-  scrollHideDelay?: number;
-  orientation?: ScrollAreaOrientation;
+  collection?: SegmentedNode[];
+  value?: string;
+  defaultValue?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  name?: string;
+  orientation?: Orientation;
   direction?: Direction;
-  private readonly idGen;
-  private readonly scrollAreaScope;
+  loop?: boolean;
+  block?: boolean;
+  tone?: Tone;
+  size?: Size;
+  private readonly declaredDisabled;
+  /** 上一帧是否整组禁用：解禁当帧 DOM 上还留着机器写回的 aria-disabled，读不得。 */
+  private wasGroupDisabled;
+  private readonly notify;
   private readonly ctrl;
   private machineProps;
+  private injectRefs;
   /**
-   * 这条滚动条管哪条轴。作者在节点上写 orientation="horizontal"，与 Vue 侧的同名 prop
-   * 是同一份声明；没写或写不出来即竖向（两个适配器同一个缺省）。
+   * 承载焦点的段被移出 DOM 时浏览器不派 focusout，焦点锚点会停在一个已消失的值上：
+   * 容器判自己"焦点在组内"退出 Tab 序列，又没有段认领得了这个锚点，
+   * 整组零个 Tab 停靠点，键盘用户再也进不来。这里替 DOM 把焦点离场如实上报。
    */
-  private barOrientation;
-  private injectRefs;
+  protected onPartsReleased(nodes: readonly HTMLElement[]): void;
+  /** 作者声明的段禁用，只认首见那一份；没写即 undefined，交给 collection 定夺 */
+  private readonly declaredItemDisabled;
+  private itemProps;
   private partsIn;
   protected wire(): void;
 }
@@ -4880,6 +6571,7 @@ declare class XhScrollAreaElement extends XhElement {
  * @attr {boolean} open - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-open - 非受控初始为展开
  * @attr {boolean} disabled - 整个控件禁用：trigger 用原生 disabled，表单影子不参与提交
+ * @attr {boolean} read-only - 只读：浮层照常展开、条目照常浏览，但选中值改不动、也清不掉
  * @attr {boolean} invalid - 校验错误态：trigger 标红并输出 aria-invalid
  * @attr {number} max-tag-count - 多选标签最多摆几个，其余折进 api 的 overflowCount；缺省全摆
  * @attr {boolean} required - 原生表单校验：无选中值时提交被拦下；多选下的门槛是至少选中一项
@@ -4900,12 +6592,14 @@ declare class XhScrollAreaElement extends XhElement {
  * @csspart trigger - 触发按钮（aria-haspopup=listbox/aria-expanded/aria-controls 所在），同时是定位锚点，须是原生 button
  * @csspart value-text - 选中项文本的显示位；留空即由元素填入 displayText，作者写了内容则归作者
  * @csspart indicator - 展开指示符（aria-hidden，data-state 随开合）
- * @csspart control - 触发器与清空按钮的收纳容器兼定位基准；清空钮据此嵌进触发器右端、悬停时替换展开指示符
- * @csspart clear-trigger - 清空按钮：trigger 的兄弟节点（放进 control 即内嵌形态），没选中或禁用时带 hidden；可及名走 translations.clear
- * @csspart tag - 多选标签，须自带 value 属性标识选中值；放触发器里是纯展示，放外面配 tag-remove 可删
- * @csspart tag-remove - 标签删除按钮，须放在 tag 里；点按摘掉所在标签的选中值，可及名走 translations.removeTag
+ * @csspart control - 盒：触发器与清空按钮在里面并排，描边、底色、控件高度与聚焦环都长在它上面
+ * @csspart clear-trigger - 清空按钮：盒里 trigger 的兄弟节点，不占 Tab 位；清不了（无值 / 禁用 / 只读）时带 hidden，点完焦点送回 trigger；可及名走 translations.clearTrigger
+ * @csspart tag - 多选标签，须自带 value 属性标识选中值；放触发器里是纯展示，放外面配 item-delete-trigger 可删
+ * @csspart item-delete-trigger - 标签删除按钮，须放在 tag 里；点按摘掉所在标签的选中值，可及名走 translations.deleteItem
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
- * @csspart content - role=listbox 容器（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
+ * @csspart content - 浮层外壳（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
+ * @csspart list - role=listbox 本体，条目放在它里面；滚动也在这一层
+ * @csspart footer - 浮层底部的操作区，是 list 的兄弟；不进列表框的拥有关系，方向键与连打检索也不认它
  * @csspart item - role=option 条目，须自带 value 属性标识身份；禁用写 aria-disabled="true"
  * @csspart item-text - 条目文本（连打检索与 value-text 的取字处）
  * @csspart item-indicator - 条目选中标记（aria-hidden）
@@ -4913,7 +6607,7 @@ declare class XhScrollAreaElement extends XhElement {
  */
 declare class XhSelectElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "content" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "control" | "tag" | "tag-remove" | "hidden-select">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "list" | "label" | "control" | "positioner" | "clear-trigger" | "item-text" | "item-indicator" | "value-text" | "item-delete-trigger" | "footer" | "tag" | "hidden-select">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4943,6 +6637,12 @@ declare class XhSelectElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
     invalid: {
       type: BooleanConstructor;
     };
@@ -5014,6 +6714,7 @@ declare class XhSelectElement extends XhElement {
   open?: boolean;
   defaultOpen?: boolean;
   disabled?: boolean;
+  readOnly?: boolean;
   invalid?: boolean;
   required?: boolean;
   name?: string;
@@ -5026,13 +6727,15 @@ declare class XhSelectElement extends XhElement {
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
-  /** 读屏文案（clear 等）；对象进不了属性，只作为 property 暴露。 */
+  /** 读屏文案（clearTrigger 等）；对象进不了属性，只作为 property 暴露。 */
   translations?: SelectSchema['props']['translations'];
   maxTagCount?: number;
   private readonly idGen;
   private readonly selectScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   /** value-text 是否归元素填：首次见到该节点时定，之后不再回读（回读到的会是自己写的字）。 */
   private readonly ownsValueText;
   /** 表单影子当前这批选项对应的值与文字，同一份不重建。 */
@@ -5116,20 +6819,22 @@ declare class XhSeparatorElement extends XhElement {
  * @fires value-change - 选中变化；detail 为 `{ value: string | null }`
  * @fires expanded-change - 展开集合变化；detail 为 `{ value: string[] }`
  * @csspart root - nav 地标根容器（aria-label 由 translations.root 给）
- * @csspart list - 顶层列表容器
+ * @csspart list - 顶层列表容器（ul），直接子节点只能是 item 与 branch
+ * @csspart item - 叶子行的列表项（li），裹住一个 link
  * @csspart group - role=group 分组，须自带 value 属性
  * @csspart group-label - 分组标题（aria-labelledby 目标）
  * @csspart branch - 分支行容器，须自带 value 属性；它裹着自己的 branch-content
- * @csspart branch-trigger - 展开/收起按钮（aria-expanded / aria-controls）
- * @csspart branch-text - 行文字载体，折叠成图标栏时隐藏
+ * @csspart branch-trigger - 展开/收起按钮（aria-expanded / aria-controls）；落在选中路径上输出 data-in-path
+ * @csspart branch-text - 行文字载体，折叠成图标栏时裁到看不见但仍参与播报，是按钮在图标栏里的可及名
  * @csspart branch-indicator - 展开方向指示符（aria-hidden）
+ * @csspart positioner - 折叠态弹出面板的定位层，坐标写在它身上；平铺态不用渲染
  * @csspart branch-content - 内嵌子层容器，收起时隐藏
- * @csspart link - 去处链接，须自带 value 属性；选中输出 aria-current="page"
- * @csspart link-text - 链接文字载体，折叠成图标栏时隐藏
+ * @csspart link - 去处链接，须自带 value 属性；选中输出 aria-current="page" 与 data-current
+ * @csspart link-text - 链接文字载体，折叠成图标栏时裁到看不见但仍参与播报，是链接在图标栏里的可及名
  */
 declare class XhSideNavElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "list" | "link" | "group" | "group-label" | "branch" | "branch-trigger" | "branch-text" | "branch-indicator" | "branch-content" | "link-text">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "list" | "link" | "positioner" | "group" | "group-label" | "branch" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content" | "link-text">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5182,41 +6887,142 @@ declare class XhSideNavElement extends XhElement {
     expandedValue: {
       attribute: boolean;
     };
-    defaultExpandedValue: {
+    defaultExpandedValue: {
+      attribute: boolean;
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  value?: string;
+  defaultValue?: string;
+  accordion?: boolean;
+  collapsed?: boolean;
+  collapsedPopout?: boolean;
+  disabled?: boolean;
+  loop?: boolean;
+  direction?: SideNavSchema['props']['dir'];
+  /** 入口树，href/禁用/层级的唯一事实源，须与标记同源。 */
+  collection?: SideNavNode[];
+  expandedValue?: string[];
+  defaultExpandedValue?: string[];
+  translations?: Partial<SideNavTranslations>;
+  private readonly notifyValue;
+  private readonly notifyExpanded;
+  private readonly idGen;
+  private readonly navScope;
+  private readonly positionEngine;
+  private config;
+  /** 每个弹出面板的定位层一份退场闸门：退场动画播完才真收。 */
+  private readonly exits;
+  private readonly ctrl;
+  private machineProps;
+  private ensureConfig;
+  /** 当前弹出分支名下的角色节点：按归属分支的 value 现查。 */
+  private findPopoutPart;
+  private readonly registerLayer;
+  private injectRefs;
+  private nodeOf;
+  disconnectedCallback(): void;
+  protected wire(): void;
+}
+//#endregion
+//#region src/elements/signature-pad.d.ts
+/**
+ * `<xh-signature-pad>` —— Light-DOM 行为宿主：作者写 root / control / segment 三个必需角色节点
+ * （可再写 label、guide、clear-trigger 与 hidden-input），元素跑 signature-pad 机器并把 connect 产出打上去。
+ *
+ * control 必须是 `<svg>`，guide 是它里面的 `<line>`、segment 是它里面的 `<path>`：
+ * 笔迹是一条填充轮廓，粗细随压感变，描边给不出这个效果。viewBox 由元素按第一笔落下时
+ * 量到的画布尺寸写上去，作者不要自己写。
+ *
+ * 画布本身不接键盘。签名天然依赖指针，要求签名的流程必须另给一条不依赖指针的替代路径。
+ *
+ * 笔迹外形（drawing）与读屏文案（translations）是对象，只走 property。
+ * 清空与取 SVG 另有 `clear()` / `toSvg()` 两个方法。
+ *
+ * @customElement xh-signature-pad
+ * @attr {boolean} disabled - 整块不可交互：落笔不认，清空按钮也按不动
+ * @attr {boolean} read-only - 只读：画好的签名照常显示，但改不动
+ * @attr {boolean} required - 必填标注；表单影子据此参与原生校验
+ * @attr {boolean} invalid - 校验未通过的标记，只改外观与表单影子上的 aria-invalid
+ * @attr {string} name - 表单字段名；给了表单影子才带 name 并参与提交
+ * @fires draw - 笔迹变了就通知一次（含清空与表单重置）；detail 为 `{ paths: string[], path: string }`
+ * @fires draw-end - 签名定稿时通知一次（抬笔、清空、表单重置）；detail 为 `{ paths: string[], svg: string }`，svg 可直接落库
+ * @csspart root - 承载 data-disabled / data-readonly / data-invalid / data-empty / data-drawing 的外壳
+ * @csspart label - 画布标题（aria-labelledby 目标）
+ * @csspart control - role=img 的画布，必须是 `<svg>`，指针落笔全在它身上
+ * @csspart guide - 基准线，必须是 control 里的 `<line>`；落位由连接层按百分比给出
+ * @csspart segment - 全部笔迹，必须是 control 里的 `<path>`；每一笔是它的一条子路径
+ * @csspart clear-trigger - 清空按钮，必须是原生 `<button>`
+ * @csspart status - 签没签的活区域（role=status）；节点里没写字时由元素填内建文案
+ * @csspart hidden-input - 表单影子输入（必须是原生 input），提交的是一份独立 SVG 文档
+ */
+declare class XhSignaturePadElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "clear-trigger" | "hidden-input" | "segment" | "guide" | "status">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    readOnly: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    required: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    invalid: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    drawing: {
       attribute: boolean;
     };
     translations: {
       attribute: boolean;
     };
   };
-  value?: string;
-  defaultValue?: string;
-  accordion?: boolean;
-  collapsed?: boolean;
-  collapsedPopout?: boolean;
   disabled?: boolean;
-  loop?: boolean;
-  direction?: SideNavSchema['props']['dir'];
-  /** 入口树，href/禁用/层级的唯一事实源，须与标记同源。 */
-  collection?: SideNavNode[];
-  expandedValue?: string[];
-  defaultExpandedValue?: string[];
-  translations?: Partial<SideNavTranslations>;
-  private readonly notifyValue;
-  private readonly notifyExpanded;
-  private readonly idGen;
-  private readonly navScope;
-  private readonly positionEngine;
-  private config;
+  readOnly?: boolean;
+  required?: boolean;
+  invalid?: boolean;
+  name?: string;
+  drawing?: SignaturePadDrawingOptions;
+  translations?: Partial<SignaturePadTranslations>;
+  private readonly notifyDraw;
+  private readonly notifyDrawEnd;
   private readonly ctrl;
   private machineProps;
-  private ensureConfig;
-  /** 当前弹出分支名下的角色节点：按归属分支的 value 现查。 */
-  private findPopoutPart;
-  private readonly registerLayer;
   private injectRefs;
-  private nodeOf;
-  disconnectedCallback(): void;
+  /** 命令式入口共用的取法；机器要到进文档（hostConnected）才建，未建则抛。 */
+  private commands;
+  /** 抹掉全部笔迹，与点清空按钮同一条路径（照样发 draw / draw-end）。 */
+  clear(): void;
+  /** 当前签名的独立 SVG 文档，与表单影子提交的是同一份；空签名为空串。 */
+  toSvg(): string;
+  /** 一笔都没画。提交前拦空签名读它。 */
+  get empty(): boolean;
+  /**
+   * 状态文本是否归元素填：节点非空即判为作者自己写了内容。
+   * 首次见到时定死，之后不再回读——回读分不出内容是作者写的还是上一帧自己写的。
+   */
+  private readonly ownsText;
+  private fillText;
   protected wire(): void;
 }
 //#endregion
@@ -5292,14 +7098,14 @@ declare class XhSkeletonElement extends XhElement {
  * @csspart track - 轨道本体，值与坐标的换算以它的矩形为准
  * @csspart range - 已选区间，起止由内联逻辑属性给出
  * @csspart marks - 刻度容器
- * @csspart mark - 刻度点（纯装饰），须自带 value 属性；落进已选区间带 data-active
+ * @csspart mark - 刻度点（纯装饰），须自带 value 属性；落进已选区间带 data-passed
  * @csspart mark-label - 刻度文案，须自带 value 属性；点按把最近的滑块跳到这一档
  * @csspart thumb - role=slider 的拇指，键盘交互全在它身上；多滑块须写 index 属性
  * @csspart hidden-input - 拇指内的表单影子（须是原生 input）
  */
 declare class XhSliderElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "track" | "range" | "thumb" | "mark" | "marks" | "mark-label">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "hidden-input" | "track" | "range" | "thumb" | "mark" | "marks" | "mark-label">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5431,6 +7237,75 @@ declare class XhSliderElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/space.d.ts
+/**
+ * `<xh-space>` —— Light-DOM 行为宿主，无状态机，把 connectSpace 产出打到 root 角色节点。
+ * 排布参数原样落成 data-*，排布规则写在皮肤里。
+ *
+ * 方向与间距恒有值：不写也留 md 间距，这是本组件与 `<xh-flex>` 的分野。
+ *
+ * 分隔符是一个角色节点：作者把它写在 root 里、夹在两个子项中间，元素替它打上 aria-hidden。
+ * 本元素不生成任何结构，也就没法替作者复制节点；Vue 版的 split 插槽是同一件事的另一种写法，
+ * 铺开后的 DOM 形状一致。
+ *
+ * 根上不写 role：容器只做排布，里面装的是列表还是一组按钮由作者自己声明。
+ *
+ * @customElement xh-space
+ * @attr {'horizontal'|'vertical'} direction - 排布方向，缺省 horizontal
+ * @attr {'xs'|'sm'|'md'|'lg'|'xl'} gap - 子项间距档位，缺省 md，逐档对应一个间距令牌
+ * @attr {'start'|'center'|'end'|'stretch'|'baseline'} align - 交叉轴对齐
+ * @attr {'start'|'center'|'end'|'between'|'around'|'evenly'} justify - 主轴分布
+ * @attr {boolean} wrap - 一行放不下时折行
+ * @attr {boolean} inline - 容器按行内盒排版，宽度收到内容
+ * @csspart root - 排布容器，承载 data-orientation / data-gap / data-align / data-justify / data-wrap / data-inline
+ * @csspart split - 夹在两个子项之间的分隔符，作者逐个写在 root 里；元素替它打上 aria-hidden
+ */
+declare class XhSpaceElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "split">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    gap: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    align: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    justify: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    wrap: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    inline: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+  };
+  direction?: SpaceProps['direction'];
+  gap?: SpaceProps['gap'];
+  align?: SpaceProps['align'];
+  justify?: SpaceProps['justify'];
+  wrap?: boolean;
+  inline?: boolean;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/spinner.d.ts
 /**
  * `<xh-spinner>` —— 加载指示器宿主，无状态机，把活区语义与可及名字打到角色节点上。
@@ -5508,7 +7383,7 @@ declare class XhSpinnerElement extends XhElement {
  */
 declare class XhSplitterElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "panel" | "resize-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "resize-trigger" | "panel">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5615,7 +7490,7 @@ declare class XhSplitterElement extends XhElement {
  */
 declare class XhStepsElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "content" | "title" | "description" | "list" | "separator">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "title" | "description" | "list" | "separator">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5703,6 +7578,9 @@ declare class XhStepsElement extends XhElement {
  * @attr {boolean} checked - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-checked - 非受控初始为选中
  * @attr {boolean} disabled - 禁用
+ * @attr {boolean} read-only - 只读：拨不动，但仍可聚焦、仍参与提交
+ * @attr {boolean} invalid - 校验失败态
+ * @attr {boolean} required - 必填
  * @attr {boolean} loading - 提交中：交互挂起、滑块转圈，仍可聚焦（aria-busy）
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
@@ -5711,10 +7589,12 @@ declare class XhStepsElement extends XhElement {
  * @csspart thumb - 滑块
  * @attr {string} name - 表单字段名；给了 hidden-input 才参与提交
  * @csspart hidden-input - type=hidden 的表单出口，省略该节点即不参与表单
+ * @csspart label - 可选：包住 root 与 text 的 <label>，点文字即切换
+ * @csspart text - 可选：控件旁的文字
  */
 declare class XhSwitchElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "hidden-input" | "thumb">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "text" | "hidden-input" | "thumb">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5730,6 +7610,16 @@ declare class XhSwitchElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    readOnly: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    invalid: {
+      type: BooleanConstructor;
+    };
+    required: {
+      type: BooleanConstructor;
+    };
     loading: {
       type: BooleanConstructor;
     };
@@ -5749,6 +7639,9 @@ declare class XhSwitchElement extends XhElement {
   checked?: boolean;
   defaultChecked?: boolean;
   disabled?: boolean;
+  readOnly?: boolean;
+  invalid?: boolean;
+  required?: boolean;
   loading?: boolean;
   name?: string;
   value?: string;
@@ -5778,7 +7671,10 @@ declare class XhSwitchElement extends XhElement {
  * @attr {'none'|'single'|'multiple'} selection-mode - 选择模式，默认 none（不声明就没有选择这回事）
  * @attr {boolean} loading - 数据在路上：root 报 aria-busy，表体为空时加载态节点显形
  * @attr {boolean} empty - 显式声明表体为空；缺省按 rows 是否为空推导，写 empty="false" 强制不空
- * @attr {boolean} sticky-header - 表头吸顶，只落 data-sticky，钉住的实现归皮肤
+ * @attr {boolean} sticky-header - 表头吸顶，只落 data-sticky（布尔）；列冻结另走 data-frozen
+ * @attr {boolean} striped - 斑马纹：表体偶数行换一层浅底
+ * @attr {boolean} borderless - 去掉外框，只留行间横线
+ * @attr {boolean} ruled - 列与列之间加竖分隔线
  * @attr {boolean} footer - 表格带脚注行：行号空间的最后一行留给它，aria-rowcount 也算上
  * @attr {boolean} loop - 上下键走到首尾回绕，默认关；写 loop="true" 打开
  * @attr {'ltr'|'rtl'} dir - 文字方向，只对调左右方向键的展开/收起语义，默认 ltr
@@ -5804,7 +7700,7 @@ declare class XhSwitchElement extends XhElement {
  */
 declare class XhTableElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "cell" | "empty" | "expand-trigger" | "body" | "footer" | "select-all-trigger" | "row" | "column-header" | "caption" | "row-select-trigger" | "sort-trigger" | "expanded-row" | "loading-state">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "cell" | "empty" | "expand-trigger" | "body" | "row" | "footer" | "select-all-trigger" | "column-header" | "caption" | "row-select-trigger" | "sort-trigger" | "expanded-row" | "loading-state">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5850,6 +7746,15 @@ declare class XhTableElement extends XhElement {
       type: BooleanConstructor;
       attribute: string;
     };
+    striped: {
+      type: BooleanConstructor;
+    };
+    borderless: {
+      type: BooleanConstructor;
+    };
+    ruled: {
+      type: BooleanConstructor;
+    };
     footer: {
       type: BooleanConstructor;
     };
@@ -5882,6 +7787,9 @@ declare class XhTableElement extends XhElement {
   loading?: boolean;
   empty?: boolean;
   stickyHeader?: boolean;
+  striped?: boolean;
+  borderless?: boolean;
+  ruled?: boolean;
   footer?: boolean;
   loop?: boolean;
   direction?: Direction;
@@ -5928,7 +7836,7 @@ declare class XhTableElement extends XhElement {
  */
 declare class XhTabsElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "trigger" | "content" | "list">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "list">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6004,6 +7912,85 @@ declare class XhTabsElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/tag.d.ts
+/**
+ * `<xh-tag>` —— Light-DOM 行为宿主：作者写 root、label、close-trigger 角色节点，
+ * 元素跑 tag 机器并把 connect 产出打上去。关闭钮须是原生 `<button>`
+ * （Enter/Space 的激活由平台负责），收起时用内联 style.display 隐藏 root。
+ *
+ * @customElement xh-tag
+ * @attr {'solid'|'subtle'|'outline'} variant - 形态，决定颜色怎么用
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气，决定用哪族颜色
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @attr {boolean} closable - 是否给出关闭钮，缺省为假；为假时该钮同时被禁用与收起
+ * @attr {boolean} disabled - 标签禁用，关闭钮留在原地但按不动
+ * @attr {boolean} open - 受控显隐；缺省该属性即非受控
+ * @attr {boolean} default-open - 非受控初始显隐，缺省为显示
+ * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
+ * @csspart root - 标签根容器
+ * @csspart label - 标签文字
+ * @csspart close-trigger - 关闭钮，须是原生 `<button>`
+ */
+declare class XhTagElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "close-trigger" | "label">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    variant: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    closable: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    open: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    defaultOpen: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  variant?: TagVariant;
+  tone?: Tone;
+  size?: Size;
+  closable?: boolean;
+  disabled?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  translations?: TagSchema['props']['translations'];
+  private readonly notify;
+  private readonly ctrl;
+  private machineProps;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/tags-input.d.ts
 /**
  * `<xh-tags-input>` —— Light-DOM 行为宿主：作者写 root/label/control/input/item 一族与
@@ -6045,12 +8032,12 @@ declare class XhTabsElement extends XhElement {
  * @csspart item-text - 标签文本
  * @csspart item-delete-trigger - 删除按钮，须是原生 `<button>`；不占 Tab 位，自带 aria-label
  * @csspart item-input - 就地编辑框，须是原生 `<input>`；不编辑时收起
- * @csspart clear-trigger - 清空按钮；没东西可清时置灰
+ * @csspart clear-trigger - 清空按钮；没东西可清时收起（hidden）
  * @csspart hidden-input - type=hidden 的表单出口，值是按 delimiter 拼好的整串
  */
 declare class XhTagsInputElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "item-text" | "input" | "clear-trigger" | "hidden-input" | "control" | "item-preview" | "item-delete-trigger" | "item-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "control" | "clear-trigger" | "item-text" | "input" | "hidden-input" | "item-delete-trigger" | "item-preview" | "item-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6201,6 +8188,7 @@ declare class XhTagsInputElement extends XhElement {
  * @customElement xh-text-field
  * @attr {string} value - 受控值；缺省该属性即非受控
  * @attr {string} default-value - 非受控初值
+ * @attr {'text'|'password'|'email'|'tel'|'url'|'search'} type - 单行输入类型，缺省 text；宿主写成 textarea 时该属性不发
  * @attr {string} placeholder - 占位文案
  * @attr {boolean} disabled - 禁用：不可聚焦、写不进
  * @attr {boolean} read-only - 只读：仍可聚焦与复制，写不进
@@ -6208,20 +8196,22 @@ declare class XhTagsInputElement extends XhElement {
  * @attr {boolean} invalid - 校验失败标注
  * @attr {string} name - 表单字段名；给了才参与提交
  * @attr {number} max-length - 字符数上限；同时落成原生 maxlength 与机器侧截断
- * @attr {boolean} clearable - 开启清空：清空按钮显出并在有值时可用，Escape 接管
+ * @attr {boolean} clearable - 开启清空：有值时清空按钮显出，Escape 接管
  * @attr {boolean} auto-size - 多行宿主（input 部件写成 textarea）的自动高度；行数界限对象经 autoSize property 赋
  * @attr {'outline'|'subtle'|'ghost'} variant - 视觉变体
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @prop {object} translations - 读屏文案（只走 property）：clearTrigger 是清空按钮的名字
  * @fires value-change - 值变化；detail 为 `{ value: string }`
  * @csspart root - 承载 data-disabled / data-readonly / data-invalid / data-empty / data-at-limit 的容器
+ * @csspart control - 视觉盒；写了它就由它画描边、底色与聚焦环，输入框与清空按钮排在它里面
  * @csspart label - 标题；`for` 恒写向 input，故须是原生 `<label>` 才点得动
  * @csspart input - 真正的输入框，须是原生 `<input>`；键盘交互全在它身上
- * @csspart clear-trigger - 清空按钮；未开 clearable 时收起，无值或不可编辑时置灰
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，名字取 translations.clearTrigger；清不了时收起
  */
 declare class XhTextFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "input" | "clear-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "clear-trigger" | "input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6236,6 +8226,11 @@ declare class XhTextFieldElement extends XhElement {
       };
       attribute: string;
     };
+    type: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     placeholder: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -6299,9 +8294,13 @@ declare class XhTextFieldElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
   };
   value?: string;
   defaultValue?: string;
+  type?: TextFieldType;
   placeholder?: string;
   disabled?: boolean;
   readOnly?: boolean;
@@ -6315,6 +8314,7 @@ declare class XhTextFieldElement extends XhElement {
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
+  translations?: TextFieldSchema['props']['translations'];
   private readonly notify;
   private readonly ctrl;
   private machineProps;
@@ -6338,7 +8338,7 @@ declare class XhTextFieldElement extends XhElement {
  */
 declare class XhThreadElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "viewport" | "scroll-button" | "live-region">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "viewport" | "content" | "scroll-button" | "live-region">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6374,7 +8374,7 @@ declare class XhThreadElement extends XhElement {
 //#endregion
 //#region src/elements/time-field.d.ts
 /**
- * `<xh-time-field>` —— Light-DOM 行为宿主：作者写 root/label/control/segment（多个）/hidden-input
+ * `<xh-time-field>` —— Light-DOM 行为宿主：作者写 root/label/control/segment（多个）/clear-trigger/hidden-input
  * 角色节点，元素跑 time-field 机器并把 connect 产出打上去。
  *
  * 每一段是一个 role=spinbutton 的展示节点：上下键加减、左右键换段、数字直输并自动跳段、
@@ -6404,12 +8404,14 @@ declare class XhThreadElement extends XhElement {
  * @csspart root - 承载 data-disabled / data-readonly / data-invalid / data-empty / data-out-of-range 的容器
  * @csspart label - 标题；点它会把焦点送到第一段
  * @csspart control - role=group 的段容器，由 label 命名
+ * @csspart segment-group - 段位与分隔符的外壳，占满盒里剩下的宽度
  * @csspart segment - 一段一个的 spinbutton，可自带 segment 属性声明身份，缺省按文档序
+ * @csspart clear-trigger - 一键清空全部段的按钮；没值或改不动时收起，不占 Tab 位，点完焦点回到第一段
  * @csspart hidden-input - type=hidden 的表单出口，值是完整 ISO 串
  */
 declare class XhTimeFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "segment">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "clear-trigger" | "hidden-input" | "segment-group" | "segment">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6466,6 +8468,9 @@ declare class XhTimeFieldElement extends XhElement {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
     required: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -6507,6 +8512,7 @@ declare class XhTimeFieldElement extends XhElement {
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
+  translations?: TimeFieldSchema['props']['translations'];
   required?: boolean;
   name?: string;
   placeholder?: string;
@@ -6549,11 +8555,15 @@ declare class XhTimeFieldElement extends XhElement {
  * @attr {'12'|'24'} hour-cycle - 小时制；不写则按 locale 推断，再没有就用 24
  * @attr {'hour'|'minute'|'second'} granularity - 值精确到哪一段，默认 minute
  * @attr {number} step - 分列的步进（分钟），默认 1
+ * @prop {TimePickerPreset[]} presets - 快捷选项（数组只走 property）：给了就在浮层里多出一列
  * @attr {boolean} disabled - 禁用：段整组退出 Tab 序列，触发器用原生 disabled，隐藏输入不参与提交
  * @attr {boolean} read-only - 只读：浮层照常展开与浏览，但值改不动也清不掉
  * @attr {boolean} invalid - 校验失败标注
  * @attr {boolean} required - 必填标注，落到每段的 aria-required 上
  * @attr {string} name - 表单字段名；给了隐藏输入才带 name
+ * @attr {'outline'|'subtle'|'ghost'} variant - 视觉变体
+ * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
  * @attr {string} placement - 首选放置位，默认 bottom-start；避让后的实际位写在 data-placement 上
  * @attr {number} offset - 浮层与锚点的间距（px）
  * @fires value-change - 值变化；detail 为 `{ value: string }`
@@ -6561,18 +8571,21 @@ declare class XhTimeFieldElement extends XhElement {
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly/data-invalid/data-empty）
  * @csspart label - 标题；点它会把焦点送到第一段
  * @csspart control - role=group 的输入行，同时是浮层的定位锚点
+ * @csspart segment-group - 段位与分隔符的外壳，占满盒里剩下的宽度
  * @csspart input - 一段一个的 spinbutton，可自带 segment 属性声明身份，缺省按文档序
  * @csspart trigger - 展开/收起按钮，须是原生 button
- * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，可及名走 translations.clearTrigger；没值即收起
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - 浮层容器（消解层与焦点域的根节点），收起时带 hidden
+ * @csspart presets - 快捷选项列（role=listbox）；没给 presets 时带 hidden
+ * @csspart preset - 一条快捷选项（role=option），须自带 value 属性（与 presets 数据里的 value 逐字对上）
  * @csspart column - role=listbox 的一列，可自带 unit 属性声明单位，缺省按文档序
- * @csspart item - role=option 的一格，须自带 value 属性（两位补零的显示串）
+ * @csspart item - role=option 的一格，须自带 value 属性（两位补零的显示串；上下午列写 '00' / '01'）
  * @csspart hidden-input - type=hidden 的表单出口，值是完整 ISO 串
  */
 declare class XhTimePickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "content" | "label" | "positioner" | "input" | "clear-trigger" | "column" | "hidden-input" | "control">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "label" | "control" | "positioner" | "clear-trigger" | "input" | "column" | "hidden-input" | "segment-group" | "preset" | "presets">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6627,6 +8640,9 @@ declare class XhTimePickerElement extends XhElement {
         fromAttribute: (v: string | null) => number | undefined;
       };
     };
+    presets: {
+      attribute: boolean;
+    };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -6643,6 +8659,12 @@ declare class XhTimePickerElement extends XhElement {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
+    isTimeUnavailable: {
+      attribute: boolean;
+    };
     required: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -6653,6 +8675,21 @@ declare class XhTimePickerElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    variant: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    tone: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     placement: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -6674,17 +8711,25 @@ declare class XhTimePickerElement extends XhElement {
   hourCycle?: TimeHourCycle;
   granularity?: TimeGranularity;
   step?: number;
+  presets?: TimePickerPreset[];
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
+  translations?: TimePickerSchema['props']['translations'];
+  isTimeUnavailable?: TimePickerSchema['props']['isTimeUnavailable'];
   required?: boolean;
   name?: string;
+  variant?: ControlVariant;
+  tone?: Tone;
+  size?: Size;
   placement?: Placement;
   offset?: number;
   private readonly idGen;
   private readonly pickerScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   private readonly notifyValue;
   private readonly notifyOpen;
   private readonly ctrl;
@@ -6702,6 +8747,100 @@ declare class XhTimePickerElement extends XhElement {
   disconnectedCallback(): void;
 }
 //#endregion
+//#region src/elements/timer.d.ts
+/**
+ * `<xh-timer>` —— Light-DOM 行为宿主：作者写 root、area、若干 item 与 separator，
+ * 需要起停就再写一个 control。元素跑 timer 机器，把 connect 产出打到角色节点上，
+ * 并把每一段的数字写进对应的 item。
+ *
+ * 时间只从单调时钟的两个时刻相减而来，一拍都不累加；`interval` 只决定数字多久跳一次，
+ * 到点另有一个精确落在终点上的定时器判定，终点不落在整拍上也不会走过头。
+ *
+ * 每个 item 用 `unit` 属性声明自己是哪一段（days / hours / minutes / seconds / milliseconds）。
+ * 它是作者的声明、不是机器写回的状态，改它本身不会另排一次接线——停着时改完要等下一次
+ * 属性变更或起跑才生效。
+ *
+ * control 里的文字归作者写（多半是个图标），元素只按当前状态换它的 `data-action` 与读屏名字。
+ *
+ * @customElement xh-timer
+ * @attr {number} start-ms - 起始值毫秒，缺省 0；正着走从它往上，倒着走从它往下
+ * @attr {number} target-ms - 终点值毫秒；倒计时缺省 0，正计时不写即没有终点
+ * @attr {boolean} countdown - 倒着走，缺省关闭
+ * @attr {boolean} auto-start - 挂载即开跑，缺省关闭；只在挂载那一刻读一次
+ * @attr {number} interval - 刷新间隔毫秒，缺省 1000，下限一帧
+ * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @fires tick - 走过一拍；detail 为 `{ value: number, elapsed: number }`
+ * @fires complete - 走到终点；detail 为 `{ value: number, elapsed: number }`
+ * @csspart root - 组件根容器（承载 data-state / data-size / data-countdown）
+ * @csspart area - 时间区，role=timer 并带着整段时间的读屏名字
+ * @csspart item - 一段数字，须自带 unit 属性说明它是哪一段；文字归元素写
+ * @csspart separator - 段与段之间的记号，对读屏隐藏
+ * @csspart control - 起停按钮，须是原生 `<button>`；按当前状态换 data-action
+ */
+declare class XhTimerElement extends XhElement {
+  static partContract: {
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "separator" | "control" | "area">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    startMs: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    targetMs: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    countdown: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    autoStart: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    interval: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    size: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  startMs?: number;
+  targetMs?: number;
+  countdown?: boolean;
+  autoStart?: boolean;
+  interval?: number;
+  size?: Size;
+  translations?: TimerSchema['props']['translations'];
+  private readonly notifyTick;
+  private readonly notifyComplete;
+  private readonly ctrl;
+  private machineProps;
+  /** 没进 DOM 时机器还没起来，此刻谈不上起停，送过去只会被丢弃并在开发期报一声。 */
+  private run;
+  /** 起停四个动作也给到元素上，作者不必自己去点那个按钮。 */
+  start(): void;
+  pause(): void;
+  resume(): void;
+  reset(): void;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/toast.d.ts
 /**
  * `<xh-toast>` —— Light-DOM 行为宿主：作者写 root/title/description/action-trigger/close-trigger
@@ -7185,9 +9324,11 @@ declare class XhToolbarElement extends XhElement {
  */
 declare class XhTooltipElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"trigger" | "content" | "positioner" | "arrow">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"content" | "trigger" | "positioner" | "arrow">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   static properties: {
     open: {
       converter: {
@@ -7244,9 +9385,13 @@ declare class XhTooltipElement extends XhElement {
   tone?: Tone;
   size?: Size;
   private engine;
+  /** 消解层与退场闸门共用一份环境包。 */
+  private config;
   private readonly notify;
   private readonly ctrl;
   private machineProps;
+  private ensureConfig;
+  private readonly registerLayer;
   private injectRefs;
   /**
    * 机器在 hostConnected 就挂载，初始即展开（open / default-open）时定位效应当场执行；
@@ -7255,6 +9400,7 @@ declare class XhTooltipElement extends XhElement {
    */
   connectedCallback(): void;
   protected wire(): void;
+  disconnectedCallback(): void;
 }
 //#endregion
 //#region src/elements/tour.d.ts
@@ -7387,6 +9533,8 @@ declare class XhTourElement extends XhElement {
   private config;
   private contentNode;
   private backdropNode;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，气泡的退场动画播完才真收。 */
+  private exit;
   /** 哪些文本节点归元素填：作者自己写了内容的一概不碰。 */
   private readonly ownsText;
   private readonly emit;
@@ -7434,7 +9582,7 @@ declare class XhTourElement extends XhElement {
  * 导航与勾选在事件那一刻按 data-scope+data-part 查活 DOM，依赖 connect 回写的 data-value，
  * 因此 wire 必须先于交互跑过（基类 updated 已保证）。
  *
- * 集合类输入（collection / value / selected / filter）都表达不成属性，只能走 property：
+ * 集合类输入（collection / value / selection / filter）都表达不成属性，只能走 property：
  * `el.collection = [...]`、`el.value = ['a']`。
  *
  * @customElement xh-transfer
@@ -7444,7 +9592,7 @@ declare class XhTourElement extends XhElement {
  * @attr {boolean} loop - 列表内方向键走到尽头回绕，默认 true；写 loop="false" 关掉
  * @attr {'ltr'|'rtl'} dir - 文字方向，决定列表内哪个横向方向键是"搬向对面"，默认 ltr
  * @fires value-change - 落在右侧的值变化；detail 为 `{ value: string[] }`
- * @fires selection-change - 勾选集合变化；detail 为 `{ selected: string[] }`
+ * @fires selection-change - 勾选集合变化；detail 为 `{ value: string[] }`
  * @csspart root - 组件根容器（承载 data-disabled/data-one-way）
  * @csspart source-panel - 左侧面板容器，其内的角色节点一律归左侧
  * @csspart target-panel - 右侧面板容器，其内的角色节点一律归右侧
@@ -7462,7 +9610,7 @@ declare class XhTourElement extends XhElement {
  */
 declare class XhTransferElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "list" | "item-text" | "select-all-trigger" | "source-panel" | "target-panel" | "panel-header" | "panel-title" | "panel-count" | "search" | "item-checkbox" | "to-target-trigger" | "to-source-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "list" | "item-text" | "select-all-trigger" | "item-checkbox" | "source-panel" | "target-panel" | "panel-header" | "panel-title" | "panel-count" | "search" | "to-target-trigger" | "to-source-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -7475,10 +9623,10 @@ declare class XhTransferElement extends XhElement {
     defaultValue: {
       attribute: boolean;
     };
-    selected: {
+    selection: {
       attribute: boolean;
     };
-    defaultSelected: {
+    defaultSelection: {
       attribute: boolean;
     };
     filter: {
@@ -7509,8 +9657,8 @@ declare class XhTransferElement extends XhElement {
   collection?: TransferItem[];
   value?: string[];
   defaultValue?: string[];
-  selected?: string[];
-  defaultSelected?: string[];
+  selection?: string[];
+  defaultSelection?: string[];
   filter?: TransferFilter;
   searchable?: boolean;
   disabled?: boolean;
@@ -7518,7 +9666,7 @@ declare class XhTransferElement extends XhElement {
   loop?: boolean;
   direction?: Direction;
   private readonly notifyValue;
-  private readonly notifySelected;
+  private readonly notifySelection;
   private readonly ctrl;
   private machineProps;
   /**
@@ -7558,8 +9706,10 @@ declare class XhTransferElement extends XhElement {
  * @csspart tree - role=tree 容器，键盘在此收口，也是 roving tabindex 的兜底位
  * @csspart item - role=treeitem 叶子，须自带 value 属性标识身份
  * @csspart item-text - 叶子文本
+ * @csspart item-checkbox - 叶子的勾选把手，点它只勾选、不触发点行；可选
  * @csspart item-indicator - 叶子选中标记（aria-hidden）
  * @csspart branch - role=treeitem 分支，须自带 value 属性；它裹着自己的 branch-content
+ * @csspart branch-checkbox - 分支的勾选把手，点它只勾选、不展开这一枝；可选
  * @csspart branch-control - 分支可点行（选中 + 按 expand-on-click 切换展开）
  * @csspart branch-trigger - 展开箭头（aria-hidden 且不占 Tab 位，只切换展开态）
  * @csspart branch-indicator - 展开方向指示符（aria-hidden）
@@ -7568,7 +9718,7 @@ declare class XhTransferElement extends XhElement {
  */
 declare class XhTreeElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "item-text" | "item-indicator" | "branch" | "branch-trigger" | "branch-text" | "branch-indicator" | "branch-content" | "tree" | "branch-control">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "item-text" | "item-indicator" | "tree" | "branch" | "branch-control" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content" | "item-checkbox" | "branch-checkbox">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -7581,10 +9731,10 @@ declare class XhTreeElement extends XhElement {
     defaultExpandedValue: {
       attribute: boolean;
     };
-    selectedValue: {
+    selection: {
       attribute: boolean;
     };
-    defaultSelectedValue: {
+    defaultSelection: {
       attribute: boolean;
     };
     selectionMode: {
@@ -7631,8 +9781,8 @@ declare class XhTreeElement extends XhElement {
   collection?: TreeNode[];
   expandedValue?: string[];
   defaultExpandedValue?: string[];
-  selectedValue?: string[];
-  defaultSelectedValue?: string[];
+  selection?: string[];
+  defaultSelection?: string[];
   selectionMode?: TreeSelectionMode;
   cascade?: boolean;
   checkedStrategy?: TreeSchema['props']['checkedStrategy'];
@@ -7701,10 +9851,11 @@ declare class XhTreeElement extends XhElement {
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly/data-invalid）
  * @csspart label - 标题（aria-labelledby 目标）
+ * @csspart control - 触发按钮与清空按钮的收纳容器：描边、底色与聚焦环都落在这一层
  * @csspart trigger - role=combobox 的触发按钮，同时是定位锚点，须是原生 button
  * @csspart value-text - 选中项文本的显示位；留空即由元素填入 displayText，作者写了内容则归作者
  * @csspart indicator - 展开指示符（aria-hidden，data-state 随开合）
- * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
+ * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位，aria-label 取 translations.clearTrigger，无值时 hidden
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - 浮层壳（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
  * @csspart tree - role=tree 容器，没有锚点时的 Tab 兜底位与落焦点
@@ -7721,7 +9872,7 @@ declare class XhTreeElement extends XhElement {
  */
 declare class XhTreeSelectElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "item" | "trigger" | "content" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "hidden-input" | "branch" | "branch-trigger" | "branch-text" | "branch-indicator" | "branch-content" | "tree" | "branch-control">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "control" | "positioner" | "clear-trigger" | "item-text" | "item-indicator" | "value-text" | "hidden-input" | "tree" | "branch" | "branch-control" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -7858,6 +10009,8 @@ declare class XhTreeSelectElement extends XhElement {
   private readonly treeSelectScope;
   private readonly positionEngine;
   private config;
+  /** 退场闸门：收起从跟着 open 走改成跟着 presence 走，退场动画播完才真收。 */
+  private exit;
   /** value-text 是否归元素填：首次见到该节点时定，之后不再回读（回读到的会是自己写的字）。 */
   private readonly ownsValueText;
   private readonly notifyValue;
@@ -7918,7 +10071,7 @@ declare class XhTreeSelectElement extends XhElement {
  */
 declare class XhVirtualizerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "viewport">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "viewport" | "content">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -8014,5 +10167,5 @@ declare class XhVirtualizerElement extends XhElement {
 //#region src/define.d.ts
 declare function defineXhElements(): void;
 //#endregion
-export { XhAccordionElement, XhAlertElement, XhAnchorElement, XhAvatarElement, XhBadgeElement, XhBreadcrumbElement, XhButtonElement, XhCalendarElement, XhCarouselElement, XhCascaderElement, XhCheckboxElement, XhCheckboxGroupElement, XhClipboardElement, XhCodeBlockElement, XhCollapsibleElement, XhColorPickerElement, XhComboboxElement, XhComposerElement, XhContextMenuElement, XhDateFieldElement, XhDatePickerElement, XhDialogElement, XhDrawerElement, XhEditableElement, XhEmptyStateElement, XhFieldElement, XhFileUploadElement, XhFormElement, XhHoverCardElement, XhIconElement, XhImageElement, XhImageViewerElement, XhListboxElement, XhLoadingBarElement, XhMenuElement, XhMenubarElement, XhNavigationMenuElement, XhNumberFieldElement, XhPaginationElement, XhPinInputElement, XhPopoverElement, XhProgressElement, XhRadioGroupElement, XhRatingElement, XhScrollAreaElement, XhSelectElement, XhSeparatorElement, XhSideNavElement, XhSkeletonElement, XhSliderElement, XhSpinnerElement, XhSplitterElement, XhStepsElement, XhSwitchElement, XhTableElement, XhTabsElement, XhTagsInputElement, XhTextFieldElement, XhThreadElement, XhTimeFieldElement, XhTimePickerElement, XhToastElement, XhToasterElement, XhToggleElement, XhToggleGroupElement, XhToolbarElement, XhTooltipElement, XhTourElement, XhTransferElement, XhTreeElement, XhTreeSelectElement, XhVirtualizerElement, defineXhElements };
+export { XhAccordionElement, XhAlertElement, XhAnchorElement, XhAvatarElement, XhBadgeElement, XhBreadcrumbElement, XhButtonElement, XhCalendarElement, XhCarouselElement, XhCascaderElement, XhCheckboxElement, XhCheckboxGroupElement, XhClipboardElement, XhCodeBlockElement, XhCollapsibleElement, XhColorPickerElement, XhComboboxElement, XhComposerElement, XhConfigElement, XhContextMenuElement, XhDateFieldElement, XhDatePickerElement, XhDialogElement, XhDownloadTriggerElement, XhDrawerElement, XhEditableElement, XhEmptyStateElement, XhFieldElement, XhFieldsetElement, XhFileUploadElement, XhFloatingPanelElement, XhFormElement, XhHeatmapElement, XhHotkeysElement, XhHoverCardElement, XhIconElement, XhImageCropperElement, XhImageElement, XhImageViewerElement, XhJsonViewerElement, XhListboxElement, XhLoadingBarElement, XhMasonryElement, XhMenuElement, XhMenubarElement, XhNavigationMenuElement, XhNumberFieldElement, XhPaginationElement, XhPasswordInputElement, XhPinInputElement, XhPopoverElement, XhProgressElement, XhRadioGroupElement, XhRatingElement, XhScrollAreaElement, XhScrollbarElement, XhSegmentedElement, XhSelectElement, XhSeparatorElement, XhSideNavElement, XhSignaturePadElement, XhSkeletonElement, XhSliderElement, XhSpaceElement, XhSpinnerElement, XhSplitterElement, XhStepsElement, XhSwitchElement, XhTableElement, XhTabsElement, XhTagElement, XhTagsInputElement, XhTextFieldElement, XhThreadElement, XhTimeFieldElement, XhTimePickerElement, XhTimerElement, XhToastElement, XhToasterElement, XhToggleElement, XhToggleGroupElement, XhToolbarElement, XhTooltipElement, XhTourElement, XhTransferElement, XhTreeElement, XhTreeSelectElement, XhVirtualizerElement, defineXhElements };
 //# sourceMappingURL=define.d.ts.map