@manohub/ui 1.0.5 → 1.0.8

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: {