@manohub/ui 0.6.1 → 0.7.1

package/dist/index.d.ts

@@ -21,12 +21,13 @@ export { Card, type CardProps, type CardVariant, type CardPadding, type CardHead
 export { Divider, type DividerProps } from './components/divider';
 export { Nav, type NavVariant } from './components/nav';
 export { Collapse, type CollapseProps, type CollapseCompound } from './components/collapse';
-export { Tabset, type TabsetOption, type TabsetProps } from './components/tabset';
+export { TabPanel, Tabs, type TabPanelProps, type TabsOption, type TabsProps } from './components/tabs';
 export { Layout, type LayoutGap, type LayoutAlign, type LayoutJustify, type LayoutColumns, type LayoutSpan, } from './components/layout';
 export { Avatar, type AvatarProps, type AvatarSize, type AvatarCompound } from './components/avatar';
 export { Skeleton, type SkeletonProps } from './components/skeleton';
 export { Radio, type RadioProps, type RadioCompound, type RadioCompoundType, type RadioCardItem, type RadioCardValue, } from './components/radio';
 export { Tag, type TagProps } from './components/tag';
+export { Text, type TextProps, type TextSize, type TextTone, type TextWeight, type TextTag, } from './components/text';
 export { Tree, type TreeNode } from './components/tree';
 export { ListView, type ListViewProps, type ListViewStatus, type ListViewStatusTone, type ListViewCardItemProps, type ListViewCompound, } from './components/list-view';
 export { Badge, type BadgeTone, type BadgeShape, type BadgeSize, type BadgeDot, type BadgeStatus, } from './components/badge';
@@ -36,7 +37,7 @@ export { Search, type SearchProps } from './components/search';
 export { Select, type SelectOption, type SelectValue } from './components/select';
 export { Switch } from './components/switch';
 export { Capsule, type CapsuleOption, type CapsuleShape } from './components/capsule';
-export { Form, type FormProps, type FormHeaderProps, type FormItemProps, type FormValues, type FormItemSlotScope, type FormLabelAlign, type FormPadding, type FormCompound, } from './components/form';
+export { Form, type FormProps, type FormHeaderProps, type FormItemProps, type FormValues, type FormItemSlotScope, type FormItemAlign, type FormLabelAlign, type FormColumns, type FormPadding, type FormCompound, } from './components/form';
 export { Checkbox, type CheckboxOption, type CheckboxCompound, type CheckboxCompoundType, } from './components/checkbox';
 export { Filter, FilterItem, FILTER_ALL, normalizeFilterValue, type FilterValue, type FilterValues, type FilterProps, type FilterItemProps, type FilterItemSlotScope, type FilterCompound, } from './components/filter';
 export { Notice, type NoticeTone } from './components/notice';
@@ -44,10 +45,10 @@ export { Notification, type NotificationTone, } from './components/notification'
 export { Dialog, type DialogWidth } from './components/dialog';
 export { Drawer, type DrawerSide } from './components/drawer';
 export { Tooltip, type TooltipSide, type TooltipAlign, } from './components/tooltip';
-export { Table, type TableColumn, type TableRow, type TableSortOrder, } from './components/table';
+export { Table, type TableColumn, type TableRow, type TableRowSelectable, type TableSortOrder, } from './components/table';
 export { Pagination, type PaginationPageItem } from './components/pagination';
-export { Tabs, type TabsOption, type TabsValue } from './components/tabs';
-export { Steps, type StepsItem, type StepsVariant, type StepsCompound, type StepsCompoundType, } from './components/steps';
+export { TabBar, type TabBarOption, type TabBarValue } from './components/tabbar';
+export { Steps, type CanJump, type StepsItem, type StepsVariant, type StepsCompound, type StepsCompoundType, } from './components/steps';
 export { Toast, type ToastTone, type ToastCompound, type ToastCompoundType, } from './components/toast';
 export { Code } from './components/code';
 export { CodeEditor, type CodeEditorProps, type CodeEditorAutoSize, } from './components/code-editor';

package/dist/index.js

@@ -4,12 +4,13 @@ import { Card } from "./components/card/index.js";
 import { Divider } from "./components/divider/index.js";
 import { Nav } from "./components/nav/index.js";
 import { Collapse } from "./components/collapse/index.js";
-import { Tabset } from "./components/tabset/index.js";
+import { TabPanel, Tabs } from "./components/tabs/index.js";
 import { Layout } from "./components/layout/index.js";
 import { Avatar } from "./components/avatar/index.js";
 import { Skeleton } from "./components/skeleton/index.js";
 import { Radio } from "./components/radio/index.js";
 import { Tag } from "./components/tag/index.js";
+import { Text } from "./components/text/index.js";
 import { Tree } from "./components/tree/index.js";
 import { ListView } from "./components/list-view/index.js";
 import { Badge } from "./components/badge/index.js";
@@ -29,7 +30,7 @@ import { Drawer } from "./components/drawer/index.js";
 import { Tooltip } from "./components/tooltip/index.js";
 import { Table } from "./components/table/index.js";
 import { Pagination } from "./components/pagination/index.js";
-import { Tabs } from "./components/tabs/index.js";
+import { TabBar } from "./components/tabbar/index.js";
 import { Steps } from "./components/steps/index.js";
 import { Toast } from "./components/toast/index.js";
 import { Code } from "./components/code/index.js";
@@ -76,10 +77,12 @@ export {
   Skeleton,
   Steps,
   Switch,
+  TabBar,
+  TabPanel,
   Table,
   Tabs,
-  Tabset,
   Tag,
+  Text,
   Textarea,
   Toast,
   Tooltip,

package/dist/services/dialog.d.ts

@@ -1,13 +1,21 @@
+import { type DialogTone } from '../components/dialog';
 export interface ConfirmOptions {
     /** 标题（缺省不渲染页头，只剩内容与底栏） */
     title?: string;
     /** 正文（纯文本；复杂内容请直接用 `Dialog` 组件） */
     detail?: string;
+    /**
+     * 语义档（决定标题左侧的裸符号与配色）：`info` / `success` / `warning` / `error`。
+     *
+     * 不传则无图标。**危险操作用 `error`** —— 它同时把确定按钮染成危险色
+     * （除非显式给了 `okDanger`），这样「删除确认」与「保存成功」不再长得一样。
+     */
+    tone?: DialogTone;
     /** 确定按钮文案 */
     okText?: string;
     /** 取消按钮文案（`alert` 不使用） */
     cancelText?: string;
-    /** 确定按钮的危险色（删除类确认） */
+    /** 确定按钮的危险色（删除类确认；不传时由 `tone === 'error'` 推出） */
     okDanger?: boolean;
     /** 是否显示关闭位（缺省开：用户总得有第三条退路） */
     closable?: boolean;
@@ -18,11 +26,15 @@ export interface ConfirmOptions {
  * 与 `Dialog` 组件的分工：组件是「受控弹窗」，本函数补齐命令式调用缺的那一层（宿主 + 收场 Promise）。
  * 语义与主流库一致：**任何非确定路径都折成 `false`**，调用方 `if (await confirm(...))` 一处判断即可。
  *
+ * **遮罩与 Esc 都归 `false`**：`Dialog` 组件形态的 `closeOnBackdrop` 默认已改为 `true`（跟主流），
+ * 但命令式确认框必须**显式关掉它** —— 这里一条误点就丢一次决策，与 Ant Design
+ * （`<Modal maskClosable>` 默认 `true`、`Modal.confirm` 默认 `false`）的分工一致。
+ *
  * 需要「确定按钮进加载态」的异步确认请直接用 `Dialog` 组件（`onOk` 返回 Promise 时自动进加载态）——
  * 命令式形态刻意不引入跨 tick 的加载态，免得调用方以为弹窗已经关了。
  *
- * @example 删除确认
- * if (await confirm({ title: '删除确认', detail: '删除后不可恢复，确认继续？', okText: '删除', okDanger: true })) {
+ * @example 删除确认（`tone: 'error'` 给标题加提示图标并把确定按钮染危险色）
+ * if (await confirm({ title: '删除确认', detail: '删除后不可恢复，确认继续？', okText: '删除', tone: 'error' })) {
  *   await remove()
  * }
  */
@@ -33,8 +45,11 @@ export declare function confirm(options?: ConfirmOptions): Promise<boolean>;
  * 底栏**自绘**而不是用内建底栏：内建底栏固定是「取消 + 确定」两枚，而告知框没有「取消」可言
  * （给两枚按钮会让用户以为还有一条分支）。
  *
- * @example
- * await alert({ title: '导入完成', detail: '共 128 条，其中 3 条被跳过。' })
+ * 与 `confirm()` 同一口径：**遮罩与 Esc 都显式关掉**（告知框同样不该被一次误点打发掉）。
+ *
+ * @example 危险操作的回执：这一条与「保存成功」在图标与配色上区分开
+ * await alert({ tone: 'error', title: '移除失败', detail: '该来源系统仍被 3 个应用引用。' })
+ * await alert({ tone: 'success', title: '导入完成', detail: '共 128 条，其中 3 条被跳过。' })
  */
 export declare function alert(options?: ConfirmOptions): Promise<void>;
 /** 收掉全部在档弹窗（逐个折成 `false`）；幂等。换应用 / 卸载时调 */

package/dist/services/dialog.js

@@ -39,10 +39,14 @@ function confirm(options = {}) {
       {
         open: ctx.isOpen(),
         title: options.title,
+        tone: options.tone,
         closable: options.closable ?? true,
+        // 组件形态默认已开（跟主流）；命令式这一层显式关掉，防误点丢决策
+        closeOnBackdrop: false,
+        maskClosable: false,
         okText: options.okText ?? "确定",
         cancelText: options.cancelText ?? "取消",
-        okDanger: options.okDanger ?? false,
+        okDanger: options.okDanger ?? options.tone === "error",
         onOk: () => ctx.finish(true),
         onCancel: () => ctx.finish(false),
         onClose: () => ctx.finish(false)
@@ -58,7 +62,10 @@ function alert(options = {}) {
       {
         open: ctx.isOpen(),
         title: options.title,
+        tone: options.tone,
         closable: options.closable ?? true,
+        closeOnBackdrop: false,
+        maskClosable: false,
         // 关闭位与 Esc 都算「看过了」
         onCancel: () => ctx.finish(true),
         onClose: () => ctx.finish(true)

package/dist/styles/components/capsule.css

@@ -14,11 +14,11 @@
  *
  * 状态三源等价：原生 `input:checked` / 组件下发 `[data-state='active']` / 静态档 `.is-selected`。
  *
- * **与面板组合**：要「选中即切面板」，外面套 `styles/operations/tabset.css` 的 `.mh-tabset` ——
- * 本族不认识它、它也不认识本族（两层零互指），壳层挂类即可。
+ * **与面板组合**：要「选中即切面板」，把本件塞进 `Tabs` 的 `selector` 插槽即可 ——
+ * 面板显隐由 `Tabs` 按受控值下发 `hidden`，本族不认识它、它也不认识本族（两层零互指）。
  *
- * **与 `Tabset` 的判据**：`Tabset` 是操作层（只给行为与档位表、不带面），面可由本件或按钮族的分段形态担任；
- * 本件是**带自己轨道与选中胶囊的轻量选择控件**。
+ * **与 `Tabs` 的判据**：`Tabs` 是操作层的**骨架**（只给根、面板组与收起态，不带面），
+ * 面可由本件或按钮族的分段形态担任；本件是**带自己轨道与选中胶囊的轻量选择控件**。
  */
 .mh-capsule {
   display: inline-flex;

package/dist/styles/components/dialog.css

@@ -16,6 +16,15 @@
  * （`class="mh-popup mh-card"` + 按钮），不需要新的面；尺寸 220/r10 那组值也不值得为它单开一族。
  */
 .mh-dialog {
+  /* 三段式列布局：页头 / 底栏由内容定高（`flex: none`），内容区吃掉剩余高度。
+     与 `Drawer` 同构（那边一直是这么写的）—— 本件此前漏了这一层，表现为
+     **高度受控时底栏不贴底**（body 只有内容高，剩余空间全留在 footer 之后）。
+     不设高度时零影响：列容器无高度约束 ⇒ body 高 = 内容高（与改前逐像素一致）。
+     ⚠️ 加 `display: flex` 会以作者源压过 UA 的 `dialog:not([open]) { display: none }`，
+     收起态靠操作层 `operations/popup.css` 的 `:is(… dialog.mh-popup:not([open]))` 兜住
+     （特异性 0-3-0，高于本行）—— **那条兜底不能删**。 */
+  display: flex;
+  flex-direction: column;
   width: var(--ui-dialog-width);
   max-width: var(--ui-dialog-width);
   padding: 0; /* UA 给 <dialog> 的内距一律归零：内距由页头 / 内容 / 底栏各自拥有 */
@@ -42,14 +51,38 @@
   align-items: center;
   justify-content: space-between;
   gap: var(--ui-space-2);
+  flex: none; /* 高度受控时不被压缩（同 Drawer） */
   padding: var(--ui-space-4) var(--ui-space-6) 0;
   font-size: var(--ui-font-heading); /* 规范 16px */
   line-height: var(--ui-line-heading);
   font-weight: var(--ui-weight-medium);
   color: var(--ui-base-content);
 }
+/* 语义档（`tone`）：标题左侧一个**裸符号**，颜色按档取语义色 ——
+   缺省（不传 tone）不渲染，故不影响既有外观。取色口径与 `Notice` 同一张表
+   （success / warning 取 -strong 档，否则浅底上对比度不足）。 */
+.mh-dialog__tone-icon {
+  flex: none;
+  width: var(--ui-font-icon);
+  height: var(--ui-font-icon);
+  color: var(--mh-dialog-tone-color, var(--ui-primary));
+}
+.mh-dialog--info {
+  --mh-dialog-tone-color: var(--ui-info);
+}
+.mh-dialog--success {
+  --mh-dialog-tone-color: var(--ui-success-strong);
+}
+.mh-dialog--warning {
+  --mh-dialog-tone-color: var(--ui-warning-strong);
+}
+.mh-dialog--error {
+  --mh-dialog-tone-color: var(--ui-error);
+}
+
 /* 标题位（插槽版也走这个类，两路渲染同一份排版） */
 .mh-dialog__title {
+  flex: 1 1 auto; /* 撑满中段：语义图标在左、关闭位在右（`space-between` 下三者的正确落位） */
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -82,8 +115,13 @@
   outline-offset: 2px;
 }
 
-/* 内容区（内距 24；三段之间无分割线，交界间距只由三段内距单一拥有） */
+/* 内容区（内距 24；三段之间无分割线，交界间距只由三段内距单一拥有）
+   `flex: 1 1 auto` + `min-height: 0`：吃掉页头与底栏之外的全部高度（含 `panelHeight` /
+   消费方经 style 给的高度），超出即**本段**滚动 —— 页头与底栏因此永远可见。 */
 .mh-dialog__body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
   padding: var(--ui-space-6);
   font-size: var(--ui-font-body);
   line-height: var(--ui-line-body);
@@ -102,5 +140,6 @@
   display: flex;
   justify-content: flex-end;
   gap: var(--ui-space-2);
+  flex: none; /* 高度受控时贴底且不被压缩（同 Drawer） */
   padding: 0 var(--ui-space-6) var(--ui-space-4);
 }

package/dist/styles/components/form.css

@@ -13,7 +13,13 @@
    （farris 用绝对定位的浮层提示条，在弹窗里会压住下一行控件）。
 
    label 列宽只由变量驱动：Form / Form.Item 落 `--mh-form-label-width`，默认取令牌，
-   故换宽窄不需要在消费方写 CSS。 */
+   故换宽窄不需要在消费方写 CSS。
+
+   行几何是**两列 grid**（label 列 + 控件列）：label 与控件同处第 1 行、交叉轴居中 ⇒ 两侧文字
+   落在同一条中线上；错误 / 说明是**行的直接子节点**，自然落第 2 行起，不会把 label 带走。
+   对齐**不依赖任何「控件高度」常量**（从前那个 `--ui-form-control-height` 在骨架层没有出处，
+   回退 `auto` ⇒ label 盒退化成一行文字并贴行顶，档位越高错得越多）。
+   需要顶对齐的行（文本域自动判定、或消费方显式 `align`）见下面的「行内垂直对齐档」。 */
 
 /* 行距取 8px 档：Form.Item 自己已经是一个完整行（label 与控件等高 + 错误/说明按文档流往下排），
    再用 16px 行距会把表单拉得很散 —— 尤其是步骤⑤那种「只读文本行」的摘要，行与行之间会显得发虚。
@@ -23,27 +29,83 @@
   display: flex;
   flex-direction: column;
   gap: var(--ui-space-2);
+  /* 多列公式用的三个变量（**都在本件**，不进 theme 令牌文件）：
+     - `--mh-form-columns`：数字档的**列数上限**（档位类只覆盖它，不复制几何）；
+     - `--mh-form-column-min`：一列的**最小宽度**（`columnMinWidth` 行内覆盖，缺省取令牌 320）；
+     - `--mh-form-gap`：行距 —— 公式里必须用**与实体 gap 同一个值**算轨道下限
+       （从前这里硬编码 8px，`gap` 调大后列宽会算偏、临界宽度上还会误判是否回落）。 */
+  --mh-form-columns: 2;
+  --mh-form-column-min: var(--ui-form-column-min);
+  --mh-form-gap: var(--ui-space-2);
 }
 
-/* 两列（Form columns=2）：`auto-fit` + 列最小宽度 ⇒ 容器够宽才并排、窄了**自动回落一列**
-   （不需要媒体查询，也不需要容器查询）。`align-items: start` 让同一行的两个字段各自顶部对齐，
-   不被隔壁那个「错误 + 多行说明」撑高的格子拉扯。 */
-
-.mh-form--two-column {
+/* ===== 多列（数字档：`columns` = 2 / 3 / 4）=====
+ * 轨道下限取「**最小列宽**」与「**按 N 列等分**」的较大者，配 `auto-fit`：
+ * - 容器放得下 N 列 ⇒ 排 N 列；
+ * - 放不下 ⇒ 轨道数减少（**自动回落**，不会把控件压成窄条）。
+ *
+ * 把「均分值」当轨道下限就是「**上限 N 列**」的实现 —— 没有它，`auto-fit` 会一路排下去
+ * （实测 1400px 得 4 列，与「最多 N 列」的承诺不符）。
+ *
+ * 这条是表单与 `Layout.Row` 的**关键差别**：后者列数恒定、窄了等分收窄（实测 480px 容器里
+ * Form 回落成一列、控件还有 360px；恒定两列会把控件压到 ~104px）。表单会被放进抽屉 / 弹窗 /
+ * 分栏，容器宽度不可预知，所以要的是「回落到能用」而不是「列数不变」。
+ *
+ * `align-items: start`：同一行的字段各自顶部对齐，不被隔壁那个「错误 + 多行说明」撑高的格子拉扯。
+ *
+ * `mh-form--two-column` 是 `columns={2}` 的**历史类名**（已发布过，改名属破坏性变更），
+ * 与 3~6 档共用下面这份几何声明（`2` 与 `3+` 走两个类名只是历史包袱，样式上完全等价）。 */
+
+.mh-form--two-column,
+.mh-form--columns-3,
+.mh-form--columns-4,
+.mh-form--columns-5,
+.mh-form--columns-6 {
   display: grid;
-  /* 上限 2 列 + 最小列宽：track 下限取「最小列宽」与「按 2 列等分」的较大者
-     —— 否则宽表单里 auto-fit 会一路排到 4 列（实测 1400px 得 4 列），
-     而 `columns={2}` 承诺的是"最多 2 列、窄了回落"（与 Layout.Row 同一公式）。 */
   grid-template-columns: repeat(
     auto-fit,
     minmax(
-      max(var(--ui-form-column-min), calc((100% - var(--ui-space-2)) / 2)),
+      max(
+        var(--mh-form-column-min),
+        calc((100% - (var(--mh-form-columns) - 1) * var(--mh-form-gap)) / var(--mh-form-columns))
+      ),
       1fr
     )
   );
   align-items: start;
 }
 
+/* 档位只覆盖变量（几何只有一份）。5 / 6 档在默认最小宽 320 下要容器 1632 / 1960px 才排得出来，
+   留着它们是给「宽屏展示页 / 大屏看板」用 —— 配合 `columnMinWidth` 调小最小宽才落地得快。 */
+.mh-form--columns-3 {
+  --mh-form-columns: 3;
+}
+.mh-form--columns-4 {
+  --mh-form-columns: 4;
+}
+.mh-form--columns-5 {
+  --mh-form-columns: 5;
+}
+.mh-form--columns-6 {
+  --mh-form-columns: 6;
+}
+
+/* ===== 动态列数（`columns="auto"`）=====
+ * `auto-fill` + `minmax(最小列宽, 1fr)`：**列数随容器宽度变**，列数 =
+ * `floor((容器宽 + 行距) / (最小宽 + 行距))`。实测（最小宽 320 / 行距 8）：
+ * 640px → 1 列、660px → 2 列、1000px → 3 列、1320px → 4 列；每列宽落在 `[最小宽, 2 × 最小宽)`。
+ *
+ * 为什么是 `auto-fill` 而不是 `auto-fit`：两者只差在「子项少于轨道数」时 ——
+ * `auto-fit` 会**折叠空轨道**，于是宽容器里 2 个字段被拉成两条长条（实测 1400px 下每项 696px）；
+ * `auto-fill` 保留轨道，字段列宽稳定在区间内（1400px 下每项 344px）。表单要的是**列宽稳定**，
+ * 不是「把剩余宽度填满」。 */
+
+.mh-form--columns-auto {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--mh-form-column-min), 1fr));
+  align-items: start;
+}
+
 /* 跨满整行：说明行 / 卡片组 / 表格 / 文本域这类整块内容（单列时 grid-column 无效，无副作用） */
 
 .mh-form-item--full {
@@ -53,20 +115,27 @@
 .mh-form-item {
   /* label 列宽：Item 行内下发 --mh-form-label-width；未传时取令牌 */
   --mh-form-label-width: var(--ui-form-label-width);
-  display: flex;
-  align-items: flex-start;
+  /* 两列：label 列（定宽）+ 控件列（吃满剩余）。控件列写 `minmax(0, 1fr)` 而不是 `1fr`：
+     它必须能被内部长内容压缩，否则长 URL / 自绘表格会撑破列宽。 */
+  display: grid;
+  grid-template-columns: var(--mh-form-label-width) minmax(0, 1fr);
+  /* **第 1 行内交叉轴居中** = label 文字与控件中线对齐。
+     第 1 行的行高由控件（恒高于一行文字）决定 ⇒ 对齐与控件高度**解耦**：
+     控件档位换 sm/md/lg、换主题、放自绘控件都自动成立，**不需要任何「控件高度」常量**。 */
+  align-items: center;
 }
 
 /* label 列：固定宽 + **右对齐**（与 farris 的动态表单一致，也是水平表单的通行默认）。
-   min-height 取**控件真实高度**（--ui-form-control-height 由桥接层按 farris 控件规则给出）：
-   label 盒与控件盒等高 ⇒ 两侧文字各自居中后落在同一条中线上。
-   曾经写的是 32px 令牌，而 farris 控件实际 ≈24px（rem，随根字号）⇒ label 明显偏低，已修。 */
+   只占第 1 行（控件那一行），所以错误 / 说明的出现不会把它带走；
+   本件**不设任何高度** —— 从前用 min-height 取一个外部注入的控件高度来「假装等高」，
+   而那个变量在骨架层没有出处（回退 auto），label 盒退化成一行文字并贴行顶：
+   输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px。 */
 
 .mh-form-item__label {
-  flex: 0 0 auto;
+  grid-column: 1;
+  grid-row: 1;
   width: var(--mh-form-label-width);
   box-sizing: border-box;
-  min-height: var(--ui-form-control-height, auto);
   padding-right: var(--ui-space-3);
   display: flex;
   align-items: center;
@@ -113,17 +182,57 @@
   white-space: nowrap;
 }
 
+/* 控件列：只装**控件本体**（错误 / 说明是行的直接子节点，自然落第 2 行起）。
+   `min-width: 0` 必须留：grid item 的默认 `min-width: auto` 会让长内容撑破列宽。 */
+
 .mh-form-item__control {
-  flex: 1;
+  grid-column: 2;
+  grid-row: 1;
   min-width: 0;
 }
 
+/* 矮控件（开关 / 勾选框 / 单选）在控件列里**按盒居中**，而不是按行盒的基线排。
+ *
+ * 它们高 14~18px，**比一行文字（20px）还矮**（`Switch` / `Checkbox` / `Radio` 三件即这一族）：
+ * 作为行内元素参与基线对齐时，控件列会被 line box 撑高（实测 22px = 18 + 行内 leading），
+ * 而控件本身在那一行里偏上 2px —— 开关与标签看着就不在一条中线上（本件第 1 行本来是居中的，
+ * 偏的是**控件列内部**这一层）。
+ *
+ * 单子项时把控件列切成 flex 并 `align-items: center`：控件列高度回到控件自身高度，
+ * 与 label 同处第 1 行、各自居中 ⇒ 两侧中线重合（实测 switch 18px / checkbox 14px 偏差都为 0，
+ * 行高也从 22px 回到 20px —— 不再被行盒的 leading 撑高）。
+ *
+ * 为什么限定「**唯一**子项」：控件列里放多个内容时（如「输入框 + 获取按钮」）原本是块级上下堆叠，
+ * 无条件 flex 会把它们排成一行 —— 那是布局变更，不是修对齐。
+ *
+ * 判据是**属性协议** `data-inline-control`，不是元素名、也不是别件的类名：
+ *
+ * - `Switch` / `Checkbox` / `Radio` 在根节点上声明这个属性（三件正好是这一族，14~18px）；
+ * - **自绘的行内小控件**（根是 `div` / `span` 都行）在根上加同一个属性就自动接入 ——
+ *   不需要对齐本库的类名，也不必知道这里的实现；
+ * - 为什么不按元素名判（`label` / `button`）：那把判据绑死在「别人怎么写 DOM」上，
+ *   自绘控件必然漏掉（而控件根是什么元素本就是它的实现自由）；
+ *   按类名判则要求两个面互相引用，本仓既有裁决不允许。
+ *
+ * 对齐**不依赖控件列的高度**（别以为 `display: flex` 让控件列从「撑满行高」变成「内容撑高」
+ * 就把对齐弄丢了）：switch 行三种行级配置实测 —— `center` 控件列 18px、`stretch` 控件列 20px，
+ * switch 中心都落在行中心、与 label 文字同线（Δ 都是 0）；三种里唯一会偏的是 `align="start"`
+ * 顶对齐档（Δ = −10，label 有 9px 上内距而控件贴顶）—— 那一档是给多行 / 整块内容用的，
+ * 开关不要放进那种行，或显式写 `align="center"`。
+ * 将来若要让控件列**占满行高**（例如给它画背景 / 分割线），在行上写 `align-items: stretch`
+ * 或给控件列 `align-self: stretch` 即可 —— 实测那样 switch 依然居中。 */
+
+.mh-form-item__control:has(> [data-inline-control]:only-child) {
+  display: flex;
+  align-items: center;
+}
+
 /* 只读文本行（Form.Item 的 text 形态：摘要 / 详情）：正文色与行高，
-   长文案（SQL where、列说明）按词折行；`pre-wrap` 保留换行符（多行过滤条件回显）。 */
+   长文案（SQL where、列说明）按词折行；`pre-wrap` 保留换行符（多行过滤条件回显）。
+   它只占第 1 行、与 label 各自居中即对齐 —— **不给任何高度**（撑到某个「控件高」等于把那个
+   外部高度变量换个名字复活；只读行按内容高排版，行与行的间距归 `Form` 的 gap）。 */
 
 .mh-form-item__text {
-  /* 与 label 同一口径：桥接层不给 `--ui-form-control-height` 时退回 auto（不给回退会让整条声明作废） */
-  min-height: var(--ui-form-control-height, auto);
   display: flex;
   align-items: center;
   font-size: var(--ui-font-body);
@@ -139,7 +248,12 @@
   color: var(--ui-base-content-subtle);
 }
 
+/* 错误 / 说明：**行的直接子节点**（不在控件列里面），排在控件行之下、与控件列同列。
+   只给 `grid-column` 不给行号 —— 自动放置会把它们推进下一个空行：控件占着第 1 行，
+   于是它们既不会挤进第 1 行、也不会掉到 label 列下面去。 */
+
 .mh-form-item__error {
+  grid-column: 2;
   margin-top: var(--ui-space-1);
   font-size: var(--ui-font-caption);
   line-height: var(--ui-line-caption);
@@ -147,33 +261,99 @@
 }
 
 .mh-form-item__hint {
+  grid-column: 2;
   margin-top: var(--ui-space-1);
   font-size: var(--ui-font-caption);
   line-height: var(--ui-line-caption);
   color: var(--ui-base-content-subtle);
 }
 
+/* ===== 无 label 列（`label` 与 `required` 都没有：整块内容 / 纯说明行）=====
+ * 控件位与提示横跨整行 —— 两列 grid 下第一列必须收掉，否则整块内容会被挤到 label 列宽之后。 */
+.mh-form-item--no-label {
+  grid-template-columns: minmax(0, 1fr);
+}
+.mh-form-item--no-label > .mh-form-item__control,
+.mh-form-item--no-label > .mh-form-item__error,
+.mh-form-item--no-label > .mh-form-item__hint {
+  grid-column: 1 / -1;
+}
+
+/* ===== 行内垂直对齐档 =====
+ * 默认（基类）`center`：label 与控件**中线**对齐 —— 第 1 行行高 = 控件真实高度，
+ * 与控件档位 / 主题 / 自绘控件都无关。需要顶对齐的是**多行与整块内容**：label 该与首行文字齐，
+ * 而不是落到整块高度的中间。
+ *
+ * 自动判定（按控件形态，消费方零配置）：认**原生元素** `textarea`，不认别件的类名（面之间不互指，
+ * 是本仓的既有裁决；认元素还顺带覆盖了代码编辑区这类自绘多行件）。
+ * 文本域的壳带 8px 上内距 + 1px 边框（控件自身内距被壳归零，见 input.css），
+ * label 补上同样的偏移才与**首行文字**同线 —— 不补则仍偏高 9px（实测）。
+ * 整条自动判定包 `:where()`：把选择器特异性压回 0-1-0，显式修饰类（0-2-0）才稳定压过它，
+ * 不必靠「谁写在后面」争胜出。 */
+.mh-form-item:where(:has(.mh-form-item__control textarea)) {
+  align-items: start;
+}
+.mh-form-item:where(:has(.mh-form-item__control textarea)) > .mh-form-item__label {
+  padding-top: calc(var(--ui-space-2) + 1px);
+}
+
+/* 显式档（`Form.Item` 的 `align`）：样式认不出形态的自绘内容（卡片组 / 表格 / 富文本）写 start；
+   要强制回到默认的中线对齐写 center。两者都会压过上面的自动判定。
+   `start` 沿用与文本域**同一口径**的上内距（8px 内距 + 1px 边框）：自绘块自带更大内距时会有几像素差
+   （实测块内距 12px 时差 4px）—— 组件无从知道自绘块内部的排版，要求严格同线时在块内自行调整。 */
+.mh-form-item.mh-form-item--align-start {
+  align-items: start;
+}
+.mh-form-item.mh-form-item--align-start > .mh-form-item__label {
+  padding-top: calc(var(--ui-space-2) + 1px);
+}
+.mh-form-item.mh-form-item--align-center {
+  align-items: center;
+}
+.mh-form-item.mh-form-item--align-center > .mh-form-item__label {
+  padding-top: 0;
+}
+
 /* ===== 纵向排布（`layout="vertical"`：label 在控件上方） =====
- * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。 */
+ * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。
+ * 单列三行：label / 控件 / 提示依次往下（提示不给行号，自动放置接在控件之后）。
+ * 选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档与显式档 ——
+ * 纵向时 label 本来就在上方，那 9px 上内距只会在 label 上多出一截空隙。 */
 .mh-form--vertical .mh-form-item {
-  flex-direction: column;
-  align-items: stretch;
+  grid-template-columns: minmax(0, 1fr);
 }
-.mh-form--vertical .mh-form-item__label {
+.mh-form--vertical .mh-form-item > .mh-form-item__label {
+  grid-column: 1;
+  grid-row: 1;
   width: auto;
   min-width: 0;
   justify-content: flex-start;
   padding-right: 0;
-  padding-bottom: var(--ui-space-1);
+  padding-top: 0;
+  padding-bottom: var(--ui-space-2);
   text-align: left;
 }
+.mh-form--vertical .mh-form-item > .mh-form-item__control {
+  grid-column: 1;
+  grid-row: 2;
+}
+.mh-form--vertical .mh-form-item > .mh-form-item__error,
+.mh-form--vertical .mh-form-item > .mh-form-item__hint {
+  grid-column: 1;
+}
 
 /* ===== 表单头（`Form.Header`：单头，成员归位到最前）=====
    只做**标题排版**与**右端操作位**，不承担区块分组（那是 `Panel` 的职责）。
    三样（title / extra / description）都没有时组件整块不渲染 —— 空盒子同样占一档
    `Form` 的 gap，会凭空多出间距。 */
 
+/* `grid-column: 1 / -1`：多列下**表头必须跨满整行** —— 它是 `Form` 的一个 grid 子项，
+   不跨行就只占一格（实测 `columns={2}`、容器 800 时表头只有 396px = 半宽；列数越多越窄）。
+   `1 / -1` 引用的是最后一条**显式**轨道线，不会生成隐式轨道，故动态列数下同样安全；
+   单列（flex 形态）时该属性无效、无副作用（与 `.mh-form-item--full` 同款写法）。 */
+
 .mh-form__header {
+  grid-column: 1 / -1;
   display: flex;
   flex-direction: column;
   gap: var(--ui-space-1);

package/dist/styles/components/input.css

@@ -327,7 +327,20 @@
   height: var(--ui-input-affix-size);
 }
 
-/* ===== 清除（有内容才由组件渲染；圆形 + close 字形） ===== */
+/* ===== 清除（有内容才由组件渲染；圆形 + close 字形）=====
+ *
+ * **默认隐形，滑过表壳或聚焦时才显形**：常显会在每一个有内容的输入框右端永远挂一颗深色实心圆点 ——
+ * 密集场景（表格内编辑、筛选条、多选触发器、带前后缀的搜索行）里那一列圆点比字段本身还抢眼，
+ * 也与「清除是低频动作」的层级不符。
+ *
+ * 为什么用 `opacity` 而不是 `display` / `visibility`：
+ * ① 它仍在流中**占位** —— 显隐时输入区宽度不变；换 `display` 会让文字在鼠标移入的一瞬间横跳；
+ * ② 它仍是可命中的**定位元素** —— 触发器形态的整箱热区靠 `position: relative` + DOM 顺序压在
+ *    覆盖层之上（见上一节），换 `visibility: hidden` 会连命中一起关掉，那一块反被热区接管。
+ *
+ * `:focus-within` 是**触屏与键盘**的兜底：没有 hover 的设备上，点进输入框同样要能点到清除
+ * （键盘另有一条 `Delete` 路径，见组件）。禁用档不显形：那时本来就不该清，圆点落在灰底上还会
+ * 被误读成可用。 */
 .mh-input__clear {
   flex: none;
   display: inline-flex;
@@ -344,6 +357,20 @@
   background: var(--ui-base-300); /* 规范 Te10 圆点底 */
   color: var(--ui-base-100);
   cursor: pointer;
+  opacity: 0;
+  transition-property: opacity;
+  transition-duration: 0.15s;
+  transition-timing-function: ease;
+}
+/* 显形：滑过**整件**（内距与附加位区域都算）或任一控件拿到焦点 */
+.mh-input__wrap:hover > .mh-input__clear,
+.mh-input__wrap:focus-within > .mh-input__clear {
+  opacity: 1;
+}
+/* 禁用：整件不可交互，清除位一并收掉（`:has()` 的特异性高于上面那条，故同时压过 hover） */
+.mh-input__wrap:has(> .mh-input:disabled) > .mh-input__clear,
+.mh-input__wrap:has(> .mh-input.is-disabled) > .mh-input__clear {
+  opacity: 0;
 }
 .mh-input__clear:hover,
 .mh-input__clear:active {
@@ -370,7 +397,7 @@
 .mh-input__eye:hover {
   color: var(--ui-primary);
 }
-/* 明文显示中：图标转主色（同一个 `eye` 字形，靠状态色表达"当前是明文"） */
+/* 明文显示中：图标转主色（同一个 `preview` 字形，靠状态色表达"当前是明文"） */
 .mh-input__eye.is-on {
   color: var(--ui-primary);
 }

package/dist/styles/components/layout.css

@@ -39,6 +39,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--mh-layout-row-gap);
+  /* 内距不在本件声明：由 `padding` prop 直接下发实体 `padding`（值来自 prop） */
   /* 交叉轴（水平）不声明 = CSS 默认的 stretch（子项齐宽）；要居中写 align="center" */
   /* 放开 min-width：行常被塞进窄格子（表格单元格、限宽控件列）——
      不放开的 flex 容器压不进窄格，会把外层撑破 */
@@ -110,6 +111,7 @@
      要贴顶写 align="start"、要齐宽写 align="stretch" */
   align-items: center;
   gap: var(--mh-layout-column-gap);
+  /* 内距不在本件声明：同 `.mh-layout-row`，由 `padding` prop 直接下发 */
   min-width: 0;
 }