@manohub/kit 1.0.1 → 1.0.3

package/CONTRACT.md

@@ -50,8 +50,8 @@
 | prop 的**存在性与取值** | 该件 `dist/components/<件>/index.d.ts` | 传 prop 前打开确认 |
 | **语义词表**（改外观的唯一正规通道） | 同上，`.d.ts` 里的联合类型 | 26 个维度，`tone` / `variant` / `shape` / `size` / `status` / `gap` / `align` / `justify` / `padding` … |
 | **骨架怎么用**（归位 / 滚动 / 页头 / 操作位） | `@manohub/ui/dist/components/page/index.d.ts`、`dist/components/panel/index.d.ts` 的头注释 | §5 已把判据写全；这两份是更细的展开 |
-| 图标**名清单** | `@manohub/icon` 的 `dist/glyphs.d.ts`（`IconNameList`） | `name` 必须在清单里搜得到 |
-| 图标**字形与出处** | `node_modules/@manohub/icon/dist/glyphs.js`（源码形态：`src/glyphs.ts`） | 缺图标改这里 + 重 build |
+| 图标**名清单** | `@manohub/icon` 的 `dist/glyphs.d.ts`（`IconNameList`） | 传 `name` 时必须在清单里搜得到（L1.5-6） |
+| 图标**字形与出处** | `node_modules/@manohub/icon/dist/glyphs.js` / `business-glyphs.js`（源码在包的 `src/glyphs.ts` / `business-glyphs.ts`）；本项目自带字形见本仓 `icons.ts`（可用 `icon-from-svg` 从 SVG 生成） | 通用字形缺了改中央包 + 重 build；业务字形缺了写进 `<Icon>` 插槽并集中一处（L1.5-6 第 ③ 类） |
 | **类名与档位类** | `@manohub/ui/dist/styles/index.css` 及其 `components/` | 应用侧**不写** `.mh-*` |
 | 本仓**类名命名空间** | 本应用自己的 `docs/kit-namespaces.md`（若还没有，建一个） | 类名形状必须匹配表内某一格 |
 
@@ -182,7 +182,7 @@ configureHost(hostEl)
 | --- | --- | --- |
 | **L1-1 应用侧不持有值** | 应用侧的 `--*` 自定义属性**一处都不该有**。只有两种合法写法：① **重设已存在的令牌**（局部换肤）② 不写 | 值的唯一来源是 theme。局部换肤是合法且推荐的（见下） |
 | **L1-2 引用必须存在** | 每个 `var(--xxx)` 的 `--xxx` 必须能在 theme 六片或 `<件>.tokens.css` 里**搜到**。**新增令牌名一律违规** | 写错名字不会报错，只会静默回退成默认值 |
-| **L1-3 尺寸取令牌** | 尺寸取 `--ui-space-*` / `--ui-radius-*` / `--ui-control-height-*` / `--ui-row-height` / `--ui-grid-column-min`；**几何是设计基准、不跟根字号**，故禁 `rem`；内距给 **px 数字**（与 `Padding` 同口径） | 设计基准不随宿主根字号分叉 |
+| **L1-3 尺寸取令牌** | 尺寸取 `--ui-space-*` / `--ui-radius-*` / `--ui-control-height-*` / `--ui-control-width` / `--ui-control-min-width` / `--ui-row-height` / `--ui-grid-column-min`；**几何是设计基准、不跟根字号**，故禁 `rem`；内距给 **px 数字**（与 `Padding` 同口径） | 设计基准不随宿主根字号分叉 |
 | **L1-4 只写布局属性** | `<style>` 与 `style={{ }}` 里的属性名必须在**下面的白名单**内 | theme 是视觉的唯一来源 |
 | **L1-5 类名形状** | 类名一律 `<本仓命名空间>-<kebab-case>`。落点 A：CSS 选择器**首段**；落点 B：`class=` 的**每个 token** | 两个应用装进同一页面时不能撞名 |
 | **L1-6 不碰库的类** | 选择器里**不得出现 `.mh-`**；不得用 `!important`；不得用裸元素选择器与 `*`。**唯一例外：入口基线**（`html` / `body` / `#app` 三个选择器及其高度链，见 §1.2）| `.mh-*` 与档位类归 ui；覆写升版即静默失效 |
@@ -228,6 +228,27 @@ configureHost(hostEl)
 区别在**「新名字」还是「已有名字」**：`--ui-primary` 在 theme 里有定义 → 合法（重设）：
 `--ui-my-brand` 在 theme 里搜不到 → 违规（发明）。想加新名字去 `@manohub/theme` 提。
 
+### 控件定宽：重设 `--ui-control-width`（同一通道的用法）
+
+可输入控件（`Input` / `Textarea` / `NumberInput` / `Select` / `SelectTree` / `Search`）的宽度由**两枚主题令牌**驱动，
+缺省是「撑满所在列 / 容器」+ 120 的收缩下限：
+
+```css
+/* 一行筛选位：整片控件一句话定宽（不必逐个挂类） */
+.vm-filter-bar { --ui-control-width: 240px; }
+/* 密集工具条里确实要更窄：局部放行下限 */
+.vm-dense-bar  { --ui-control-min-width: 0; }
+```
+
+- **什么时候要用它**：控件落在**宽度由内容决定**的容器里时（典型是页头右位那类 flex 的 shrink-to-fit 槽），
+  百分比宽度解析不出确定值，会回退成**内容宽** —— 症状是下拉只剩占位文字那一小截、同排两件还不等宽；
+  行被 flex 挤压时同理（下限就是防「无限缩」）。
+- **不要用 `width` 覆写**：那会绕过口径，值只落在你写的那**一个件**上（同排的第二件还得再写一次），
+  下一版若调整了控件宽度的来源又得再改一遍。
+- **没有自己的容器时**（如页头右位），把类挂在**控件自身**上写这两枚令牌 —— 各件都把消费方的 `class`
+  落在自己的**可见箱**上（`Input` 是表壳 `.mh-input__wrap`、`Select` / `SelectTree` 是触发器表壳、
+  `Search` 是整行那个根）。两枚令牌都**向下继承**，故挂在容器的任意祖先上同样成立。
+
 ### 正误对照
 
 ```css
@@ -253,13 +274,13 @@ configureHost(hostEl)
 
 | 条款 | 要什么（闭集） | 为什么 |
 | --- | --- | --- |
-| **L1.5-1 唯一来源** | 需要图形处一律 `<Icon name="…" />`（非 Vue 场景用 `renderIconSvg()`）。**不得**自绘（`<svg` / `<path` / `<circle`）；**不得**用文字符号（`✓` `⌄` `×` `▶` `←`）冒充 | 一套线重、一个视觉族；文字符号在不同字体下高矮不一 |
+| **L1.5-1 唯一来源** | 需要图形处一律 `<Icon name="…" />`（非 Vue 场景用 `renderIconSvg()`）。**不得**自绘（`<svg` / `<path` / `<circle`）；**不得**用文字符号（`✓` `⌄` `×` `▶` `←`）冒充。**唯一例外**：本项目自带的业务字形 —— 写进 `<Icon>` 的**默认插槽**，且图形集中在一处定义（L1.5-6 第 ③ 类） | 一套线重、一个视觉族；文字符号在不同字体下高矮不一 |
 | **L1.5-2 尺寸在面层给** | 图标槽**只写 `width` / `height`** 两个属性，值取 `var(--ui-font-icon)`（要档距用 `calc()`）；件内令牌写成它的**别名**。**不传 `size`** | `size` 默认 16，不写就静默落到 16；写死了也不跟主题缩放。**消费侧没有例外** |
 | **L1.5-3 只继承色、不承载色** | 不给图标写任何颜色（`color` / `stroke` / `fill` / `stroke-width`） | 图标随文案色；theme 里**有意没有 icons 片**，不要想着去补一片 |
 | **L1.5-4 方位在字形里** | 方位一律 `chevron-*`（四向齐备）；**不得**为「翻向」写 `transform: rotate()`。面层出现 `rotate(` 的唯一合法情形是 `loading` 的转圈动效；`back` 只作「返回」语义 | 旋转过的字形在视觉上不是同一个族 |
 | **L1.5-5 语义图标按容器挑族** | 图标位**有**圆形色底 → 取裸字形（`info` / `check` / `alert` / `close`），色底那一圈由**组件**给（字形再自带一圈会叠成双圈）；图标位**没有**色底 → 取带圈字形（`info-circle` / `check-circle` / `alert-circle` / `close-circle`），否则裸符号孤零零撑不住状态的分量 | 两族各自成立，混用必错一边 |
-| **L1.5-6 名字取自清单，缺图标补包** | `name` 必须能在 `IconNameList` 里搜到；缺图标 → 在 `@manohub/icon` 加一条并重 build，**不在应用仓画路，也不在 ui 画路** | 就地画一个 = 第二次分叉 |
-| **L1.5-7 入口分栈** | Vue 应用只认主入口 `@manohub/icon`；`@manohub/icon/glyphs` **只在没有 Vue 组件可用处**（静态页 / 模板串 / 非 Vue 栈） | 两个入口的产物类型不同 |
+| **L1.5-6 缺图形时按三类走** | **① 通用 UI 字形**（`chevron-*` / `edit` / `search` / `info` …）→ `name` 必须能在 `IconNameList` 里搜到；缺了就补 `@manohub/icon` 并重 build，**不得**在应用仓画。**② 产品专属图形**（多色 / 渐变 / 品牌 logo / 插画）→ **不进字形表**，留应用侧 assets。**③ 本项目业务字形**（本菜单 / 页头专属的**单色**字形）→ 走 `<Icon>` 的**默认插槽**：`<Icon><path …/></Icon>`（整段 SVG 用 `icon-from-svg` 归一成片段）。硬要求：图形**集中在项目自己的一个文件里**，不得在页面里就地画裸 `<svg>` | 判据：**散装内联 `<svg>` = 第二次分叉；`<Icon>` 插槽 + 集中定义 ≠ 分叉**。防的是「同一图形两处各画一遍、改一处漏一处」，不是「字形必须出自中央包」—— 中央包发版要走完整个流程，业务字形不该排那个队 |
+| **L1.5-7 入口分栈** | Vue 应用只认主入口 `@manohub/icon`；`@manohub/icon/glyphs` **只在没有 Vue 组件可用处**（静态页 / 模板串 / 非 Vue 栈）；`@manohub/icon/svg` 是**归一工具**（构建期 `icon-from-svg` 用，也可在运行期应急归一），不做渲染 | 三个入口的产物职责不同 |
 
 ### 正误对照
 
@@ -274,6 +295,24 @@ configureHost(hostEl)
 .vm-select-caret { width: var(--ui-font-icon); height: var(--ui-font-icon); }
 ```
 
+业务字形（L1.5-6 第 ③ 类）的合法姿势 —— 图形集中在一处、经 `<Icon>` 的插槽渲染：
+
+```tsx
+// icons.ts —— 项目唯一一处字形定义；整段 SVG 可先用 icon-from-svg 归一成片段（产物进 git 可 review）
+export const MY_GLYPHS = { 'aip-foo': '<g transform="scale(1.5)" fill="currentColor" stroke="none">…</g>' }
+
+// 调用点
+import { Icon } from '@manohub/icon'
+import { MY_GLYPHS } from './icons'
+<Icon>{MY_GLYPHS['aip-foo']}</Icon>
+<Icon><path d="M2 2h6v6H2z" /></Icon>   {/* 现写现用也行，前提是这一处就是唯一出处 */}
+```
+
+```tsx
+// ✗ 散装内联：这一处画一个 <svg>，另一处又画一个 —— 同一图形两处各一份，改一处必漏一处
+<svg viewBox="0 0 24 24"><path d="…" /></svg>
+```
+
 自检见 §7 第 9–12 问。
 
 ---
@@ -460,10 +499,10 @@ import Sortable from 'sortablejs'                        // 行为库：不产
 
 **L1.5**
 
-9. 我这次用到的每个图形都是 `<Icon name="…">` 吗？有没有手绘 `<svg` / 用 `✓ ⌄ ×` 一类文字符号冒充？
+9. 我这次用到的每个图形都是 `<Icon>` 吗（内置走 `name`、业务字形走默认插槽）？有没有手绘裸 `<svg` / 用 `✓ ⌄ ×` 一类文字符号冒充？**业务字形若是我自己加的**：是否集中在唯一的 `icons.ts` 里、别处只是引用？
 10. 我有没有给 `<Icon>` 传 `size`？尺寸是在 CSS 里写 `var(--ui-font-icon)` 吗？
 11. 我有没有给图标写颜色（`color` / `stroke` / `fill` / `stroke-width`）？面层出现 `rotate(` 了吗（只允许 `loading` 的转圈）？
-12. 我用的 `name` 在 `IconNameList` 里搜得到吗？方位是 `chevron-*` 吗？有没有把 `back` 当方位？
+12. 我用的 `name` 在 `IconNameList` 里搜得到吗（业务字形走插槽，本就不该出现在 `name` 里）？方位是 `chevron-*` 吗？有没有把 `back` 当方位？
 
 **L2**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manohub/kit",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "type": "module",
   "description": "子应用入口编排层：createSubApp（作用域容器与宿主锚点、pinia/路由/vue-query 装配、宿主挂载协议）、i18n 单实例与语言探测，外加随包分发的接入契约（CONTRACT.md，五层闭集条款 + 自检清单）与三个 AI 技能包。本包**零样式产物**：设计令牌（值）在 @manohub/theme，组件（类与行为）在 @manohub/ui，两者由消费方直接引入。",