@manohub/ui 1.0.4 → 1.0.6

package/dist/components/steps/index.d.ts

@@ -9,9 +9,10 @@ export interface StepsItem {
 }
 export type StepsVariant = 'node' | 'bar';
 /**
- * 跳转验证：**能不能跳到第 `index` 步**（`current` 是当前步）。
+ * 跳转验证：**能不能跳到第 `index` 步**（`current` 是当前步）。不传即「全可跳」—— 件不猜业务规则，限制由调用方
+ * 注入（如「只允许回退」= `i <= current`）。
  *
- * 不传即「全可跳」—— 件不猜业务规则，限制由调用方注入（如「只允许回退」= `i <= current`）。
+ * 用法见 `docs/demos/steps/`（每个维度一份可运行样例；文档页 `docs/components/steps.md`）。
  */
 export type CanJump = (index: number, current: number) => boolean;
 /**
@@ -19,46 +20,29 @@ export type CanJump = (index: number, current: number) => boolean;
  *
  * ## 状态怎么给
  *
- * 只认一个数：`current`（当前步下标，0 起）。**小于它的都是已完成**、大于它是未开始 —— 由本件按下标算出
+ * 只认一个数：`current`（当前步下标，0 起）—— **小于它的都是已完成**、大于它是未开始。由本件按下标算出
  * `--done` / `--current` 与连线是否 `--active`，调用方不必自己拼类名。
- *
  * 连线取「**当前步之后那一段**」为活动档（规范实测取向）：已完成步之后的连线仍是灰的，别做成"已完成段全蓝"。
  *
  * ## 两种形态的判据
  *
  * - `variant="node"`（缺省）：节点 + 同行标题 + 点线折角箭头，段长弹性 —— 步骤数少、要给每步留标题时用；
- * - `variant="bar"`：燕尾段条（定宽 140、相邻重叠 10），只有当前段是主色 —— 段数固定、像进度分段时用。
+ * - `variant="bar"`：燕尾段条（定宽 140、相邻重叠 10），只有当前段是主色 —— 段数固定时用。
  *
  * ## 可点档（`clickable`）
  *
- * 规范未演示跳步 ⇒ **缺省不可点**（连手型都不给；步的标签与类名也与老版本一致，只多一个
- * `aria-current="step"` —— 那是当前步的语义标注，与可不可点无关）。要跳转就显式开
- * `clickable`：步渲染成**原生 `<button>`**（键盘 / 焦点 / 禁用都交浏览器）。
- *
- * ### 「哪几步能跳」由调用方给（`canJump`）
- *
- * 本件**不猜业务规则**：`canJump` 缺省 `true`（每一步都可跳），要限制就注入一条判定：
- *
- * ```tsx
- * <Steps clickable :can-jump="(index, current) => index <= current" … />
- * ```
- *
- * 为什么不给内置的「前进最多一步 / 只允许后退」默认：向导的「往前走」几乎总带着前置校验
- * （扫过了吗 / 风险确认了吗），而**步骤条上的点击不会跑那些校验** —— 件若自己放开一步，
- * 就等于给了一条绕开门禁的旁路；可若定成「一律不许前进」，那又是替业务做了决定。
- * 通用件该回答的是「能不能跳」，答案让调用方给。
- *
- * 本件**不给 `beforeChange` / `onBeforeChange` 一类的钩子**：它认 `current`（受控件），件本就不自己
- * 换步，「跳转前验证」的落点是**渲染期的 `disabled`** —— 在事件里再判一次只会得到
- * 「看着可点、点了没反应」这个更差的状态。
+ * 规范未演示跳步 ⇒ **缺省不可点**（连手型都不给；步的标签与类名与老版本一致，只多一个 `aria-current="step"`
+ * —— 那是当前步的语义标注，与可不可点无关）。要跳转就显式开 `clickable`：步渲染成**原生 `<button>`**
+ * （键盘 / 焦点 / 禁用都交浏览器）。
+ * **「哪几步能跳」由调用方给（`canJump`）**：本件**不猜业务规则**，`canJump` 缺省 `true`（每一步都可跳），要
+ * 限制就注入一条判定 —— `<Steps clickable :can-jump="(index, current) => index <= current" … />`。
+ * 为什么不内置「前进最多一步 / 只允许后退」：向导的「往前走」几乎总带着前置校验，而**步骤条上的点击不会跑那些
+ * 校验** —— 件自己放开一步就等于给了一条绕开门禁的旁路；定成「一律不许前进」又是替业务做决定。
+ * 也**不给 `beforeChange` / `onBeforeChange` 一类钩子**：它认 `current`（受控件）、本就不自己换步，
+ * 「跳转前验证」的落点是**渲染期的 `disabled`**（在事件里再判一次只会得到「看着可点、点了没反应」这个更差的
+ * 状态）。
  *
  * 进度条（`Steps.Progress`）单列，用于"跑到百分之几"这类无步骤语义的场景。
- *
- * @example
- * <Steps :steps="[{title:'填单'},{title:'审批'},{title:'完成'}]" :current="1" />
- *
- * @example 燕尾段式
- * <Steps variant="bar" :steps="[{title:'支付明细'},{title:'确认'}]" :current="0" />
  */
 export declare const Steps: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 步骤表（标题 + 可选节点图标） */
@@ -81,14 +65,10 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         default: string;
     };
     /**
-     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-     *
-     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-     *
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+     * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+     * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+     * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
      * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
      */
     clickable: {
@@ -96,14 +76,10 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-     *
-     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-     *
-     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+     * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+     * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+     * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
      */
     canJump: {
         type: PropType<(index: number, current: number) => boolean>;
@@ -137,14 +113,10 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         default: string;
     };
     /**
-     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-     *
-     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-     *
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+     * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+     * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+     * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
      * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
      */
     clickable: {
@@ -152,14 +124,10 @@ export declare const Steps: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-     *
-     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-     *
-     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+     * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+     * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+     * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
      */
     canJump: {
         type: PropType<(index: number, current: number) => boolean>;
@@ -209,14 +177,10 @@ export declare const StepsCompound: {
             default: string;
         };
         /**
-         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-         *
-         * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-         * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-         *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-         * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-         * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-         *
+         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+         * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+         * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+         * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
          * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
          */
         clickable: {
@@ -224,14 +188,10 @@ export declare const StepsCompound: {
             default: boolean;
         };
         /**
-         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-         *
-         * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-         * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-         * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-         *
-         * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-         * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+         * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+         * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+         * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
          */
         canJump: {
             type: PropType<(index: number, current: number) => boolean>;
@@ -288,14 +248,10 @@ export declare const StepsCompound: {
             default: string;
         };
         /**
-         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-         *
-         * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-         * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-         *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-         * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-         * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-         *
+         * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+         * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+         * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+         * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
          * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
          */
         clickable: {
@@ -303,14 +259,10 @@ export declare const StepsCompound: {
             default: boolean;
         };
         /**
-         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-         *
-         * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-         * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-         * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-         *
-         * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-         * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+         * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+         * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+         * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+         * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
          */
         canJump: {
             type: PropType<(index: number, current: number) => boolean>;
@@ -356,14 +308,10 @@ export declare const StepsCompound: {
         default: string;
     };
     /**
-     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-     *
-     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-     *
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+     * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+     * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+     * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
      * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
      */
     clickable: {
@@ -371,14 +319,10 @@ export declare const StepsCompound: {
         default: boolean;
     };
     /**
-     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-     *
-     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-     *
-     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+     * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+     * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+     * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
      */
     canJump: {
         type: PropType<(index: number, current: number) => boolean>;

package/dist/components/steps/index.js

@@ -24,14 +24,10 @@ const Steps = /* @__PURE__ */ defineComponent({
       default: "md"
     },
     /**
-     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。
-     *
-     * 缺省 `false` —— 规范未演示跳步，件不凭空长交互。开了之后：
-     * - 步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环。
-     *   不要再靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持；
-     * - 「哪几步能跳」由 `canJump` 决定（缺省全可跳）；
-     * - 点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
-     *
+     * 步骤可点：点某步即切到该步（**节点与标题整块**都是点击区）。缺省 `false`（规范未演示跳步，件不凭空长交互）。
+     * 开了之后：步渲染成**原生 `<button type="button">`** ⇒ 键盘 Tab/Enter 可达、`:focus-visible` 有焦点环（不要再
+     * 靠 `title` 插槽自绘可点元素：那会嵌进 `<button>` 形成嵌套交互，且拿不到键盘支持）；「哪几步能跳」由
+     * `canJump` 决定（缺省全可跳）；点击发 `update:current`（可写 `v-model:current`）与 `onChange`。
      * ⚠️ 「跳转前验证」写在**渲染期**（`disabled`），不要写成点击时的事件拦截 —— 见文件头。
      */
     clickable: {
@@ -39,14 +35,10 @@ const Steps = /* @__PURE__ */ defineComponent({
       default: false
     },
     /**
-     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步）。缺省全可跳。
-     *
-     * 返回 `false` 的步会被画成禁用态（置灰 + `not-allowed`）、拦掉点击、**也不进键盘序列** ——
-     * 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着可点、点了没反应」）。
-     * 需要异步验证才能决定能不能跳时，把结果先存进状态、再据此返回。
-     *
-     * ⚠️ 它只回答「能不能跳」。若某一步是「本身不可用」（不论从哪来），也用它统一表达 ——
-     * 本件不另设行级 `disabled`，免得同一条规则散在两处。
+     * 跳转验证：**能不能跳到第 `index` 步**（第二参是当前步），缺省全可跳。返回 `false` 的步会被画成禁用态（置灰 +
+     * `not-allowed`）、拦掉点击、**也不进键盘序列** —— 判定跑在**渲染期**，不是「点了再拦」（那样只能得到「看着
+     * 可点、点了没反应」）；需要异步验证时先把结果存进状态、再据此返回。
+     * ⚠️ 它只回答「能不能跳」；若某一步是「本身不可用」（不论从哪来）也用它统一表达 —— 本件不另设行级 `disabled`。
      */
     canJump: {
       type: Function,

package/dist/components/switch/index.d.ts

@@ -3,35 +3,23 @@ import type { ControlSize } from '../control-size';
 /**
  * 开关（**自绘**，不封装 farris）。
  *
- * 统一词表（与 `Checkbox` / `Radio` 同款）：`modelValue` / `onChange` / `disabled` / `size`。
- * 三档尺寸：`sm` 28×14 / `md` 36×18（表格与列表档）/ `lg` 50×24（表单档）——
- * 几何全在样式层的 `--ui-switch-*` 令牌里，档位只覆盖令牌。`form` 是 `size="lg"` 的既有写法。
+ * 统一词表（与 `Checkbox` / `Radio` 同款）：`modelValue` / `onChange` / `disabled` / `size`。三档尺寸：`sm` 28×14 /
+ * `md` 36×18（表格与列表档）/ `lg` 50×24（表单档）—— 几何全在样式层的 `--ui-switch-*` 令牌里，档位只覆盖令牌；
+ * `form` 是 `size="lg"` 的既有写法。
  *
- * 实现要点（与 `Checkbox` 同配方）：
- * - 真实 `<input type="checkbox">` 负责可访问性与键盘（Tab / Space），视觉由轨道 + 滑块自绘；
- * - 结构固定 `input → label → track > knob`：样式层靠**通用兄弟** `~` 命中轨道（文字可夹在中间）；
- * - 选中态三源等价：原生 `:checked` / 组件下发 `data-state` / 静态档 `.is-checked`；
- * - `labelPosition` 用 flex `order` 翻转，**不改 DOM 顺序** —— 否则那条 `~` 兄弟规则立刻失效。
+ * 实现要点（与 `Checkbox` 同配方）：真实 `<input type="checkbox">` 负责可访问性与键盘（Tab / Space），视觉由轨道 +
+ * 滑块自绘；结构固定 `input → label → track > knob`，样式层靠**通用兄弟** `~` 命中轨道（文字可夹在中间）；选中态三源
+ * 等价（原生 `:checked` / `data-state` / 静态档 `.is-checked`）；`labelPosition` 用 flex `order` 翻转、**不改 DOM
+ * 顺序** —— 否则那条 `~` 兄弟规则立刻失效。
  *
  * ## 与 `Form.Item` 的关系（**同一个词别写两遍**）
+ * `label` 是**控件自己的文案**（长在根 `<label>` 里，**点它也切换开关**），而 `Form.Item` 的 `label` 是**字段名**
+ * （点它只是聚焦控件）—— 两者不是一回事，故放进表单行时**不要再传一次**：字段名归 `Form.Item`，开关只放控件本身。
+ * 正确 `<Form.Item label="启用"><Switch v-model={on} /></Form.Item>`；错误 `<Switch label="启用" />`（会显示成
+ * 「启用 启用 （开关）」，同一个词出现两遍）。只有**没有表单行**的场合（表格行内 / 工具栏 / 设置面板）才需要 `label`
+ * 自带文字，那种场景要把文字放到开关右侧就给 `labelPosition="right"`。
  *
- * `label` 是**控件自己的文案** —— 它长在根 `<label>` 里，**点它也切换开关**；
- * 而 `Form.Item` 的 `label` 是**字段名**（点它只是聚焦控件）。两者不是一回事。
- *
- * 所以放进表单行时**不要再传一次**：字段名归 `Form.Item`，开关只放控件本身。
- *
- * - 正确：`<Form.Item label="启用"><Switch v-model={on} /></Form.Item>`
- * - 错误：`<Form.Item label="启用"><Switch v-model={on} label="启用" /></Form.Item>`
- *   —— 同一行会显示成「启用 启用 （开关）」，同一个词出现两遍。
- *
- * 只有**没有表单行**的场合（表格行内 / 工具栏 / 设置面板）才需要 `label` 自己带文字；
- * 那种场景若要把文字放到开关右侧，给 `labelPosition="right"`。
- *
- * @example
- * <Switch modelValue={on} onChange={(v) => (on = v)} />
- *
- * @example 轨道内文案 + 尺寸 + 加载
- * <Switch v-model={auto} checkedText="开" uncheckedText="关" size="lg" loading={saving} />
+ * 用法见 `docs/demos/switch/`（每个维度一份可运行样例；文档页 `docs/components/switch.md`）。
  */
 export declare const Switch: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 受控开关值 */
@@ -40,10 +28,8 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         default: boolean;
     };
     /**
-     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
-     *
-     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
-     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item`
+     * 的 `label` 给，两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
      */
     label: {
         type: StringConstructor;
@@ -102,10 +88,8 @@ export declare const Switch: import("vue").DefineComponent<import("vue").Extract
         default: boolean;
     };
     /**
-     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
-     *
-     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
-     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item`
+     * 的 `label` 给，两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
      */
     label: {
         type: StringConstructor;

package/dist/components/switch/index.js

@@ -9,10 +9,8 @@ const Switch = /* @__PURE__ */ defineComponent({
       default: false
     },
     /**
-     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。
-     *
-     * ⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item` 的 `label` 给，
-     * 两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
+     * 开关**自己的文案**（点它也切换；复杂内容走默认插槽）。⚠️ 放进 `Form.Item` 时**不要传** —— 字段名由 `Form.Item`
+     * 的 `label` 给，两处写同一个词会显示成「启用 启用 （开关）」。独立使用（表格行内 / 工具栏 / 设置面板）才用它。
      */
     label: {
       type: String,

package/dist/components/tabbar/index.d.ts

@@ -34,12 +34,7 @@ export type TabBarType = 'line' | 'card';
  * 给 `more` 插槽即出「更多 ▾」页签 + 操作层浮层（原生 popover，零 JS 开合）；哪些页签收进"更多"由调用方
  * 决定 —— 收多久、收哪些是业务判断，不是皮肤能定的。
  *
- * @example 基本
- * <TabBar :options="[{label:'全部',value:'all'},{label:'进行中',value:'doing'}]" v-model:value="current" />
- *
- * @example 选项卡形态 + 可关闭可新增
- * <TabBar type="card" closable addable :options="tabs" v-model:value="current"
- *   :on-close="remove" :on-add="add" />
+ * 用法见 `docs/demos/tabbar/`（每个维度一份可运行样例；文档页 `docs/components/tabbar.md`）。
  */
 export declare const TabBar: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     options: {

package/dist/components/table/index.d.ts

@@ -13,6 +13,8 @@ export interface TableColumn {
      * - `'120px'` —— 固定宽（`fixed` 下是硬宽，**容器变窄也不收缩**，可能横向滚动）
      * - `'20%'` —— 百分比（**吃满 + 严格按比例 + 任意容器宽不溢出**，响应式首选）
      * - 不传 —— 单用时吃剩余/等分；**与 `px` 混用会被压到 0**，不建议
+   *
+   * 用法见 `docs/demos/table/`（每个维度一份可运行样例；文档页 `docs/components/table.md`）。
      */
     width?: string | number;
     align?: 'left' | 'center' | 'right';
@@ -30,11 +32,9 @@ export interface TableColumn {
      */
     wrap?: boolean;
     /**
-     * 列下限（px）：防止窄容器把该列压没。**给了才下发 `min-width`** ——
-     * ⚠️ 它**不是硬下限**：实测（Chrome）`<col>` 上的 `min-width` 会被当成**分配权重**参与按比例
-     * 分摊 —— 800 宽容器下 `width:50% + min-width:500px` 的列实测只有 **444**，不是 500。
-     * 想要真下限得换机制（该列直接给 px 硬宽，或把内容包一层带 `min-width` 的盒）。
-     * 只在调用方显式要时才下发（`<col>` 上不写时不会出现）。
+     * 列下限（px）：防止窄容器把该列压没。**给了才下发 `min-width`**（`<col>` 上不写就不会出现）。⚠️ **不是硬下限**：
+     * 实测 `<col>` 上的 `min-width` 会被当成**分配权重**参与按比例分摊 —— 800 宽容器下 `width:50% + min-width:500px`
+     * 的列只有 **444**。想要真下限得换机制（该列直接给 px 硬宽，或把内容包一层带 `min-width` 的盒）。
      */
     minWidth?: number;
     /** 必填列：表头加星号 */
@@ -61,15 +61,6 @@ export interface TableRowProps {
  * **回写是受控的**：`setValue(next)` 只把「这一格变成了什么」上报出去
  * （= 发一次 `onCellChange(row, column.key, next, index)`）。本件**从不改 `data`** ——
  * 新数组与「这次改动该不该被接受」都由调用方决定，与行选中同一套受控口径。
- *
- * @example 编辑格：套 `Form.Item` 拿错误位，控件自己绑值、回写走 `setValue`
- * <Table :columns="columns" :data="rows" row-key="id" layout="fixed" :on-cell-change="write">
- *   <template #cell="{ row, column, value, index, setValue }">
- *     <!-- 格子里的框由控件自己带：默认有框 / `:bordered="false"` 无框 / `bordered="focus"` 聚焦才显框 -->
- *     <Input v-if="column.key === 'name'" :model-value="String(value ?? '')" @change="setValue" />
- *     <template v-else>{{ value }}</template>
- *   </template>
- * </Table>
  */
 export interface TableCellSlotScope {
     row: TableRow;
@@ -80,10 +71,7 @@ export interface TableCellSlotScope {
     /** 上报该格的新值（= 发一次 `onCellChange`）；调用方没接 `onCellChange` 时是空操作 */
     setValue: (next: unknown) => void;
 }
-/**
- * 行级可勾选判定（`selectable` 的函数形态）：返回 `false` 的行渲染**禁用态**勾选框，
- * 且不进表头全选的增删范围。签名与 `onRow` / `rowClass` 一致（都给 `index`）。
- */
+/** 行级可勾选判定（`selectable` 的函数形态）：返回 `false` 的行渲染**禁用态**勾选框，且不进表头全选的增删范围；签名与 `onRow` / `rowClass` 一致（都给 `index`）。 */
 export type TableRowSelectable = (row: TableRow, index: number) => boolean;
 /** 分页档：`false` 不渲染；给对象就渲染分页条（**本件不切片，`data` 是当前页数据**） */
 export interface TablePagination {
@@ -98,49 +86,20 @@ export interface TablePagination {
  *
  * ## 这个组件负责什么、不负责什么（都是刻意的）
  *
- * **负责**：把 `columns` × `data` 渲成表格；列对齐/宽度/省略/必填；行选中（勾选列复用本包的 `Checkbox`
- * 组件 —— 它内部才是真实 `<input type="checkbox">`，故面上的 `tr:has(.mh-table__col-check input:checked)`
- * 零 JS 路径仍成立；选择器**限定在勾选列内**，否则功能列的 `Switch` 也会把整行点亮）；
- * 展开行；排序按钮的**状态与事件**；加载态与空态；分页条的排布与事件透传；
+ * **负责**：把 `columns` × `data` 渲成表格；列对齐 / 宽度 / 省略 / 必填；行选中（勾选列复用本包的
+ * `Checkbox` 组件 —— 它内部才是真实 `<input type="checkbox">`，故面上的
+ * `tr:has(.mh-table__col-check input:checked)` 零 JS 路径仍成立；选择器**限定在勾选列内**，否则功能列的
+ * `Switch` 也会把整行点亮）；展开行；排序按钮的**状态与事件**；加载态与空态；分页条的排布与事件透传；
  * `rowClass` / `onRow` 让调用方标分组行、禁用行与挂行级点击。
  *
  * **不负责**：
  *
- * - **排序与列宽拖拽的算法**：规范只给了 `↕` 字形与拖拽线这两处视觉，而 `↕` 是文字符号（本包禁拿文字
- *   符号冒充图标），故朝向改用现成字形 `chevron-up` / `chevron-down` 表达 —— 本件发 `sort` 事件、画态，
- *   真正排序、真正改列宽由调用方决定（它有数据、也知道业务口径）；
- * - **分页切片**：`pagination` 只渲染分页条并把页码事件透传出去，**`data` 始终是当前页数据** ——
- *   组件自己切片会让「服务端分页」与「客户端分页」两套口径藏在同一个 prop 里；
+ * - **排序算法归调用方**（列宽拖拽同理）：规范只给了 `↕` 字形与拖拽线两处视觉，而 `↕` 是文字符号（本包禁
+ *   拿文字符号冒充图标），故朝向改用现成字形 `chevron-up` / `chevron-down` 表达 —— 本件发 `sort` 事件、
+ *   画态，真正排序 / 改列宽由调用方决定（它有数据、也知道业务口径）；
+ * - **分页切片**：`pagination` 只渲染分页条并透传页码事件，**`data` 始终是当前页数据** —— 组件自己切片会
+ *   让「服务端分页」与「客户端分页」两套口径藏在同一个 prop 里；
  * - **错误态**：归 `QueryState`（表格只管列数据）。
- *
- * @example 基本列表（表默认满宽；列宽给权重 + `fixed` 才严格按比例）
- * <Table
- *   layout="fixed" striped row-key="id" :data="rows"
- *   :columns="[
- *     { key: 'name', title: '名称', width: 3 },
- *     { key: 'amount', title: '金额', width: 1, align: 'right' },
- *     { key: 'description', title: '描述', width: 4, wrap: true },
- *   ]"
- *   :pagination="{ total: 120, current: page, onChange: (p) => (page = p) }"
- * />
- *
- * @example 操作列（用 `actions` 插槽 + 一列 `align:'right'`；行内操作同族，`Button.Group` 收口）
- * <Table :columns="columns" :data="rows" row-key="id">
- *   {{
- *     actions: ({ row }) => (
- *       <Button.Group>
- *         <Button variant="text" onClick={() => open(row)}>编辑</Button>
- *         <Button variant="text" danger onClick={() => remove(row)}>删除</Button>
- *       </Button.Group>
- *     ),
- *   }}
- * </Table>
- *
- * @example 单元格自定义 + 按行判定可勾选
- * <Table :columns="columns" :data="rows" row-key="id" v-model="selected"
- *   :selectable="(row) => row.status === 'draft'">
- *   {{ cell: ({ value, column }) => column.key === 'status' ? <Text tone="success">{value}</Text> : value }}
- * </Table>
  */
 export declare const Table: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     columns: {
@@ -181,11 +140,8 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
-     *
-     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
-     * 要不要接受、以及新数组怎么产生，都由调用方决定。
-     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。本件**不改 `data`**（全受控、只发
+     * 事件、不排序、不切片）；要不要接受、新数组怎么产生都由调用方决定；没接这个回调时 `setValue` 是空操作。
      */
     onCellChange: {
         type: PropType<(row: TableRow, key: string, value: unknown, index: number) => void>;
@@ -350,11 +306,8 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
-     *
-     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
-     * 要不要接受、以及新数组怎么产生，都由调用方决定。
-     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。本件**不改 `data`**（全受控、只发
+     * 事件、不排序、不切片）；要不要接受、新数组怎么产生都由调用方决定；没接这个回调时 `setValue` 是空操作。
      */
     onCellChange: {
         type: PropType<(row: TableRow, key: string, value: unknown, index: number) => void>;
@@ -504,12 +457,7 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
     expandable: (row: TableRow, index: number) => VNodeChild;
     pagination: false | TablePagination;
 }, SlotsType<{
-    /**
-     * 单元格：`{ row, column, value, index, setValue }`（不给则直接输出原值）。
-     *
-     * **编辑格也走这里**（见 `TableCellSlotScope` 的说明）：本件不替调用方渲染控件，
-     * 只给值、给位置、给一个受控的回写口 `setValue`。
-     */
+    /** 单元格插槽：`{ row, column, value, index, setValue }`（不给则直接输出原值）。**编辑格也走这里** —— 本件不替调用方渲染控件，只给值、给位置、给一个受控的回写口。 */
     cell?: (context: TableCellSlotScope) => VNodeChild;
     /** 行尾操作区：`{ row, index }`（面里用 `align: 'right'` 的列承载） */
     actions?: (context: {

package/dist/components/table/index.js

@@ -44,11 +44,8 @@ const Table = /* @__PURE__ */ defineComponent({
       default: false
     },
     /**
-     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
-     *
-     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
-     * 要不要接受、以及新数组怎么产生，都由调用方决定。
-     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。本件**不改 `data`**（全受控、只发
+     * 事件、不排序、不切片）；要不要接受、新数组怎么产生都由调用方决定；没接这个回调时 `setValue` 是空操作。
      */
     onCellChange: {
       type: Function,
@@ -312,9 +309,8 @@ const Table = /* @__PURE__ */ defineComponent({
           "name": "chevron-down",
           "class": "mh-table__expand-icon"
         }, null)])]) : null, hasSelectColumn.value ? (
-          /* 勾选列复用 `Checkbox`（不在表格里手写原生 input）。行本身可能带 onClick（onRow）：
-             勾选不该顺带触发行点击 —— 阻断挂在**单元格**上，因为 `Checkbox` 的根是 `label`，
-             点它会冒泡两次（label 自身一次 + 转发给 input 一次），只挡 input 挡不住行点击。
+          /* 勾选列复用 `Checkbox`（不手写原生 input）。行本身可能带 `onRow` 的 onClick：勾选不该顺带触发行
+             点击 —— 阻断挂在**单元格**上（`Checkbox` 的根是 `label`，点它会冒泡两次，只挡 input 挡不住）。
              `selectable` 为函数时逐行判定：返回 `false` 的行给禁用态（置灰 + not-allowed）。 */
           createVNode("td", {
             "class": "mh-table__col-check",