huibo-ui 0.3.0 → 0.5.0

package/dist/types/components.d.ts

@@ -7,18 +7,21 @@
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
 import { AnchorClickDetail, AnchorItem } from "./components/Anchor/Anchor";
 import { CarouselArrow } from "./components/Carousel/Carousel";
-import { CascaderOption } from "./components/Cascader/Cascader";
+import { CascaderOption, ValuePath } from "./components/Cascader/Cascader";
 import { DatePickerPaneView } from "./components/DatePickerPane/DatePickerPane";
 import { ComponentSize } from "./utils/form-input-base";
 import { DescriptionItem } from "./components/Descriptions/Descriptions";
 import { DropdownItem } from "./components/Dropdown/Dropdown";
 import { ImagePreviewChangeDetail } from "./components/ImagePreview/ImagePreview";
+import { ColResponsive } from "./components/Layout/Layout";
 import { MessageType } from "./components/Message/Message";
 import { NotificationPosition, NotificationType } from "./components/Notification/Notification";
 import { Placement } from "./utils/popup-manager";
 import { ResultStatus } from "./components/Result/Result";
 import { SegmentedOption } from "./components/Segmented/Segmented";
 import { SelectOption } from "./components/Select/Select";
+import { SliderMark } from "./components/Slider/Slider";
+import { StepStatus } from "./components/Steps/Steps";
 import { SortDirection, TableAction, TableColumn, TableTreeProps } from "./components/Table/Table";
 import { TimelineItem } from "./components/Timeline/Timeline";
 import { TourStep } from "./components/Tour/Tour";
@@ -28,18 +31,21 @@ import { TreeNode as TreeNode1 } from "./components/Tree/Tree";
 import { UploadFile } from "./components/Upload/Upload";
 export { AnchorClickDetail, AnchorItem } from "./components/Anchor/Anchor";
 export { CarouselArrow } from "./components/Carousel/Carousel";
-export { CascaderOption } from "./components/Cascader/Cascader";
+export { CascaderOption, ValuePath } from "./components/Cascader/Cascader";
 export { DatePickerPaneView } from "./components/DatePickerPane/DatePickerPane";
 export { ComponentSize } from "./utils/form-input-base";
 export { DescriptionItem } from "./components/Descriptions/Descriptions";
 export { DropdownItem } from "./components/Dropdown/Dropdown";
 export { ImagePreviewChangeDetail } from "./components/ImagePreview/ImagePreview";
+export { ColResponsive } from "./components/Layout/Layout";
 export { MessageType } from "./components/Message/Message";
 export { NotificationPosition, NotificationType } from "./components/Notification/Notification";
 export { Placement } from "./utils/popup-manager";
 export { ResultStatus } from "./components/Result/Result";
 export { SegmentedOption } from "./components/Segmented/Segmented";
 export { SelectOption } from "./components/Select/Select";
+export { SliderMark } from "./components/Slider/Slider";
+export { StepStatus } from "./components/Steps/Steps";
 export { SortDirection, TableAction, TableColumn, TableTreeProps } from "./components/Table/Table";
 export { TimelineItem } from "./components/Timeline/Timeline";
 export { TourStep } from "./components/Tour/Tour";
@@ -288,22 +294,28 @@ export namespace Components {
     }
     /**
      * Cascader 级联选择器组件
-     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择
+     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
+     * 支持单选 / 多选（multiple）、可选任意层级（checkStrictly）、搜索（filterable）、动态加载（lazy）。
      */
     interface HbCascader {
+        /**
+          * 是否严格的选中行为（父子不关联）。 单选：点击任意层级（含非叶子）即选中该路径； 多选：勾选独立，不向下联动选中叶子、取消也不联动。
+         */
+        "checkStrictly": boolean;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
+         */
+        "check-strictly"?: boolean;
         /**
           * 是否可清空
-          * @default false
          */
         "clearable": boolean;
         /**
           * 是否禁用
-          * @default false
          */
         "disabled": boolean;
         /**
-          * 是否动态加载子节点
-          * @default true
+          * modelValue 是否输出完整路径（保留 AntD 兼容位）
          */
         "emitPath": boolean;
         /**
@@ -311,12 +323,11 @@ export namespace Components {
          */
         "emit-path"?: boolean;
         /**
-          * 是否可搜索（filterable） 开启后下拉顶部渲染搜索输入框，输入时按 label（含所有子级）扁平化过滤， 匹配项以完整路径展示，点击即选中其完整路径。
-          * @default false
+          * 是否可搜索（filterable）。下拉顶部渲染搜索框，输入时按 label 扁平化过滤， 匹配项以完整路径展示，点击即选中（单选）或 toggle 勾选（多选）。
          */
         "filterable": boolean;
         /**
-          * 输入框的原生属性
+          * 输入框原生属性
          */
         "inputId"?: string;
         /**
@@ -324,20 +335,31 @@ export namespace Components {
          */
         "input-id"?: string;
         /**
-          * 是否开启动态加载（lazy load）。开启后，展开含 children=undefined 的节点时， 调用 load(node) 获取其子级并填充进 options，加载中显示 loading 态。
-          * @default false
+          * 是否开启动态加载（lazy）。展开 children=undefined 的节点时调用 load(node) 填充子级。
          */
         "lazy": boolean;
         /**
-          * 动态加载子节点的函数（仅在 lazy=true 时生效）。 接收被展开的节点，返回其子节点数组（Promise）。 加载结果会以不可变方式合并进 options 树（替换该节点 children）。
+          * 动态加载函数（仅 lazy=true 生效）
          */
         "load"?: (node: CascaderOption) => Promise<CascaderOption[]>;
         /**
-          * 选中项绑定值
+          * 多选时输入框最多展示的 tag 数量，超出折叠为 +N（可选）。
          */
-        "modelValue"?: (string | number)[];
+        "maxTagCount"?: number;
         /**
-          * 输入框的原生属性
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
+         */
+        "max-tag-count"?: number;
+        /**
+          * 选中项绑定值。单选为一维路径数组（如 ['zhejiang','hangzhou']）， 多选（multiple）为二维数组（如 [['zhejiang','ningbo'], ['jiangsu']]）。
+         */
+        "modelValue"?: ValuePath | ValuePath[];
+        /**
+          * 是否开启多选。开启后 modelValue 为二维数组，每条为一个选中路径； 菜单项前渲染 checkbox，输入框以 tag 列表展示选中项。
+         */
+        "multiple": boolean;
+        /**
+          * 输入框原生属性
          */
         "name"?: string;
         /**
@@ -349,13 +371,11 @@ export namespace Components {
          */
         "placeholder": string;
         /**
-          * 分隔符
-          * @default ' / '
+          * 路径分隔符
          */
         "separator": string;
         /**
-          * 是否显示完整路径
-          * @default true
+          * 是否显示完整路径（单选输入框 / 多选 tag 文本）
          */
         "showAllLevels": boolean;
         /**
@@ -473,8 +493,13 @@ export namespace Components {
          */
         "disabled": boolean;
         /**
-          * 唯一标识（手风琴模式协调用）
+          * 唯一标识（手风琴模式协调用）。 O3：推荐用 itemKey。保留 key 作为向后兼容别名（key 是 Stencil/React 保留 prop， 通过 JSX 设置时可能被 vdom 拦截；HTML 属性 key="..." 仍可工作）。
          */
+        "itemKey": string;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
+         */
+        "item-key"?: string;
         "key": string;
         /**
           * 标题
@@ -636,9 +661,9 @@ export namespace Components {
          */
         "size": 'large' | 'default' | 'small';
         /**
-          * 日期选择器类型 当前仅支持 'date'，更多类型将在后续版本实现
+          * 日期选择器类型： - 'date'：日选择（默认） - 'month'：月选择（month 视图网格，emit YYYY-MM） - 'year'：年选择（year 视图网格，emit YYYY） 注：'datetime'/'week' 请用独立的 DateTimePicker 组件 / 后续补全。
          */
-        "type": "date";
+        "type": 'date' | 'month' | 'year';
         /**
           * 显示在输入框中的格式
          */
@@ -897,7 +922,12 @@ export namespace Components {
     }
     /**
      * Dropdown 下拉菜单组件
-     * 将动作或菜单折叠到下拉菜单中
+     * 将动作或菜单折叠到下拉菜单中。
+     * 无障碍（对齐 WAI-ARIA menu / antd）：
+     * - 触发器 role=button + aria-haspopup=menu + aria-expanded
+     * - 菜单 role=menu，菜单项 role=menuitem + aria-disabled
+     * - 键盘：trigger 上 Enter/Space/↓ 打开；菜单内 ↑↓ 导航、Enter/Space 选中、Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HbDropdown {
         /**
@@ -1405,17 +1435,18 @@ export namespace Components {
     }
     /**
      * Layout 布局组件
-     * 通过基础的 24 分栏，迅速简便地创建布局
+     * 通过基础的 24 分栏，迅速简便地创建布局。
+     * 支持响应式：xs/sm/md/lg/xl 在对应断点应用各自的 span/offset/push/pull。
      */
     interface HbLayout {
         /**
-          * ≥1200px 响应式栅格数或者栅格属性对象
+          * ≥992px 响应式栅格数或者栅格属性对象
          */
-        "lg"?: number | object;
+        "lg"?: number | ColResponsive;
         /**
-          * ≥992px 响应式栅格数或者栅格属性对象
+          * ≥768px 响应式栅格数或者栅格属性对象
          */
-        "md"?: number | object;
+        "md"?: number | ColResponsive;
         /**
           * 栅格左侧的间隔格数
           * @default 0
@@ -1432,22 +1463,22 @@ export namespace Components {
          */
         "push": number;
         /**
-          * ≥768px 响应式栅格数或者栅格属性对象
+          * ≥576px 响应式栅格数或者栅格属性对象
          */
-        "sm"?: number | object;
+        "sm"?: number | ColResponsive;
         /**
           * 栅格占据的列数
           * @default 24
          */
         "span": number;
         /**
-          * ≥1920px 响应式栅格数或者栅格属性对象
+          * ≥1200px 响应式栅格数或者栅格属性对象
          */
-        "xl"?: number | object;
+        "xl"?: number | ColResponsive;
         /**
-          * <768px 响应式栅格数或者栅格属性对象
+          * <576px 响应式栅格数或者栅格属性对象
          */
-        "xs"?: number | object;
+        "xs"?: number | ColResponsive;
     }
     /**
      * Link 链接组件
@@ -1569,8 +1600,13 @@ export namespace Components {
          */
         "icon"?: string;
         /**
-          * 唯一标识
+          * 唯一标识。 O3：推荐用 itemKey。保留 key 作为向后兼容别名（key 是 Stencil/React 保留 prop， 通过 JSX 设置时可能被 vdom 拦截；HTML 属性 key="..." 仍可工作）。
+         */
+        "itemKey": string;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
          */
+        "item-key"?: string;
         "key": string;
     }
     /**
@@ -1717,6 +1753,14 @@ export namespace Components {
          */
         "total": number;
     }
+    /**
+     * Popconfirm 气泡确认框
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded + aria-describedby
+     * - 浮层 role=dialog + aria-live=polite（确认文屏幕阅读器实时播报）
+     * - 键盘：trigger Enter/Space 打开；Esc=取消关闭；打开时自动聚焦确认按钮
+     * 进出场动画：用 leaving state 延迟卸载。
+     */
     interface HbPopconfirm {
         "cancelButtonText": string;
         /**
@@ -1733,6 +1777,14 @@ export namespace Components {
         "placement": Placement;
         "title": string;
     }
+    /**
+     * Popover 气泡卡片
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded
+     * - 浮层 role=dialog + aria-labelledby（title）
+     * - 键盘：trigger 上 Enter/Space 打开/关闭；Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
+     */
     interface HbPopover {
         "disabled": boolean;
         "placement": Placement;
@@ -1981,7 +2033,11 @@ export namespace Components {
     }
     /**
      * Segmented 分段控制器组件
-     * 类似 iOS 分段控件，选中项有高亮滑块背景
+     * 类似 iOS 分段控件，选中项有高亮滑块背景。
+     * 无障碍（对齐 WAI-ARIA radiogroup / antd Segmented）：
+     * - 容器 role=radiogroup
+     * - 选项 role=radio + aria-checked + tabindex（仅选中项 tabindex=0，roving）
+     * - 键盘：←→ 在选项间移动并选中、Home/End 跳首尾
      */
     interface HbSegmented {
         /**
@@ -2126,7 +2182,7 @@ export namespace Components {
     }
     /**
      * Slider 滑块组件
-     * 通过拖动滑块在一个固定区间内进行选择
+     * 通过拖动滑块在一个固定区间内进行选择，支持单滑块/双滑块（range）/竖向/刻度。
      */
     interface HbSlider {
         /**
@@ -2142,6 +2198,10 @@ export namespace Components {
           * 高度，竖向模式时必填
          */
         "height"?: string;
+        /**
+          * 刻度标记（对齐 antd marks）
+         */
+        "marks"?: SliderMark[] | Record<number, string>;
         /**
           * 最大值
           * @default 100
@@ -2276,11 +2336,11 @@ export namespace Components {
          */
         "align-center"?: boolean;
         "direction": 'horizontal' | 'vertical';
-        "processStatus": 'wait' | 'process' | 'finish' | 'error';
+        "processStatus": StepStatus;
         /**
          * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
          */
-        "process-status"?: 'wait' | 'process' | 'finish' | 'error';
+        "process-status"?: StepStatus;
     }
     /**
      * SubMenu 子菜单
@@ -2719,7 +2779,13 @@ export namespace Components {
     }
     /**
      * Tooltip 文字提示组件
-     * 鼠标悬停或点击时显示提示文字
+     * 鼠标悬停或点击时显示提示文字。
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 aria-describedby 关联浮层 id（屏幕阅读器读出 content）
+     * - 浮层 role=tooltip
+     * - hover 触发时：focus 也显示（键盘用户可见，关键修复）
+     * - click 触发时：Enter/Space 切换；任意模式 Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HbTooltip {
         /**
@@ -3349,12 +3415,13 @@ declare global {
         new (): HTMLHbCarouselElement;
     };
     interface HTMLHbCascaderElementEventMap {
-        "hbChange": (string | number)[] | undefined;
-        "hbExpandChange": (string | number)[];
+        "hbChange": ValuePath | ValuePath[] | undefined;
+        "hbExpandChange": ValuePath;
     }
     /**
      * Cascader 级联选择器组件
-     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择
+     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
+     * 支持单选 / 多选（multiple）、可选任意层级（checkStrictly）、搜索（filterable）、动态加载（lazy）。
      */
     interface HTMLHbCascaderElement extends Components.HbCascader, HTMLStencilElement {
         addEventListener<K extends keyof HTMLHbCascaderElementEventMap>(type: K, listener: (this: HTMLHbCascaderElement, ev: HbCascaderCustomEvent<HTMLHbCascaderElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3640,7 +3707,12 @@ declare global {
     }
     /**
      * Dropdown 下拉菜单组件
-     * 将动作或菜单折叠到下拉菜单中
+     * 将动作或菜单折叠到下拉菜单中。
+     * 无障碍（对齐 WAI-ARIA menu / antd）：
+     * - 触发器 role=button + aria-haspopup=menu + aria-expanded
+     * - 菜单 role=menu，菜单项 role=menuitem + aria-disabled
+     * - 键盘：trigger 上 Enter/Space/↓ 打开；菜单内 ↑↓ 导航、Enter/Space 选中、Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HTMLHbDropdownElement extends Components.HbDropdown, HTMLStencilElement {
         addEventListener<K extends keyof HTMLHbDropdownElementEventMap>(type: K, listener: (this: HTMLHbDropdownElement, ev: HbDropdownCustomEvent<HTMLHbDropdownElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -3834,7 +3906,8 @@ declare global {
     };
     /**
      * Layout 布局组件
-     * 通过基础的 24 分栏，迅速简便地创建布局
+     * 通过基础的 24 分栏，迅速简便地创建布局。
+     * 支持响应式：xs/sm/md/lg/xl 在对应断点应用各自的 span/offset/push/pull。
      */
     interface HTMLHbLayoutElement extends Components.HbLayout, HTMLStencilElement {
     }
@@ -3987,12 +4060,28 @@ declare global {
         prototype: HTMLHbPaginationElement;
         new (): HTMLHbPaginationElement;
     };
+    /**
+     * Popconfirm 气泡确认框
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded + aria-describedby
+     * - 浮层 role=dialog + aria-live=polite（确认文屏幕阅读器实时播报）
+     * - 键盘：trigger Enter/Space 打开；Esc=取消关闭；打开时自动聚焦确认按钮
+     * 进出场动画：用 leaving state 延迟卸载。
+     */
     interface HTMLHbPopconfirmElement extends Components.HbPopconfirm, HTMLStencilElement {
     }
     var HTMLHbPopconfirmElement: {
         prototype: HTMLHbPopconfirmElement;
         new (): HTMLHbPopconfirmElement;
     };
+    /**
+     * Popover 气泡卡片
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded
+     * - 浮层 role=dialog + aria-labelledby（title）
+     * - 键盘：trigger 上 Enter/Space 打开/关闭；Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
+     */
     interface HTMLHbPopoverElement extends Components.HbPopover, HTMLStencilElement {
     }
     var HTMLHbPopoverElement: {
@@ -4093,7 +4182,11 @@ declare global {
     }
     /**
      * Segmented 分段控制器组件
-     * 类似 iOS 分段控件，选中项有高亮滑块背景
+     * 类似 iOS 分段控件，选中项有高亮滑块背景。
+     * 无障碍（对齐 WAI-ARIA radiogroup / antd Segmented）：
+     * - 容器 role=radiogroup
+     * - 选项 role=radio + aria-checked + tabindex（仅选中项 tabindex=0，roving）
+     * - 键盘：←→ 在选项间移动并选中、Home/End 跳首尾
      */
     interface HTMLHbSegmentedElement extends Components.HbSegmented, HTMLStencilElement {
         addEventListener<K extends keyof HTMLHbSegmentedElementEventMap>(type: K, listener: (this: HTMLHbSegmentedElement, ev: HbSegmentedCustomEvent<HTMLHbSegmentedElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -4147,7 +4240,7 @@ declare global {
     }
     /**
      * Slider 滑块组件
-     * 通过拖动滑块在一个固定区间内进行选择
+     * 通过拖动滑块在一个固定区间内进行选择，支持单滑块/双滑块（range）/竖向/刻度。
      */
     interface HTMLHbSliderElement extends Components.HbSlider, HTMLStencilElement {
         addEventListener<K extends keyof HTMLHbSliderElementEventMap>(type: K, listener: (this: HTMLHbSliderElement, ev: HbSliderCustomEvent<HTMLHbSliderElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -4373,7 +4466,13 @@ declare global {
     };
     /**
      * Tooltip 文字提示组件
-     * 鼠标悬停或点击时显示提示文字
+     * 鼠标悬停或点击时显示提示文字。
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 aria-describedby 关联浮层 id（屏幕阅读器读出 content）
+     * - 浮层 role=tooltip
+     * - hover 触发时：focus 也显示（键盘用户可见，关键修复）
+     * - click 触发时：Enter/Space 切换；任意模式 Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HTMLHbTooltipElement extends Components.HbTooltip, HTMLStencilElement {
     }
@@ -4845,22 +4944,28 @@ declare namespace LocalJSX {
     }
     /**
      * Cascader 级联选择器组件
-     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择
+     * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
+     * 支持单选 / 多选（multiple）、可选任意层级（checkStrictly）、搜索（filterable）、动态加载（lazy）。
      */
     interface HbCascader {
+        /**
+          * 是否严格的选中行为（父子不关联）。 单选：点击任意层级（含非叶子）即选中该路径； 多选：勾选独立，不向下联动选中叶子、取消也不联动。
+         */
+        "checkStrictly"?: boolean;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
+         */
+        "check-strictly"?: boolean;
         /**
           * 是否可清空
-          * @default false
          */
         "clearable"?: boolean;
         /**
           * 是否禁用
-          * @default false
          */
         "disabled"?: boolean;
         /**
-          * 是否动态加载子节点
-          * @default true
+          * modelValue 是否输出完整路径（保留 AntD 兼容位）
          */
         "emitPath"?: boolean;
         /**
@@ -4868,12 +4973,11 @@ declare namespace LocalJSX {
          */
         "emit-path"?: boolean;
         /**
-          * 是否可搜索（filterable） 开启后下拉顶部渲染搜索输入框，输入时按 label（含所有子级）扁平化过滤， 匹配项以完整路径展示，点击即选中其完整路径。
-          * @default false
+          * 是否可搜索（filterable）。下拉顶部渲染搜索框，输入时按 label 扁平化过滤， 匹配项以完整路径展示，点击即选中（单选）或 toggle 勾选（多选）。
          */
         "filterable"?: boolean;
         /**
-          * 输入框的原生属性
+          * 输入框原生属性
          */
         "inputId"?: string;
         /**
@@ -4881,30 +4985,41 @@ declare namespace LocalJSX {
          */
         "input-id"?: string;
         /**
-          * 是否开启动态加载（lazy load）。开启后，展开含 children=undefined 的节点时， 调用 load(node) 获取其子级并填充进 options，加载中显示 loading 态。
-          * @default false
+          * 是否开启动态加载（lazy）。展开 children=undefined 的节点时调用 load(node) 填充子级。
          */
         "lazy"?: boolean;
         /**
-          * 动态加载子节点的函数（仅在 lazy=true 时生效）。 接收被展开的节点，返回其子节点数组（Promise）。 加载结果会以不可变方式合并进 options 树（替换该节点 children）。
+          * 动态加载函数（仅 lazy=true 生效）
          */
         "load"?: (node: CascaderOption) => Promise<CascaderOption[]>;
         /**
-          * 选中项绑定值
+          * 多选时输入框最多展示的 tag 数量，超出折叠为 +N（可选）。
          */
-        "modelValue"?: (string | number)[];
+        "maxTagCount"?: number;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
+         */
+        "max-tag-count"?: number;
+        /**
+          * 选中项绑定值。单选为一维路径数组（如 ['zhejiang','hangzhou']）， 多选（multiple）为二维数组（如 [['zhejiang','ningbo'], ['jiangsu']]）。
+         */
+        "modelValue"?: ValuePath | ValuePath[];
         /**
-          * 输入框的原生属性
+          * 是否开启多选。开启后 modelValue 为二维数组，每条为一个选中路径； 菜单项前渲染 checkbox，输入框以 tag 列表展示选中项。
+         */
+        "multiple"?: boolean;
+        /**
+          * 输入框原生属性
          */
         "name"?: string;
         /**
-          * 值改变事件
+          * 值改变事件：单选 emit 一维路径或 undefined；多选 emit 二维数组（可能为 []）
          */
-        "onHbChange"?: (event: HbCascaderCustomEvent<(string | number)[] | undefined>) => void;
+        "onHbChange"?: (event: HbCascaderCustomEvent<ValuePath | ValuePath[] | undefined>) => void;
         /**
-          * 展开节点发生变化时触发
+          * 展开节点变化时触发
          */
-        "onHbExpandChange"?: (event: HbCascaderCustomEvent<(string | number)[]>) => void;
+        "onHbExpandChange"?: (event: HbCascaderCustomEvent<ValuePath>) => void;
         /**
           * 可选项数据源
          */
@@ -4914,13 +5029,11 @@ declare namespace LocalJSX {
          */
         "placeholder"?: string;
         /**
-          * 分隔符
-          * @default ' / '
+          * 路径分隔符
          */
         "separator"?: string;
         /**
-          * 是否显示完整路径
-          * @default true
+          * 是否显示完整路径（单选输入框 / 多选 tag 文本）
          */
         "showAllLevels"?: boolean;
         /**
@@ -5046,8 +5159,13 @@ declare namespace LocalJSX {
          */
         "disabled"?: boolean;
         /**
-          * 唯一标识（手风琴模式协调用）
+          * 唯一标识（手风琴模式协调用）。 O3：推荐用 itemKey。保留 key 作为向后兼容别名（key 是 Stencil/React 保留 prop， 通过 JSX 设置时可能被 vdom 拦截；HTML 属性 key="..." 仍可工作）。
+         */
+        "itemKey"?: string;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
          */
+        "item-key"?: string;
         "key"?: string;
         /**
           * 标题
@@ -5225,9 +5343,9 @@ declare namespace LocalJSX {
          */
         "size"?: 'large' | 'default' | 'small';
         /**
-          * 日期选择器类型 当前仅支持 'date'，更多类型将在后续版本实现
+          * 日期选择器类型： - 'date'：日选择（默认） - 'month'：月选择（month 视图网格，emit YYYY-MM） - 'year'：年选择（year 视图网格，emit YYYY） 注：'datetime'/'week' 请用独立的 DateTimePicker 组件 / 后续补全。
          */
-        "type"?: "date";
+        "type"?: 'date' | 'month' | 'year';
         /**
           * 显示在输入框中的格式
          */
@@ -5520,7 +5638,12 @@ declare namespace LocalJSX {
     }
     /**
      * Dropdown 下拉菜单组件
-     * 将动作或菜单折叠到下拉菜单中
+     * 将动作或菜单折叠到下拉菜单中。
+     * 无障碍（对齐 WAI-ARIA menu / antd）：
+     * - 触发器 role=button + aria-haspopup=menu + aria-expanded
+     * - 菜单 role=menu，菜单项 role=menuitem + aria-disabled
+     * - 键盘：trigger 上 Enter/Space/↓ 打开；菜单内 ↑↓ 导航、Enter/Space 选中、Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HbDropdown {
         /**
@@ -6084,17 +6207,18 @@ declare namespace LocalJSX {
     }
     /**
      * Layout 布局组件
-     * 通过基础的 24 分栏，迅速简便地创建布局
+     * 通过基础的 24 分栏，迅速简便地创建布局。
+     * 支持响应式：xs/sm/md/lg/xl 在对应断点应用各自的 span/offset/push/pull。
      */
     interface HbLayout {
         /**
-          * ≥1200px 响应式栅格数或者栅格属性对象
+          * ≥992px 响应式栅格数或者栅格属性对象
          */
-        "lg"?: number | object;
+        "lg"?: number | ColResponsive;
         /**
-          * ≥992px 响应式栅格数或者栅格属性对象
+          * ≥768px 响应式栅格数或者栅格属性对象
          */
-        "md"?: number | object;
+        "md"?: number | ColResponsive;
         /**
           * 栅格左侧的间隔格数
           * @default 0
@@ -6111,22 +6235,22 @@ declare namespace LocalJSX {
          */
         "push"?: number;
         /**
-          * ≥768px 响应式栅格数或者栅格属性对象
+          * ≥576px 响应式栅格数或者栅格属性对象
          */
-        "sm"?: number | object;
+        "sm"?: number | ColResponsive;
         /**
           * 栅格占据的列数
           * @default 24
          */
         "span"?: number;
         /**
-          * ≥1920px 响应式栅格数或者栅格属性对象
+          * ≥1200px 响应式栅格数或者栅格属性对象
          */
-        "xl"?: number | object;
+        "xl"?: number | ColResponsive;
         /**
-          * <768px 响应式栅格数或者栅格属性对象
+          * <576px 响应式栅格数或者栅格属性对象
          */
-        "xs"?: number | object;
+        "xs"?: number | ColResponsive;
     }
     /**
      * Link 链接组件
@@ -6256,8 +6380,13 @@ declare namespace LocalJSX {
          */
         "icon"?: string;
         /**
-          * 唯一标识
+          * 唯一标识。 O3：推荐用 itemKey。保留 key 作为向后兼容别名（key 是 Stencil/React 保留 prop， 通过 JSX 设置时可能被 vdom 拦截；HTML 属性 key="..." 仍可工作）。
+         */
+        "itemKey"?: string;
+        /**
+         * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
          */
+        "item-key"?: string;
         "key"?: string;
     }
     /**
@@ -6420,6 +6549,14 @@ declare namespace LocalJSX {
          */
         "total"?: number;
     }
+    /**
+     * Popconfirm 气泡确认框
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded + aria-describedby
+     * - 浮层 role=dialog + aria-live=polite（确认文屏幕阅读器实时播报）
+     * - 键盘：trigger Enter/Space 打开；Esc=取消关闭；打开时自动聚焦确认按钮
+     * 进出场动画：用 leaving state 延迟卸载。
+     */
     interface HbPopconfirm {
         "cancelButtonText"?: string;
         /**
@@ -6436,6 +6573,14 @@ declare namespace LocalJSX {
         "placement"?: Placement;
         "title"?: string;
     }
+    /**
+     * Popover 气泡卡片
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 role=button + aria-haspopup=dialog + aria-expanded
+     * - 浮层 role=dialog + aria-labelledby（title）
+     * - 键盘：trigger 上 Enter/Space 打开/关闭；Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
+     */
     interface HbPopover {
         "disabled"?: boolean;
         "placement"?: Placement;
@@ -6680,7 +6825,11 @@ declare namespace LocalJSX {
     }
     /**
      * Segmented 分段控制器组件
-     * 类似 iOS 分段控件，选中项有高亮滑块背景
+     * 类似 iOS 分段控件，选中项有高亮滑块背景。
+     * 无障碍（对齐 WAI-ARIA radiogroup / antd Segmented）：
+     * - 容器 role=radiogroup
+     * - 选项 role=radio + aria-checked + tabindex（仅选中项 tabindex=0，roving）
+     * - 键盘：←→ 在选项间移动并选中、Home/End 跳首尾
      */
     interface HbSegmented {
         /**
@@ -6837,7 +6986,7 @@ declare namespace LocalJSX {
     }
     /**
      * Slider 滑块组件
-     * 通过拖动滑块在一个固定区间内进行选择
+     * 通过拖动滑块在一个固定区间内进行选择，支持单滑块/双滑块（range）/竖向/刻度。
      */
     interface HbSlider {
         /**
@@ -6853,6 +7002,10 @@ declare namespace LocalJSX {
           * 高度，竖向模式时必填
          */
         "height"?: string;
+        /**
+          * 刻度标记（对齐 antd marks）
+         */
+        "marks"?: SliderMark[] | Record<number, string>;
         /**
           * 最大值
           * @default 100
@@ -6995,11 +7148,11 @@ declare namespace LocalJSX {
          */
         "align-center"?: boolean;
         "direction"?: 'horizontal' | 'vertical';
-        "processStatus"?: 'wait' | 'process' | 'finish' | 'error';
+        "processStatus"?: StepStatus;
         /**
          * @deprecated use camelCase instead. Support for dash-casing will be removed in Stencil v5.
          */
-        "process-status"?: 'wait' | 'process' | 'finish' | 'error';
+        "process-status"?: StepStatus;
     }
     /**
      * SubMenu 子菜单
@@ -7486,7 +7639,13 @@ declare namespace LocalJSX {
     }
     /**
      * Tooltip 文字提示组件
-     * 鼠标悬停或点击时显示提示文字
+     * 鼠标悬停或点击时显示提示文字。
+     * 无障碍（对齐 antd / WAI-ARIA）：
+     * - 触发器 aria-describedby 关联浮层 id（屏幕阅读器读出 content）
+     * - 浮层 role=tooltip
+     * - hover 触发时：focus 也显示（键盘用户可见，关键修复）
+     * - click 触发时：Enter/Space 切换；任意模式 Esc 关闭
+     * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
      */
     interface HbTooltip {
         /**
@@ -7932,7 +8091,8 @@ declare module "@stencil/core" {
             "hb-carousel": LocalJSX.HbCarousel & JSXBase.HTMLAttributes<HTMLHbCarouselElement>;
             /**
              * Cascader 级联选择器组件
-             * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择
+             * 当一个数据集合有清晰的层级结构时，可通过级联选择器逐级查看并选择。
+             * 支持单选 / 多选（multiple）、可选任意层级（checkStrictly）、搜索（filterable）、动态加载（lazy）。
              */
             "hb-cascader": LocalJSX.HbCascader & JSXBase.HTMLAttributes<HTMLHbCascaderElement>;
             /**
@@ -8006,7 +8166,12 @@ declare module "@stencil/core" {
             "hb-drawer": LocalJSX.HbDrawer & JSXBase.HTMLAttributes<HTMLHbDrawerElement>;
             /**
              * Dropdown 下拉菜单组件
-             * 将动作或菜单折叠到下拉菜单中
+             * 将动作或菜单折叠到下拉菜单中。
+             * 无障碍（对齐 WAI-ARIA menu / antd）：
+             * - 触发器 role=button + aria-haspopup=menu + aria-expanded
+             * - 菜单 role=menu，菜单项 role=menuitem + aria-disabled
+             * - 键盘：trigger 上 Enter/Space/↓ 打开；菜单内 ↑↓ 导航、Enter/Space 选中、Esc 关闭
+             * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
              */
             "hb-dropdown": LocalJSX.HbDropdown & JSXBase.HTMLAttributes<HTMLHbDropdownElement>;
             "hb-empty": LocalJSX.HbEmpty & JSXBase.HTMLAttributes<HTMLHbEmptyElement>;
@@ -8064,7 +8229,8 @@ declare module "@stencil/core" {
             "hb-input-tag": LocalJSX.HbInputTag & JSXBase.HTMLAttributes<HTMLHbInputTagElement>;
             /**
              * Layout 布局组件
-             * 通过基础的 24 分栏，迅速简便地创建布局
+             * 通过基础的 24 分栏，迅速简便地创建布局。
+             * 支持响应式：xs/sm/md/lg/xl 在对应断点应用各自的 span/offset/push/pull。
              */
             "hb-layout": LocalJSX.HbLayout & JSXBase.HTMLAttributes<HTMLHbLayoutElement>;
             /**
@@ -8111,7 +8277,23 @@ declare module "@stencil/core" {
              * 当数据量过多时，使用分页分解数据
              */
             "hb-pagination": LocalJSX.HbPagination & JSXBase.HTMLAttributes<HTMLHbPaginationElement>;
+            /**
+             * Popconfirm 气泡确认框
+             * 无障碍（对齐 antd / WAI-ARIA）：
+             * - 触发器 role=button + aria-haspopup=dialog + aria-expanded + aria-describedby
+             * - 浮层 role=dialog + aria-live=polite（确认文屏幕阅读器实时播报）
+             * - 键盘：trigger Enter/Space 打开；Esc=取消关闭；打开时自动聚焦确认按钮
+             * 进出场动画：用 leaving state 延迟卸载。
+             */
             "hb-popconfirm": LocalJSX.HbPopconfirm & JSXBase.HTMLAttributes<HTMLHbPopconfirmElement>;
+            /**
+             * Popover 气泡卡片
+             * 无障碍（对齐 antd / WAI-ARIA）：
+             * - 触发器 role=button + aria-haspopup=dialog + aria-expanded
+             * - 浮层 role=dialog + aria-labelledby（title）
+             * - 键盘：trigger 上 Enter/Space 打开/关闭；Esc 关闭
+             * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
+             */
             "hb-popover": LocalJSX.HbPopover & JSXBase.HTMLAttributes<HTMLHbPopoverElement>;
             "hb-progress": LocalJSX.HbProgress & JSXBase.HTMLAttributes<HTMLHbProgressElement>;
             /**
@@ -8141,7 +8323,11 @@ declare module "@stencil/core" {
             "hb-scrollbar": LocalJSX.HbScrollbar & JSXBase.HTMLAttributes<HTMLHbScrollbarElement>;
             /**
              * Segmented 分段控制器组件
-             * 类似 iOS 分段控件，选中项有高亮滑块背景
+             * 类似 iOS 分段控件，选中项有高亮滑块背景。
+             * 无障碍（对齐 WAI-ARIA radiogroup / antd Segmented）：
+             * - 容器 role=radiogroup
+             * - 选项 role=radio + aria-checked + tabindex（仅选中项 tabindex=0，roving）
+             * - 键盘：←→ 在选项间移动并选中、Home/End 跳首尾
              */
             "hb-segmented": LocalJSX.HbSegmented & JSXBase.HTMLAttributes<HTMLHbSegmentedElement>;
             /**
@@ -8156,7 +8342,7 @@ declare module "@stencil/core" {
             "hb-skeleton": LocalJSX.HbSkeleton & JSXBase.HTMLAttributes<HTMLHbSkeletonElement>;
             /**
              * Slider 滑块组件
-             * 通过拖动滑块在一个固定区间内进行选择
+             * 通过拖动滑块在一个固定区间内进行选择，支持单滑块/双滑块（range）/竖向/刻度。
              */
             "hb-slider": LocalJSX.HbSlider & JSXBase.HTMLAttributes<HTMLHbSliderElement>;
             /**
@@ -8227,7 +8413,13 @@ declare module "@stencil/core" {
             "hb-timeline": LocalJSX.HbTimeline & JSXBase.HTMLAttributes<HTMLHbTimelineElement>;
             /**
              * Tooltip 文字提示组件
-             * 鼠标悬停或点击时显示提示文字
+             * 鼠标悬停或点击时显示提示文字。
+             * 无障碍（对齐 antd / WAI-ARIA）：
+             * - 触发器 aria-describedby 关联浮层 id（屏幕阅读器读出 content）
+             * - 浮层 role=tooltip
+             * - hover 触发时：focus 也显示（键盘用户可见，关键修复）
+             * - click 触发时：Enter/Space 切换；任意模式 Esc 关闭
+             * 进出场动画：用 leaving state 延迟卸载，让 fade-out 有机会播放。
              */
             "hb-tooltip": LocalJSX.HbTooltip & JSXBase.HTMLAttributes<HTMLHbTooltipElement>;
             /**