@done-coding/admin-core 0.17.1-alpha.0 → 0.18.1-alpha.0

package/types/components/display/TabsTile.vue.d.ts

@@ -2,12 +2,19 @@ import { nextTick } from 'vue';
 import { TabsMainItem, TabsMainTileNavMode, TabsMainTileNavPosition } from './types';
 type __VLS_Props = {
     tabs: TabsMainItem[];
+    /** 精细化布局:true 卡片在有界容器内滚(容器高 = channel 视口高度) */
     refine?: boolean;
+    /** px,视口可用高度(refine=true 时算容器高用);链路同 TabsMain */
     viewportHeight?: number;
+    /** px,容器高度兜底下限 */
     minHeight?: number;
+    /** 作为子时要消费的父通道标识(refine 高度链路,透传给 useChannelViewportHeight) */
     parentChannel?: string;
+    /** 角落 nav 落角 */
     navPosition?: TabsMainTileNavPosition;
+    /** 角落 nav 定位模式;auto 按 refine 选(refine→absolute / 自然→sticky) */
     navMode?: TabsMainTileNavMode;
+    /** 角落 nav 距角像素 */
     navOffset?: number;
 };
 type __VLS_PublicProps = {
@@ -37,7 +44,26 @@ declare function __VLS_template(): {
                 readonly direction?: "vertical" | "horizontal" | undefined;
                 readonly selectScrollTop?: boolean | undefined;
                 readonly onChange?: ((href: string) => any) | undefined | undefined;
-                readonly onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined | undefined;
+                readonly onClick?: ((e: MouseEvent, href
+                /**
+                 * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+                 *
+                 * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+                 * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+                 *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+                 *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+                 * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+                 *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+                 *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+                 * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+                 *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+                 * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+                 *
+                 * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+                 * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+                 * 无单一"可用视口高度"语义)。
+                 */
+                ?: string | undefined) => any) | undefined | undefined;
             } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps;
             $attrs: import('vue').Attrs;
             $refs: {
@@ -53,12 +79,69 @@ declare function __VLS_template(): {
             $el: any;
             $options: import('vue').ComponentOptionsBase<Readonly<import('element-plus').AnchorProps> & Readonly<{
                 onChange?: ((href: string) => any) | undefined;
-                onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined;
+                onClick?: ((e: MouseEvent, href
+                /**
+                 * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+                 *
+                 * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+                 * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+                 *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+                 *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+                 * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+                 *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+                 *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+                 * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+                 *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+                 * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+                 *
+                 * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+                 * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+                 * 无单一"可用视口高度"语义)。
+                 */
+                ?: string | undefined) => any) | undefined;
             }>, {
-                scrollTo: (href?: string) => void;
+                scrollTo: (href
+                /**
+                 * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+                 *
+                 * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+                 * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+                 *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+                 *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+                 * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+                 *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+                 *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+                 * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+                 *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+                 * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+                 *
+                 * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+                 * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+                 * 无单一"可用视口高度"语义)。
+                 */
+                ?: string) => void;
             }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
                 change: (href: string) => void;
-                click: (e: MouseEvent, href?: string | undefined) => void;
+                click: (e: MouseEvent, href
+                /**
+                 * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+                 *
+                 * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+                 * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+                 *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+                 *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+                 * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+                 *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+                 *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+                 * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+                 *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+                 * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+                 *
+                 * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+                 * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+                 * 无单一"可用视口高度"语义)。
+                 */
+                ?: string | undefined) => void;
             }, string, {
                 offset: number;
                 type: "default" | "underline";
@@ -95,9 +178,47 @@ declare function __VLS_template(): {
             bound: number;
         }> & Omit<Readonly<import('element-plus').AnchorProps> & Readonly<{
             onChange?: ((href: string) => any) | undefined;
-            onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined;
+            onClick?: ((e: MouseEvent, href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string | undefined) => any) | undefined;
         }>, "type" | "marker" | "offset" | "bound" | "duration" | "direction" | "scrollTo"> & {
-            scrollTo: (href?: string) => void;
+            scrollTo: (href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string) => void;
         } & {} & import('vue').ComponentCustomProperties & {} & {
             $slots: {
                 default?: (props: {}) => any;
@@ -132,7 +253,26 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
             readonly direction?: "vertical" | "horizontal" | undefined;
             readonly selectScrollTop?: boolean | undefined;
             readonly onChange?: ((href: string) => any) | undefined | undefined;
-            readonly onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined | undefined;
+            readonly onClick?: ((e: MouseEvent, href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string | undefined) => any) | undefined | undefined;
         } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps;
         $attrs: import('vue').Attrs;
         $refs: {
@@ -148,12 +288,69 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
         $el: any;
         $options: import('vue').ComponentOptionsBase<Readonly<import('element-plus').AnchorProps> & Readonly<{
             onChange?: ((href: string) => any) | undefined;
-            onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined;
+            onClick?: ((e: MouseEvent, href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string | undefined) => any) | undefined;
         }>, {
-            scrollTo: (href?: string) => void;
+            scrollTo: (href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string) => void;
         }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
             change: (href: string) => void;
-            click: (e: MouseEvent, href?: string | undefined) => void;
+            click: (e: MouseEvent, href
+            /**
+             * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+             *
+             * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+             * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+             *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+             *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+             * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+             *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+             *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+             * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+             *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+             * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+             *
+             * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+             * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+             * 无单一"可用视口高度"语义)。
+             */
+            ?: string | undefined) => void;
         }, string, {
             offset: number;
             type: "default" | "underline";
@@ -190,9 +387,47 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
         bound: number;
     }> & Omit<Readonly<import('element-plus').AnchorProps> & Readonly<{
         onChange?: ((href: string) => any) | undefined;
-        onClick?: ((e: MouseEvent, href?: string | undefined) => any) | undefined;
+        onClick?: ((e: MouseEvent, href
+        /**
+         * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+         *
+         * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+         * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+         *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+         *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+         * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+         *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+         *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+         * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+         *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+         * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+         *
+         * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+         * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+         * 无单一"可用视口高度"语义)。
+         */
+        ?: string | undefined) => any) | undefined;
     }>, "type" | "marker" | "offset" | "bound" | "duration" | "direction" | "scrollTo"> & {
-        scrollTo: (href?: string) => void;
+        scrollTo: (href
+        /**
+         * TabsTile —— TabsMain 平铺(tile)模式渲染分支(仅 TabsMain 内部经 `v-if=tile` 消费,不对外单独发布)。
+         *
+         * 平铺:所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,改由角落 nav 导航。
+         * - 导航 + scrollspy + 聚焦滚动全托付 **ElAnchor**:点 nav 平滑滚到卡(ElAnchor rAF animateScrollTo,
+         *   不被组件重渲染打断——手写原生 `scrollIntoView({behavior:"smooth"})` 经 v-model 回流重渲染会被打断);
+         *   手动滚 → ElAnchor `@change` 反写激活 tab(内建 isScrolling 闸,程序化滚动期不抖动)。
+         * - 卡片挂稳定 DOM id(`paneId`,锚点靶),ElAnchorLink `href="#id"`。model ↔ 锚点双向:
+         *   `@change`(scrollspy)→ 写 model;model 外部变(深链 / 父程序化)→ `anchorRef.scrollTo` 程序化定位。
+         *   `fromAnchor` 闸区分二者,避免 scrollspy 反写又触发回滚。
+         * - 滚动模型跟 refine:refine=true → 卡片在有界容器(高 = channel 视口可用高度)内滚,ElAnchor container
+         *   指向该容器;refine=false → 页面滚(container=window)。nav 角落定位(navMode/navPosition)是本组件自有壳。
+         * - 槽转发沿用 TabsMain 既有中转:内容 `#{key}` / 标题 `#header-{key}`,优先级同非平铺路径。
+         *
+         * 与 TabsMain 非平铺路径(TabsRefineFlow/NaturalFlow + TabPane + KeepAlive 单 pane)是平行分支:
+         * 平铺全渲染所有卡(弃 KeepAlive、all mount),故内容槽 scope 不带 viewportHeight(每卡独立自然流,
+         * 无单一"可用视口高度"语义)。
+         */
+        ?: string) => void;
     } & {} & import('vue').ComponentCustomProperties & {} & {
         $slots: {
             default?: (props: {}) => any;

package/types/components/display/WatchSize.vue.d.ts

@@ -1,6 +1,15 @@
 type __VLS_Props = {
     mode?: "height" | "width" | "both";
+    /**
+     * 是否用 ResizeObserver 观测自身盒尺寸（默认 false）。
+     * 默认时机 = 激活首测 + window resize + onUpdated（激活态重渲染补测）——已覆盖
+     * 「伴随本组件重渲染的尺寸变化」（v-if / 响应式样式 / 槽内容随父状态变化等常规场景）。
+     * 测不到「不触发本组件重渲染的尺寸变化」：内容 CSS 过渡（如侧栏折叠动画，onUpdated
+     * 读到过渡起点漏终值）、异步内容撑开、槽内后代组件自更新——此类场景显式开启 RO
+     * （AppPage 四向槽已内置开启，右槽 CSS 过渡折叠不重算即此坑）。
+     */
     observeResize?: boolean;
+    /** 防抖时间（默认 16ms）。只接受初始值，后面变化不更新。 */
     debounceTime?: number;
 };
 declare function __VLS_template(): {

package/types/components/display/index.d.ts

@@ -5,5 +5,41 @@ import { default as ActionBtn } from './ActionBtn.vue';
 import { default as ActionConfirm } from './ActionConfirm.vue';
 import { default as ActionBtnGroup } from './ActionBtnGroup.vue';
 import { default as BooleanTag } from './BooleanTag.vue';
-export { WatchSize, TabsMain, HeightProvider, ActionBtn, ActionConfirm, ActionBtnGroup, BooleanTag, };
+export { 
+/** 尺寸监听容器：debounce 测默认槽内容宽/高，派发 `@height-change` / `@size-change` */
+WatchSize, 
+/**
+ * Tab 容器：手写 tab-bar + 滑动下划线 + 懒渲染 KeepAlive。
+ * 嵌套联动用 `channel="x"` / `parentChannel="x"` 字符串显式配对（[MUST NOT] 响应式）。
+ */
+TabsMain, 
+/**
+ * 纯数值高度预算节点：`available = max(viewportHeight - reserve, minHeight ?? 0)`，
+ * 默认槽 `{ height }` 暴露。Fragment 双根，不撑开自身，不 inject 不 provide。
+ * 消费方 [MUST] 用 slot scope `:height` 自设容器高。
+ */
+HeightProvider, 
+/**
+ * ElButton 超集按钮原语：透传全 ElButton props + 默认槽 label + `confirmConfig`
+ * 确认闸门 + `beforeOpen` 异步预取 + onClick 返 Promise 自动 loading（内部接管）。
+ */
+ActionBtn, 
+/**
+ * confirm 原语（扁平，可独立于 ActionBtn 消费）：触发元素由默认 slot 提供，
+ * 弹层可见性 `v-model:show` 声明式驱动；`submitFn` 返 Promise 时仅成功才关弹层。
+ */
+ActionConfirm, 
+/**
+ * 配置式按钮组（泛型 Ctx 由消费方决定形状）。
+ * - 二选一渲染：`actionBtnProps`（走 ActionBtn 带 confirm/beforeOpen）优先 / `props`（走 ElButton）。
+ * - `render` 对标 FormItem.render 三态：string | Component | (props:{ctx})=>VNode。
+ * - `show` 函数过滤；`defaultSize` 给基础 size，业务侧显式 size 优先。
+ * - 典型消费：TableMain.toolbar 内置 / 表格 OPERATE 列（BL-5 推广）。
+ */
+ActionBtnGroup, 
+/**
+ * boolean 只读展示为彩色标签（纯展示，无交互）：`value` → active/inactive 文本 + ElTag 色彩。
+ * 编辑布尔用 ElSwitch；[MUST NOT] 给展示标签挂 onClick toggle 改数据（展示≠编辑，详见 paradigm §9）。
+ */
+BooleanTag, };
 export * from './types';

package/types/components/display/types.d.ts

@@ -1,78 +1,241 @@
 import { Component, VNode } from 'vue';
 import { ButtonProps, TagProps } from 'element-plus';
+/** ActionConfirm 确认交互形态：弹层气泡 / 居中模态框 */
 export type ActionConfirmMode = "popconfirm" | "messageConfirm";
+/**
+ * ActionConfirm 文案解析器。
+ * - string：直接渲染
+ * - 无参函数：返回字符串或 VNode 数组（富文本）；动态数据由调用方闭包捕获
+ */
 export type ActionConfirmTextResolver = string | (() => string | VNode[]);
+/**
+ * ActionBtn 的确认配置（嵌套对象；无此配置则为普通按钮，不触发确认）。
+ *
+ * ⚠️ 瞬时用户激活限制：`confirmConfig` 与 `beforeOpen` 均会异步打断点击的瞬时
+ * 用户激活窗口（transient user activation）——confirm 后 / beforeOpen 之后的
+ * handler 与原始点击之间隔了一次异步等待，原始激活此时已过期（注意：事件对象
+ * `isTrusted` 仍为 true，失效的是激活窗口而非事件本身）。故 confirm 后 /
+ * beforeOpen 之后的 handler [MUST NOT] 调用依赖瞬时用户激活的 API——
+ * `window.open`、`navigator.clipboard.*`、`requestFullscreen` 等会被浏览器
+ * 拦截。需要这类操作时改用无 `confirmConfig` 且无 `beforeOpen` 的 ActionBtn /
+ * 普通按钮。此为 confirm-gate / async-prefetch 模式固有代价，组件层无法绕过。
+ */
 export interface ActionBtnConfirmConfig {
+    /** 确认标题 */
     title?: ActionConfirmTextResolver;
+    /** 确认正文内容 */
     content?: ActionConfirmTextResolver;
+    /** 确认按钮文案，默认"确定" */
     confirmText?: string;
+    /** 取消按钮文案，默认"取消" */
     cancelText?: string;
+    /** 确认按钮 type */
     type?: ButtonProps["type"];
 }
+/**
+ * ActionBtn 组件 props。
+ * 完全兼容 ElButton（继承 ButtonProps），仅一处改写 + 三个增量：
+ * - `loading` 被 Omit：有意的 ElButton 不兼容，唯一接管项——loading 由组件内部
+ *   独占，对接异步 confirm / beforeOpen 的进行态（innerLoading），对外不可设置。
+ * - `disabled` 原生透传，不改写不扩展。
+ * - 增量：`confirmMode` / `confirmConfig` / `beforeOpen`。
+ * - 泛型 `T`：由 `beforeOpen` 返回值反推，并透传给 `confirmConfig` 函数形态的
+ *   入参；未传 `beforeOpen` 时默认 `T = void`，函数形态的 `data = undefined`。
+ */
 export type ActionBtnProps<T = void> = Omit<ButtonProps, "loading"> & {
+    /** 确认交互形态，仅在 confirmConfig 存在时生效，默认 "popconfirm" */
     confirmMode?: ActionConfirmMode;
+    /**
+     * 确认配置；存在时点击需经确认闸门，确认后才触发 click。
+     * - 对象形态：静态确认配置（向后兼容）。
+     * - 函数形态：`(data: T) => ActionBtnConfirmConfig`，`data` 来自 `beforeOpen`
+     *   返回值；无 `beforeOpen` 时 `data = undefined`（T 默认 `void`）。
+     */
     confirmConfig?: ActionBtnConfirmConfig | ((data: T) => ActionBtnConfirmConfig);
+    /**
+     * 点击后、弹层前的异步预取钩子。
+     * - 返回值类型 `T` 反推给 `confirmConfig` 函数形态的入参。
+     * - 失败时静默退出（不弹层、不触发 `@click` handler）；调用方 [MUST] 在内部
+     *   自行 catch 并显示反馈（如 `ElMessage.error`），忘记 catch 会"点了没反应"。
+     * - 期间按钮显 loading 态（`innerLoading`）；同 `confirmConfig` 一样消耗
+     *   瞬时用户激活（详见 {@link ActionBtnConfirmConfig} 顶部注释）。
+     */
     beforeOpen?: () => Promise<T>;
 };
+/**
+ * ActionConfirm 组件 props（扁平，confirm 原语；可独立于 ActionBtn 消费）。
+ * 触发元素由默认 slot 提供；弹层可见性由 `v-model:show` 声明式驱动。
+ */
 export interface ActionConfirmProps {
+    /** 确认交互形态 */
     mode: ActionConfirmMode;
+    /** 确认标题 */
     title?: ActionConfirmTextResolver;
+    /** 确认正文内容 */
     content?: ActionConfirmTextResolver;
+    /** 确认按钮文案，默认"确定" */
     confirmText?: string;
+    /** 取消按钮文案，默认"取消" */
     cancelText?: string;
+    /** 确认按钮 type */
     type?: ButtonProps["type"];
+    /**
+     * 点击确认后调用。返回 Promise 时确认按钮 loading + 弹层保持不关，
+     * **仅成功（fulfill）才关闭弹层**；失败（reject 或同步 throw）时清 loading、
+     * 弹层保持打开，错误由 `submitFn` 内部自行 catch 反馈。
+     */
     submitFn: () => void | Promise<void>;
 }
+/** ActionBtnGroup 按钮 size 枚举(对齐 element-plus ElButton size) */
 export type ActionBtnSize = "large" | "default" | "small";
+/**
+ * ActionBtnGroup 单项配置
+ * ---
+ * 泛型 Ctx 由消费方决定形状(toolbar 传 ToolbarButtonContext / 表格 OPERATE 列传 row 上下文 / 等)。
+ * 与 FormItem.render 三态对标:string(全局组件名)/ Component(对象/异步)/ functional((props) => VNode)。
+ */
 export interface ActionBtnConfigItem<Ctx = void> {
+    /** 唯一标识 */
     key: string;
+    /** ActionBtn props 工厂(含 confirmConfig / beforeOpen / ElButton 全透传),与 props 二选一优先 */
     actionBtnProps?: (ctx: Ctx) => Record<string, any>;
+    /** ElButton props 工厂,与 actionBtnProps 二选一 */
     props?: (ctx: Ctx) => Record<string, any>;
+    /** 按钮文字;render 缺省时回退 */
     label?: string;
+    /**
+     * 按钮内容 render(对标 FormItem.render 三态);优先级高于 label。
+     * - string:全局注册组件名
+     * - Component:对象/异步组件
+     * - functional:`(props: { ctx }) => VNode`——通过 `:ctx` prop 拿到上下文
+     */
     render?: string | Component | ((props: {
         ctx: Ctx;
     }) => VNode);
+    /** 显示条件,返回 false 跳过该项;缺省视为 true */
     show?: (ctx: Ctx) => boolean;
 }
+/** ActionBtnGroup props */
 export interface ActionBtnGroupProps<Ctx = void> {
+    /** 按钮配置列表 */
     configs?: ActionBtnConfigItem<Ctx>[];
+    /** 渲染上下文(透传给每项 actionBtnProps / props / render / show) */
     ctx: Ctx;
+    /**
+     * 默认按钮 size——未传时不强加 size(沿用 ElButton 自身默认);
+     * 传入时作为基础 size 注入每项,业务侧 actionBtnProps / props 返回对象内显式 size 优先。
+     */
     defaultSize?: ActionBtnSize;
 }
+/** HeightProvider props——见组件 JSDoc */
 export interface HeightProviderProps {
+    /** px，视口可用高度（必填） */
     viewportHeight: number;
+    /** px，默认槽可用高度兜底下限；超 viewportHeight 时会撑破父容器（有意设计） */
     minHeight?: number;
 }
+/** TabsMain 单个 tab 项配置 */
 export interface TabsMainItem {
+    /** 唯一标识，v-model 值与槽名（#{key} / #header-{key}）以此为准 */
     key: string;
+    /** 标题文本，#header-{key} 槽缺省时回退 */
     title: string;
+    /** 内容组件，#{key} 槽缺省时回退渲染 */
     component?: Component;
 }
+/** [top, right, bottom, left] px——TabsMain 默认插槽容器内置 padding（top+bottom 同步从 channel viewportHeight 扣减） */
 export type TabsMainPadding = [number, number, number, number];
+/**
+ * TabsHeader 视觉风格变体(与 level 字号解耦)。
+ * - card:浏览器 tabs 风格(active 三面 border + 两侧 100vw separator,真打通)
+ * - indicator:标准 2px 下划线
+ * - indicator-compact:紧凑 1px 下划线
+ * - plain:无装饰(active 加粗 + primary 字色)
+ */
 export type TabsHeaderVariant = "card" | "indicator" | "indicator-compact" | "plain";
+/**
+ * 平铺(tile)模式角落 nav 的落角。
+ * 四角由 `bottom/top` × `left/right` 组合，配合 `navOffset` 距角像素。
+ */
 export type TabsMainTileNavPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/**
+ * 平铺(tile)模式角落 nav 的定位模式。
+ * - `absolute`:相对 TabsTile 根定位——内层滚、nav 不动留在根的角(有界滚动容器最干净)。
+ * - `sticky`:`position:sticky` 贴滚动视口角——页面滚时粘在 TabsMain 列内的角(不先入为主接管整个视口)。
+ * - `fixed`:相对**视口**角(消费方显式要才用的逃生口)。
+ * - `auto`(默认):`refine=true`→`absolute`；`refine=false`→`sticky`。
+ */
 export type TabsMainTileNavMode = "auto" | "absolute" | "sticky" | "fixed";
+/**
+ * TabsMain props。
+ *
+ * 高度优先级：viewportHeight > inject `SCOPE_VIEWPORT_MAX_HEIGHT` scope 链（parentChannel 定向 / 就近）> 0。
+ * channel / parentChannel [MUST NOT] 响应式变更（setup 期快照，变更 console.error 忽略）。
+ */
 export interface TabsMainProps {
+    /** tab 配置列表 */
     tabs: TabsMainItem[];
+    /** px，视口可用高度（显式指定，优先级最高）；未传时降级 SCOPE_VIEWPORT_MAX_HEIGHT scope 链 */
     viewportHeight?: number;
+    /** px，默认内容区高度兜底下限 */
     minHeight?: number;
+    /** 作为父时的 scope 标识（进 SCOPE_VIEWPORT_MAX_HEIGHT 对象链的 scope 字段） */
     channel?: string;
+    /** 作为子时要定向消费的祖先 scope 标识（沿对象链 parent 找 scope === parentChannel） */
     parentChannel?: string;
+    /** 默认插槽容器内置 padding [top,right,bottom,left]，默认 [10,0,0,0]；top+bottom 同步从 slot scope/channel viewportHeight 扣减 */
     padding?: TabsMainPadding;
+    /** 精细化布局:false(默认) 不包 HeightProvider,默认槽 viewportHeight 直接给 viewportHeightFinal(不扣减),业务自然流;true 走 HeightProvider 精确扣 header reserve + padding 给 available */
     refine?: boolean;
+    /** 精细化预留高度(px),从 viewportHeightFinal 中预扣,refine=false 时同样生效 */
     refineReduceHeight?: number;
+    /** 显式指定 TabsHeader 视觉风格,不传则按 visualLevel 推导默认(L1=card / L2=indicator / L3=indicator-compact / L4=plain)。字号始终跟随 level,不受 variant 影响。 */
     variant?: TabsHeaderVariant;
+    /**
+     * 把当前激活 tab(v-model)同步到路由 URL query 的 key 名。
+     * - 传了即启用**双向同步**：切 tab → `router.replace` 写 `?{queryKey}={tab.key}`(不压历史栈、只增删自己这个 key、不动其它 query);
+     *   进入/刷新/前进后退 → query 反向恢复激活 tab。
+     * - 不传(默认)→ 不同步。
+     * - 无 vue-router 环境(useRouter 返回 undefined)→ 静默失效,不接线。
+     * - query 值非法/无对应 tab → 交由 v-model 既有归一(回退 tabs[0]),不强写。
+     */
     queryKey?: string;
+    /**
+     * 平铺模式:把所有 tab item 同时铺开成一列卡片(各裹 ElCard、标题进卡头),隐藏 tab-bar,
+     * 改由角落 nav 导航;聚焦(v-model / 点 nav)= 滚动该卡到视口,手动滚 = scrollspy 反写激活 tab。
+     * - 默认 `false`:tabs 路径逐字不动(平铺是 `v-if` 平行分支,不影响既有行为)。
+     * - `refine=true` 时卡片在有界容器内滚(容器高 = refine 可用高度);`refine=false` 页面滚。
+     */
     tile?: boolean;
+    /**
+     * 平铺模式角落 nav 落角,默认 `"bottom-right"`。仅 `tile=true` 生效。
+     */
     navPosition?: TabsMainTileNavPosition;
+    /**
+     * 平铺模式角落 nav 定位模式,默认 `"auto"`(refine→absolute / 自然流→sticky)。仅 `tile=true` 生效。
+     * 见 {@link TabsMainTileNavMode}。
+     */
     navMode?: TabsMainTileNavMode;
+    /**
+     * 平铺模式角落 nav 距角像素,默认 `12`。仅 `tile=true` 生效。
+     */
     navOffset?: number;
 }
+/** BooleanTag 标签色彩类型（派生 ElTag type，不重定义） */
 export type BooleanTagType = NonNullable<TagProps["type"]>;
+/**
+ * BooleanTag props——boolean 只读展示为彩色标签（纯展示，无交互 / 无 v-model）。
+ * enum / number 状态在调用点一行映射为 boolean 传入（组件保持 boolean 纯粹）。
+ */
 export interface BooleanTagProps {
+    /** 待展示布尔值 */
     value: boolean;
+    /** true 时标签文本，默认「是」 */
     activeText?: string;
+    /** false 时标签文本，默认「否」 */
     inactiveText?: string;
+    /** true 时标签色彩（派生 ElTag type），默认 success */
     activeTagType?: BooleanTagType;
+    /** false 时标签色彩，默认 info */
     inactiveTagType?: BooleanTagType;
 }