@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/input-otp/input-otp.meta.md

@@ -2,12 +2,13 @@
 id: input-otp
 name: InputOTP
 type: component
-category: form
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 验证码输入
 ---
 
-# InputOTP
+# InputOTP 验证码输入
 
 OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/input-otp)。**shadcn-only**(antd 无对标组件)。
 4~8 位短验证码常见场景:登录、二步验证、支付确认。

package/src/components/input-otp/input-otp.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { REGEXP_ONLY_DIGITS } from 'input-otp';
 import {
   InputOTP,
@@ -9,14 +9,14 @@ import {
 } from './input-otp';
 
 const meta: Meta<typeof InputOTP> = {
-  title: '表单与输入 · Form/InputOTP',
+  title: '废弃 · Deprecated/InputOTP',
   component: InputOTP,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。',
       },
     },
   },

package/src/components/input-otp/input-otp.tsx

@@ -67,7 +67,7 @@ const InputOTPSlot = React.forwardRef<
     <div
       ref={ref}
       className={cn(
-        'relative flex size-10 items-center justify-center border-y border-r border-input text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md',
+        'relative flex size-10 items-center justify-center border-y border-r border-input text-xs shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md',
         isActive && 'z-10 ring-1 ring-ring',
         className,
       )}

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

@@ -2,12 +2,13 @@
 id: item
 name: Item
 type: component
-category: layout
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 列表项
 ---
 
-# Item
+# Item 列表项
 
 通用列表项 / 卡片项容器 — shadcn 2025-10 新增。**取代我们之前自实现的 `List.Item` + `List.Item.Meta`**(antd 老 List 在 v6 已 deprecated)。用 5 个语义槽组合:`ItemMedia` 媒体 / `ItemContent` 主体 / `ItemTitle` 标题 / `ItemDescription` 描述 / `ItemActions` 操作。排列用 `ItemGroup`(纵向 + 分隔)或自行 div / ul 自由布局。
 
@@ -24,6 +25,8 @@ package: "@teamix-evo/ui"
 - 完整业务卡片(带 Header / Cover / Footer)→ `Card`
 - 树形嵌套 → `Tree`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -31,6 +34,8 @@ package: "@teamix-evo/ui"
 | `interactive` | `boolean` | `false` | – | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

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,19 +13,22 @@ 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: {
     docs: {
       description: {
         component:
-          '通用列表项 / 卡片项 — 5 个语义槽组合(ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions),配 ItemGroup 纵向排列。shadcn 2025-10 新增,取代之前自实现的 List.Item(antd 老 List 在 v6 已 deprecated)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '通用列表项 / 卡片项 — 5 个语义槽组合（ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions），配 ItemGroup 纵向排列。shadcn 2025-10 新增，取代之前自实现的 List.Item（antd 老 List 在 v6 已 deprecated）。',
       },
     },
   },
   argTypes: {
-    variant: { control: 'inline-radio', options: ['default', 'outline', 'muted'] },
+    variant: {
+      control: 'inline-radio',
+      options: ['default', 'outline', 'muted'],
+    },
     interactive: { control: 'boolean' },
   },
   args: { variant: 'default', interactive: false },
@@ -57,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

@@ -1,13 +1,14 @@
 ---
 id: kbd
 name: Kbd
+displayName: 键位展示
 type: component
-category: foundation
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Kbd
+# Kbd 键位展示
 
 键位展示 — shadcn 2025-10 新增。语义化的 `<kbd>` 元素 + `KbdGroup` 组合容器,用于在 UI 中标注**快捷键**(`⌘K` / `Ctrl + Enter` / `Esc`)。常见于 Command Palette、Tooltip、文档 / 帮助提示。
 
@@ -22,12 +23,20 @@ package: "@teamix-evo/ui"
 - 引用代码片段 → 用 `<code>` / Typography Code(`<Kbd>` 语义是物理键位)
 - 普通行内强调 → 用 `<strong>` / Typography Text strong
 
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
 <!-- auto:props:end -->
 
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

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、文档帮助。shadcn 2025-10 新增,antd 体系无对应原子。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '⚠️ **已废弃** — 仅 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

@@ -4,16 +4,18 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/utils/cn';
 
 const kbdVariants = cva(
-  '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)]',
+  // 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 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-[10px]',
+        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' },
   },
 );
 
@@ -24,7 +26,7 @@ export interface KbdProps
    * 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 
 /**
@@ -65,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

@@ -1,16 +1,17 @@
 ---
 id: label
 name: Label
+displayName: 标签
 type: component
-category: foundation
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Label
+# 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
 
@@ -30,7 +31,11 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
 | `disabled` | `boolean` | `false` | – | 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式; 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。 |
-| `required` | `boolean` | `false` | – | 必填标记。`true` 时在 children 后追加红色 `*`(语义来自 design destructive token), 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
+| `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 -->
 
 ## 依赖
@@ -59,11 +64,14 @@ pnpm add @radix-ui/react-label@^2.1.0 class-variance-authority@^0.7.0
 
 ## 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

@@ -1,13 +1,14 @@
 ---
 id: masonry
 name: Masonry
+displayName: 瀑布流
 type: component
-category: layout
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Masonry
+# Masonry 瀑布流
 
 瀑布流 — antd 独有补足。**等价 antd `Masonry`**(v6.0 新)。基于 CSS `column-count` + `break-inside: avoid` 的纯 CSS 实现 — **0 JS、SSR 友好、自动按 children 高度填充列**。
 
@@ -23,6 +24,8 @@ package: "@teamix-evo/ui"
 - 严格视觉对齐(按"哪列最矮就填哪列")→ 用 JS-driven masonry(react-masonry-css)
 - 等宽等高数据流 → `List grid={{column:N}}` / `Item` + Tailwind grid
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -30,6 +33,8 @@ package: "@teamix-evo/ui"
 | `gap` | `number` | `16` | – | 列间距(像素)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖