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

package/dist/define.d.ts

@@ -1,7 +1,7 @@
 import { t as XhReactiveElement } from "./element-DRoFjrYO.js";
 import { t as Spreader } from "./spread-Ch8ZXZDC.js";
 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, CascaderValue, CheckboxCheckedState, CheckboxGroupNode, ColorPickerFormat, ColorPickerTranslations, ComboboxInputBehavior, ComboboxNode, ComponentMeta, ComposerRunStatus, ComposerTranslations, ContextMenuNode, DateGranularity, DatePickerSchema, DateSegmentType, DrawerSchema, EditableActivationMode, EditableSubmitMode, EmptyStateLive, FileUploadTranslations, FormErrorPatch, FormSchema, FormValidateOn, FormValues, IconWeight, ListboxNode, ListboxSelectionMode, LoadingBarTranslations, MenuNode, MenubarNode, NavigationMenuNode, NavigationMenuTranslations, PaginationTranslations, PinInputTranslations, PinInputType, PopoverTranslations, RadioGroupNode, ResolvedToast, ScrollAreaOrientation, ScrollAreaType, SelectNode, SkeletonVariant, SliderValueTextDetails, SpinnerTranslations, SplitterPanelProps, TableColumnDef, TableRowDef, TableSelection, TableSelectionMode, TableSortDescriptor, TabsActivationMode, TabsNode, TabsVariant, TagsInputBlurBehavior, ThreadStatus, ThreadTranslations, TimeGranularity, TimeHourCycle, ToastOptions, ToastPlacement, ToastRecord, ToastTranslations, ToastType, ToasterTranslations, ToggleGroupNode, TourStep, TourTranslations, TransferFilter, TransferItem, TreeNode, TreeSelectionMode, VirtualizerAlign, VirtualizerItemState } from "@xihan-ui/headless";
+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 {
@@ -103,7 +103,7 @@ declare abstract class XhElement extends XhReactiveElement {
  */
 declare class XhAccordionElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "header" | "indicator" | "trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "header" | "trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -767,6 +767,9 @@ declare class XhCarouselElement extends XhElement {
  * @attr {'click'|'hover'} expand-trigger - 子列由点还是悬停展开，默认 click
  * @attr {boolean} change-on-select - 中间层（分支）也能落值
  * @attr {boolean} multiple - 多选：选中后浮层不收起，焦点留在列里
+ * @attr {boolean} searchable - 开启搜索：input 部件可用，输入后整条路径连缀过滤、候选替换列视图
+ * @attr {boolean} cascade - 多选下父子级联勾选（整枝传导/半选/禁用冻结），默认 false
+ * @attr {string} checked-strategy - 级联下对外值的收敛策略：child（默认）/ parent / all
  * @attr {boolean} disabled - 整个控件禁用：trigger 用原生 disabled，浮层展不开
  * @attr {boolean} read-only - 只读：浮层照常展开、列照常浏览，但选中值改不动、也清不掉
  * @attr {boolean} invalid - 校验失败标注
@@ -788,7 +791,11 @@ declare class XhCarouselElement extends XhElement {
  * @csspart indicator - 展开指示符（aria-hidden，data-state 随开合）
  * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
- * @csspart content - 浮层壳（焦点域与消解层的根节点），键盘在此收口，收起时带 hidden
+ * @csspart content - 浮层壳（焦点域与消解层的根节点），键盘在此收口，收起时带 hidden；根列没有条目时带 data-empty
+ * @csspart input - 搜索框（content 顶部）；没开 searchable 时带 hidden。上下键走候选、Enter 选中、Escape 先清词
+ * @csspart search-list - 候选列表容器；不在搜索视图时带 hidden，无候选时带 data-empty
+ * @csspart search-item - 一条候选，须用 value 属性写整条路径的 JSON 数组串（如 value='["a","b"]'）；词换了不匹配的带 hidden
+ * @csspart empty - 空态占位：搜索无候选或 collection 为空时露面，其余时候带 hidden。标记里没写就由元素在 content 末尾补一个并填缺省文案；写了就用作者那份，文案也归作者
  * @csspart column - role=listbox 的一列，须自带 level 属性标识它是第几列；砍掉时带 hidden
  * @csspart item - role=option 的条目，须自带 value 属性标识身份；不在当前列里时带 hidden
  * @csspart item-text - 条目文本
@@ -796,7 +803,7 @@ declare class XhCarouselElement extends XhElement {
  */
 declare class XhCascaderElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "column">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "input" | "empty" | "clear-trigger" | "value-text" | "column" | "search-list" | "search-item">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -833,6 +840,18 @@ declare class XhCascaderElement extends XhElement {
     multiple: {
       type: BooleanConstructor;
     };
+    searchable: {
+      type: BooleanConstructor;
+    };
+    cascade: {
+      type: BooleanConstructor;
+    };
+    checkedStrategy: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     disabled: {
       type: BooleanConstructor;
     };
@@ -872,6 +891,9 @@ declare class XhCascaderElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
     placement: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -902,6 +924,9 @@ declare class XhCascaderElement extends XhElement {
   expandTrigger?: CascaderExpandTrigger;
   changeOnSelect?: boolean;
   multiple?: boolean;
+  searchable?: boolean;
+  cascade?: boolean;
+  checkedStrategy?: CascaderSchema['props']['checkedStrategy'];
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
@@ -914,12 +939,15 @@ declare class XhCascaderElement extends XhElement {
   offset?: number;
   loop?: boolean;
   direction?: Direction;
+  translations?: CascaderSchema['props']['translations'];
   private readonly idGen;
   private readonly cascaderScope;
   private readonly positionEngine;
   private config;
   /** value-text 是否归元素填：首次见到该节点时定，之后不再回读（回读到的会是自己写的字）。 */
   private readonly ownsValueText;
+  /** 空态占位的文案是否归元素填，判定同 ownsValueText。 */
+  private readonly ownsEmptyText;
   private readonly notifyValue;
   private readonly notifyOpen;
   private readonly ctrl;
@@ -943,8 +971,13 @@ declare class XhCascaderElement extends XhElement {
   private levelOf;
   /** 摘掉作者写在条目上的原生 disabled，条目禁用一律由 collection 决定并以 aria-disabled 表达。 */
   private stripNativeDisabled;
-  /** 把整条路径的文字填进 value-text；首次见到该节点时若已有内容则判为归作者，之后一概不碰。 */
-  private fillValueText;
+  /** 把文字填进角色节点；首次见到该节点时若已有内容则判为归作者，之后一概不碰。 */
+  private fillOwnedText;
+  /**
+   * 取空态占位；标记里没写就在 content 末尾补一个，位置与 Vue 侧一致。
+   * 作者写了就用作者那份，只接线不新建。补出来的节点下一轮由 discoverParts 收进 partMap。
+   */
+  private ensureEmpty;
   protected wire(): void;
   disconnectedCallback(): void;
 }
@@ -962,10 +995,12 @@ declare class XhCascaderElement extends XhElement {
  * @fires checked-change - checked 状态变化；detail 为 `{ checked: boolean }`
  * @csspart root - role=checkbox 的按钮（承载 aria-checked / data-state）
  * @csspart indicator - 选中标记
+ * @attr {string} name - 表单字段名；给了 hidden-input 才参与提交
+ * @csspart hidden-input - type=hidden 的表单出口，省略该节点即不参与表单
  */
 declare class XhCheckboxElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "hidden-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -983,12 +1018,24 @@ declare class XhCheckboxElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     tone: {};
     size: {};
   };
   checked?: CheckboxCheckedState;
   defaultChecked?: CheckboxCheckedState;
   disabled?: boolean;
+  name?: string;
+  value?: string;
   tone?: Tone;
   size?: Size;
   private readonly notify;
@@ -1000,7 +1047,7 @@ declare class XhCheckboxElement extends XhElement {
 //#region src/elements/checkbox-group.d.ts
 /**
  * `<xh-checkbox-group>` —— Light-DOM 行为宿主：作者写 root/label 与若干 item 角色节点，
- * 每个 item 内自带 item-hidden-input/item-control/item-text，元素跑 checkbox-group 机器
+ * 每个 item 内自带 hidden-input/indicator/item-text，元素跑 checkbox-group 机器
  * 并把 connect 产出打上去。条目身份取自条目节点上的 value 属性。
  *
  * 不做 roving tabindex：组内每一项都是独立的 Tab 停靠点（禁用项也保留），容器自己不占位。
@@ -1018,14 +1065,14 @@ declare class XhCheckboxElement extends XhElement {
  * @csspart root - role=group 容器
  * @csspart label - 组标题（aria-labelledby 目标）
  * @csspart item - role=checkbox 条目，作者用 value 属性声明身份
- * @csspart item-control - 条目的视觉方框（对读屏隐藏）
+ * @csspart indicator - 条目的视觉方框（对读屏隐藏）
  * @csspart item-text - 条目文本，条目的可及名来源
- * @csspart item-hidden-input - 条目的表单影子输入（必须是原生 input）
+ * @csspart hidden-input - 条目的表单影子输入（必须是原生 input）
  * @csspart trigger - 全选/半选的父复选框，须写在 root 之内
  */
 declare class XhCheckboxGroupElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "trigger" | "label" | "item-text" | "item-control" | "item-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: {
@@ -1124,7 +1171,7 @@ declare class XhCheckboxGroupElement extends XhElement {
  */
 declare class XhClipboardElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "trigger" | "label" | "control" | "input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "indicator" | "trigger" | "label" | "input" | "control">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -1274,6 +1321,7 @@ declare class XhCollapsibleElement extends XhElement {
  * @attr {'ltr'|'rtl'} dir - 文字方向，只改写横轴上左右两键与指针的语义，默认 ltr
  * @attr {string} placement - 首选放置位，默认 bottom-start；避让后的实际位写在 data-placement 上
  * @attr {number} offset - 浮层与锚点的间距（px）
+ * @attr {string} name - 表单字段名；给了 hidden-input 才带 name 并参与提交
  * @fires value-change - 颜色变化；detail 为 `{ value: string }`
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @csspart root - 组件根容器（承载 data-state/data-disabled/data-readonly）
@@ -1292,10 +1340,11 @@ declare class XhCollapsibleElement extends XhElement {
  * @csspart eye-dropper-trigger - 屏幕取色按钮，须是原生 button；环境不支持时自动禁用
  * @csspart swatch-group - role=group 的预设色板容器
  * @csspart swatch-item - 预设色板一格，须是原生 button 且自带 value 属性
+ * @csspart hidden-input - type=hidden 的表单出口，值是当前颜色串；作者不写这个部件就不参与提交
  */
 declare class XhColorPickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "positioner" | "value-text" | "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" | "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: {
@@ -1345,6 +1394,11 @@ declare class XhColorPickerElement extends XhElement {
         fromAttribute: (v: string | null) => string[] | undefined;
       };
     };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     direction: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -1374,6 +1428,7 @@ declare class XhColorPickerElement extends XhElement {
   readOnly?: boolean;
   alpha?: boolean;
   swatches?: string[];
+  name?: string;
   direction?: Direction;
   placement?: Placement;
   offset?: number;
@@ -1449,17 +1504,24 @@ declare class XhColorPickerElement extends XhElement {
  * @csspart item-indicator - 候选选中标记（aria-hidden）
  * @csspart item-group - role=group 分组容器，须自带 value 属性标识身份
  * @csspart item-group-label - 分组标题（本组 aria-labelledby 的目标）
+ * @attr {string} name - 表单字段名；给了 hidden-input 才参与提交（多选按逗号拼成一串）
+ * @csspart hidden-input - type=hidden 的表单出口，省略该节点即不参与表单
  * @csspart empty - 无匹配项提示；须放在 positioner 里当 content 的兄弟（列表内只允许 option 与 group）
  */
 declare class XhComboboxElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "label" | "item-group" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "control" | "input" | "item-group-label" | "empty">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "label" | "item-group" | "positioner" | "item-text" | "item-indicator" | "input" | "empty" | "clear-trigger" | "hidden-input" | "control" | "item-group-label">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
     collection: {
       attribute: boolean;
     };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     value: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -1571,6 +1633,7 @@ declare class XhComboboxElement extends XhElement {
   readOnly?: boolean;
   invalid?: boolean;
   loop?: boolean;
+  name?: string;
   placeholder?: string;
   allowCustomValue?: boolean;
   openOnClick?: boolean;
@@ -1752,6 +1815,9 @@ declare class XhContextMenuElement extends XhElement {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
     direction: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -1782,6 +1848,8 @@ declare class XhContextMenuElement extends XhElement {
   offset?: number;
   loop?: boolean;
   typeahead?: boolean;
+  /** 读屏文案（菜单名字）；对象进不了属性，只作为 property 暴露。 */
+  translations?: ContextMenuSchema['props']['translations'];
   direction?: Direction;
   longPressDelay?: number;
   tone?: Tone;
@@ -1858,7 +1926,7 @@ type SegmentTexts = { readonly [K in DateSegmentType]?: string; };
  */
 declare class XhDateFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "hidden-input" | "segment">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "segment">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2021,6 +2089,9 @@ declare class XhDateFieldElement extends XhElement {
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - role=dialog 浮层（消解层的根节点），收起时带 hidden
  * @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-trigger - 上一月；越过 min 时转原生 disabled
  * @csspart next-trigger - 下一月；越过 max 时转原生 disabled
@@ -2036,9 +2107,9 @@ declare class XhDateFieldElement extends XhElement {
  */
 declare class XhDatePickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "positioner" | "clear-trigger" | "control" | "input" | "calendar">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "positioner" | "input" | "clear-trigger" | "control" | "confirm-trigger" | "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" | "control" | "hidden-input" | "segment">)[];
+    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">)[];
   };
   static properties: {
     value: {
@@ -2139,6 +2210,18 @@ declare class XhDatePickerElement extends XhElement {
       };
       attribute: string;
     };
+    showTime: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    timeGranularity: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     isDateUnavailable: {
       attribute: boolean;
     };
@@ -2162,6 +2245,8 @@ declare class XhDatePickerElement extends XhElement {
   placement?: Placement;
   offset?: number;
   closeOnSelect?: boolean;
+  showTime?: boolean;
+  timeGranularity?: DatePickerSchema['props']['timeGranularity'];
   isDateUnavailable?: (value: string) => boolean;
   private readonly idGen;
   private readonly pickerScope;
@@ -2270,11 +2355,14 @@ declare class XhDialogElement extends XhElement {
   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;
@@ -2373,11 +2461,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;
@@ -2429,7 +2520,7 @@ declare class XhDrawerElement extends XhElement {
  */
 declare class XhEditableElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "input" | "area" | "submit-trigger" | "cancel-trigger" | "preview" | "edit-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "input" | "control" | "area" | "submit-trigger" | "cancel-trigger" | "preview" | "edit-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2664,7 +2755,11 @@ declare class XhFieldElement extends XhElement {
  * @attr {boolean} allow-drop - 是否接受拖拽投放，默认 true；写 allow-drop="false" 关掉
  * @attr {boolean} directory - 选目录而不是选文件（隐藏输入带 webkitdirectory）
  * @attr {'user'|'environment'} capture - 移动端直接调用摄像头/麦克风采集
+ * @attr {boolean} auto-upload - 收下即自动开传（须配 upload 实现），默认 true；写 auto-upload="false" 关掉
  * @fires files-change - 列表变化；detail 为 `{ files: File[] }`
+ * @fires remote-files-change - 远程附件列表变化；detail 为 `{ files: FileUploadRemoteFile[] }`
+ * @fires upload-complete - 单个文件传完；detail 为 `{ file, url? }`
+ * @fires upload-error - 单个文件传败；detail 为 `{ file, error }`
  * @fires file-accept - 本次收下了哪些；detail 为 `{ files: File[] }`
  * @fires file-reject - 本次拒了哪些、各自为什么；detail 为 `{ files: { file, reasons }[] }`
  * @csspart root - 组件根容器，承载 data-dragging / data-disabled / data-invalid / data-empty
@@ -2692,6 +2787,21 @@ declare class XhFileUploadElement extends XhElement {
     defaultFiles: {
       attribute: boolean;
     };
+    remoteFiles: {
+      attribute: boolean;
+    };
+    defaultRemoteFiles: {
+      attribute: boolean;
+    };
+    upload: {
+      attribute: boolean;
+    };
+    autoUpload: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
     accept: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -2746,6 +2856,10 @@ declare class XhFileUploadElement extends XhElement {
   };
   files?: File[];
   defaultFiles?: File[];
+  remoteFiles?: FileUploadRemoteFile[];
+  defaultRemoteFiles?: FileUploadRemoteFile[];
+  upload?: FileUploadSchema['props']['upload'];
+  autoUpload?: boolean;
   accept?: string | string[];
   maxFiles?: number;
   maxFileSize?: number;
@@ -2761,6 +2875,9 @@ declare class XhFileUploadElement extends XhElement {
   private readonly notifyChange;
   private readonly notifyAccept;
   private readonly notifyReject;
+  private readonly notifyRemoteChange;
+  private readonly notifyUploadComplete;
+  private readonly notifyUploadError;
   private readonly ctrl;
   private machineProps;
   /** 命令式入口共用的取法；机器要到进文档（hostConnected）才建，未建则抛。 */
@@ -2806,6 +2923,9 @@ declare class XhFileUploadElement extends XhElement {
  *
  * @customElement xh-form
  * @attr {string} validate-on - 校验时机：submit（默认）/ blur / change
+ * @attr {string} layout - 排布：vertical（默认）/ horizontal（标签左置两列）/ inline（横排一行流）
+ * @attr {string} label-width - horizontal 下标签列宽（CSS 长度），整表统一对齐
+ * @attr {string} label-align - horizontal 下标签对齐缘：end（默认，贴控件）/ start
  * @attr {boolean} disabled - 整个表单禁用：提交、重置、写值一概不发生，两颗按钮带原生 disabled
  * @attr {boolean} read-only - 只读：写值与重置不发生，但仍可提交
  * @fires values-change - 值表变化；detail 为 `{ values }`
@@ -2813,7 +2933,8 @@ declare class XhFileUploadElement extends XhElement {
  * @fires submit - 校验通过才派发；detail 为 `{ values }`
  * @fires invalid - 校验不通过时派发；detail 为 `{ errors, values }`
  * @csspart root - 表单根容器，必须是原生 `<form>`（承载 data-state/data-disabled/data-readonly/data-invalid）
- * @csspart field-group - 单个字段的容器，须自带 value 属性标识字段名；带 id 供摘要链接指向
+ * @csspart field-group - 单个字段的容器，须自带 value 属性标识字段名；带 id 供摘要链接指向。
+ *   组里的 `<xh-field>` 由表单驱动 invalid/required/disabled，作者显式设的会被顶掉
  * @csspart error-summary - role=alert 的错误汇总，提交失败且仍有错误时才显形
  * @csspart error-summary-item - 摘要里的一条，须是原生 `<a>` 且自带 value 属性标识字段名；无对应错误时带 hidden
  * @csspart submit-trigger - 提交键，须是原生 button（连接层写成 type=submit）
@@ -2821,7 +2942,7 @@ declare class XhFileUploadElement extends XhElement {
  */
 declare class XhFormElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "submit-trigger" | "field-group" | "error-summary" | "error-summary-item" | "reset-trigger">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "submit-trigger" | "reset-trigger" | "field-group" | "error-summary" | "error-summary-item">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -2840,12 +2961,35 @@ declare class XhFormElement extends XhElement {
     validate: {
       attribute: boolean;
     };
+    rules: {
+      attribute: boolean;
+    };
+    validateMessages: {
+      attribute: boolean;
+    };
     validateOn: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
       };
       attribute: string;
     };
+    layout: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    labelWidth: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    labelAlign: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -2863,7 +3007,13 @@ declare class XhFormElement extends XhElement {
   errors?: FormErrorPatch;
   defaultErrors?: FormErrorPatch;
   validate?: FormSchema['props']['validate'];
+  /** 声明式校验规则；对象进不了属性，只作为 property 暴露。 */
+  rules?: FormSchema['props']['rules'];
+  validateMessages?: FormSchema['props']['validateMessages'];
   validateOn?: FormValidateOn;
+  layout?: FormSchema['props']['layout'];
+  labelWidth?: string;
+  labelAlign?: FormSchema['props']['labelAlign'];
   disabled?: boolean;
   readOnly?: boolean;
   private readonly notifyValues;
@@ -3134,6 +3284,154 @@ declare class XhImageElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/image-viewer.d.ts
+/**
+ * `<xh-image-viewer>` —— Light-DOM 行为宿主，跑 image-viewer 机器：
+ * 模态看片浮层，滚轮缩放、拖拽平移、旋转翻转与多图翻页。
+ *
+ * @customElement xh-image-viewer
+ * @attr {boolean} open - 受控开合；缺省该属性即非受控
+ * @attr {boolean} default-open - 非受控初始为打开
+ * @attr {number} index - 受控下标（0 起）
+ * @attr {number} default-index - 非受控初始下标，默认 0
+ * @attr {boolean} loop - 前后翻页到头回绕，默认 true；写 loop="false" 关掉
+ * @attr {number} zoom-step - 缩放步长（加法），默认 0.5
+ * @attr {number} min-scale - 缩放下限，默认 0.25
+ * @attr {number} max-scale - 缩放上限，默认 8
+ * @attr {boolean} close-on-escape - Esc 关闭，默认 true
+ * @attr {boolean} close-on-interact-outside - 点遮罩关闭，默认 true
+ * @attr {boolean} restore-focus - 关闭后把焦点归还触发元素，默认 true
+ * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
+ * @fires index-change - 下标变化；detail 为 `{ index: number }`
+ * @csspart trigger - 触发按钮
+ * @csspart backdrop - 遮罩层
+ * @csspart positioner - 浮层定位容器
+ * @csspart content - 看片容器（role=dialog + aria-modal；方向键翻页在这里）
+ * @csspart viewport - 手势视口（滚轮缩放、拖拽平移）
+ * @csspart image - 当前那张图（src/alt/transform 由元素代填）
+ * @csspart toolbar - 工具条容器
+ * @csspart zoom-in-trigger - 放大
+ * @csspart zoom-out-trigger - 缩小
+ * @csspart rotate-left-trigger - 左转 90°
+ * @csspart rotate-right-trigger - 右转 90°
+ * @csspart flip-horizontal-trigger - 水平翻转
+ * @csspart flip-vertical-trigger - 垂直翻转
+ * @csspart reset-trigger - 变换归零
+ * @csspart prev-trigger - 上一张
+ * @csspart next-trigger - 下一张
+ * @csspart counter - 「第 n / 共 m」计数（元素代填）
+ * @csspart close-trigger - 关闭
+ */
+declare class XhImageViewerElement extends XhElement {
+  static partContract: {
+    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: {
+    open: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    defaultOpen: {
+      type: BooleanConstructor;
+      attribute: string;
+    };
+    index: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+    };
+    defaultIndex: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    loop: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    zoomStep: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    minScale: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    maxScale: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    closeOnEscape: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    closeOnInteractOutside: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    restoreFocus: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    items: {
+      attribute: boolean;
+    };
+    translations: {
+      attribute: boolean;
+    };
+  };
+  open?: boolean;
+  defaultOpen?: boolean;
+  index?: number;
+  defaultIndex?: number;
+  loop?: boolean;
+  zoomStep?: number;
+  minScale?: number;
+  maxScale?: number;
+  closeOnEscape?: boolean;
+  closeOnInteractOutside?: boolean;
+  restoreFocus?: boolean;
+  /** 图片清单。看单张就给长度 1 的数组。 */
+  items?: ImageViewerItem[];
+  /** 工具条按钮的可及名与计数文案；connect 每帧重写，只能从这里给。 */
+  translations?: Partial<ImageViewerTranslations>;
+  private readonly idGen;
+  private readonly viewerScope;
+  private config;
+  private contentNode;
+  private exit;
+  private backdropNode;
+  /** counter 的文本归属：首帧为空才代填，作者写过内容就不碰。 */
+  private counterOwned;
+  private readonly notifyOpen;
+  private readonly notifyIndex;
+  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/listbox.d.ts
 /**
  * `<xh-listbox>` —— Light-DOM 行为宿主：作者写 root/label/content 与若干 item 角色节点，
@@ -3434,6 +3732,29 @@ declare class XhMenuElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    submenu: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    openOnHover: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    hoverOpenDelay: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
+    hoverCloseDelay: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
   };
   collection?: MenuNode[];
   open?: boolean;
@@ -3444,6 +3765,10 @@ declare class XhMenuElement extends XhElement {
   direction?: Direction;
   tone?: Tone;
   size?: Size;
+  submenu?: boolean;
+  openOnHover?: boolean;
+  hoverOpenDelay?: number;
+  hoverCloseDelay?: number;
   private readonly idGen;
   private readonly menuScope;
   private readonly positionEngine;
@@ -4195,20 +4520,39 @@ declare class XhPopoverElement extends XhElement {
 //#endregion
 //#region src/elements/progress.d.ts
 /**
- * `<xh-progress>` —— Light-DOM 行为宿主，无状态机，把 connectProgress 产出打到 root/track/range 角色节点。
+ * `<xh-progress>` —— Light-DOM 行为宿主，无状态机，把 connectProgress 产出打到各角色节点。
+ *
+ * 线形写三层 div（root > track > range）；环形要把 track 与 range 写成 `<circle>`、
+ * 外面套一层 `<svg>` 当 canvas，环心的文字放进 label：
+ *
+ * ```html
+ * <xh-progress variant="circle" value="60">
+ *   <div data-part="root">
+ *     <svg data-part="canvas"><circle data-part="track" /><circle data-part="range" /></svg>
+ *     <div data-part="label">60%</div>
+ *   </div>
+ * </xh-progress>
+ * ```
  *
  * @customElement xh-progress
  * @attr {number} value - 当前进度值，越界会被夹到 [0, max]，默认 0
  * @attr {number} max - 满值上限，默认 100
+ * @attr {'line'|'circle'|'dashboard'} variant - 形态，默认 line
+ * @attr {number} stroke-width - 环的线宽（viewBox 单位），默认 6；只对 circle / dashboard 生效
+ * @attr {number} gap-degree - 缺口角度，默认 75；只对 dashboard 生效
+ * @attr {'top'|'right'|'bottom'|'left'} gap-position - 缺口朝向，默认 bottom；只对 dashboard 生效
+ * @attr {string} value-text - 读屏播报的文字，覆盖默认的数值播报
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
- * @attr {'sm'|'md'|'lg'} size - 尺寸
+ * @attr {'sm'|'md'|'lg'} size - 尺寸：线形改厚度，环形改直径
  * @csspart root - role=progressbar 的容器（承载 aria-valuenow/aria-valuemax/data-state）
- * @csspart track - 进度轨道（满长背景）
- * @csspart range - 已完成区段，长度按百分比写成内联 inline-size
+ * @csspart canvas - 承载环的 svg（线形不用）
+ * @csspart track - 进度轨道：线形是满长背景，环形是整段弧
+ * @csspart range - 已完成区段：线形写内联 inline-size，环形写 stroke-dashoffset
+ * @csspart label - 环心那一块，写什么由使用者决定（线形不用）
  */
 declare class XhProgressElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "track" | "range">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "track" | "range" | "canvas">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4218,11 +4562,31 @@ declare class XhProgressElement extends XhElement {
     max: {
       type: NumberConstructor;
     };
+    variant: {};
+    strokeWidth: {
+      type: NumberConstructor;
+      attribute: string;
+    };
+    gapDegree: {
+      type: NumberConstructor;
+      attribute: string;
+    };
+    gapPosition: {
+      attribute: string;
+    };
+    valueText: {
+      attribute: string;
+    };
     tone: {};
     size: {};
   };
   value?: number;
   max?: number;
+  variant?: ProgressVariant;
+  strokeWidth?: number;
+  gapDegree?: number;
+  gapPosition?: ProgressGapPosition;
+  valueText?: string;
   tone?: Tone;
   size?: Size;
   protected wire(): void;
@@ -4318,6 +4682,7 @@ declare class XhRadioGroupElement extends XhElement {
  * @attr {number} default-value - 非受控初值，缺省 0（还没评）
  * @attr {number} count - 星星颗数，默认 5
  * @attr {boolean} allow-half - 允许半颗星：档位从 1 变成 0.5
+ * @attr {boolean} allow-clear - 再点当前档位清零，键盘最低档再往下也清；默认开，写 "false" 关
  * @attr {boolean} disabled - 整个不可交互：整条带子退出 Tab 序列，指针与键盘都不认
  * @attr {boolean} read-only - 只读：仍可聚焦与朗读，但改不动，也没有悬停预览
  * @attr {boolean} required - 必填标注；表单影子据此参与原生校验
@@ -4336,7 +4701,7 @@ declare class XhRadioGroupElement extends XhElement {
  */
 declare class XhRatingElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "control" | "hidden-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "hidden-input" | "control">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4362,6 +4727,12 @@ declare class XhRatingElement extends XhElement {
       };
       attribute: string;
     };
+    allowClear: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
     disabled: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -4404,6 +4775,7 @@ declare class XhRatingElement extends XhElement {
   defaultValue?: number;
   count?: number;
   allowHalf?: boolean;
+  allowClear?: boolean;
   disabled?: boolean;
   readOnly?: boolean;
   required?: boolean;
@@ -4517,6 +4889,8 @@ declare class XhScrollAreaElement extends XhElement {
  * @attr {boolean} open - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-open - 非受控初始为展开
  * @attr {boolean} disabled - 整个控件禁用：trigger 用原生 disabled，表单影子不参与提交
+ * @attr {boolean} invalid - 校验错误态：trigger 标红并输出 aria-invalid
+ * @attr {number} max-tag-count - 多选标签最多摆几个，其余折进 api 的 overflowCount；缺省全摆
  * @attr {boolean} required - 原生表单校验：无选中值时提交被拦下；多选下的门槛是至少选中一项
  * @attr {string} name - 表单字段名；给定后表单影子才带 name 并参与提交
  * @attr {string} placeholder - 无选中时 value-text 显示的占位文字
@@ -4535,6 +4909,10 @@ 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 positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - role=listbox 容器（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
  * @csspart item - role=option 条目，须自带 value 属性标识身份；禁用写 aria-disabled="true"
@@ -4544,7 +4922,7 @@ declare class XhScrollAreaElement extends XhElement {
  */
 declare class XhSelectElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "value-text" | "hidden-select">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "control" | "tag" | "tag-remove" | "hidden-select">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4574,6 +4952,9 @@ declare class XhSelectElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    invalid: {
+      type: BooleanConstructor;
+    };
     required: {
       type: BooleanConstructor;
     };
@@ -4626,6 +5007,15 @@ declare class XhSelectElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
+    maxTagCount: {
+      converter: {
+        fromAttribute: (v: string | null) => number | undefined;
+      };
+      attribute: string;
+    };
   };
   collection?: SelectNode[];
   value?: string | string[];
@@ -4633,6 +5023,7 @@ declare class XhSelectElement extends XhElement {
   open?: boolean;
   defaultOpen?: boolean;
   disabled?: boolean;
+  invalid?: boolean;
   required?: boolean;
   name?: string;
   placeholder?: string;
@@ -4644,6 +5035,9 @@ declare class XhSelectElement extends XhElement {
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
+  /** 读屏文案（clear 等）；对象进不了属性，只作为 property 暴露。 */
+  translations?: SelectSchema['props']['translations'];
+  maxTagCount?: number;
   private readonly idGen;
   private readonly selectScope;
   private readonly positionEngine;
@@ -4713,6 +5107,128 @@ declare class XhSeparatorElement extends XhElement {
   protected wire(): void;
 }
 //#endregion
+//#region src/elements/side-nav.d.ts
+/**
+ * `<xh-side-nav>` —— Light-DOM 行为宿主：管理后台侧栏导航。
+ * 作者写 root/list 与若干 branch / link 角色节点，元素跑 side-nav 机器并把 connect 产出打上去。
+ * 节点身份取自节点上的 value 属性；href 与禁用查 `collection` 这份树数据。
+ *
+ * @customElement xh-side-nav
+ * @attr {string} value - 受控选中的叶子；缺省该属性即非受控
+ * @attr {string} default-value - 非受控初始选中
+ * @attr {boolean} accordion - 同层手风琴：展开一枝收起同层其余，默认 false
+ * @attr {boolean} collapsed - 折叠成图标栏（内嵌展开整体收起、文字由皮肤藏掉；顶层分支换装浮层弹出）
+ * @attr {boolean} collapsed-popout - 折叠态下顶层分支是否弹出子级面板，默认 true
+ * @attr {boolean} disabled - 整个侧栏禁用
+ * @attr {boolean} loop - 上下键走到首尾回绕，默认关
+ * @attr {'ltr'|'rtl'} dir - 文字方向，只对调左右方向键的展开/收起语义，默认 ltr
+ * @fires value-change - 选中变化；detail 为 `{ value: string | null }`
+ * @fires expanded-change - 展开集合变化；detail 为 `{ value: string[] }`
+ * @csspart root - nav 地标根容器（aria-label 由 translations.root 给）
+ * @csspart list - 顶层列表容器
+ * @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-indicator - 展开方向指示符（aria-hidden）
+ * @csspart branch-content - 内嵌子层容器，收起时隐藏
+ * @csspart link - 去处链接，须自带 value 属性；选中输出 aria-current="page"
+ * @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">;
+    meta: import("@xihan-ui/headless").ComponentMeta;
+  };
+  static properties: {
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    defaultValue: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    accordion: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    collapsed: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    collapsedPopout: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    disabled: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    loop: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+    };
+    direction: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
+    collection: {
+      attribute: boolean;
+    };
+    expandedValue: {
+      attribute: boolean;
+    };
+    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 ctrl;
+  private machineProps;
+  private ensureConfig;
+  /** 当前弹出分支名下的角色节点：按归属分支的 value 现查。 */
+  private findPopoutPart;
+  private readonly registerLayer;
+  private injectRefs;
+  private nodeOf;
+  disconnectedCallback(): void;
+  protected wire(): void;
+}
+//#endregion
 //#region src/elements/skeleton.d.ts
 /**
  * `<xh-skeleton>` —— 骨架屏宿主，无状态机，把 connectSkeleton 产出的属性打到角色节点上。
@@ -4768,6 +5284,7 @@ declare class XhSkeletonElement extends XhElement {
  * @attr {number} step - 方向键与吸附网格的步长，默认 1
  * @attr {number} large-step - PageUp/PageDown 的步长，默认 10 倍 step
  * @attr {number} min-steps-between-thumbs - 相邻滑块至少隔几格，默认 0
+ * @attr {boolean} snap-to-marks - 只认刻度落点：拖动、点按与键盘都吸到最近/下一档刻度；刻度表经 marks property 赋
  * @attr {'horizontal'|'vertical'} orientation - 轨道朝向，默认 horizontal
  * @attr {'ltr'|'rtl'} dir - 文字方向，只改写水平轨道上左右两键与指针的语义，默认 ltr
  * @attr {boolean} disabled - 禁用：拇指退出 Tab 序列、推不动、不参与表单提交
@@ -4783,12 +5300,15 @@ declare class XhSkeletonElement extends XhElement {
  * @csspart control - 指针命中区，按下即跳到落点并接管拖动
  * @csspart track - 轨道本体，值与坐标的换算以它的矩形为准
  * @csspart range - 已选区间，起止由内联逻辑属性给出
+ * @csspart marks - 刻度容器
+ * @csspart mark - 刻度点（纯装饰），须自带 value 属性；落进已选区间带 data-active
+ * @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" | "control" | "hidden-input" | "track" | "range" | "thumb">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "track" | "range" | "thumb" | "mark" | "marks" | "mark-label">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -4830,6 +5350,15 @@ declare class XhSliderElement extends XhElement {
       };
       attribute: string;
     };
+    snapToMarks: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
+    marks: {
+      attribute: boolean;
+    };
     orientation: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -4883,6 +5412,9 @@ declare class XhSliderElement extends XhElement {
   step?: number;
   largeStep?: number;
   minStepsBetweenThumbs?: number;
+  /** 刻度表；数组进不了属性，只作为 property 暴露。 */
+  marks?: SliderSchema['props']['marks'];
+  snapToMarks?: boolean;
   orientation?: Orientation;
   direction?: Direction;
   disabled?: boolean;
@@ -4969,16 +5501,16 @@ declare class XhSpinnerElement extends XhElement {
  * 第 index 条分隔条坐在第 index 与第 index+1 块面板之间，调整的是前一块。
  *
  * @customElement xh-splitter
- * @attr {string} size - 受控布局，逗号分隔的百分比（如 "30,70"）；缺省该属性即非受控
- * @attr {string} default-size - 非受控初值，同样逗号分隔；缺省时按面板数等分
+ * @attr {string} sizes - 受控布局，逗号分隔的百分比（如 "30,70"）；缺省该属性即非受控
+ * @attr {string} default-sizes - 非受控初值，同样逗号分隔；缺省时按面板数等分
  * @attr {string} panels - 逐块约束的 JSON 数组：id / min / max / collapsible / collapsedSize
  * @attr {'horizontal'|'vertical'} orientation - 面板排布轴，默认 horizontal（并排）
  * @attr {'ltr'|'rtl'} dir - 文字方向，只对调水平排布下左右两键与指针位移的正负，默认 ltr
  * @attr {boolean} disabled - 禁用：分隔条退出 Tab 序列、拖不动也推不动
  * @attr {number} step - 方向键的步长（百分比），默认 1
  * @attr {number} large-step - Shift + 方向键的步长（百分比），默认 10
- * @fires size-change - 布局变化（拖动途中会连发）；detail 为 `{ size: number[] }`
- * @fires size-change-end - 一次拖拽收尾发一次；detail 为 `{ size: number[], index: number }`
+ * @fires sizes-change - 布局变化（拖动途中会连发）；detail 为 `{ sizes: number[] }`
+ * @fires sizes-change-end - 一次拖拽收尾发一次；detail 为 `{ sizes: number[], index: number }`
  * @csspart root - 承载 data-orientation / data-disabled / data-dragging 的容器，矩形以它为准
  * @csspart panel - 一块面板；尺寸由内联 flex-basis 给出，折叠时带 data-collapsed
  * @csspart resize-trigger - role=separator 的分隔条，指针与键盘交互全在它身上
@@ -4989,12 +5521,12 @@ declare class XhSplitterElement extends XhElement {
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
-    size: {
+    sizes: {
       converter: {
         fromAttribute: (v: string | null) => number[] | undefined;
       };
     };
-    defaultSize: {
+    defaultSizes: {
       converter: {
         fromAttribute: (v: string | null) => number[] | undefined;
       };
@@ -5033,8 +5565,8 @@ declare class XhSplitterElement extends XhElement {
       attribute: string;
     };
   };
-  size?: number[];
-  defaultSize?: number[];
+  sizes?: number[];
+  defaultSizes?: number[];
   panels?: SplitterPanelProps[];
   orientation?: Orientation;
   direction?: Direction;
@@ -5180,15 +5712,18 @@ declare class XhStepsElement extends XhElement {
  * @attr {boolean} checked - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-checked - 非受控初始为选中
  * @attr {boolean} disabled - 禁用
+ * @attr {boolean} loading - 提交中：交互挂起、滑块转圈，仍可聚焦（aria-busy）
  * @attr {'brand'|'neutral'|'success'|'warning'|'danger'|'info'} tone - 语气
  * @attr {'sm'|'md'|'lg'} size - 尺寸
  * @fires checked-change - checked 状态变化；detail 为 `{ checked: boolean }`
  * @csspart root - role=switch 的按钮（承载 aria-checked / data-state）
  * @csspart thumb - 滑块
+ * @attr {string} name - 表单字段名；给了 hidden-input 才参与提交
+ * @csspart hidden-input - type=hidden 的表单出口，省略该节点即不参与表单
  */
 declare class XhSwitchElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "thumb">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "hidden-input" | "thumb">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5204,12 +5739,28 @@ declare class XhSwitchElement extends XhElement {
     disabled: {
       type: BooleanConstructor;
     };
+    loading: {
+      type: BooleanConstructor;
+    };
+    name: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
+    value: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+    };
     tone: {};
     size: {};
   };
   checked?: boolean;
   defaultChecked?: boolean;
   disabled?: boolean;
+  loading?: boolean;
+  name?: string;
+  value?: string;
   tone?: Tone;
   size?: Size;
   private readonly notify;
@@ -5257,12 +5808,12 @@ declare class XhSwitchElement extends XhElement {
  * @csspart sort-trigger - 排序把手，自占一个 Tab 位；按住 Shift 点是追加到排序链
  * @csspart expand-trigger - 展开把手（aria-hidden 且不占 Tab 位，键盘那一路由左右方向键承担）
  * @csspart expanded-row - role=row 详情行，须自带 value 属性与它所属的数据行配对，内部须放一个 cell 承载详情；收起时 hidden
- * @csspart empty-state - 空态节点，表体为空且不在加载时显形
+ * @csspart empty - 空态节点，表体为空且不在加载时显形
  * @csspart loading-state - 加载态节点，表体为空且正在加载时显形
  */
 declare class XhTableElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "header" | "cell" | "expand-trigger" | "body" | "footer" | "empty-state" | "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" | "footer" | "select-all-trigger" | "row" | "column-header" | "caption" | "row-select-trigger" | "sort-trigger" | "expanded-row" | "loading-state">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5508,7 +6059,7 @@ declare class XhTabsElement extends XhElement {
  */
 declare class XhTagsInputElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "item-text" | "clear-trigger" | "control" | "input" | "hidden-input" | "item-preview" | "item-delete-trigger" | "item-input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "label" | "item-text" | "input" | "clear-trigger" | "hidden-input" | "control" | "item-preview" | "item-delete-trigger" | "item-input">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5667,6 +6218,7 @@ declare class XhTagsInputElement extends XhElement {
  * @attr {string} name - 表单字段名；给了才参与提交
  * @attr {number} max-length - 字符数上限；同时落成原生 maxlength 与机器侧截断
  * @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 - 尺寸
@@ -5678,7 +6230,7 @@ declare class XhTagsInputElement extends XhElement {
  */
 declare class XhTextFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "clear-trigger" | "input">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "input" | "clear-trigger">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5735,6 +6287,12 @@ declare class XhTextFieldElement extends XhElement {
         fromAttribute: (v: string | null) => boolean | undefined;
       };
     };
+    autoSize: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
     variant: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -5761,6 +6319,8 @@ declare class XhTextFieldElement extends XhElement {
   name?: string;
   maxLength?: number;
   clearable?: boolean;
+  /** 布尔走 auto-size 属性；行数界限对象进不了属性，只作为 property 赋。 */
+  autoSize?: TextFieldSchema['props']['autoSize'];
   variant?: ControlVariant;
   tone?: Tone;
   size?: Size;
@@ -5858,7 +6418,7 @@ declare class XhThreadElement extends XhElement {
  */
 declare class XhTimeFieldElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "control" | "hidden-input" | "segment">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "label" | "hidden-input" | "control" | "segment">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -5978,7 +6538,7 @@ declare class XhTimeFieldElement extends XhElement {
 //#region src/elements/time-picker.d.ts
 /**
  * `<xh-time-picker>` —— Light-DOM 行为宿主：作者写 root/label/control/input（多个）/trigger/
- * clear-trigger/positioner/content/column（多个）/option（多个）/hidden-input 角色节点，
+ * clear-trigger/positioner/content/column（多个）/item（多个）/hidden-input 角色节点，
  * 元素跑 time-picker 机器并把 connect 产出打上去。浮层定位引擎在本元素里建好、经 refs 注入机器，
  * 锚点取 control（浮层因此与整个输入行对齐），被定位的浮层取 positioner。
  *
@@ -6016,12 +6576,12 @@ declare class XhTimeFieldElement extends XhElement {
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
  * @csspart content - 浮层容器（消解层与焦点域的根节点），收起时带 hidden
  * @csspart column - role=listbox 的一列，可自带 unit 属性声明单位，缺省按文档序
- * @csspart option - role=option 的一格，须自带 value 属性（两位补零的显示串）
+ * @csspart item - role=option 的一格，须自带 value 属性（两位补零的显示串）
  * @csspart hidden-input - type=hidden 的表单出口，值是完整 ISO 串
  */
 declare class XhTimePickerElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "content" | "trigger" | "label" | "positioner" | "clear-trigger" | "column" | "control" | "input" | "hidden-input" | "option">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "trigger" | "label" | "positioner" | "input" | "clear-trigger" | "column" | "hidden-input" | "control">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -6723,6 +7283,7 @@ declare class XhTooltipElement extends XhElement {
  * @attr {boolean} close-on-interact-outside - 层外交互关闭，默认 false；写 "true" 打开
  * @attr {boolean} show-backdrop - 画遮罩，默认 true；写 show-backdrop="false" 关掉
  * @attr {number} spotlight-padding - 高亮框在目标四周留出的空白（px），默认 8
+ * @attr {boolean} auto-scroll - 展开与换步时自动把目标滚进视口（nearest），默认 true；写 auto-scroll="false" 关掉
  * @fires open-change - open 状态变化；detail 为 `{ open: boolean }`
  * @fires step-change - 步序变化；detail 为 `{ step: number }`
  * @fires complete - 末步再按下一步；detail 为 `{ step: number }`
@@ -6801,6 +7362,12 @@ declare class XhTourElement extends XhElement {
       };
       attribute: string;
     };
+    autoScroll: {
+      converter: {
+        fromAttribute: (v: string | null) => boolean | undefined;
+      };
+      attribute: string;
+    };
     steps: {
       attribute: boolean;
     };
@@ -6818,6 +7385,7 @@ declare class XhTourElement extends XhElement {
   closeOnInteractOutside?: boolean;
   showBackdrop?: boolean;
   spotlightPadding?: number;
+  autoScroll?: boolean;
   /** 步骤清单。它是步序的上界，也是读屏"第 m 步，共 n 步"的分母。 */
   steps?: TourStep[];
   /** 关闭按钮的无障碍名与进度文案；connect 每帧重写，作者写在节点上会被盖掉，只能从这里给。 */
@@ -6854,6 +7422,8 @@ declare class XhTourElement extends XhElement {
    */
   private fillText;
   protected wire(): void;
+  /** 重量高亮框与浮层位置：目标节点被外部改动（换位、变尺寸）后调它校准。 */
+  remeasure(): void;
   private wireWith;
   disconnectedCallback(): void;
 }
@@ -6864,7 +7434,7 @@ declare class XhTourElement extends XhElement {
  * root/source-panel/target-panel/panel-header/panel-title/panel-count/search/list/item/...
  * 角色节点，元素跑 transfer 机器并把 connect 产出打上去。
  *
- * 条目全集由 `items` 属性（property）给出，它是标签与禁用的唯一事实源；
+ * 条目全集由 `collection` 属性（property）给出，它是标签与禁用的唯一事实源；
  * **两侧面板各挂一份全集**，不属于本侧、或被搜索筛掉的那一份由元素打上 hidden，
  * 节点不卸载。条目身份取节点上的 `value` 属性，归哪一侧则取它落在哪个面板里。
  *
@@ -6873,8 +7443,8 @@ declare class XhTourElement extends XhElement {
  * 导航与勾选在事件那一刻按 data-scope+data-part 查活 DOM，依赖 connect 回写的 data-value，
  * 因此 wire 必须先于交互跑过（基类 updated 已保证）。
  *
- * 集合类输入（items / value / selected / filter）都表达不成属性，只能走 property：
- * `el.items = [...]`、`el.value = ['a']`。
+ * 集合类输入（collection / value / selected / filter）都表达不成属性，只能走 property：
+ * `el.collection = [...]`、`el.value = ['a']`。
  *
  * @customElement xh-transfer
  * @attr {boolean} searchable - 每侧带一个搜索框；关掉时搜索框仍在 DOM 里但带 hidden
@@ -6883,7 +7453,7 @@ declare class XhTourElement extends XhElement {
  * @attr {boolean} loop - 列表内方向键走到尽头回绕，默认 true；写 loop="false" 关掉
  * @attr {'ltr'|'rtl'} dir - 文字方向，决定列表内哪个横向方向键是"搬向对面"，默认 ltr
  * @fires value-change - 落在右侧的值变化；detail 为 `{ value: string[] }`
- * @fires selected-change - 勾选集合变化；detail 为 `{ selected: string[] }`
+ * @fires selection-change - 勾选集合变化；detail 为 `{ selected: string[] }`
  * @csspart root - 组件根容器（承载 data-disabled/data-one-way）
  * @csspart source-panel - 左侧面板容器，其内的角色节点一律归左侧
  * @csspart target-panel - 右侧面板容器，其内的角色节点一律归右侧
@@ -6892,7 +7462,7 @@ declare class XhTourElement extends XhElement {
  * @csspart panel-count - 计数节点，只带 data-count / data-checked-count，文案由作者写
  * @csspart search - 本侧搜索框，须是原生 input；searchable 关掉时带 hidden
  * @csspart list - role=listbox 容器，键盘在此收口，也是 roving tabindex 的兜底位
- * @csspart item - role=option 条目，须自带 value 属性标识身份；禁用写在 items 里，不写在节点上
+ * @csspart item - role=option 条目，须自带 value 属性标识身份；禁用写在 collection 里，不写在节点上
  * @csspart item-text - 条目文本
  * @csspart item-checkbox - 条目勾选标记（aria-hidden）；oneWay 下右侧的那一份带 hidden
  * @csspart select-all-trigger - 本侧全选格，须是原生 button；三态经 aria-checked 上报
@@ -6905,7 +7475,7 @@ declare class XhTransferElement extends XhElement {
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
-    items: {
+    collection: {
       attribute: boolean;
     };
     value: {
@@ -6945,7 +7515,7 @@ declare class XhTransferElement extends XhElement {
       attribute: string;
     };
   };
-  items?: TransferItem[];
+  collection?: TransferItem[];
   value?: string[];
   defaultValue?: string[];
   selected?: string[];
@@ -6983,6 +7553,8 @@ declare class XhTransferElement extends XhElement {
  *
  * @customElement xh-tree
  * @attr {'single'|'multiple'} selection-mode - 选择模式，默认 single
+ * @attr {boolean} cascade - multiple 下父子级联勾选（整枝传导/半选/禁用冻结），默认 false
+ * @attr {string} checked-strategy - 级联下对外值的收敛策略：child（默认）/ parent / all
  * @attr {boolean} expand-on-click - 点分支行顺带展开/收起，默认开；写 expand-on-click="false" 关掉
  * @attr {boolean} disabled - 整棵树禁用：所有节点转 aria-disabled，键盘与点击都改不了展开与选中
  * @attr {boolean} loop - 上下键走到首尾回绕，默认关；写 loop="true" 打开
@@ -7005,7 +7577,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" | "tree" | "branch" | "branch-control" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content">;
+    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">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -7030,6 +7602,15 @@ declare class XhTreeElement extends XhElement {
       };
       attribute: string;
     };
+    cascade: {
+      type: BooleanConstructor;
+    };
+    checkedStrategy: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     expandOnClick: {
       converter: {
         fromAttribute: (v: string | null) => boolean | undefined;
@@ -7062,6 +7643,8 @@ declare class XhTreeElement extends XhElement {
   selectedValue?: string[];
   defaultSelectedValue?: string[];
   selectionMode?: TreeSelectionMode;
+  cascade?: boolean;
+  checkedStrategy?: TreeSchema['props']['checkedStrategy'];
   expandOnClick?: boolean;
   disabled?: boolean;
   loop?: boolean;
@@ -7108,6 +7691,8 @@ declare class XhTreeElement extends XhElement {
  * @attr {boolean} open - 受控开合；缺省该属性即非受控
  * @attr {boolean} default-open - 非受控初始为展开
  * @attr {boolean} multiple - 多选：选中后浮层不收起，焦点留在树里
+ * @attr {boolean} cascade - 多选下父子级联勾选（整枝传导/半选/禁用冻结），默认 false
+ * @attr {string} checked-strategy - 级联下对外值的收敛策略：child（默认）/ parent / all
  * @attr {boolean} disabled - 整个控件禁用：trigger 用原生 disabled，表单出口不参与提交
  * @attr {boolean} read-only - 只读：浮层照常展开、树照常浏览，但选中值改不动、也清不掉
  * @attr {boolean} invalid - 校验失败标注
@@ -7130,8 +7715,8 @@ declare class XhTreeElement extends XhElement {
  * @csspart indicator - 展开指示符（aria-hidden，data-state 随开合）
  * @csspart clear-trigger - 清空按钮，须是原生 button；不占 Tab 位且对读屏隐藏
  * @csspart positioner - 浮层定位容器，坐标由引擎写成内联样式
- * @csspart content - 浮层壳（焦点域与消解层的根节点），收起时带 hidden
- * @csspart tree - role=tree 容器，键盘在此收口，也是没有锚点时的 Tab 兜底位
+ * @csspart content - 浮层壳（焦点域与消解层的根节点，键盘在此收口），收起时带 hidden
+ * @csspart tree - role=tree 容器，没有锚点时的 Tab 兜底位与落焦点
  * @csspart item - role=treeitem 叶子，须自带 value 属性标识身份
  * @csspart item-text - 叶子文本
  * @csspart item-indicator - 叶子选中标记（aria-hidden）
@@ -7145,7 +7730,7 @@ declare class XhTreeElement extends XhElement {
  */
 declare class XhTreeSelectElement extends XhElement {
   static partContract: {
-    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "hidden-input" | "tree" | "branch" | "branch-control" | "branch-trigger" | "branch-indicator" | "branch-text" | "branch-content">;
+    anatomy: import("@xihan-ui/kernel").Anatomy<"root" | "item" | "content" | "indicator" | "trigger" | "label" | "positioner" | "item-text" | "item-indicator" | "clear-trigger" | "value-text" | "hidden-input" | "branch" | "branch-trigger" | "branch-text" | "branch-indicator" | "branch-content" | "tree" | "branch-control">;
     meta: import("@xihan-ui/headless").ComponentMeta;
   };
   static properties: {
@@ -7181,6 +7766,15 @@ declare class XhTreeSelectElement extends XhElement {
     multiple: {
       type: BooleanConstructor;
     };
+    cascade: {
+      type: BooleanConstructor;
+    };
+    checkedStrategy: {
+      converter: {
+        fromAttribute: (v: string | null) => string | undefined;
+      };
+      attribute: string;
+    };
     disabled: {
       type: BooleanConstructor;
     };
@@ -7215,6 +7809,9 @@ declare class XhTreeSelectElement extends XhElement {
         fromAttribute: (v: string | null) => string | undefined;
       };
     };
+    translations: {
+      attribute: boolean;
+    };
     placement: {
       converter: {
         fromAttribute: (v: string | null) => string | undefined;
@@ -7250,6 +7847,8 @@ declare class XhTreeSelectElement extends XhElement {
   open?: boolean;
   defaultOpen?: boolean;
   multiple?: boolean;
+  cascade?: boolean;
+  checkedStrategy?: TreeSelectSchema['props']['checkedStrategy'];
   disabled?: boolean;
   readOnly?: boolean;
   invalid?: boolean;
@@ -7257,6 +7856,8 @@ declare class XhTreeSelectElement extends XhElement {
   tone?: Tone;
   size?: Size;
   placeholder?: string;
+  /** 读屏文案（树容器兜底名字）；对象进不了属性，只作为 property 暴露。 */
+  translations?: TreeSelectSchema['props']['translations'];
   placement?: Placement;
   offset?: number;
   loop?: boolean;
@@ -7422,5 +8023,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, XhListboxElement, XhLoadingBarElement, XhMenuElement, XhMenubarElement, XhNavigationMenuElement, XhNumberFieldElement, XhPaginationElement, XhPinInputElement, XhPopoverElement, XhProgressElement, XhRadioGroupElement, XhRatingElement, XhScrollAreaElement, XhSelectElement, XhSeparatorElement, 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, 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 };
 //# sourceMappingURL=define.d.ts.map