@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/tag/meta.md

@@ -0,0 +1,256 @@
+# Tag
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+标签 Tag
+用于分类标识、状态标记或可选择的筛选项。支持 4 种形态:
+背景色块(`solid` / `outline` / `ghost`)与状态形态(`variant='status'`,
+圆点默认、`showIcon` 切换为图标)。
+关闭路径对齐 antd v6:`closable` 支持对象签名(自定义 closeIcon /
+closeArea / aria-label),`onClose(e)` 调用 `e.preventDefault()` 即可
+阻止默认关闭;并提供 `visible` / `defaultVisible` 双形态可见性与
+`afterClose` 隐藏后回调。
+组合结构:TagGroup > Tag * | CheckableTagGroup > CheckableTag *
+
+## 使用场景
+
+- 展示分类标签(项目类型、技术栈、博客标签)
+- 标记任务 / 资源状态(成功 / 运行中 / 失败 / 暂停 / 加载中 / 帮助 / 提示)
+- 可关闭的动态标签列表(支持外部受控可见性 / 阻止默认关闭)
+- 多选或单选筛选场景(CheckableTagGroup)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'solid' \| 'outline' \| 'ghost' \| 'status'` | – | – | 形态轴:`solid` 实色背景(默认) / `outline` 仅描边 / `ghost` 仅文字 / `status` 状态形态(颜色由 `status` 决定,`variant='status'` 时 color/palette/icon 失效)。 |
+| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'destructive'` | – | – | 语义色 — 5 档(ADR 0021)。仅在 `variant !== 'status'` 时生效。装饰类别区分用 `palette`。 |
+| `size` | `'sm' \| 'md' \| 'lg'` | – | – | 尺寸:`sm` 高 20px / `md` 高 24px(默认) / `lg` 高 28px。 |
+| `status` | `TagStatus` | – | – | 状态语义 9 档:`success` / `processing` / `error` / `warning` / `pause` / `loading` / `help` / `mention` / `default`。`variant='status'` 渲染圆点/图标;其他 variant 自动派生彩色。 |
+| `showIcon` | `boolean` | – | – | `variant='status'` 时是否渲染前缀图标(默认 `false`,渲染圆点)。 |
+| `palette` | `TagPalettePreset \| (string & {})` | – | – | 分类装饰色，与语义色正交。9 预设 + 任意 CSS 值。`variant='status'` 时失效。 |
+| `icon` | `React.ReactNode` | – | – | 标签文字左侧图标插槽。`variant='status'` 时失效(由内置图标接管)。 |
+| `closable` | `boolean \| TagClosableConfig` | – | – | 关闭按钮配置。`true` 启用默认关闭，对象签名可配 `closeIcon` / `closeArea` / `aria-label`。`onClose(e).preventDefault()` 可阻止。 |
+| `onClose` | `( e: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>, ) => void` | – | – | 关闭回调。可调用 `e.preventDefault()` 阻止默认关闭(对齐 antd v6)。 |
+| `afterClose` | `() => void` | – | – | 关闭隐藏后回调(对齐 cloud-design `afterClose`)。 |
+| `visible` | `boolean` | – | – | 受控可见性。 |
+| `defaultVisible` | `boolean` | – | – | 非受控初始可见性,默认 `true`。 |
+| `disabled` | `boolean` | – | – | 禁用态:灰显 + cursor-not-allowed,点击 / 关闭均无效。 |
+| `asChild` | `boolean` | – | – | Slot 模式渲染为子元素(如 `<a>`);此模式下不内置渲染 icon 与关闭按钮。 |
+| `gap` | `'sm' \| 'md' \| 'lg'` | – | – | 间距档位:`sm` 6px / `md` 8px(默认) / `lg` 12px。 |
+| `checked` | `boolean` | – | ✓ | 是否选中(受控)。 |
+| `onChange` | `(next: boolean) => void` | – | – | 选中态变化回调。 |
+| `variant` | `'solid' \| 'outline'` | – | – | 形态:`solid`(默认) 选中填充 / `outline` 选中描边。 |
+| `disabled` | `boolean` | – | – | 禁用。 |
+| `multiple` | `true` | – | – | 多选模式(默认)。 |
+| `value` | `string[]` | – | – | 受控选中 value 集合。 |
+| `defaultValue` | `string[]` | – | – | 非受控初值。 |
+| `onChange` | `(next: string[]) => void` | – | – | 选中变化回调(多选)。 |
+| `multiple` | `false` | – | ✓ | 单选模式。 |
+| `value` | `string \| null` | – | – | 受控选中 value(单选)。 |
+| `defaultValue` | `string \| null` | – | – | 非受控初值(单选)。 |
+| `onChange` | `(next: string \| null) => void` | – | – | 选中变化回调(单选,取消时回传 `null`)。 |
+
+## 示例
+
+### Variants
+
+形态轴 × 语义色矩阵(ADR 0021)。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <TagGroup>
+    <Tag variant="solid" color="default">
+      Default
+    </Tag>
+    <Tag variant="solid" color="primary">
+      Primary
+    </Tag>
+    <Tag variant="solid" color="success">
+      Success
+    </Tag>
+    <Tag variant="solid" color="warning">
+      Warning
+    </Tag>
+    <Tag variant="solid" color="destructive">
+      Destructive
+    </Tag>
+  </TagGroup>
+  <TagGroup>
+    <Tag variant="outline" color="default">
+      Default
+    </Tag>
+    <Tag variant="outline" color="primary">
+      Primary
+    </Tag>
+    <Tag variant="outline" color="success">
+      Success
+    </Tag>
+    <Tag variant="outline" color="warning">
+      Warning
+    </Tag>
+    <Tag variant="outline" color="destructive">
+      Destructive
+    </Tag>
+  </TagGroup>
+  <TagGroup>
+    <Tag variant="ghost" color="default">
+      Default
+    </Tag>
+    <Tag variant="ghost" color="primary">
+      Primary
+    </Tag>
+    <Tag variant="ghost" color="success">
+      Success
+    </Tag>
+    <Tag variant="ghost" color="warning">
+      Warning
+    </Tag>
+    <Tag variant="ghost" color="destructive">
+      Destructive
+    </Tag>
+  </TagGroup>
+</div>
+```
+
+### Sizes
+
+三档尺寸 sm / md / lg。
+
+```tsx
+<TagGroup>
+  <Tag size="sm" color="primary">
+    Small
+  </Tag>
+  <Tag size="md" color="primary">
+    Medium
+  </Tag>
+  <Tag size="lg" color="primary">
+    Large
+  </Tag>
+</TagGroup>
+```
+
+### WithIcon
+
+文字左侧图标 slot。
+
+```tsx
+<TagGroup>
+  <Tag icon={<Star />} color="primary">
+    收藏
+  </Tag>
+  <Tag icon={<Flame />} color="destructive">
+    热门
+  </Tag>
+  <Tag icon={<Zap />} palette="orange">
+    闪电
+  </Tag>
+</TagGroup>
+```
+
+### Disabled
+
+禁用态:普通 / closable / checkable 三态。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <TagGroup>
+    <Tag disabled color="primary">
+      disabled solid
+    </Tag>
+    <Tag disabled variant="outline" color="success">
+      disabled outline
+    </Tag>
+    <Tag disabled variant="ghost" color="destructive">
+      disabled ghost
+    </Tag>
+  </TagGroup>
+  <TagGroup>
+    <Tag disabled closable color="primary">
+      disabled closable
+    </Tag>
+  </TagGroup>
+  <TagGroup>
+    <CheckableTag checked disabled>
+      disabled checked
+    </CheckableTag>
+    <CheckableTag checked={false} disabled>
+      disabled unchecked
+    </CheckableTag>
+  </TagGroup>
+</div>
+```
+
+### Palette
+
+装饰色 palette 9 预设 + 任意 CSS 值。
+
+```tsx
+<TagGroup>
+  <Tag palette="blue">Blue</Tag>
+  <Tag palette="cyan">Cyan</Tag>
+  <Tag palette="green">Green</Tag>
+  <Tag palette="orange">Orange</Tag>
+  <Tag palette="purple">Purple</Tag>
+  <Tag palette="red">Red</Tag>
+  <Tag palette="magenta">Magenta</Tag>
+  <Tag palette="lime">Lime</Tag>
+  <Tag palette="gold">Gold</Tag>
+  <Tag palette="var(--color-primary)">Custom</Tag>
+</TagGroup>
+```
+
+### Group
+
+TagGroup 三档间距。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <div>
+    <h4 className="mb-2 text-xs text-muted-foreground">gap = sm</h4>
+    <TagGroup gap="sm">
+      <Tag>Tag A</Tag>
+      <Tag>Tag B</Tag>
+      <Tag>Tag C</Tag>
+    </TagGroup>
+  </div>
+  <div>
+    <h4 className="mb-2 text-xs text-muted-foreground">gap = md(默认)</h4>
+    <TagGroup>
+      <Tag>Tag A</Tag>
+      <Tag>Tag B</Tag>
+      <Tag>Tag C</Tag>
+    </TagGroup>
+  </div>
+  <div>
+    <h4 className="mb-2 text-xs text-muted-foreground">gap = lg</h4>
+    <TagGroup gap="lg">
+      <Tag>Tag A</Tag>
+      <Tag>Tag B</Tag>
+      <Tag>Tag C</Tag>
+    </TagGroup>
+  </div>
+</div>
+```
+
+### AsChild
+
+asChild — 把 Tag 渲染为子元素(如链接)。
+
+```tsx
+<TagGroup>
+  <Tag asChild color="primary">
+    <a href="#tag" target="_self" rel="noreferrer">
+      link tag
+    </a>
+  </Tag>
+  <Tag asChild variant="outline" color="success">
+    <a href="#tag" target="_self" rel="noreferrer">
+      another link
+    </a>
+  </Tag>
+</TagGroup>
+```

package/src/components/tag/stories.tsx

@@ -0,0 +1,431 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Flame, Star, Trash2, Zap } from 'lucide-react';
+
+import { Tag, TagGroup, CheckableTag, CheckableTagGroup } from '.';
+
+const meta: Meta<typeof Tag> = {
+  title: '数据展示 · Data Display/Tag 标签',
+  component: Tag,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tag>;
+
+/** 最小演示。 */
+export const Default: Story = {
+  args: { children: 'Tag' },
+};
+
+/** 形态轴 × 语义色矩阵(ADR 0021)。 */
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <TagGroup>
+        <Tag variant="solid" color="default">
+          Default
+        </Tag>
+        <Tag variant="solid" color="primary">
+          Primary
+        </Tag>
+        <Tag variant="solid" color="success">
+          Success
+        </Tag>
+        <Tag variant="solid" color="warning">
+          Warning
+        </Tag>
+        <Tag variant="solid" color="destructive">
+          Destructive
+        </Tag>
+      </TagGroup>
+      <TagGroup>
+        <Tag variant="outline" color="default">
+          Default
+        </Tag>
+        <Tag variant="outline" color="primary">
+          Primary
+        </Tag>
+        <Tag variant="outline" color="success">
+          Success
+        </Tag>
+        <Tag variant="outline" color="warning">
+          Warning
+        </Tag>
+        <Tag variant="outline" color="destructive">
+          Destructive
+        </Tag>
+      </TagGroup>
+      <TagGroup>
+        <Tag variant="ghost" color="default">
+          Default
+        </Tag>
+        <Tag variant="ghost" color="primary">
+          Primary
+        </Tag>
+        <Tag variant="ghost" color="success">
+          Success
+        </Tag>
+        <Tag variant="ghost" color="warning">
+          Warning
+        </Tag>
+        <Tag variant="ghost" color="destructive">
+          Destructive
+        </Tag>
+      </TagGroup>
+    </div>
+  ),
+};
+
+/** 三档尺寸 sm / md / lg。 */
+export const Sizes: Story = {
+  render: () => (
+    <TagGroup>
+      <Tag size="sm" color="primary">
+        Small
+      </Tag>
+      <Tag size="md" color="primary">
+        Medium
+      </Tag>
+      <Tag size="lg" color="primary">
+        Large
+      </Tag>
+    </TagGroup>
+  ),
+};
+
+/** 文字左侧图标 slot。 */
+export const WithIcon: Story = {
+  render: () => (
+    <TagGroup>
+      <Tag icon={<Star />} color="primary">
+        收藏
+      </Tag>
+      <Tag icon={<Flame />} color="destructive">
+        热门
+      </Tag>
+      <Tag icon={<Zap />} palette="orange">
+        闪电
+      </Tag>
+    </TagGroup>
+  ),
+};
+
+/**
+ * 关闭路径升级:
+ * - `closable` 接受 boolean / 对象,可自定义 `closeIcon` / `closeArea` / `aria-label`
+ * - `onClose(e)` 调用 `e.preventDefault()` 阻止默认关闭
+ * - `visible` / `defaultVisible` 双形态可见性
+ */
+export const Closable: Story = {
+  render: () => {
+    const [visible, setVisible] = React.useState(true);
+    return (
+      <div className="flex flex-col gap-4">
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">默认 tail</h4>
+          <TagGroup>
+            <Tag closable color="primary">
+              tail close
+            </Tag>
+            <Tag closable color="success" onClose={() => console.log('closed')}>
+              带回调
+            </Tag>
+          </TagGroup>
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">
+            自定义 closeIcon
+          </h4>
+          <TagGroup>
+            <Tag
+              closable={{ closeIcon: <Trash2 />, 'aria-label': 'Delete' }}
+              color="destructive"
+            >
+              custom icon
+            </Tag>
+          </TagGroup>
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">
+            closeArea = &quot;tag&quot;(整体可点击关闭)
+          </h4>
+          <TagGroup>
+            <Tag closable={{ closeArea: 'tag' }} color="warning">
+              click anywhere
+            </Tag>
+          </TagGroup>
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">
+            preventDefault 阻止默认关闭
+          </h4>
+          <TagGroup>
+            <Tag
+              closable
+              color="primary"
+              onClose={(e) => {
+                e.preventDefault();
+                console.log('blocked');
+              }}
+            >
+              cannot close
+            </Tag>
+          </TagGroup>
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">受控 visible</h4>
+          <TagGroup>
+            <Tag
+              closable
+              visible={visible}
+              onClose={(e) => {
+                e.preventDefault();
+                setVisible(false);
+              }}
+              color="primary"
+            >
+              controlled
+            </Tag>
+            <CheckableTag checked={visible} onChange={setVisible}>
+              {visible ? '隐藏' : '显示'}
+            </CheckableTag>
+          </TagGroup>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** 禁用态:普通 / closable / checkable 三态。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <TagGroup>
+        <Tag disabled color="primary">
+          disabled solid
+        </Tag>
+        <Tag disabled variant="outline" color="success">
+          disabled outline
+        </Tag>
+        <Tag disabled variant="ghost" color="destructive">
+          disabled ghost
+        </Tag>
+      </TagGroup>
+      <TagGroup>
+        <Tag disabled closable color="primary">
+          disabled closable
+        </Tag>
+      </TagGroup>
+      <TagGroup>
+        <CheckableTag checked disabled>
+          disabled checked
+        </CheckableTag>
+        <CheckableTag checked={false} disabled>
+          disabled unchecked
+        </CheckableTag>
+      </TagGroup>
+    </div>
+  ),
+};
+
+/**
+ * status 9 档对照表：彩色标签(tag) / 圆点(statusTag) / 图标(statusIconTag)。
+ * 对齐 teamix-pro ProField status demo 矩阵。
+ */
+export const Status: Story = {
+  render: () => {
+    const rows: Array<{
+      label: string;
+      status:
+        | 'success'
+        | 'processing'
+        | 'error'
+        | 'warning'
+        | 'pause'
+        | 'loading'
+        | 'help'
+        | 'mention'
+        | 'default';
+      noTag?: boolean;
+      noStatus?: boolean;
+    }> = [
+      { label: '成功', status: 'success' },
+      { label: '运行中', status: 'processing' },
+      { label: '失败', status: 'error' },
+      { label: '提醒', status: 'warning' },
+      { label: '暂停', status: 'pause', noTag: true },
+      { label: '加载中', status: 'loading', noTag: true },
+      { label: '帮助', status: 'help' },
+      { label: '提示', status: 'mention', noStatus: true },
+      { label: '默认', status: 'default' },
+    ];
+    return (
+      <table className="text-sm">
+        <thead>
+          <tr className="text-left text-muted-foreground">
+            <th className="w-20 pb-2 font-normal">类型</th>
+            <th className="w-20 pb-2 font-normal">描述</th>
+            <th className="px-4 pb-2 font-normal">tag</th>
+            <th className="px-4 pb-2 font-normal">statusTag</th>
+            <th className="px-4 pb-2 font-normal">statusIconTag</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row.status}>
+              <td className="py-1.5 pr-2 font-mono text-xs text-muted-foreground">
+                {row.status}
+              </td>
+              <td className="py-1.5 pr-2 text-muted-foreground">{row.label}</td>
+              <td className="px-4 py-1.5">
+                {row.noTag ? (
+                  <span className="text-muted-foreground">-</span>
+                ) : (
+                  <Tag status={row.status}>{row.label}</Tag>
+                )}
+              </td>
+              <td className="px-4 py-1.5">
+                {row.noStatus ? (
+                  <span className="text-muted-foreground">-</span>
+                ) : (
+                  <Tag variant="status" status={row.status}>
+                    {row.label}
+                  </Tag>
+                )}
+              </td>
+              <td className="px-4 py-1.5">
+                {row.noStatus ? (
+                  <span className="text-muted-foreground">-</span>
+                ) : (
+                  <Tag variant="status" status={row.status} showIcon>
+                    {row.label}
+                  </Tag>
+                )}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    );
+  },
+};
+
+/** 装饰色 palette 9 预设 + 任意 CSS 值。 */
+export const Palette: Story = {
+  render: () => (
+    <TagGroup>
+      <Tag palette="blue">Blue</Tag>
+      <Tag palette="cyan">Cyan</Tag>
+      <Tag palette="green">Green</Tag>
+      <Tag palette="orange">Orange</Tag>
+      <Tag palette="purple">Purple</Tag>
+      <Tag palette="red">Red</Tag>
+      <Tag palette="magenta">Magenta</Tag>
+      <Tag palette="lime">Lime</Tag>
+      <Tag palette="gold">Gold</Tag>
+      <Tag palette="var(--color-primary)">Custom</Tag>
+    </TagGroup>
+  ),
+};
+
+/** TagGroup 三档间距。 */
+export const Group: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h4 className="mb-2 text-xs text-muted-foreground">gap = sm</h4>
+        <TagGroup gap="sm">
+          <Tag>Tag A</Tag>
+          <Tag>Tag B</Tag>
+          <Tag>Tag C</Tag>
+        </TagGroup>
+      </div>
+      <div>
+        <h4 className="mb-2 text-xs text-muted-foreground">gap = md(默认)</h4>
+        <TagGroup>
+          <Tag>Tag A</Tag>
+          <Tag>Tag B</Tag>
+          <Tag>Tag C</Tag>
+        </TagGroup>
+      </div>
+      <div>
+        <h4 className="mb-2 text-xs text-muted-foreground">gap = lg</h4>
+        <TagGroup gap="lg">
+          <Tag>Tag A</Tag>
+          <Tag>Tag B</Tag>
+          <Tag>Tag C</Tag>
+        </TagGroup>
+      </div>
+    </div>
+  ),
+};
+
+/** CheckableTagGroup 多选 / 单选 / outline 三种模式。 */
+export const Selectable: Story = {
+  render: () => {
+    const [single, setSingle] = React.useState<string | null>('react');
+    return (
+      <div className="flex flex-col gap-4">
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">多选(默认)</h4>
+          <CheckableTagGroup
+            options={[
+              { label: 'React', value: 'react' },
+              { label: 'Vue', value: 'vue' },
+              { label: 'Angular', value: 'angular' },
+              { label: 'Svelte', value: 'svelte', disabled: true },
+            ]}
+            defaultValue={['react']}
+          />
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">
+            单选(multiple = false)
+          </h4>
+          <CheckableTagGroup
+            multiple={false}
+            value={single}
+            onChange={setSingle}
+            options={[
+              { label: 'React', value: 'react' },
+              { label: 'Vue', value: 'vue' },
+              { label: 'Angular', value: 'angular' },
+            ]}
+          />
+        </div>
+        <div>
+          <h4 className="mb-2 text-xs text-muted-foreground">outline 模式</h4>
+          <CheckableTagGroup
+            variant="outline"
+            options={[
+              { label: 'React', value: 'react' },
+              { label: 'Vue', value: 'vue' },
+              { label: 'Angular', value: 'angular' },
+              { label: 'Svelte', value: 'svelte' },
+            ]}
+            defaultValue={['react', 'vue']}
+          />
+        </div>
+      </div>
+    );
+  },
+};
+
+/** asChild — 把 Tag 渲染为子元素(如链接)。 */
+export const AsChild: Story = {
+  render: () => (
+    <TagGroup>
+      <Tag asChild color="primary">
+        <a href="#tag" target="_self" rel="noreferrer">
+          link tag
+        </a>
+      </Tag>
+      <Tag asChild variant="outline" color="success">
+        <a href="#tag" target="_self" rel="noreferrer">
+          another link
+        </a>
+      </Tag>
+    </TagGroup>
+  ),
+};