@teamix-evo/ui 0.2.0 → 0.4.0

package/src/components/item/item.meta.md

@@ -2,7 +2,7 @@
 id: item
 name: Item
 type: component
-category: layout
+category: data-display
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 列表项
@@ -28,39 +28,22 @@ displayName: 列表项
 ## Props
 
 <!-- auto:props:begin -->
-
-#### Item
-
-| 名称          | 类型                                | 默认值      | 必填 | 说明                                                                                                |
-| ------------- | ----------------------------------- | ----------- | ---- | --------------------------------------------------------------------------------------------------- |
-| `variant`     | `'default' \| 'outline' \| 'muted'` | `"default"` | –    | 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。 |
-| `interactive` | `boolean`                           | `false`     | –    | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。                                                  |
-
-#### ItemMedia
-
-| 名称   | 类型                | 默认值      | 必填 | 说明                                        |
-| ------ | ------------------- | ----------- | ---- | ------------------------------------------- |
-| `size` | `'default' \| 'lg'` | `"default"` | –    | 媒体尺寸 — `lg` 适用于大封面 / 大头像场景。 |
-
-#### ItemGroup
-
-| 名称      | 类型      | 默认值 | 必填 | 说明                           |
-| --------- | --------- | ------ | ---- | ------------------------------ |
-| `divided` | `boolean` | `true` | –    | 是否在各 Item 之间显示分割线。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `"default"` | – | 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。 |
+| `interactive` | `boolean` | `false` | – | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add item` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -69,7 +52,6 @@ displayName: 列表项
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/item/item.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Item,
   ItemMedia,
@@ -13,7 +13,7 @@ import { Button } from '@/components/button/button';
 import { Switch } from '@/components/switch/switch';
 
 const meta: Meta<typeof Item> = {
-  title: '布局与容器 · Layout/Item',
+  title: '数据展示 · Data Display/Item',
   component: Item,
   tags: ['autodocs'],
   parameters: {
@@ -60,7 +60,7 @@ const users = [
 export const ContactList: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <ItemGroup className="w-96 rounded-md border">
+    <ItemGroup className="w-96 rounded-md border border-border">
       {users.map((u) => (
         <Item key={u.id} interactive className="px-3 py-2">
           <ItemMedia>

package/src/components/item/item.tsx

@@ -4,12 +4,13 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/utils/cn';
 
 const itemVariants = cva(
-  'flex w-full items-start gap-3 text-sm transition-colors',
+  'flex w-full items-start gap-3 text-xs transition-colors',
   {
     variants: {
       variant: {
         default: '',
-        outline: 'rounded-md border bg-card p-3 text-card-foreground shadow-sm',
+        outline:
+          'rounded-md border border-border bg-card p-3 text-card-foreground shadow-sm',
         muted: 'rounded-md bg-muted p-3',
       },
       interactive: {
@@ -61,11 +62,11 @@ export interface ItemMediaProps extends React.HTMLAttributes<HTMLDivElement> {
    * 媒体尺寸 — `default` 用于头像 / 图标;`lg` 用于缩略图。
    * @default "default"
    */
-  size?: 'default' | 'lg';
+  size?: 'md' | 'default' | 'lg';
 }
 
 const ItemMedia = React.forwardRef<HTMLDivElement, ItemMediaProps>(
-  ({ size = 'default', className, ...props }, ref) => (
+  ({ size = 'md', className, ...props }, ref) => (
     <div
       ref={ref}
       className={cn(
@@ -101,7 +102,7 @@ const ItemTitle = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('truncate text-sm font-semibold leading-none', className)}
+    className={cn('truncate text-xs font-semibold leading-none', className)}
     {...props}
   />
 ));
@@ -113,7 +114,7 @@ const ItemDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
-    className={cn('truncate text-sm text-muted-foreground', className)}
+    className={cn('truncate text-xs text-muted-foreground', className)}
     {...props}
   />
 ));

package/src/components/kbd/kbd.meta.md

@@ -3,7 +3,7 @@ id: kbd
 name: Kbd
 displayName: 键位展示
 type: component
-category: foundation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -28,19 +28,9 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-#### Kbd
-
-| 名称   | 类型                        | 默认值      | 必填 | 说明                                                          |
-| ------ | --------------------------- | ----------- | ---- | ------------------------------------------------------------- |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | –    | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
-
-#### KbdGroup
-
-| 名称        | 类型     | 默认值 | 必填 | 说明                                                  |
-| ----------- | -------- | ------ | ---- | ----------------------------------------------------- |
-| `separator` | `string` | `""`   | –    | 组合键之间的分隔符(如 `"+"` / `"→"`),留空时仅用 gap。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -48,14 +38,13 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add kbd` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -64,7 +53,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/kbd/kbd.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Kbd, KbdGroup } from './kbd';
 
 const meta: Meta<typeof Kbd> = {
-  title: '基础原语 · Foundation/Kbd',
+  title: '废弃 · Deprecated/Kbd',
   component: Kbd,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '键位展示 — 语义化 `<kbd>` 元素，标注快捷键（⌘K / Ctrl + Enter）。单键 + KbdGroup 组合容器，常用于 Command Palette、Tooltip、文档帮助。antd 体系无对应原子。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n键位展示 — 语义化 `<kbd>` 元素，标注快捷键（⌘K / Ctrl + Enter）。单键 + KbdGroup 组合容器，常用于 Command Palette、Tooltip、文档帮助。antd 体系无对应原子。',
       },
     },
   },
@@ -59,7 +59,7 @@ export const WinCombo: Story = {
 export const InContext: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex items-center justify-between rounded-md border bg-card p-3 text-sm">
+    <div className="flex items-center justify-between rounded-md border border-border bg-card p-3 text-sm">
       <span>打开命令面板</span>
       <KbdGroup>
         <Kbd>⌘</Kbd>

package/src/components/kbd/kbd.tsx

@@ -5,16 +5,17 @@ import { cn } from '@/utils/cn';
 
 const kbdVariants = cva(
   // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- physical-key inset shadow; one-off effect not used elsewhere.
-  'pointer-events-none inline-flex select-none items-center gap-1 rounded border bg-muted font-mono tabular-nums text-muted-foreground shadow-[0_1px_0_0_rgba(0,0,0,0.08)]',
+  'pointer-events-none inline-flex select-none items-center gap-1 rounded border border-border bg-muted font-mono tabular-nums text-muted-foreground shadow-[0_1px_0_0_rgba(0,0,0,0.08)]',
   {
     variants: {
       size: {
         sm: 'h-4 px-1 text-xxs',
+        md: 'h-5 px-1.5 text-xs',
         default: 'h-5 px-1.5 text-xs',
         lg: 'h-6 px-2 text-sm',
       },
     },
-    defaultVariants: { size: 'default' },
+    defaultVariants: { size: 'md' },
   },
 );
 
@@ -25,7 +26,7 @@ export interface KbdProps
    * 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 
 /**
@@ -66,7 +67,10 @@ const KbdGroup = React.forwardRef<HTMLSpanElement, KbdGroupProps>(
         {items.map((child, i) => (
           <React.Fragment key={i}>
             {i > 0 && separator ? (
-              <span aria-hidden="true" className="text-xs text-muted-foreground">
+              <span
+                aria-hidden="true"
+                className="text-xs text-muted-foreground"
+              >
                 {separator}
               </span>
             ) : null}

package/src/components/label/label.meta.md

@@ -3,7 +3,7 @@ id: label
 name: Label
 displayName: 标签
 type: component
-category: foundation
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -11,7 +11,7 @@ package: '@teamix-evo/ui'
 # Label 标签
 
 表单字段标签 — 基于 [`@radix-ui/react-label`](https://www.radix-ui.com/primitives/docs/components/label) 包装。
-shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd Form.Item 风格的 `required`(红色 `*` 标记)+ 显式 `disabled` prop,适合 label 与目标控件**不直接相邻**的场景。
+shadcn 原版只继承 Radix 的 `peer-disabled:` 联动；本版本补一条 antd Form.Item 风格的 `required`（红色 `*` 标记，**后置**在文字和 tooltip icon 右侧）+ 显式 `disabled` prop，适合 label 与目标控件**不直接相邻**的场景。
 
 ## When to use
 
@@ -28,12 +28,14 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`label.tsx`](./label.tsx) 的 `LabelProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:props:begin -->
-
-| 名称       | 类型      | 默认值  | 必填 | 说明                                                                                                                                       |
-| ---------- | --------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `disabled` | `boolean` | `false` | –    | 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式; 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。     |
-| `required` | `boolean` | `false` | –    | 必填标记。`true` 时在 children 后追加红色 `*`(语义来自 design destructive token), 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | – | 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式; 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。 |
+| `required` | `boolean` | `false` | – | 必填标记。`true` 时在 children 与 info icon **后**追加红色 `*` (语义来自 design destructive token);顺序为 `文字 ⓘ *`,三者间距 4px。 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
+| `tooltip` | `string` | – | – | 辅助说明文本 — 有值时在 label 文字后渲染 info icon + hover tooltip (对齐 antd `Form.Item.tooltip` 习惯)。 |
+| `tooltipSide` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | – | Tooltip 弹出方向。 |
+| `maxWidth` | `number \| string` | `undefined` | – | 最大宽度 — 超出时截断省略号。数字单位为 px,字符串直接用作 CSS 值。 适合长字段名在固定宽度表单中防止换行影响布局。 |
+| `minWidth` | `number` | `undefined` | – | 最小宽度(px) — 防止过度压缩,在响应式布局中保留可读宽度下限。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -41,14 +43,13 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add label` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -57,18 +58,20 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 ```bash
 pnpm add @radix-ui/react-label@^2.1.0 class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 > 除上述 props 外,Label 透传所有 `<label>` 原生属性(`htmlFor` / `id` / `aria-*` / `onClick` / ...)。
 
 ## AI 生成纪律
 
-- **`htmlFor` 必填**:Label 必须通过 `htmlFor` 关联到目标控件的 `id`,或把控件包裹在 Label 内。**不要**只渲染孤立 Label。
-- **`required` 配 `aria-required`**:仅视觉的 `*` 不够,目标 input 也要 `aria-required="true"`。
-- **`disabled` 不替代 input 的 disabled**:Label 的 `disabled` 仅控制视觉,目标控件的 `disabled` 必须独立设置。
-- **不内嵌交互元素**:Label 内不要放 button / link / 复杂控件 — Radix Label 的事件冒泡可能误触发关联控件。
-- **文案克制**:Label 文字 ≤ 8 个汉字 / 16 字符,过长用 Tooltip 补充。
+- **`htmlFor` 必填**：Label 必须通过 `htmlFor` 关联到目标控件的 `id`，或把控件包裹在 Label 内。**不要**只渲染孤立 Label。
+- **`required` 配 `aria-required`**：仅视觉的 `*` 不够，目标 input 也要 `aria-required="true"`。
+- **`*` 后置不可额外加空格**：请使用 `required` prop，不要手写 `<span>邮箱 *</span>`，走组件才能保证间距一致 + double-click 文字可快捷选中标题。
+- **`disabled` 不替代 input 的 disabled**：Label 的 `disabled` 仅控制视觉，目标控件的 `disabled` 必须独立设置。
+- **不内嵌交互元素**：Label 内不要放 button / link / 复杂控件 — Radix Label 的事件冒泡可能误触发关联控件。
+- **文案克制**：Label 文字 ≤ 8 个汉字 / 16 字符，过长用 `tooltip` prop 补充说明（不要手写 `<Tooltip>` 包裹）。
+- **截断走 `maxWidth`**：长 label 用 `maxWidth` 自动截断 + ellipsis，不要手写 `truncate` className。
+- **horizontal 对齐走 `minWidth`**：表单 label 列宽对齐用 `minWidth={120}` 等档位，不要手写 `min-w-32` 等 utility。
 
 ## Examples
 

package/src/components/label/label.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Label } from './label';
 
 const meta: Meta<typeof Label> = {
-  title: '基础原语 · Foundation/Label',
+  title: '数据录入 · Data Entry/Label',
   component: Label,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '表单字段标签 — Radix Label 包装,shadcn 工程基线 + antd `required` 红 `*` 与显式 `disabled` 视觉。',
+          '表单字段标签 —— 标记并描述表单控件的文本入口。Radix Label 实现 + 工程化扩展并集：`disabled` 显式禁用态(脱离 peer 也工作)、`required` 后置红色 `*`(顺序为 `文字 ⓘ *`,对齐设计规范)、`tooltip` 文字后 info icon hover 提示(对齐 antd `Form.Item.tooltip`)、`maxWidth` / `minWidth` 宽度约束 + `truncate` 省略号(应对长字段名固定栅格表单场景)。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
       },
     },
   },
@@ -19,13 +19,31 @@ const meta: Meta<typeof Label> = {
       control: 'boolean',
     },
     required: {
-      description: '必填标记,在文本后追加红色 `*`',
+      description:
+        '必填标记，在文字和 tooltip icon **后**追加红色 `*`（顺序为 `文字 ⓘ *`）',
       control: 'boolean',
     },
     children: {
       description: '标签文本',
       control: 'text',
     },
+    tooltip: {
+      description: '辅助说明文本，有值时在文字后渲染 info icon + hover tooltip',
+      control: 'text',
+    },
+    tooltipSide: {
+      description: 'tooltip 弹出方向',
+      control: 'inline-radio',
+      options: ['top', 'right', 'bottom', 'left'],
+    },
+    maxWidth: {
+      description: '最大宽度，超出截断省略号',
+      control: 'number',
+    },
+    minWidth: {
+      description: '最小宽度(px)',
+      control: 'number',
+    },
   },
   args: {
     children: '邮箱',
@@ -38,14 +56,27 @@ const meta: Meta<typeof Label> = {
 export default meta;
 type Story = StoryObj<typeof Label>;
 
-/** 默认 Label,可在 Controls 调 `required` / `disabled` 等 props。 */
+/** 默认 Label，可在 Controls 调 `required` / `disabled` 等 props。 */
 export const Playground: Story = {};
 
-/** 必填态:文本后追加红色 `*`(语义来自 design destructive token,不要手写颜色)。 */
+/** 必填态：文字和 tooltip icon **后**追加红色 `*`（顺序为 `文字 ⓘ *`，语义来自 design destructive token，对齐设计规范，不要手写颜色）。 */
 export const Required: Story = {
   args: { children: '用户名', required: true },
 };
 
+/** 对比：仅视觉示范必填 vs 非必填。 */
+export const RequiredComparison: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Label htmlFor="req-1" required>
+        必填字段
+      </Label>
+      <Label htmlFor="req-2">可选字段</Label>
+    </div>
+  ),
+};
+
 /** 禁用态:文字 70% 透明 + cursor-not-allowed。 */
 export const Disabled: Story = {
   args: { children: '只读字段', disabled: true },
@@ -85,3 +116,30 @@ export const PeerDisabled: Story = {
     </div>
   ),
 };
+
+/** 带 tooltip：文字后跟随 info icon，hover 触发气泡说明，对齐 antd `Form.Item.tooltip`。 */
+export const WithTooltip: Story = {
+  args: {
+    children: '客户编号',
+    tooltip: '由系统自动生成的全局唯一编号，提交后不可修改',
+  },
+};
+
+/** 截断：当字段名过长且布局栅格固定时，使用 `maxWidth` 触发 truncate 省略号。 */
+export const Truncated: Story = {
+  args: {
+    children: '这是一段非常非常非常长的字段标签文本',
+    maxWidth: 160,
+  },
+};
+
+/** 全特性组合：required 红 `*` + tooltip info icon + maxWidth 截断（典型业务表单形态）。 */
+export const WithAllFeatures: Story = {
+  args: {
+    children: '这是一段需要被截断的必填字段标签',
+    required: true,
+    tooltip: '该字段必填，长度限制 32 字符；超出栅格宽度自动省略，hover label 看完整文案。',
+    tooltipSide: 'right',
+    maxWidth: 200,
+  },
+};

package/src/components/label/label.tsx

@@ -1,11 +1,18 @@
 import * as React from 'react';
 import * as LabelPrimitive from '@radix-ui/react-label';
 import { cva, type VariantProps } from 'class-variance-authority';
+import { Info } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
+import {
+  TooltipContent,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+} from '@/components/tooltip/tooltip';
 
 const labelVariants = cva(
-  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70',
+  'text-xs font-medium leading-8 peer-disabled:cursor-not-allowed peer-disabled:opacity-70',
   {
     variants: {
       disabled: {
@@ -29,11 +36,33 @@ export interface LabelProps
    */
   disabled?: boolean;
   /**
-   * 必填标记。`true` 时在 children 后追加红色 `*`(语义来自 design destructive token),
+   * 必填标记。`true` 时在 children 与 info icon **后**追加红色 `*`
+   * (语义来自 design destructive token);顺序为 `文字 ⓘ *`,三者间距 4px。
    * 配合 `aria-required` 在 input 上一起使用以保证可访问性。
    * @default false
    */
   required?: boolean;
+  /**
+   * 辅助说明文本 — 有值时在 label 文字后渲染 info icon + hover tooltip
+   * (对齐 antd `Form.Item.tooltip` 习惯)。
+   */
+  tooltip?: string;
+  /**
+   * Tooltip 弹出方向。
+   * @default 'top'
+   */
+  tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+  /**
+   * 最大宽度 — 超出时截断省略号。数字单位为 px,字符串直接用作 CSS 值。
+   * 适合长字段名在固定宽度表单中防止换行影响布局。
+   * @default undefined
+   */
+  maxWidth?: number | string;
+  /**
+   * 最小宽度(px) — 防止过度压缩,在响应式布局中保留可读宽度下限。
+   * @default undefined
+   */
+  minWidth?: number;
 }
 
 const Label = React.forwardRef<
@@ -41,25 +70,68 @@ const Label = React.forwardRef<
   LabelProps
 >(
   (
-    { className, disabled = false, required = false, children, ...props },
+    {
+      className,
+      style,
+      disabled = false,
+      required = false,
+      tooltip,
+      tooltipSide = 'top',
+      maxWidth,
+      minWidth,
+      children,
+      ...props
+    },
     ref,
-  ) => (
-    <LabelPrimitive.Root
-      ref={ref}
-      className={cn(labelVariants({ disabled }), className)}
-      {...props}
-    >
-      {children}
-      {required ? (
-        <span
-          className="ml-0.5 text-destructive"
-          aria-hidden="true"
-        >
-          *
+  ) => {
+    const mergedStyle: React.CSSProperties = {
+      ...style,
+      ...(maxWidth !== undefined && {
+        maxWidth: typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+      }),
+      ...(minWidth !== undefined && { minWidth: `${minWidth}px` }),
+    };
+
+    return (
+      <LabelPrimitive.Root
+        ref={ref}
+        data-required={required ? '' : undefined}
+        style={mergedStyle}
+        className={cn(
+          labelVariants({ disabled }),
+          maxWidth !== undefined && 'truncate',
+          className,
+        )}
+        {...props}
+      >
+        <span className="inline-flex items-center gap-1 align-middle">
+          <span className={cn(maxWidth !== undefined && 'truncate')}>
+            {children}
+          </span>
+          {tooltip ? (
+            <TooltipProvider delayDuration={200}>
+              <TooltipRoot>
+                <TooltipTrigger asChild>
+                  <Info
+                    className="size-3.5 shrink-0 cursor-help text-muted-foreground transition-colors hover:text-foreground"
+                    aria-hidden="true"
+                  />
+                </TooltipTrigger>
+                <TooltipContent side={tooltipSide}>
+                  <p className="max-w-xs text-xs">{tooltip}</p>
+                </TooltipContent>
+              </TooltipRoot>
+            </TooltipProvider>
+          ) : null}
+          {required ? (
+            <span className="shrink-0 text-destructive" aria-hidden="true">
+              *
+            </span>
+          ) : null}
         </span>
-      ) : null}
-    </LabelPrimitive.Root>
-  ),
+      </LabelPrimitive.Root>
+    );
+  },
 );
 Label.displayName = 'Label';
 

package/src/components/masonry/masonry.meta.md

@@ -3,7 +3,7 @@ id: masonry
 name: Masonry
 displayName: 瀑布流
 type: component
-category: layout
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -27,30 +27,26 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称      | 类型     | 默认值 | 必填 | 说明                                                                                                                                                                                                                                                                           |
-| --------- | -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `columns` | `number` | `3`    | –    | 列数(antd `columns` 并集) — 固定值或响应式断点配置 `{ default, sm, md, lg, xl }`。 **响应式注意**:本组件用 CSS `column-count`,断点匹配靠 Tailwind `@container` 不便, 简化为 fixed 列数。响应式建议直接在外层包 className(如 `md:columns-3 columns-2`)+ `columns={undefined}`。 |
-| `gap`     | `number` | `16`   | –    | 列间距(像素)。                                                                                                                                                                                                                                                                 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `columns` | `number` | `3` | – | 列数(antd `columns` 并集) — 固定值或响应式断点配置 `{ default, sm, md, lg, xl }`。 **响应式注意**:本组件用 CSS `column-count`,断点匹配靠 Tailwind `@container` 不便, 简化为 fixed 列数。响应式建议直接在外层包 className(如 `md:columns-3 columns-2`)+ `columns={undefined}`。 |
+| `gap` | `number` | `16` | – | 列间距(像素)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add masonry` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律