@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -1,145 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Label } from './label';
-
-const meta: Meta<typeof Label> = {
-  title: '数据录入 · Data Entry/Label',
-  component: Label,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '表单字段标签 —— 标记并描述表单控件的文本入口。Radix Label 实现 + 工程化扩展并集：`disabled` 显式禁用态(脱离 peer 也工作)、`required` 后置红色 `*`(顺序为 `文字 ⓘ *`,对齐设计规范)、`tooltip` 文字后 info icon hover 提示(对齐 antd `Form.Item.tooltip`)、`maxWidth` / `minWidth` 宽度约束 + `truncate` 省略号(应对长字段名固定栅格表单场景)。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
-      },
-    },
-  },
-  argTypes: {
-    disabled: {
-      description: '视觉禁用态(脱离 peer 也工作)',
-      control: 'boolean',
-    },
-    required: {
-      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: '邮箱',
-    htmlFor: 'demo-input',
-    disabled: false,
-    required: false,
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Label>;
-
-/** 默认 Label，可在 Controls 调 `required` / `disabled` 等 props。 */
-export const Playground: Story = {};
-
-/** 必填态：文字和 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 },
-};
-
-/** 与 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>
-  ),
-};
-
-/** 带 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,138 +0,0 @@
-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-xs font-medium leading-8 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 与 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<
-  React.ElementRef<typeof LabelPrimitive.Root>,
-  LabelProps
->(
-  (
-    {
-      className,
-      style,
-      disabled = false,
-      required = false,
-      tooltip,
-      tooltipSide = 'top',
-      maxWidth,
-      minWidth,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    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>
-      </LabelPrimitive.Root>
-    );
-  },
-);
-Label.displayName = 'Label';
-
-export { Label, labelVariants };

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

@@ -1,90 +0,0 @@
----
-id: masonry
-name: Masonry
-displayName: 瀑布流
-type: component
-category: deprecated
-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
-
-## 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` | – | 列间距(像素)。 |
-<!-- 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

@@ -1,68 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Masonry } from './masonry';
-
-const meta: Meta<typeof Masonry> = {
-  title: '废弃 · Deprecated/Masonry',
-  component: Masonry,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n瀑布流 — CSS column-count + break-inside: avoid 的 0 JS 实现(图片墙 / 资讯卡片流 / Dashboard 卡片墙)。等价 antd `Masonry`(v6.0 新)。响应式建议外层 className 控制。',
-      },
-    },
-  },
-  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 border-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

@@ -1,60 +0,0 @@
-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}
-            // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- runtime CSS var driven by `gap` prop; consumes per-instance var, not tokenizable.
-            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

@@ -1,119 +0,0 @@
----
-id: mentions
-name: Mentions
-displayName: 提及
-type: component
-category: deprecated
-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` + 业务侧自渲染建议列表
-
-## Props
-
-<!-- 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) |
-| `input` | component | 文本输入合集 — Input(单行 + prefix/suffix/clearable/showCount/addonBefore/addonAfter/size)+ Textarea(多行 + autoSize)+ InputGroup 系列(InputGroupAddon / InputGroupInput / InputGroupTextarea)三件合一,size 与 Button 同档(sm 24 / md 32 / lg 36) |
-
-### 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
-```
-
----
-
-## Mentions 形态 — 旧库无此组件
-
-> 旧库(hybridcloud)不含 Mentions;本组件为**新库独有**,对齐 antd `Mentions` API 形态。
-> 基于内置 Textarea + 自绘候选列表(无 portal);用 `prefix` 触发、`onSearch` 异步刷新、`onSelect` 埋点。
-
-### antd Mentions 对齐表
-
-| antd prop           | 新库 prop          | 备注                                    |
-| ------------------- | ------------------ | --------------------------------------- |
-| `options`           | `options`          | 结构一致 `{ value, label?, disabled? }` |
-| `prefix`            | `prefix`           | 触发符,单字符                           |
-| `split`             | `split`            | 选中后尾随分隔,默认空格                 |
-| `onSearch`          | `onSearch`         | 异步刷新回调                            |
-| `onSelect`          | `onSelect`         | 选中回调                                |
-| `value / onChange`  | `value / onChange` | 受控模式                                |
-| `defaultValue`      | `defaultValue`     | 非受控初值                              |
-| `disabled`          | `disabled`         | 整组禁用                                |
-| `rows`              | `rows`             | Textarea 行数(默认 3)                   |
-| `placement`         | 不支持             | 固定 bottom-left(级联层级场景不需调整)  |
-| `getPopupContainer` | 不支持             | 无 portal,列表就在组件内 relative 定位  |
-| `filterOption`      | 内置 includes      | 如需自定义过滤逻辑,请在 onSearch 中做   |
-| `validateSearch`    | 不支持             | 低频                                    |