@manohub/ui 0.10.5 → 1.0.1

package/dist/components/select/select-trigger.d.ts

@@ -21,6 +21,14 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
+     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
+     */
+    bordered: {
+        type: PropType<boolean | "focus">;
+        default: boolean;
+    };
     clearable: {
         type: BooleanConstructor;
         default: boolean;
@@ -90,6 +98,14 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
+     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
+     */
+    bordered: {
+        type: PropType<boolean | "focus">;
+        default: boolean;
+    };
     clearable: {
         type: BooleanConstructor;
         default: boolean;
@@ -145,6 +161,7 @@ export declare const SelectTrigger: import("vue").DefineComponent<import("vue").
     disabled: boolean;
     label: string;
     onKeydown: (event: KeyboardEvent) => void;
+    bordered: boolean | "focus";
     placeholder: string;
     status: InputStatus;
     clearable: boolean;

package/dist/components/select/select-trigger.js

@@ -24,6 +24,14 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
+    /**
+     * 有无边框（**直接透传给输入面**，三档口径与 `Input` 的同名 prop 完全一致）：
+     * `true` 常有框 / `false` 无框（任何状态都不显）/ `'focus'` 聚焦（与悬停）才显框。
+     */
+    bordered: {
+      type: [Boolean, String],
+      default: true
+    },
     clearable: {
       type: Boolean,
       default: false
@@ -81,6 +89,7 @@ const SelectTrigger = /* @__PURE__ */ defineComponent({
       "size": props.size,
       "status": props.status,
       "disabled": props.disabled,
+      "bordered": props.bordered,
       "clearable": props.clearable,
       "hasValue": props.hasValue,
       "placeholder": props.placeholder,

package/dist/components/table/index.d.ts

@@ -50,6 +50,36 @@ export interface TableRowProps {
     class?: string;
     onClick?: (row: TableRow, index: number, event: MouseEvent) => void;
 }
+/**
+ * `#cell` 插槽的作用域 —— **单元格编辑走这条**。
+ *
+ * 表格**不替调用方渲染控件**：编辑格要摆什么（`Input` / `Select` / `NumberInput`、外层要不要套
+ * `Form.Item` 拿 label 位与错误文案位、只读态摆什么）全由调用方在插槽里决定。口径与 `Form.Item`
+ * 同款 —— 它的默认插槽也是「你自己放控件」；骨架层因此不必猜每种业务格子的排版，
+ * 也不会把「哪一格长什么样」的开关堆成一张越来越长的 prop 表。
+ *
+ * **回写是受控的**：`setValue(next)` 只把「这一格变成了什么」上报出去
+ * （= 发一次 `onCellChange(row, column.key, next, index)`）。本件**从不改 `data`** ——
+ * 新数组与「这次改动该不该被接受」都由调用方决定，与行选中同一套受控口径。
+ *
+ * @example 编辑格：套 `Form.Item` 拿错误位，控件自己绑值、回写走 `setValue`
+ * <Table :columns="columns" :data="rows" row-key="id" layout="fixed" :on-cell-change="write">
+ *   <template #cell="{ row, column, value, index, setValue }">
+ *     <!-- 格子里的框由控件自己带：默认有框 / `:bordered="false"` 无框 / `bordered="focus"` 聚焦才显框 -->
+ *     <Input v-if="column.key === 'name'" :model-value="String(value ?? '')" @change="setValue" />
+ *     <template v-else>{{ value }}</template>
+ *   </template>
+ * </Table>
+ */
+export interface TableCellSlotScope {
+    row: TableRow;
+    column: TableColumn;
+    /** 该格当前值（`row[column.key]` 的原值；表格不改写它，也不做任何格式化） */
+    value: unknown;
+    index: number;
+    /** 上报该格的新值（= 发一次 `onCellChange`）；调用方没接 `onCellChange` 时是空操作 */
+    setValue: (next: unknown) => void;
+}
 /**
  * 行级可勾选判定（`selectable` 的函数形态）：返回 `false` 的行渲染**禁用态**勾选框，
  * 且不进表头全选的增删范围。签名与 `onRow` / `rowClass` 一致（都给 `index`）。
@@ -150,6 +180,17 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
+     *
+     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
+     * 要不要接受、以及新数组怎么产生，都由调用方决定。
+     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     */
+    onCellChange: {
+        type: PropType<(row: TableRow, key: string, value: unknown, index: number) => void>;
+        default: undefined;
+    };
     /** 尺寸档：`sm` 紧凑（表格嵌在卡片里）/ `md` 标准 / `lg` 宽松（详情页） */
     size: {
         type: PropType<ControlSize>;
@@ -160,7 +201,18 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
-    borderless: {
+    /**
+     * 有无外框（缺省**有**框）：去外框写 `:bordered="false"`。
+     *
+     * **极性口径**：本库的「有无外框」一律用**肯定式** `bordered`（`Input` / `Textarea` /
+     * `NumberInput` / `Nav` 同款，见 `docs/guide/naming-and-defaults.md` §2.1）。本件原名
+     * `borderless`（否定式、默认 `false`），2026-10 按同名同义统一改成 `bordered` —— 默认行为不变
+     * （都是「缺省有框」），只是名字的极性换到与其余件一致，调用方不必再记「哪件用否定式」。
+     *
+     * 类名仍是 `.mh-table--borderless`：面层词根**统一为否定式**（输入族关框时也输出它），
+     * 与 prop 的极性相反 —— 两套各自内部一致，`Input` 的文档页记着同一处口径。
+     */
+    bordered: {
         type: BooleanConstructor;
         default: boolean;
     };
@@ -297,6 +349,17 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
+     *
+     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
+     * 要不要接受、以及新数组怎么产生，都由调用方决定。
+     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     */
+    onCellChange: {
+        type: PropType<(row: TableRow, key: string, value: unknown, index: number) => void>;
+        default: undefined;
+    };
     /** 尺寸档：`sm` 紧凑（表格嵌在卡片里）/ `md` 标准 / `lg` 宽松（详情页） */
     size: {
         type: PropType<ControlSize>;
@@ -307,7 +370,18 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
-    borderless: {
+    /**
+     * 有无外框（缺省**有**框）：去外框写 `:bordered="false"`。
+     *
+     * **极性口径**：本库的「有无外框」一律用**肯定式** `bordered`（`Input` / `Textarea` /
+     * `NumberInput` / `Nav` 同款，见 `docs/guide/naming-and-defaults.md` §2.1）。本件原名
+     * `borderless`（否定式、默认 `false`），2026-10 按同名同义统一改成 `bordered` —— 默认行为不变
+     * （都是「缺省有框」），只是名字的极性换到与其余件一致，调用方不必再记「哪件用否定式」。
+     *
+     * 类名仍是 `.mh-table--borderless`：面层词根**统一为否定式**（输入族关框时也输出它），
+     * 与 prop 的极性相反 —— 两套各自内部一致，`Input` 的文档页记着同一处口径。
+     */
+    bordered: {
         type: BooleanConstructor;
         default: boolean;
     };
@@ -414,11 +488,12 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
     expandedKeys: (string | number)[];
     defaultExpandedKeys: (string | number)[];
     onExpandChange: (keys: Array<string | number>) => void;
+    bordered: boolean;
     modelValue: (string | number)[];
     emptyText: string;
     selectable: boolean | TableRowSelectable;
     striped: boolean;
-    borderless: boolean;
+    onCellChange: (row: TableRow, key: string, value: unknown, index: number) => void;
     stickyHead: boolean;
     stickyCol: boolean;
     showHeader: boolean;
@@ -429,13 +504,13 @@ export declare const Table: import("vue").DefineComponent<import("vue").ExtractP
     expandable: (row: TableRow, index: number) => VNodeChild;
     pagination: false | TablePagination;
 }, SlotsType<{
-    /** 单元格：`{ row, column, value, index }`（不给则直接输出原值） */
-    cell?: (context: {
-        row: TableRow;
-        column: TableColumn;
-        value: unknown;
-        index: number;
-    }) => VNodeChild;
+    /**
+     * 单元格：`{ row, column, value, index, setValue }`（不给则直接输出原值）。
+     *
+     * **编辑格也走这里**（见 `TableCellSlotScope` 的说明）：本件不替调用方渲染控件，
+     * 只给值、给位置、给一个受控的回写口 `setValue`。
+     */
+    cell?: (context: TableCellSlotScope) => VNodeChild;
     /** 行尾操作区：`{ row, index }`（面里用 `align: 'right'` 的列承载） */
     actions?: (context: {
         row: TableRow;

package/dist/components/table/index.js

@@ -43,6 +43,17 @@ const Table = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
+    /**
+     * 单元格值变更 —— 由 `#cell` 插槽里的 `setValue` 触发，是**唯一的回写通道**。
+     *
+     * 本件**不改 `data`**（与本仓表格一贯的克制口径一致：全受控、只发事件、不排序、不切片）；
+     * 要不要接受、以及新数组怎么产生，都由调用方决定。
+     * 没接这个回调时 `setValue` 是空操作（插槽里的控件照旧可绑，不会报错）。
+     */
+    onCellChange: {
+      type: Function,
+      default: void 0
+    },
     /** 尺寸档：`sm` 紧凑（表格嵌在卡片里）/ `md` 标准 / `lg` 宽松（详情页） */
     size: {
       type: String,
@@ -53,9 +64,20 @@ const Table = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    borderless: {
+    /**
+     * 有无外框（缺省**有**框）：去外框写 `:bordered="false"`。
+     *
+     * **极性口径**：本库的「有无外框」一律用**肯定式** `bordered`（`Input` / `Textarea` /
+     * `NumberInput` / `Nav` 同款，见 `docs/guide/naming-and-defaults.md` §2.1）。本件原名
+     * `borderless`（否定式、默认 `false`），2026-10 按同名同义统一改成 `bordered` —— 默认行为不变
+     * （都是「缺省有框」），只是名字的极性换到与其余件一致，调用方不必再记「哪件用否定式」。
+     *
+     * 类名仍是 `.mh-table--borderless`：面层词根**统一为否定式**（输入族关框时也输出它），
+     * 与 prop 的极性相反 —— 两套各自内部一致，`Input` 的文档页记着同一处口径。
+     */
+    bordered: {
       type: Boolean,
-      default: false
+      default: true
     },
     /** 外框交给包裹层（满高表格用） */
     fill: {
@@ -178,6 +200,9 @@ const Table = /* @__PURE__ */ defineComponent({
     const columnCount = computed(() => leadColumns.value + props.columns.length);
     const isEmpty = computed(() => props.data.length === 0);
     const cellClass = (column) => [column.align === "center" ? "mh-table__cell-center" : "", column.align === "right" ? "mh-table__cell-amount" : "", column.wrap ? "mh-table__cell-wrap" : ""].filter(Boolean);
+    const cellSetValue = (row, column, index) => (next) => {
+      props.onCellChange?.(row, column.key, next, index);
+    };
     const colStyles = computed(() => {
       const weightSum = props.columns.reduce((sum, item) => typeof item.width === "number" ? sum + item.width : sum, 0);
       return props.columns.map((column) => {
@@ -221,7 +246,7 @@ const Table = /* @__PURE__ */ defineComponent({
     };
     const sortGlyph = (key) => props.sortKey === key && props.sortOrder === "asc" ? "chevron-up" : "chevron-down";
     return () => {
-      const tableClass = ["mh-table", resolvedSize.value === "sm" ? "mh-table--xs" : "", resolvedSize.value === "lg" ? "mh-table--lg" : "", props.borderless ? "mh-table--borderless" : "", props.fill ? "mh-table--fill" : "", props.layout === "fixed" ? "mh-table--fixed" : "", props.stickyHead ? "mh-table--sticky-head" : "", props.stickyCol ? "mh-table--sticky-col" : "", attrs.class].filter(Boolean).join(" ");
+      const tableClass = ["mh-table", resolvedSize.value === "sm" ? "mh-table--xs" : "", resolvedSize.value === "lg" ? "mh-table--lg" : "", props.bordered ? "" : "mh-table--borderless", props.fill ? "mh-table--fill" : "", props.layout === "fixed" ? "mh-table--fixed" : "", props.stickyHead ? "mh-table--sticky-head" : "", props.stickyCol ? "mh-table--sticky-col" : "", attrs.class].filter(Boolean).join(" ");
       const pager = typeof props.pagination === "object" ? props.pagination : null;
       return createVNode("div", {
         "class": "mh-table-wrapper",
@@ -303,12 +328,16 @@ const Table = /* @__PURE__ */ defineComponent({
         ) : null, props.columns.map((column) => createVNode("td", {
           "key": column.key,
           "class": cellClass(column).join(" ")
-        }, [slots.cell ? slots.cell({
-          row,
-          column,
-          value: row[column.key],
-          index
-        }) : slots.actions && column.align === "right" ? slots.actions({
+        }, [slots.cell ? (
+          /* 编辑格与展示格都走这条：值、位置、回写口一并交给调用方 */
+          slots.cell({
+            row,
+            column,
+            value: row[column.key],
+            index,
+            setValue: cellSetValue(row, column, index)
+          })
+        ) : slots.actions && column.align === "right" ? slots.actions({
           row,
           index
         }) : String(row[column.key] ?? "")]))]), isExpanded ? createVNode("tr", {

package/dist/index.d.ts

@@ -32,7 +32,7 @@ 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';
 export { Button, type ButtonVariant, type ButtonCompound, type ButtonCompoundType, } from './components/button';
-export { Input, Textarea, type TextareaProps, type InputCompound, type InputCompoundType, } from './components/input';
+export { Input, Textarea, NumberInput, type TextareaProps, type NumberInputProps, type InputCompound, type InputCompoundType, } from './components/input';
 export { Search, type SearchProps } from './components/search';
 export { Select, SelectTree, type SelectOption, type SelectValue } from './components/select';
 export { Switch } from './components/switch';
@@ -45,7 +45,7 @@ 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 TableRowSelectable, type TableSortOrder, } from './components/table';
+export { Table, type TableColumn, type TableCellSlotScope, type TableRow, type TableRowSelectable, type TableSortOrder, } from './components/table';
 export { Pagination, type PaginationPageItem } from './components/pagination';
 export { TabBar, type TabBarOption, type TabBarValue } from './components/tabbar';
 export { Steps, type CanJump, type StepsItem, type StepsVariant, type StepsCompound, type StepsCompoundType, } from './components/steps';

package/dist/index.js

@@ -38,6 +38,7 @@ import { Upload, formatFileSize } from "./components/upload/index.js";
 import { QueryState } from "./components/query-state/index.js";
 import { Loading } from "./components/loading/index.js";
 import { mergePartStyle, partPaddingStyle } from "./components/part-padding.js";
+import { NumberInput } from "./components/input/number-input.js";
 import { SelectTree } from "./components/select/select-tree.js";
 import { alert, closeAllDialogs, confirm } from "./services/dialog.js";
 import { clearToasts, toast } from "./services/toast.js";
@@ -66,6 +67,7 @@ export {
   Nav,
   Notice,
   Notification,
+  NumberInput,
   Page,
   Pagination,
   Panel,

package/dist/styles/components/avatar.css

@@ -1,131 +1,131 @@
-/**
- * Avatar —— 头像（四档尺寸 / 文字 / 图标 / 占位 / 方角 / 带框 / 计数 / 头像组 / 角标）。
- *
- * 出处：`@aihub/theme` 的 `playground/components/avatar.css` 与 `src/components/avatar.css`
- * （实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
- *
- * 两条来自规范的硬结论，改前先读：
- * 1. **圆形裁切归图片自身，容器不裁**：角上的角标（`__badge`）与徽章（`__chip`）是绝对定位件，
- *    容器若带 `overflow: hidden`，会沿圆弧把它们各切掉一半（实测反馈）。故容器 `overflow: visible`，
- *    图片用 `border-radius: inherit` 跟着形态自裁。
- * 2. **头像组靠负边距堆叠**（`.mh-avatar-group`），每个头像带 2px 的底描边把相邻项隔开。
- */
-.mh-avatar {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  position: relative;
-  flex-shrink: 0;
-  overflow: visible; /* 见文件头第 1 条：裁切归图片 */
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-base-400); /* Ne04 占位底 */
-  color: var(--ui-base-100); /* 占位前景 */
-}
-
-/* 图片：撑满 + 跟随形态自裁（否则去掉容器 overflow 后长宽不符的图会外溢）。
-   `display: block` 必须自己写：元素级基线不再把 `img` 转块级（那条会压消费方的 `h-*` / `hidden`），
-   否则行内基线间隙会把圆形头像顶偏。 */
-.mh-avatar > img {
-  display: block;
-  width: 100%;
-  height: 100%;
-  border-radius: inherit;
-  object-fit: cover;
-}
-
-/* ===== 尺寸四档 ===== */
-.mh-avatar--sm {
-  width: var(--ui-avatar-size-sm);
-  height: var(--ui-avatar-size-sm);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar--md {
-  width: var(--ui-avatar-size-md);
-  height: var(--ui-avatar-size-md);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar--lg {
-  width: var(--ui-avatar-size-lg);
-  height: var(--ui-avatar-size-lg);
-  font-size: var(--ui-font-title);
-}
-.mh-avatar--xl {
-  width: var(--ui-avatar-size-xl);
-  height: var(--ui-avatar-size-xl);
-  font-size: var(--ui-font-display);
-}
-
-/* ===== 内容形态 ===== */
-/* 文字头像：底取主色（业务要按人名哈希换色时给 `.mh-avatar--letter` 覆盖 background 即可） */
-.mh-avatar--letter {
-  background: var(--ui-primary);
-}
-/* 图标头像：图标由 @manohub/icon 渲染，这里只给尺寸档 */
-.mh-avatar--icon {
-  color: var(--ui-base-100);
-}
-/* 占位：虚线框 + 说明字（虚线线色取线型档，口径「实线 base-300 / 虚线 base-400」） */
-.mh-avatar--placeholder {
-  border: 1px dashed var(--ui-line-dashed);
-  background: var(--ui-base-100);
-  color: var(--ui-base-content-subtle);
-  font-size: var(--ui-font-caption);
-}
-/* 方角（商业图像）：圆角矩形 */
-.mh-avatar--square {
-  border-radius: var(--ui-radius-control);
-}
-/* 带框：靠阴影画出 2px 底环（不占布局，避免与角标抢位） */
-.mh-avatar--framed {
-  box-shadow: 0 0 0 2px var(--ui-base-100), var(--ui-shadow-card);
-}
-/* 计数档（头像组末位的「+N」） */
-.mh-avatar--count {
-  background: var(--ui-base-200);
-  color: var(--ui-base-content-muted);
-  font-size: var(--ui-font-caption);
-}
-
-/* ===== 角上外挂件（见文件头第 1 条：容器不裁，故它们不会被切）===== */
-.mh-avatar__badge {
-  position: absolute;
-  top: 0;
-  right: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-width: var(--ui-avatar-badge-size);
-  height: var(--ui-avatar-badge-size);
-  padding: 0 var(--ui-space-1);
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-error); /* 红底（规范 Badge 专页实测） */
-  border: 2px solid var(--ui-base-100); /* 白描边 */
-  color: var(--ui-error-content);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar__chip {
-  position: absolute;
-  right: -2px;
-  bottom: -2px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-primary);
-  border: 2px solid var(--ui-base-100);
-  cursor: pointer;
-}
-
-/* ===== 头像组：负边距堆叠，靠 2px 底描边分隔 ===== */
-.mh-avatar-group {
-  display: inline-flex;
-  align-items: center;
-}
-.mh-avatar-group .mh-avatar {
-  border: 2px solid var(--ui-base-100);
-}
-.mh-avatar-group .mh-avatar + .mh-avatar {
-  margin-left: calc(-1 * var(--ui-avatar-gap));
-}
+/**
+ * Avatar —— 头像（四档尺寸 / 文字 / 图标 / 占位 / 方角 / 带框 / 计数 / 头像组 / 角标）。
+ *
+ * 出处：`@aihub/theme` 的 `playground/components/avatar.css` 与 `src/components/avatar.css`
+ * （实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
+ *
+ * 两条来自规范的硬结论，改前先读：
+ * 1. **圆形裁切归图片自身，容器不裁**：角上的角标（`__badge`）与徽章（`__chip`）是绝对定位件，
+ *    容器若带 `overflow: hidden`，会沿圆弧把它们各切掉一半（实测反馈）。故容器 `overflow: visible`，
+ *    图片用 `border-radius: inherit` 跟着形态自裁。
+ * 2. **头像组靠负边距堆叠**（`.mh-avatar-group`），每个头像带 2px 的底描边把相邻项隔开。
+ */
+.mh-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  flex-shrink: 0;
+  overflow: visible; /* 见文件头第 1 条：裁切归图片 */
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-base-400); /* Ne04 占位底 */
+  color: var(--ui-base-100); /* 占位前景 */
+}
+
+/* 图片：撑满 + 跟随形态自裁（否则去掉容器 overflow 后长宽不符的图会外溢）。
+   `display: block` 必须自己写：元素级基线不再把 `img` 转块级（那条会压消费方的 `h-*` / `hidden`），
+   否则行内基线间隙会把圆形头像顶偏。 */
+.mh-avatar > img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  object-fit: cover;
+}
+
+/* ===== 尺寸四档 ===== */
+.mh-avatar--sm {
+  width: var(--ui-avatar-size-sm);
+  height: var(--ui-avatar-size-sm);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar--md {
+  width: var(--ui-avatar-size-md);
+  height: var(--ui-avatar-size-md);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar--lg {
+  width: var(--ui-avatar-size-lg);
+  height: var(--ui-avatar-size-lg);
+  font-size: var(--ui-font-title);
+}
+.mh-avatar--xl {
+  width: var(--ui-avatar-size-xl);
+  height: var(--ui-avatar-size-xl);
+  font-size: var(--ui-font-display);
+}
+
+/* ===== 内容形态 ===== */
+/* 文字头像：底取主色（业务要按人名哈希换色时给 `.mh-avatar--letter` 覆盖 background 即可） */
+.mh-avatar--letter {
+  background: var(--ui-primary);
+}
+/* 图标头像：图标由 @manohub/icon 渲染，这里只给尺寸档 */
+.mh-avatar--icon {
+  color: var(--ui-base-100);
+}
+/* 占位：虚线框 + 说明字（虚线线色取线型档，口径「实线 base-300 / 虚线 base-400」） */
+.mh-avatar--placeholder {
+  border: 1px dashed var(--ui-line-dashed);
+  background: var(--ui-base-100);
+  color: var(--ui-base-content-subtle);
+  font-size: var(--ui-font-caption);
+}
+/* 方角（商业图像）：圆角矩形 */
+.mh-avatar--square {
+  border-radius: var(--ui-radius-control);
+}
+/* 带框：靠阴影画出 2px 底环（不占布局，避免与角标抢位） */
+.mh-avatar--framed {
+  box-shadow: 0 0 0 2px var(--ui-base-100), var(--ui-shadow-card);
+}
+/* 计数档（头像组末位的「+N」） */
+.mh-avatar--count {
+  background: var(--ui-base-200);
+  color: var(--ui-base-content-muted);
+  font-size: var(--ui-font-caption);
+}
+
+/* ===== 角上外挂件（见文件头第 1 条：容器不裁，故它们不会被切）===== */
+.mh-avatar__badge {
+  position: absolute;
+  top: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--ui-avatar-badge-size);
+  height: var(--ui-avatar-badge-size);
+  padding: 0 var(--ui-space-1);
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-error); /* 红底（规范 Badge 专页实测） */
+  border: 2px solid var(--ui-base-100); /* 白描边 */
+  color: var(--ui-error-content);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar__chip {
+  position: absolute;
+  right: -2px;
+  bottom: -2px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-primary);
+  border: 2px solid var(--ui-base-100);
+  cursor: pointer;
+}
+
+/* ===== 头像组：负边距堆叠，靠 2px 底描边分隔 ===== */
+.mh-avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+.mh-avatar-group .mh-avatar {
+  border: 2px solid var(--ui-base-100);
+}
+.mh-avatar-group .mh-avatar + .mh-avatar {
+  margin-left: calc(-1 * var(--ui-avatar-gap));
+}

package/dist/styles/components/avatar.tokens.css

@@ -1,24 +1,24 @@
-/**
- * avatar —— 单件令牌（**基础值**）。
- *
- * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
- *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `avatar.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
- *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
- */
-[data-manohub-ui] {
-  /* 单件令牌（只服务本件；跨件令牌才进 theme/） */
-  --ui-avatar-size-sm: 24px;
-  --ui-avatar-size-md: 36px;
-  --ui-avatar-size-lg: 60px;
-  --ui-avatar-size-xl: 80px;
-  --ui-avatar-badge-size: 20px; /* 角标高 20，宽按位数撑开 */
-  --ui-avatar-gap: 10px; /* 堆叠重叠量（组件可用 gap 覆盖） */
-}
+/**
+ * avatar —— 单件令牌（**基础值**）。
+ *
+ * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
+ *
+ * ## 抽出说明
+ * 本文件从面文件里抽出（原先混写在 `avatar.css` 顶部）：这些是**基础值**，锚在
+ * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
+ * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
+ * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
+ *
+ * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
+ * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
+ * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+ */
+[data-manohub-ui] {
+  /* 单件令牌（只服务本件；跨件令牌才进 theme/） */
+  --ui-avatar-size-sm: 24px;
+  --ui-avatar-size-md: 36px;
+  --ui-avatar-size-lg: 60px;
+  --ui-avatar-size-xl: 80px;
+  --ui-avatar-badge-size: 20px; /* 角标高 20，宽按位数撑开 */
+  --ui-avatar-gap: 10px; /* 堆叠重叠量（组件可用 gap 覆盖） */
+}