@manohub/ui 0.10.5 → 1.0.1

package/dist/styles/components/form.css

@@ -1,425 +1,456 @@
-/**
- * Form + Form.Item（自建表单：label 列 + 控件列 + 错误 / 说明）。
- *
- * 依据：`@aihub/theme` 的 `components/field.css`（标签色与列宽 / 必填星标 / 说明与报错）与
- * 设计稿《MH后台-0911》的表单（`02.1` 高级筛选区：标签 13px、必填星号 `#ff1922`、
- * 标签与控件间距 10）。**必填星号取 `--ui-required-mark`（专用色），不复用 `--ui-error`**。
- */
-
-/* ===== Form（自建表单：label + 控件 + 错误 + 说明）=====
-   沿 farris 表单的既有约定：label **右对齐**、必填星号在 label 文本**左侧**。
-   与 farris 动态表单的两处有意差异：① 控件撑满剩余宽度（按需用 controlWidth 收敛），
-   不受 farris「字段 max-width 26.625rem」约束；② 错误与说明走**文档流**排在控件下方
-   （farris 用绝对定位的浮层提示条，在弹窗里会压住下一行控件）。
-
-   label 列宽只由变量驱动：Form / Form.Item 落 `--mh-form-label-width`，默认取令牌，
-   故换宽窄不需要在消费方写 CSS。
-
-   行几何是**两列 grid**（label 列 + 控件列）：label 与控件同处第 1 行、交叉轴居中 ⇒ 两侧文字
-   落在同一条中线上；错误 / 说明是**行的直接子节点**，自然落第 2 行起，不会把 label 带走。
-   对齐**不依赖任何「控件高度」常量**（从前那个 `--ui-form-control-height` 在骨架层没有出处，
-   回退 `auto` ⇒ label 盒退化成一行文字并贴行顶，档位越高错得越多）。
-   需要顶对齐的行（文本域自动判定、或消费方显式 `align`）见下面的「行内垂直对齐档」。 */
-
-/* 行距取 8px 档：Form.Item 自己已经是一个完整行（label 与控件等高 + 错误/说明按文档流往下排），
-   再用 16px 行距会把表单拉得很散 —— 尤其是步骤⑤那种「只读文本行」的摘要，行与行之间会显得发虚。
-   要更松的排版属于消费方场景，改这里之前先确认不是想把「行距」当成区块间距在用。 */
-
-.mh-form {
-  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);
-}
-
-/* ===== 多列（数字档：`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;
-  grid-template-columns: repeat(
-    auto-fit,
-    minmax(
-      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 {
-  grid-column: 1 / -1;
-}
-
-.mh-form-item {
-  /* label 列宽：Item 行内下发 --mh-form-label-width；未传时取令牌 */
-  --mh-form-label-width: var(--ui-form-label-width);
-  /* 两列：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 的动态表单一致，也是水平表单的通行默认）。
-   只占第 1 行（控件那一行），所以错误 / 说明的出现不会把它带走；
-   本件**不设任何高度** —— 从前用 min-height 取一个外部注入的控件高度来「假装等高」，
-   而那个变量在骨架层没有出处（回退 auto），label 盒退化成一行文字并贴行顶：
-   输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px。 */
-
-.mh-form-item__label {
-  grid-column: 1;
-  grid-row: 1;
-  width: var(--mh-form-label-width);
-  box-sizing: border-box;
-  padding-right: var(--ui-space-3);
-  display: flex;
-  align-items: center;
-  /* 右对齐：label 文本贴着控件列，短标签也不会在列里留下大段空隙（与 farris 动态表单一致） */
-  justify-content: flex-end;
-  gap: 2px;
-  font-size: var(--ui-font-body);
-  line-height: var(--ui-line-body);
-  color: var(--ui-base-content);
-}
-
-.mh-form-item__required {
-  flex: 0 0 auto;
-  /* **不是** `--ui-error`：星号表达「这里有个必填要求」，不是「这里出错了」。
-     两者放同一枚令牌时，改错误色会顺带改掉全站的必填星号（反之亦然）。
-     设计实证：`02.1 > 高级筛选 > 1..4` 的 `*` = `#ff1922`（比错误色 `#f23030` 更艳）。 */
-  color: var(--ui-required-mark);
-}
-
-/* ===== label 提示位（`Form.Item` 的 `tip`）=====
- * 图标与气泡都**不新造** —— 图标取 `@manohub/icon` 的 `help`（带圈问号），气泡复用 `Tooltip` 的面
- * （`.mh-tooltip`）与操作层 `popup.css` 的 hover 档；本件只声明**提示位在 label 行里怎么排**。
- *
- * 宿主位（Tooltip 落在 label 里的那个 span）有两件事必做，少一件就有肉眼可见的偏移：
- * ① `flex: 0 0 auto` —— label 文本过长时走省略号，图标不被挤压；
- * ② 行高归 1 —— 图标比一行文字矮（图标档对 20px 行盒），留在 label 的行盒里会按基线排，
- *    中线与 label 文字错开（本仓对这类 1~6px 偏移有实测前科，见 `.mh-form-item__control` 那段）。
- * 气泡本身是固定定位（操作层 hover 档），不参与本行排布，故宿主宽度恒等于图标宽度。 */
-
-.mh-form-item__tip {
-  display: inline-flex;
-  align-items: center;
-  flex: 0 0 auto;
-  /* 行盒归零（`font-size: 0` + `line-height: 0`）：`Tooltip` 的宿主里还夹着一层 **inline 的锚点
-     span**（`.mh-popup-anchor`），它会给内含的 `inline-flex` 触发器生成行盒 —— 行盒按基线对齐，
-     于是宿主比图标高出一个 descender 间隙（实测 16px 图标 ⇒ 宿主 17px）。宿主再把这 17px 在
-     label 行里居中，图标中线就比文字中线高 0.5px。归零后宿主高度 === 图标高度，中线才重合。
-     图标 svg 不受影响（它自带尺寸，不读字号）。 */
-  font-size: 0;
-  line-height: 0;
-}
-
-/* 触发器（问号按钮）：`reset` 不代消费方归零控件外观，故边 / 底 / 内距三项自备。
-   颜色取次要色 —— label 旁是**辅助**信息，不与字段名抢层级；悬停 / 聚焦升到正文色。 */
-
-.mh-form-item__tip-btn {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  border: none;
-  background: transparent;
-  /* 静止：**浅灰**（`subtle`，同计数器档）；滑过 / 键盘聚焦转**正文色（黑）** ——
-     从 muted(#666) 起手的那版与 hover 后的 content(#1a1a1a) 只差一档，视觉上几乎看不出交互。 */
-  color: var(--ui-base-content-subtle);
-  cursor: help;
-}
-
-.mh-form-item__tip-btn:hover {
-  color: var(--ui-base-content);
-}
-
-
-
-
-/* label 对齐：基类默认右对齐（贴控件列，`labelAlign` 缺省档）；
-   `labelAlign="left"` 时挂这个修饰类改成左对齐 —— 只给「非默认值」挂类，避免两段声明争胜出顺序。
-   位置必须在基类规则之后：`.mh-form-item__label {` 是它的子串，测试取规则体时按首次出现命中。 */
-
-.mh-form-item--label-left .mh-form-item__label {
-  justify-content: flex-start;
-}
-
-/* 只读展示行（`Form.Item` 的 `text` 形态，或显式 `readonly`）的 label 降一档为**次要色**：
-   值与字段名同取正文色时，摘要 / 详情读起来是一串并列文本，分不清哪个是字段名
-   （原型 .sum-group td.k / .field-item .k 用的正是次要色）。值侧不变，仍是正文色。
-   `muted` 而非 `subtle`：空值占位「—」已经是 subtle，label 再用同色会让空行整行同调。
-   位置同样必须在基类 `.mh-form-item__label {` 之后（spec 的 ruleBody 按首次出现取规则体）。 */
-
-.mh-form-item--readonly .mh-form-item__label {
-  color: var(--ui-base-content-muted);
-}
-
-/* label 文本过长时省略而不是换行（换行会把控件列挤错位） */
-
-.mh-form-item__label-text {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-/* 控件列：只装**控件本体**（错误 / 说明是行的直接子节点，自然落第 2 行起）。
-   `min-width: 0` 必须留：grid item 的默认 `min-width: auto` 会让长内容撑破列宽。 */
-
-.mh-form-item__control {
-  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;
-}
-
-/* 错误 / 说明：**行的直接子节点**（不在控件列里面），排在控件行之下、与控件列同列。
-   只给 `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);
-  color: var(--ui-error);
-}
-
-.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 / 控件 / 提示依次往下（提示不给行号，自动放置接在控件之后）。
- * 选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档与显式档 ——
- * 纵向时 label 本来就在上方，那 9px 上内距只会在 label 上多出一截空隙。 */
-.mh-form--vertical .mh-form-item {
-  grid-template-columns: minmax(0, 1fr);
-}
-.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-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);
-}
-
-/* 标题行：14px/600 —— 与字段 label（14px/400）拉开「这是标题」的字重差；
-   有意不打到 16px（`--ui-font-heading` 是弹窗标题那一档）。
-   行高由这一行**最高的孩子**决定：筛选条里是两颗 32px 按钮 ⇒ 这一行就是 32px（与设计稿一致）。 */
-
-.mh-form__title {
-  display: flex;
-  align-items: center;
-  gap: var(--ui-space-2);
-  font-size: var(--ui-font-body);
-  font-weight: var(--ui-weight-semibold);
-  line-height: var(--ui-line-body);
-  color: var(--ui-base-content);
-}
-
-/* 标题文本允许被挤窄（右端操作位不参与收缩）；长标题**换行**而不是截断
-   —— 截断会让这一块读不出是什么。 */
-
-.mh-form__title-text {
-  min-width: 0;
-}
-
-/* 右端操作位（`extra` 槽）：贴右由 `margin-left: auto` 表达，不用 `justify-content: space-between`
-   （那条依赖「这一行只有两个子节点」，标题换行或将来再加子节点时就不再贴右）；
-   `flex: none` 让操作位自身不被标题挤变形（与卡片便捷头同一手法）。 */
-
-.mh-form__title-extra {
-  margin-left: auto;
-  display: flex;
-  align-items: center;
-  gap: var(--ui-space-2);
-  flex: none;
-}
-
-.mh-form__description {
-  margin: 0;
-  font-size: var(--ui-font-caption);
-  line-height: var(--ui-line-caption);
-  color: var(--ui-base-content-muted);
-}
+/**
+ * Form + Form.Item（自建表单：label 列 + 控件列 + 错误 / 说明）。
+ *
+ * 依据：`@aihub/theme` 的 `components/field.css`（标签色与列宽 / 必填星标 / 说明与报错）与
+ * 设计稿《MH后台-0911》的表单（`02.1` 高级筛选区：标签 13px、必填星号 `#ff1922`、
+ * 标签与控件间距 10）。**必填星号取 `--ui-required-mark`（专用色），不复用 `--ui-error`**。
+ */
+
+/* ===== Form（自建表单：label + 控件 + 错误 + 说明）=====
+   沿 farris 表单的既有约定：label **右对齐**、必填星号在 label 文本**左侧**。
+   与 farris 动态表单的两处有意差异：① 控件撑满剩余宽度（按需用 controlWidth 收敛），
+   不受 farris「字段 max-width 26.625rem」约束；② 错误与说明走**文档流**排在控件下方
+   （farris 用绝对定位的浮层提示条，在弹窗里会压住下一行控件）。
+
+   label 列宽只由变量驱动：Form / Form.Item 落 `--mh-form-label-width`，默认取令牌，
+   故换宽窄不需要在消费方写 CSS。
+
+   行几何是**两列 grid**（label 列 + 控件列）：label 与控件同处第 1 行、交叉轴居中 ⇒ 两侧文字
+   落在同一条中线上；错误 / 说明是**行的直接子节点**，自然落第 2 行起，不会把 label 带走。
+   对齐**不依赖任何「控件高度」常量**（从前那个 `--ui-form-control-height` 在骨架层没有出处，
+   回退 `auto` ⇒ label 盒退化成一行文字并贴行顶，档位越高错得越多）。
+   需要顶对齐的行（文本域自动判定、或消费方显式 `align`）见下面的「行内垂直对齐档」。 */
+
+/* 行距取 8px 档：Form.Item 自己已经是一个完整行（label 与控件等高 + 错误/说明按文档流往下排），
+   再用 16px 行距会把表单拉得很散 —— 尤其是步骤⑤那种「只读文本行」的摘要，行与行之间会显得发虚。
+   要更松的排版属于消费方场景，改这里之前先确认不是想把「行距」当成区块间距在用。 */
+
+.mh-form {
+  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);
+}
+
+/* ===== 多列（数字档：`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;
+  grid-template-columns: repeat(
+    auto-fit,
+    minmax(
+      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 {
+  grid-column: 1 / -1;
+}
+
+.mh-form-item {
+  /* label 列宽：Item 行内下发 --mh-form-label-width；未传时取令牌 */
+  --mh-form-label-width: var(--ui-form-label-width);
+  /* 两列：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 的动态表单一致，也是水平表单的通行默认）。
+   只占第 1 行（控件那一行），所以错误 / 说明的出现不会把它带走；
+   本件**不设任何高度** —— 从前用 min-height 取一个外部注入的控件高度来「假装等高」，
+   而那个变量在骨架层没有出处（回退 auto），label 盒退化成一行文字并贴行顶：
+   输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px。 */
+
+.mh-form-item__label {
+  grid-column: 1;
+  grid-row: 1;
+  width: var(--mh-form-label-width);
+  box-sizing: border-box;
+  padding-right: var(--ui-space-3);
+  display: flex;
+  align-items: center;
+  /* 右对齐：label 文本贴着控件列，短标签也不会在列里留下大段空隙（与 farris 动态表单一致） */
+  justify-content: flex-end;
+  gap: 2px;
+  font-size: var(--ui-font-body);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+}
+
+.mh-form-item__required {
+  flex: 0 0 auto;
+  /* **不是** `--ui-error`：星号表达「这里有个必填要求」，不是「这里出错了」。
+     两者放同一枚令牌时，改错误色会顺带改掉全站的必填星号（反之亦然）。
+     设计实证：`02.1 > 高级筛选 > 1..4` 的 `*` = `#ff1922`（比错误色 `#f23030` 更艳）。 */
+  color: var(--ui-required-mark);
+}
+
+/* ===== label 提示位（`Form.Item` 的 `tip`）=====
+ * 图标与气泡都**不新造** —— 图标取 `@manohub/icon` 的 `help`（带圈问号），气泡复用 `Tooltip` 的面
+ * （`.mh-tooltip`）与操作层 `popup.css` 的 hover 档；本件只声明**提示位在 label 行里怎么排**。
+ *
+ * 宿主位（Tooltip 落在 label 里的那个 span）有两件事必做，少一件就有肉眼可见的偏移：
+ * ① `flex: 0 0 auto` —— label 文本过长时走省略号，图标不被挤压；
+ * ② 行高归 1 —— 图标比一行文字矮（图标档对 20px 行盒），留在 label 的行盒里会按基线排，
+ *    中线与 label 文字错开（本仓对这类 1~6px 偏移有实测前科，见 `.mh-form-item__control` 那段）。
+ * 气泡本身是固定定位（操作层 hover 档），不参与本行排布，故宿主宽度恒等于图标宽度。 */
+
+.mh-form-item__tip {
+  display: inline-flex;
+  align-items: center;
+  flex: 0 0 auto;
+  /* 行盒归零（`font-size: 0` + `line-height: 0`）：`Tooltip` 的宿主里还夹着一层 **inline 的锚点
+     span**（`.mh-popup-anchor`），它会给内含的 `inline-flex` 触发器生成行盒 —— 行盒按基线对齐，
+     于是宿主比图标高出一个 descender 间隙（实测 16px 图标 ⇒ 宿主 17px）。宿主再把这 17px 在
+     label 行里居中，图标中线就比文字中线高 0.5px。归零后宿主高度 === 图标高度，中线才重合。
+     图标 svg 不受影响（它自带尺寸，不读字号）。 */
+  font-size: 0;
+  line-height: 0;
+}
+
+/* 触发器（问号按钮）：`reset` 不代消费方归零控件外观，故边 / 底 / 内距三项自备。
+   颜色取次要色 —— label 旁是**辅助**信息，不与字段名抢层级；悬停 / 聚焦升到正文色。 */
+
+.mh-form-item__tip-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  background: transparent;
+  /* 静止：**浅灰**（`subtle`，同计数器档）；滑过 / 键盘聚焦转**正文色（黑）** ——
+     从 muted(#666) 起手的那版与 hover 后的 content(#1a1a1a) 只差一档，视觉上几乎看不出交互。 */
+  color: var(--ui-base-content-subtle);
+  cursor: help;
+}
+
+.mh-form-item__tip-btn:hover,
+.mh-form-item__tip-btn:focus-visible {
+  color: var(--ui-base-content);
+}
+
+/* 键盘可达：气泡显形靠操作层的宿主 `:focus-within` 档，这里只管**焦点可见**（主色环）。
+   环只该出现在**真键盘焦点**上：点标签文字的转发式聚焦已由组件层掐掉（见 form/index.tsx）。 */
+
+.mh-form-item__tip-btn:focus-visible {
+  outline: 2px solid var(--ui-primary);
+  outline-offset: 2px;
+}
+
+/* 图标尺寸：常规图标一律取全局图标档。`<Icon>` 的宽高是**属性**，面层能覆盖；
+   不写就会静默落到组件默认的 16（口径见 `contract-icon-direction.spec.ts`）。 */
+
+.mh-form-item__tip-btn > svg {
+  width: var(--ui-font-icon);
+  height: var(--ui-font-icon);
+}
+
+
+
+
+/* label 对齐：基类默认右对齐（贴控件列，`labelAlign` 缺省档）；
+   `labelAlign="left"` 时挂这个修饰类改成左对齐 —— 只给「非默认值」挂类，避免两段声明争胜出顺序。
+   位置必须在基类规则之后：`.mh-form-item__label {` 是它的子串，测试取规则体时按首次出现命中。 */
+
+.mh-form-item--label-left .mh-form-item__label {
+  justify-content: flex-start;
+}
+
+/* 只读展示行（`Form.Item` 的 `text` 形态，或显式 `readonly`）的 label 降一档为**次要色**：
+   值与字段名同取正文色时，摘要 / 详情读起来是一串并列文本，分不清哪个是字段名
+   （原型 .sum-group td.k / .field-item .k 用的正是次要色）。值侧不变，仍是正文色。
+   `muted` 而非 `subtle`：空值占位「—」已经是 subtle，label 再用同色会让空行整行同调。
+   位置同样必须在基类 `.mh-form-item__label {` 之后（spec 的 ruleBody 按首次出现取规则体）。 */
+
+.mh-form-item--readonly .mh-form-item__label {
+  color: var(--ui-base-content-muted);
+}
+
+/* label 文本过长时省略而不是换行（换行会把控件列挤错位） */
+
+.mh-form-item__label-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 控件列：只装**控件本体**（错误 / 说明是行的直接子节点，自然落第 2 行起）。
+   `min-width: 0` 必须留：grid item 的默认 `min-width: auto` 会让长内容撑破列宽。 */
+
+.mh-form-item__control {
+  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;
+}
+
+/* 错误 / 说明：**行的直接子节点**（不在控件列里面），排在控件行之下、与控件列同列。
+   只给 `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);
+  color: var(--ui-error);
+}
+
+.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 / 控件 / 提示依次往下（提示不给行号，自动放置接在控件之后）。
+ * 选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档与显式档 ——
+ * 纵向时 label 本来就在上方，那 9px 上内距只会在 label 上多出一截空隙。 */
+.mh-form--vertical .mh-form-item {
+  grid-template-columns: minmax(0, 1fr);
+}
+.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-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);
+}
+
+/* 标题行：14px/600 —— 与字段 label（14px/400）拉开「这是标题」的字重差；
+   有意不打到 16px（`--ui-font-heading` 是弹窗标题那一档）。
+   行高由这一行**最高的孩子**决定：筛选条里是两颗 32px 按钮 ⇒ 这一行就是 32px（与设计稿一致）。 */
+
+.mh-form__title {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  font-size: var(--ui-font-body);
+  font-weight: var(--ui-weight-semibold);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+}
+
+/* 标题左端的品牌色竖标（主色胶囊，值与文档站示例标题同一套：见 `form.tokens.css`）。
+ * **只在有标题文本时出现**：这一行也会在「只给 `extra`」时渲染（筛选条那种），
+ * 那时凭空多一条竖标就成了坏的排版 —— 用 `:has()` 守住真正有标题的那一种。
+ * `flex: none`：标题换行时竖标不许被挤扁。竖标与文本之间的间距由标题行既有的 `gap` 给，
+ * 本句不另写间距（两处各写一遍必然漂）。 */
+.mh-form__title:has(> .mh-form__title-text)::before {
+  content: '';
+  flex: none;
+  width: var(--ui-form-title-bar-width);
+  height: var(--ui-form-title-bar-height);
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-primary);
+}
+
+/* 标题文本允许被挤窄（右端操作位不参与收缩）；长标题**换行**而不是截断
+   —— 截断会让这一块读不出是什么。 */
+
+.mh-form__title-text {
+  min-width: 0;
+}
+
+/* 右端操作位（`extra` 槽）：贴右由 `margin-left: auto` 表达，不用 `justify-content: space-between`
+   （那条依赖「这一行只有两个子节点」，标题换行或将来再加子节点时就不再贴右）；
+   `flex: none` 让操作位自身不被标题挤变形（与卡片便捷头同一手法）。 */
+
+.mh-form__title-extra {
+  margin-left: auto;
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  flex: none;
+}
+
+.mh-form__description {
+  margin: 0;
+  font-size: var(--ui-font-caption);
+  line-height: var(--ui-line-caption);
+  color: var(--ui-base-content-muted);
+}