@manohub/icon 0.10.5 → 1.0.1

package/README.md

@@ -1,125 +1,125 @@
-# @manohub/icon
-
-AIHub 图标包：**图标表**（名字 → SVG 片段字符串）+ **纯字符串渲染器** + **Vue `<Icon>` 组件**。
-TS 源码、**不含 JSX**，`tsc` 一个命令直出 `dist`（不引 vite、不引 vue-tsc）；任何仓库、任何 UI 栈都可消费。
-
-## 为什么单独成包
-
-原先图标寄居在 `@manohub/ui/components/icon`（经子路径 `@manohub/ui/icon` 暴露）。问题：
-
-1. `@manohub/ui` 是 Tailwind + reka + cva 栈的组件库，**消费它意味着连带接受整套栈**；
-2. `packages/kit`（farris 封装 + 原生 CSS，无 Tailwind）只需要一个图标，却因此成为 `@manohub/ui` 的依赖方；
-3. 跨仓分发时，一个只想用图标的工程不应被迫安装组件库。
-
-抽出后依赖方向变为：`@manohub/ui` 与 `@manohub/kit` **都依赖** `@manohub/icon`，图标成为两侧共享的底座，不再有"骨架层依赖组件库"的倒挂。
-
-## 两个入口
-
-| 入口 | 内容 | 是否引 `vue` |
-|---|---|---|
-| `@manohub/icon` | `Icon` 组件 + 图标表 + 字符串渲染器 | 是（组件那半边） |
-| `@manohub/icon/glyphs` | 图标表 + `renderIconSvg()` + `IconNameList` | **否** |
-
-### 纯 JS 用法（不装 Vue、不打包、静态页也能用）
-
-```js
-import { renderIconSvg, ICON_GLYPHS } from '@manohub/icon/glyphs'
-
-el.innerHTML = renderIconSvg('refresh', { size: 18, class: 'text-primary' })
-// 或者只要片段，自己包一层容器：
-el.innerHTML = `<svg viewBox="0 0 24 24" width="18" height="18">${ICON_GLYPHS.refresh}</svg>`
-```
-
-`renderIconSvg` 产出的属性（`viewBox` / `data-slot` / `fill` / `stroke` / `stroke-width` / 圆头端点 / 基底内联样式）与 `<Icon>` 组件**逐字一致**，两版可以互相替换。
-
-### Vue 组件用法
-
-```tsx
-import { Icon, IconNameList, type IconName } from '@manohub/icon'
-
-<Icon name="page-title" size={26} />
-<Icon name="refresh" size={16} class="text-primary" />
-```
-
-- `name`：图标名（`IconName` 联合类型，取自内容表键名；运行时清单见 `IconNameList`）
-- `size`：宽高（px，同时设置 `width`/`height`，默认 16）
-- `class`：附加类名（基底样式为内联 style，不再占用类名）
-- `style`：附加内联样式，会与基底样式合并（同键以消费方传入的为准）
-- 图标为 24×24 viewBox 的 SVG 片段，`stroke` 继承 `currentColor`（随文字颜色）
-
-## 交付形态：TS 源码 + `tsc` 直出 dist
-
-```bash
-pnpm --filter @manohub/icon build        # node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json
-pnpm --filter @manohub/icon type-check   # tsc --noEmit -p tsconfig.json
-```
-
-- `exports` 指向 `dist`（产物分发，与 `ui` / `kit` 一致），消费方无需任何别名或 `paths` 映射。
-- **不需要 vite、也不需要 vue-tsc**：源码里没有 JSX（图标数据是字符串，组件用 `h()` + `innerHTML` 渲染），
-  没有 CSS、没有第三方运行时依赖，所以纯 `tsc` 就能同时产出 `dist/*.js` 与 `dist/*.d.ts`。
-- **类型是编译产出的**（`dist/*.d.ts`），不是手写声明 —— 新增图标时类型自动跟着内容表走，不会漂。
-- 内部 `content` 以 `innerHTML` 注入：数据是包内静态常量、不含任何外部输入，无注入面；
-  代价是片段必须自带合法闭合（表里的串按此约定生成，SSR 与浏览器解析结果一致）。
-
-## 依赖与行为约定
-
-- **零运行时依赖 + 零 CSS 依赖**：不引入 `clsx` / `tailwind-merge`，也不依赖任何 CSS 框架；类名直接透传，无需任何合并工具。
-- **基底样式为内联 style**：`{ display: 'inline-block', flexShrink: '0' }`。
-  原先是 Tailwind 工具类 `inline-block shrink-0` —— 在 Tailwind 仓（如 portal）生效，在非 Tailwind 仓（如 kit 各子应用）是**死类**，图标会丢掉 `flex-shrink: 0`、在 flex 行内被长文本压扁；改内联 style 后两种栈取值一致。
-  **代价**：内联 style 优先级高于 class，**无法再用 class 覆盖 `display` / `flex-shrink`**（需要覆盖时请传 `style` —— Vue 会把回退的 style 与基底对象合并，同键以后者为准）。
-- **未知图标名渲染成空图标，不抛错**：消费方可能把业务侧来的字符串透传给 `icon`（如头像的图标档），
-  抛错会把整棵组件树带崩；拼写错误由 `IconName` 类型在编译期拦住。
-- 本包只含图标，不含任何 CSS 文件（`sideEffects: false`），不引入样式副作用。
-- 与 `aihub-ui` 仓的 `@aihub/ui`（自带 `renderIcon` / `ICON_NAMES`）**是两套独立图标资产**。
-  本包随 `frontend-infra` 独立分发，不绑定任何单一消费仓。
-
-## 维护
-
-图标内容表在 `src/glyphs.ts`：新增图标 = 在 `ICON_GLYPHS` 里加一条 `name: '<path …/>'`，
-`IconName` / `IconNameList` 与类型声明都由键自动推导，**无需改别处**；改完重新 `build` 即可。
-
-约定：片段内不写容器属性（`viewBox`/`width`/`stroke` 由渲染方统一给）；线性图标继承 `currentColor`；实心图标显式 `fill="currentColor" stroke="none"`。
-
-### 命名与用法约定
-
-- **一律 kebab-case**：动作类用业务动词（`edit` / `delete` / `copy` / `refresh` / `upload`），方位类用 `-left` / `-right` / `-up` / `-down` 后缀。
-- **按用途取名，不按形状取名**（0.7.0 起收紧）。判据一句话：**看到名字，能猜到该在什么场景用它吗？**
-  - ✅ `edit` / `delete` / `preview` / `notification` —— 要「编辑 / 删除 / 预览 / 通知」时直接想到它；
-  - ❌ `pencil` / `trash` / `eye` / `bell` —— 说的是「画的是什么」，用它得先知道「编辑图标画的是一支铅笔」；
-  - **符号族例外**：`plus` / `minus` / `check` / `close` / `info` / `alert` / `more` 保留符号名 ——
-    符号本身就是语义的最小载体（`+` 就是「加」），改叫 `add` / `subtract` 反而啰嗦；带圈族
-    （`plus-circle` / `close-circle` / `info-circle` / `check-circle` / `alert-circle`）同理。
-  - **语义符号分两族**：裸符号（`info` / `check` / `alert` / `close`）给**自带圆形色底**的容器用
-    （`Toast` 的 18px 圆底）；带圈字形（`info-circle` / `check-circle` / `alert-circle` / `close-circle`）
-    给**没有色底**的光图标位用（`Notice` / `Notification` / `Dialog` 的语义图标）。挑错族要么与色底叠成
-    双圈，要么显得孤零零。
-- **一处只承担一个语义**：`grid-dots` 曾同时当「宫格入口」（我的技能）与「拖拽手柄」（列表排序），
-  0.7.0 拆成 `apps`（9 点宫格）与 `drag-handle`（6 点手柄）两个字形。
-- **线性路径数据取自 [lucide](https://lucide.dev)（ISC License）**，与既有 `file-text` / `chevron-down` / `folder` 同源，线重与 24 视口口径一致；自绘图标（设计稿原始路径，如 `page-title` / `favorite` / `settings`）在条目上方注明出处。
-- **方位只有一个族：`chevron-*`**（四个方向齐备）。翻页、展开收起、下拉 caret、表头升降序一律用它；**禁止再用 `transform: rotate()` 把别的图标转成方位**——旋转是补丁，时间一长没人知道原字形是什么。
-- **`back` 是"返回"语义**（↩ 曲线箭头，实心填充族），只用于返回上一级 / 面包屑。它**不响应 `stroke-width`**（线重烘在路径几何里），与描边族并排时粗细对不上，别塞进描边图标的位置。
-- **判据一句话**：这个箭头要能四向切换吗？要 → `chevron-*`；不要且含"回退"含义 → `back`。
-- **实心 / 空心配对用 `-filled` 后缀**（沿 `favorite` / `favorite-filled`），不写 `-solid` / `-fill`。
-- **新增前先查 `IconNameList` 是否已有同义项**（例如"查找"已由 `search` 覆盖，不要再造 `lookup`；"删除"用 `delete`，不要并存 `trash`）。
-
-### 0.7.0 改名对照（**不给别名**）
-
-0.6.x 的旧名已从表里移除，**没有 alias** —— 升级后按 `IconName` 的类型报错逐个替换即可。
-
-| 0.6.x | 0.7.0 | 为什么改 |
-| --- | --- | --- |
-| `bell` | `notification` | 用途是「通知」，`bell` 说的是「画的是一只铃铛」 |
-| `wrench` | `tool` | 用途是「工具」（MCP 工具列表），`wrench` 说的是「画的是一把扳手」 |
-| `heart` | `favorite` | 用途是「收藏 / 订阅」 |
-| `heart-filled` | `favorite-filled` | 实心配对，随 `heart` 一起改 |
-| `eye` | `preview` | 用途是「预览」（密码可见性切换也走它） |
-| `grid-dots` | `apps` + `drag-handle` | 原来一名两用，拆成「宫格入口」与「拖拽手柄」两个字形 |
-| `sparkles` | `ai` | 用途是「AI 场景」，`sparkles` 说的是「画的是一片星光」 |
-
-**没改的**：其余本来就是用途名（`folder` / `file-code` / `settings` / `filter` / `chevron-*` / `search` …），
-以及符号族（`plus` / `minus` / `check` / `close` / `info` / `alert` / `more` 与带圈族 `plus-circle` /
-`close-circle` / `info-circle` / `check-circle` / `alert-circle`）—— 见上方判据。
-
-> ⚠️ **`@manohub/base-ui` 里另有一份图标副本**（旧 66 个，含 `bell` / `heart` / `grid-dots` / `wrench`），
-> 本包改名**不影响它**。portal 目前两处混用（`AppNavbar` 走本包、`ConsoleSidebar` 等走 base-ui），
-> 会出现新旧名并存；portal 迁到本包时按上表对齐即可。
+# @manohub/icon
+
+AIHub 图标包：**图标表**（名字 → SVG 片段字符串）+ **纯字符串渲染器** + **Vue `<Icon>` 组件**。
+TS 源码、**不含 JSX**，`tsc` 一个命令直出 `dist`（不引 vite、不引 vue-tsc）；任何仓库、任何 UI 栈都可消费。
+
+## 为什么单独成包
+
+原先图标寄居在 `@manohub/ui/components/icon`（经子路径 `@manohub/ui/icon` 暴露）。问题：
+
+1. `@manohub/ui` 是 Tailwind + reka + cva 栈的组件库，**消费它意味着连带接受整套栈**；
+2. `packages/kit`（farris 封装 + 原生 CSS，无 Tailwind）只需要一个图标，却因此成为 `@manohub/ui` 的依赖方；
+3. 跨仓分发时，一个只想用图标的工程不应被迫安装组件库。
+
+抽出后依赖方向变为：`@manohub/ui` 与 `@manohub/kit` **都依赖** `@manohub/icon`，图标成为两侧共享的底座，不再有"骨架层依赖组件库"的倒挂。
+
+## 两个入口
+
+| 入口 | 内容 | 是否引 `vue` |
+|---|---|---|
+| `@manohub/icon` | `Icon` 组件 + 图标表 + 字符串渲染器 | 是（组件那半边） |
+| `@manohub/icon/glyphs` | 图标表 + `renderIconSvg()` + `IconNameList` | **否** |
+
+### 纯 JS 用法（不装 Vue、不打包、静态页也能用）
+
+```js
+import { renderIconSvg, ICON_GLYPHS } from '@manohub/icon/glyphs'
+
+el.innerHTML = renderIconSvg('refresh', { size: 18, class: 'text-primary' })
+// 或者只要片段，自己包一层容器：
+el.innerHTML = `<svg viewBox="0 0 24 24" width="18" height="18">${ICON_GLYPHS.refresh}</svg>`
+```
+
+`renderIconSvg` 产出的属性（`viewBox` / `data-slot` / `fill` / `stroke` / `stroke-width` / 圆头端点 / 基底内联样式）与 `<Icon>` 组件**逐字一致**，两版可以互相替换。
+
+### Vue 组件用法
+
+```tsx
+import { Icon, IconNameList, type IconName } from '@manohub/icon'
+
+<Icon name="page-title" size={26} />
+<Icon name="refresh" size={16} class="text-primary" />
+```
+
+- `name`：图标名（`IconName` 联合类型，取自内容表键名；运行时清单见 `IconNameList`）
+- `size`：宽高（px，同时设置 `width`/`height`，默认 16）
+- `class`：附加类名（基底样式为内联 style，不再占用类名）
+- `style`：附加内联样式，会与基底样式合并（同键以消费方传入的为准）
+- 图标为 24×24 viewBox 的 SVG 片段，`stroke` 继承 `currentColor`（随文字颜色）
+
+## 交付形态：TS 源码 + `tsc` 直出 dist
+
+```bash
+pnpm --filter @manohub/icon build        # node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json
+pnpm --filter @manohub/icon type-check   # tsc --noEmit -p tsconfig.json
+```
+
+- `exports` 指向 `dist`（产物分发，与 `ui` / `kit` 一致），消费方无需任何别名或 `paths` 映射。
+- **不需要 vite、也不需要 vue-tsc**：源码里没有 JSX（图标数据是字符串，组件用 `h()` + `innerHTML` 渲染），
+  没有 CSS、没有第三方运行时依赖，所以纯 `tsc` 就能同时产出 `dist/*.js` 与 `dist/*.d.ts`。
+- **类型是编译产出的**（`dist/*.d.ts`），不是手写声明 —— 新增图标时类型自动跟着内容表走，不会漂。
+- 内部 `content` 以 `innerHTML` 注入：数据是包内静态常量、不含任何外部输入，无注入面；
+  代价是片段必须自带合法闭合（表里的串按此约定生成，SSR 与浏览器解析结果一致）。
+
+## 依赖与行为约定
+
+- **零运行时依赖 + 零 CSS 依赖**：不引入 `clsx` / `tailwind-merge`，也不依赖任何 CSS 框架；类名直接透传，无需任何合并工具。
+- **基底样式为内联 style**：`{ display: 'inline-block', flexShrink: '0' }`。
+  原先是 Tailwind 工具类 `inline-block shrink-0` —— 在 Tailwind 仓（如 portal）生效，在非 Tailwind 仓（如 kit 各子应用）是**死类**，图标会丢掉 `flex-shrink: 0`、在 flex 行内被长文本压扁；改内联 style 后两种栈取值一致。
+  **代价**：内联 style 优先级高于 class，**无法再用 class 覆盖 `display` / `flex-shrink`**（需要覆盖时请传 `style` —— Vue 会把回退的 style 与基底对象合并，同键以后者为准）。
+- **未知图标名渲染成空图标，不抛错**：消费方可能把业务侧来的字符串透传给 `icon`（如头像的图标档），
+  抛错会把整棵组件树带崩；拼写错误由 `IconName` 类型在编译期拦住。
+- 本包只含图标，不含任何 CSS 文件（`sideEffects: false`），不引入样式副作用。
+- 与 `aihub-ui` 仓的 `@aihub/ui`（自带 `renderIcon` / `ICON_NAMES`）**是两套独立图标资产**。
+  本包随 `frontend-infra` 独立分发，不绑定任何单一消费仓。
+
+## 维护
+
+图标内容表在 `src/glyphs.ts`：新增图标 = 在 `ICON_GLYPHS` 里加一条 `name: '<path …/>'`，
+`IconName` / `IconNameList` 与类型声明都由键自动推导，**无需改别处**；改完重新 `build` 即可。
+
+约定：片段内不写容器属性（`viewBox`/`width`/`stroke` 由渲染方统一给）；线性图标继承 `currentColor`；实心图标显式 `fill="currentColor" stroke="none"`。
+
+### 命名与用法约定
+
+- **一律 kebab-case**：动作类用业务动词（`edit` / `delete` / `copy` / `refresh` / `upload`），方位类用 `-left` / `-right` / `-up` / `-down` 后缀。
+- **按用途取名，不按形状取名**（0.7.0 起收紧）。判据一句话：**看到名字，能猜到该在什么场景用它吗？**
+  - ✅ `edit` / `delete` / `preview` / `notification` —— 要「编辑 / 删除 / 预览 / 通知」时直接想到它；
+  - ❌ `pencil` / `trash` / `eye` / `bell` —— 说的是「画的是什么」，用它得先知道「编辑图标画的是一支铅笔」；
+  - **符号族例外**：`plus` / `minus` / `check` / `close` / `info` / `alert` / `more` 保留符号名 ——
+    符号本身就是语义的最小载体（`+` 就是「加」），改叫 `add` / `subtract` 反而啰嗦；带圈族
+    （`plus-circle` / `close-circle` / `info-circle` / `check-circle` / `alert-circle`）同理。
+  - **语义符号分两族**：裸符号（`info` / `check` / `alert` / `close`）给**自带圆形色底**的容器用
+    （`Toast` 的 18px 圆底）；带圈字形（`info-circle` / `check-circle` / `alert-circle` / `close-circle`）
+    给**没有色底**的光图标位用（`Notice` / `Notification` / `Dialog` 的语义图标）。挑错族要么与色底叠成
+    双圈，要么显得孤零零。
+- **一处只承担一个语义**：`grid-dots` 曾同时当「宫格入口」（我的技能）与「拖拽手柄」（列表排序），
+  0.7.0 拆成 `apps`（9 点宫格）与 `drag-handle`（6 点手柄）两个字形。
+- **线性路径数据取自 [lucide](https://lucide.dev)（ISC License）**，与既有 `file-text` / `chevron-down` / `folder` 同源，线重与 24 视口口径一致；自绘图标（设计稿原始路径，如 `page-title` / `favorite` / `settings`）在条目上方注明出处。
+- **方位只有一个族：`chevron-*`**（四个方向齐备）。翻页、展开收起、下拉 caret、表头升降序一律用它；**禁止再用 `transform: rotate()` 把别的图标转成方位**——旋转是补丁，时间一长没人知道原字形是什么。
+- **`back` 是"返回"语义**（↩ 曲线箭头，实心填充族），只用于返回上一级 / 面包屑。它**不响应 `stroke-width`**（线重烘在路径几何里），与描边族并排时粗细对不上，别塞进描边图标的位置。
+- **判据一句话**：这个箭头要能四向切换吗？要 → `chevron-*`；不要且含"回退"含义 → `back`。
+- **实心 / 空心配对用 `-filled` 后缀**（沿 `favorite` / `favorite-filled`），不写 `-solid` / `-fill`。
+- **新增前先查 `IconNameList` 是否已有同义项**（例如"查找"已由 `search` 覆盖，不要再造 `lookup`；"删除"用 `delete`，不要并存 `trash`）。
+
+### 0.7.0 改名对照（**不给别名**）
+
+0.6.x 的旧名已从表里移除，**没有 alias** —— 升级后按 `IconName` 的类型报错逐个替换即可。
+
+| 0.6.x | 0.7.0 | 为什么改 |
+| --- | --- | --- |
+| `bell` | `notification` | 用途是「通知」，`bell` 说的是「画的是一只铃铛」 |
+| `wrench` | `tool` | 用途是「工具」（MCP 工具列表），`wrench` 说的是「画的是一把扳手」 |
+| `heart` | `favorite` | 用途是「收藏 / 订阅」 |
+| `heart-filled` | `favorite-filled` | 实心配对，随 `heart` 一起改 |
+| `eye` | `preview` | 用途是「预览」（密码可见性切换也走它） |
+| `grid-dots` | `apps` + `drag-handle` | 原来一名两用，拆成「宫格入口」与「拖拽手柄」两个字形 |
+| `sparkles` | `ai` | 用途是「AI 场景」，`sparkles` 说的是「画的是一片星光」 |
+
+**没改的**：其余本来就是用途名（`folder` / `file-code` / `settings` / `filter` / `chevron-*` / `search` …），
+以及符号族（`plus` / `minus` / `check` / `close` / `info` / `alert` / `more` 与带圈族 `plus-circle` /
+`close-circle` / `info-circle` / `check-circle` / `alert-circle`）—— 见上方判据。
+
+> ⚠️ **`@manohub/base-ui` 里另有一份图标副本**（旧 66 个，含 `bell` / `heart` / `grid-dots` / `wrench`），
+> 本包改名**不影响它**。portal 目前两处混用（`AppNavbar` 走本包、`ConsoleSidebar` 等走 base-ui），
+> 会出现新旧名并存；portal 迁到本包时按上表对齐即可。

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "@manohub/icon",
-  "version": "0.10.5",
-  "private": false,
-  "type": "module",
-  "description": "AIHub 图标包：内置 SVG 图标内容表 + 纯字符串渲染器 + <Icon> 组件。零运行时依赖（仅 peer vue），供任意 UI 栈消费",
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://git.iec.io/gsp-cloud-ds/dip/ibp/aihub/frontend-infra.git",
-    "directory": "packages/icon"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./glyphs": {
-      "types": "./dist/glyphs.d.ts",
-      "import": "./dist/glyphs.js"
-    }
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "scripts": {
-    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
-    "type-check": "tsc --noEmit -p tsconfig.json"
-  },
-  "peerDependencies": {
-    "vue": "^3.5.0"
-  },
-  "devDependencies": {
-    "typescript": "catalog:",
-    "vue": "catalog:"
-  }
-}
+{
+  "name": "@manohub/icon",
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "description": "AIHub 图标包：内置 SVG 图标内容表 + 纯字符串渲染器 + <Icon> 组件。零运行时依赖（仅 peer vue），供任意 UI 栈消费",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.iec.io/gsp-cloud-ds/dip/ibp/aihub/frontend-infra.git",
+    "directory": "packages/icon"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./glyphs": {
+      "types": "./dist/glyphs.d.ts",
+      "import": "./dist/glyphs.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vue": "^3.5.40"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit -p tsconfig.json"
+  }
+}