@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,91 @@
+---
+id: label
+name: Label
+type: component
+category: foundation
+since: 0.1.0
+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 与目标控件**不直接相邻**的场景。
+
+## When to use
+
+- 表单字段标题(配合 `htmlFor` 或 Radix Label 默认的 click-to-focus 关联)
+- 任何需要"不可点击的强标题"的位置(如设置面板的开关组),提供清晰的可读层级
+
+## When NOT to use
+
+- 整段说明文字 → 用普通 `<p>` 或 design `Typography`
+- 表单字段说明(辅助说明) → 用 `<p className="text-sm text-muted-foreground">` 而非 Label
+
+## Props
+
+> 以下表格由 `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 上一起使用以保证可访问性。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `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) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```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 补充。
+
+## Examples
+
+```tsx
+import { Label } from '@/components/ui/label';
+import { Input } from '@/components/ui/input';
+
+// 基本
+<Label htmlFor="email">邮箱</Label>
+<Input id="email" type="email" />
+
+// 必填(视觉 + 语义)
+<Label htmlFor="username" required>用户名</Label>
+<Input id="username" required aria-required="true" />
+
+// 禁用
+<Label htmlFor="readonly" disabled>只读字段</Label>
+<Input id="readonly" disabled />
+
+// 与控件相邻 — 用 peer 自动联动
+<div>
+  <Input id="auto" disabled className="peer" />
+  <Label htmlFor="auto">自动联动 disabled 视觉</Label>
+</div>
+```

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

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Label } from './label';
+
+const meta: Meta<typeof Label> = {
+  title: '基础原语 · Foundation/Label',
+  component: Label,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '表单字段标签 — Radix Label 包装,shadcn 工程基线 + antd `required` 红 `*` 与显式 `disabled` 视觉。',
+      },
+    },
+  },
+  argTypes: {
+    disabled: {
+      description: '视觉禁用态(脱离 peer 也工作)',
+      control: 'boolean',
+    },
+    required: {
+      description: '必填标记,在文本后追加红色 `*`',
+      control: 'boolean',
+    },
+    children: {
+      description: '标签文本',
+      control: 'text',
+    },
+  },
+  args: {
+    children: '邮箱',
+    htmlFor: 'demo-input',
+    disabled: false,
+    required: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+/** 默认 Label,可在 Controls 调 `required` / `disabled` 等 props。 */
+export const Playground: Story = {};
+
+/** 必填态:文本后追加红色 `*`(语义来自 design destructive token,不要手写颜色)。 */
+export const Required: Story = {
+  args: { children: '用户名', required: true },
+};
+
+/** 禁用态:文字 70% 透明 + cursor-not-allowed。 */
+export const Disabled: Story = {
+  args: { children: '只读字段', disabled: true },
+};
+
+/** 与 input 配合(实际项目中最常用形态)。 */
+export const WithInput: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Label htmlFor="email-with-input" required>
+        邮箱
+      </Label>
+      <input
+        id="email-with-input"
+        type="email"
+        aria-required="true"
+        placeholder="you@example.com"
+        className="rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+      />
+    </div>
+  ),
+};
+
+/** Peer 联动:input 禁用时 Label 自动响应(无需显式 `disabled` prop)。 */
+export const PeerDisabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <input
+        id="peer-input"
+        disabled
+        placeholder="disabled input"
+        className="peer rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm"
+      />
+      <Label htmlFor="peer-input">peer-disabled 自动响应</Label>
+    </div>
+  ),
+};

package/src/components/label/label.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const labelVariants = cva(
+  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70',
+  {
+    variants: {
+      disabled: {
+        true: 'cursor-not-allowed opacity-70',
+        false: '',
+      },
+    },
+    defaultVariants: {
+      disabled: false,
+    },
+  },
+);
+
+export interface LabelProps
+  extends React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>,
+    VariantProps<typeof labelVariants> {
+  /**
+   * 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式;
+   * 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * 必填标记。`true` 时在 children 后追加红色 `*`(语义来自 design destructive token),
+   * 配合 `aria-required` 在 input 上一起使用以保证可访问性。
+   * @default false
+   */
+  required?: boolean;
+}
+
+const Label = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  LabelProps
+>(
+  (
+    { className, disabled = false, required = false, 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"
+        >
+          *
+        </span>
+      ) : null}
+    </LabelPrimitive.Root>
+  ),
+);
+Label.displayName = 'Label';
+
+export { Label, labelVariants };

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

@@ -0,0 +1,85 @@
+---
+id: masonry
+name: Masonry
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Masonry
+
+瀑布流 — antd 独有补足。**等价 antd `Masonry`**(v6.0 新)。基于 CSS `column-count` + `break-inside: avoid` 的纯 CSS 实现 — **0 JS、SSR 友好、自动按 children 高度填充列**。
+
+## When to use
+
+- 图片墙 / Pinterest 风格的相册
+- 博客 / 资讯卡片流(每张卡高度不一)
+- Dashboard 卡片墙(不同卡片高度差异大)
+
+## When NOT to use
+
+- 严格等高网格 → `Grid (Row/Col)` / Tailwind `grid grid-cols-N`
+- 严格视觉对齐(按"哪列最矮就填哪列")→ 用 JS-driven masonry(react-masonry-css)
+- 等宽等高数据流 → `List grid={{column:N}}` / `Item` + Tailwind grid
+
+<!-- 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` | – | 列间距(像素)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add masonry` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **子项填充顺序**:CSS columns 是**自上而下、自左而右一列填完再到下一列**(不像 JS masonry 选最矮列)— 对内容流 OK,对严格视觉对齐不适用
+- **`columns` 是固定值**:响应式建议外层包 Tailwind `md:columns-3 columns-2` + 本组件传 `columns={undefined}` 让 CSS class 接管
+- **每个子项最好独立卡片化**(rounded-md / border / shadow),不要嵌套裸文本 — column-break 在裸文本上会断行不优雅
+- **不要给子项设 fixed height**:Masonry 的核心价值就是按自然高度填充;如需等高直接用 Grid
+- **图片项务必设 `width=100%`**:否则会按原图宽度撑破列宽
+
+## Examples
+
+```tsx
+import { Masonry } from '@/components/ui/masonry';
+
+// 基础
+<Masonry columns={3} gap={16}>
+  {photos.map((p) => (
+    <img key={p.id} src={p.url} alt={p.alt} className="w-full rounded-md" />
+  ))}
+</Masonry>
+
+// 卡片墙
+<Masonry columns={4} gap={12}>
+  {cards.map((c) => (
+    <Card key={c.id}>
+      <CardHeader><CardTitle>{c.title}</CardTitle></CardHeader>
+      <CardContent>{c.body}</CardContent>
+    </Card>
+  ))}
+</Masonry>
+
+// 响应式(外层 className 控制列数,组件不强加)
+<div className="columns-2 md:columns-3 lg:columns-4">
+  {items.map((it) => (
+    <div key={it.id} className="mb-4 break-inside-avoid">
+      <Card>{it.content}</Card>
+    </div>
+  ))}
+</div>
+```

package/src/components/masonry/masonry.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Masonry } from './masonry';
+
+const meta: Meta<typeof Masonry> = {
+  title: '布局与容器 · Layout/Masonry',
+  component: Masonry,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '瀑布流 — CSS column-count + break-inside: avoid 的 0 JS 实现(图片墙 / 资讯卡片流 / Dashboard 卡片墙)。等价 antd `Masonry`(v6.0 新)。响应式建议外层 className 控制(`md:columns-3`)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    columns: { control: { type: 'number', min: 1, max: 6 } },
+    gap: { control: { type: 'number', min: 0, max: 48 } },
+  },
+  args: { columns: 3, gap: 16 },
+};
+
+export default meta;
+type Story = StoryObj<typeof Masonry>;
+
+const cards = Array.from({ length: 12 }).map((_, i) => ({
+  id: i,
+  h: 80 + ((i * 37) % 180),
+  text: `卡片 ${i + 1}`,
+}));
+
+export const Playground: Story = {
+  render: (args) => (
+    <Masonry {...args} className="w-full">
+      {cards.map((c) => (
+        <div
+          key={c.id}
+          className="flex items-center justify-center rounded-md border bg-card text-sm"
+          style={{ height: c.h }}
+        >
+          {c.text}({c.h}px)
+        </div>
+      ))}
+    </Masonry>
+  ),
+};
+
+export const ColorfulPhotos: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Masonry columns={4} gap={12} className="w-full">
+      {cards.map((c) => (
+        <div
+          key={c.id}
+          className="rounded-md bg-muted text-center text-xs text-muted-foreground"
+          style={{
+            height: c.h,
+            background: `linear-gradient(135deg, hsl(${(c.id * 30) % 360}, 60%, 70%), hsl(${(c.id * 30 + 60) % 360}, 60%, 50%))`,
+          }}
+        >
+          <span className="block py-2 text-white/90">photo {c.id + 1}</span>
+        </div>
+      ))}
+    </Masonry>
+  ),
+};

package/src/components/masonry/masonry.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+
+export interface MasonryProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 列数(antd `columns` 并集) — 固定值或响应式断点配置 `{ default, sm, md, lg, xl }`。
+   *
+   * **响应式注意**:本组件用 CSS `column-count`,断点匹配靠 Tailwind `@container` 不便,
+   * 简化为 fixed 列数。响应式建议直接在外层包 className(如 `md:columns-3 columns-2`)+ `columns={undefined}`。
+   * @default 3
+   */
+  columns?: number;
+  /**
+   * 列间距(像素)。
+   * @default 16
+   */
+  gap?: number;
+}
+
+/**
+ * 瀑布流 — antd 独有补足。**等价 antd `Masonry`**(v6.0 新)。基于 CSS `column-count`
+ * + `break-inside: avoid` 的纯 CSS 实现 — 0 JS、SSR 友好、自动按 children 高度填充列。
+ *
+ * **局限**(对齐 CSS columns 的固有限制):
+ *   - 子项按 **DOM 顺序**填充列(自上而下、自左而右一列填完再到下一列)
+ *   - 不像 JS-driven masonry(react-masonry-css / Pinterest 风格)那样按"哪列最矮就填哪列"
+ *   - 适合内容流(博客、相册),不适合严格视觉对齐的场景
+ */
+const Masonry = React.forwardRef<HTMLDivElement, MasonryProps>(
+  ({ columns = 3, gap = 16, className, children, style, ...props }, ref) => {
+    const items = React.Children.toArray(children).filter(Boolean);
+    return (
+      <div
+        ref={ref}
+        className={cn('block', className)}
+        style={{
+          columnCount: columns,
+          columnGap: `${gap}px`,
+          ...style,
+        }}
+        {...props}
+      >
+        {items.map((child, i) => (
+          <div
+            key={i}
+            className="mb-[var(--masonry-gap)] break-inside-avoid"
+            style={{ ['--masonry-gap' as string]: `${gap}px` }}
+          >
+            {child}
+          </div>
+        ))}
+      </div>
+    );
+  },
+);
+Masonry.displayName = 'Masonry';
+
+export { Masonry };

package/src/components/mentions/mentions.meta.md

@@ -0,0 +1,89 @@
+---
+id: mentions
+name: Mentions
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Mentions
+
+@提及 — antd 独有补足。在 Textarea 中输入 `@`(或自定义 `prefix`)即弹出候选下拉,选中后插入 `@name `。键盘 ↑↓ 切换、Enter / Tab 选中、Esc 关闭。**异步候选**用 `onSearch(query)` 由消费方刷新 `options`。
+
+## When to use
+
+- 评论 / 工单输入框需要 @ 同事、# 话题
+- 任意需要"输入触发字符 → 弹出候选 → 选中插入"的场景
+
+## When NOT to use
+
+- 全字段候选(下拉选单)→ `Select` / `Combobox`
+- 仅是搜索输入 → `Input` + 业务侧自渲染建议列表
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `MentionsOption[]` | – | ✓ | 候选项(antd `options` 并集)。 |
+| `value` | `string` | – | – | 受控值。 |
+| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
+| `onChange` | `(value: string) => void` | – | – | 文本变化回调。 |
+| `prefix` | `string` | `"@"` | – | 触发符(antd `prefix` 并集) — 通常是 `@` 或 `#`。 |
+| `split` | `string` | `" "` | – | 选中候选项后插入文本的尾随分隔(对齐 antd `split` 默认空格)。 |
+| `onSearch` | `(query: string, prefix: string) => void` | – | – | 用户在 prefix 后输入时的搜索回调,用于业务侧异步刷新 `options`。 |
+| `onSelect` | `(option: MentionsOption, prefix: string) => void` | – | – | 选中候选项时回调。 |
+| `rows` | `number` | `3` | – | 文本框尺寸传透传 Textarea(行数)。 |
+| `disabled` | `boolean` | – | – | 禁用。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add mentions` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `textarea` | component | 多行文本输入 — shadcn 基底 + antd autoSize / showCount |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`onSearch` 是异步刷新点**:`options` 由消费方根据 `query` 拉接口刷新,组件本身不内置网络层
+- **`prefix` 必须是单字符**(`@` / `#` / `/` 等)— 多字符触发会与正文混淆
+- **不要在 `onSelect` 里改 `value`** — 组件已经替消费方插入并触发了 `onChange`
+- **email 不会误触**:`a@b` 中 `@` 前是字母,组件不会把它当作触发符;触发符前必须是空白或行首
+- **键盘冲突**:Enter 在候选打开时被消费(选中候选),关闭时回归原生换行 — 这是预期
+- **大候选列表**(> 100 项)请在 `onSearch` 中做服务端筛选,组件不内置虚拟化
+
+## Examples
+
+```tsx
+import { Mentions } from '@/components/ui/mentions';
+import * as React from 'react';
+
+const users = [
+  { value: 'alice', label: 'Alice (前端)' },
+  { value: 'bob', label: 'Bob (后端)' },
+  { value: 'carol', label: 'Carol (设计)' },
+];
+
+// 静态候选
+<Mentions options={users} placeholder="输入 @ 提及同事..." />
+
+// 异步候选
+const [opts, setOpts] = React.useState(users);
+<Mentions
+  options={opts}
+  onSearch={async (q) => {
+    const list = await fetchUsers(q);
+    setOpts(list);
+  }}
+/>
+
+// 双触发符:@ + # — 当前组件支持单 prefix,如需多触发请实例化两个 Mentions
+```

package/src/components/mentions/mentions.stories.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Mentions } from './mentions';
+
+const meta: Meta<typeof Mentions> = {
+  title: '表单与输入 · Form/Mentions',
+  component: Mentions,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '@提及输入 — Textarea + @ 触发候选下拉(评论 @ 同事、# 话题)。↑↓ 切换、Enter / Tab 选中、Esc 关闭。异步候选用 onSearch 由消费方刷新 options。视觉走 OpenTrek tokens,等价 antd `Mentions`,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    prefix: { control: 'text' },
+    placeholder: { control: 'text' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Mentions>;
+
+const users = [
+  { value: 'alice', label: 'Alice (前端)' },
+  { value: 'bob', label: 'Bob (后端)' },
+  { value: 'carol', label: 'Carol (设计)' },
+  { value: 'david', label: 'David (产品)' },
+];
+
+export const Playground: Story = {
+  args: { placeholder: '输入 @ 提及同事...', options: users },
+};
+
+export const HashtagPrefix: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Mentions
+      options={[
+        { value: 'frontend', label: '#frontend' },
+        { value: 'backend', label: '#backend' },
+        { value: 'design', label: '#design' },
+      ]}
+      prefix="#"
+      placeholder="输入 # 添加话题..."
+    />
+  ),
+};
+
+export const AsyncSearch: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [opts, setOpts] = React.useState(users);
+    return (
+      <div className="flex flex-col gap-2">
+        <Mentions
+          options={opts}
+          placeholder="输入 @ 触发模拟异步搜索..."
+          onSearch={(q) => {
+            const next = users.filter((u) =>
+              u.value.toLowerCase().includes(q.toLowerCase()),
+            );
+            // simulate latency
+            window.setTimeout(() => setOpts(next), 80);
+          }}
+        />
+        <div className="text-xs text-muted-foreground">
+          当前候选数: {opts.length}
+        </div>
+      </div>
+    );
+  },
+};