@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,116 @@
+---
+id: item
+name: Item
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Item
+
+通用列表项 / 卡片项容器 — shadcn 2025-10 新增。**取代我们之前自实现的 `List.Item` + `List.Item.Meta`**(antd 老 List 在 v6 已 deprecated)。用 5 个语义槽组合:`ItemMedia` 媒体 / `ItemContent` 主体 / `ItemTitle` 标题 / `ItemDescription` 描述 / `ItemActions` 操作。排列用 `ItemGroup`(纵向 + 分隔)或自行 div / ul 自由布局。
+
+## When to use
+
+- 消息流 / 通知列表的单条
+- 设置项(标题 + 描述 + 开关 / 按钮)
+- 文件 / 联系人 / 任务卡片化展示
+- 配 Flex / Grid / Card / Sidebar 自由组合排列容器
+
+## When NOT to use
+
+- 结构化数据(有列对齐 / 排序)→ `Table` / `DataTable`
+- 完整业务卡片(带 Header / Cover / Footer)→ `Card`
+- 树形嵌套 → `Tree`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **5 个槽是约定不是强制**:`Item` 内子节点顺序就是渲染顺序,可以只用 `ItemContent + ItemActions`,也可以五个都用
+- **`ItemContent`** 必须放主体内容,它有 `min-w-0 flex-1` 用来对抗 truncate;不要外面再裹 div
+- **`ItemTitle / ItemDescription` 自带 `truncate`** — 不希望截断的场景请覆盖 `className="whitespace-normal"`
+- **`variant="default"`(默认)透明无边框** — 嵌入 `ItemGroup` / `List` / `Sidebar` 容器使用
+- **`variant="outline"` 卡片化** — 独立单 Item 卡片(关注小白卡 / 消息中心整条)
+- **`interactive=true` 等价 cursor-pointer + hover 高亮** — 配合 `onClick` 或外层 `<a>` 包裹;**不要**给 Item 加 `role="button"`,完整按钮请用 Button
+
+## Examples
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemGroup,
+} from '@/components/ui/item';
+import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { Button } from '@/components/ui/button';
+import { Switch } from '@/components/ui/switch';
+
+// 设置项
+<Item>
+  <ItemContent>
+    <ItemTitle>邮件通知</ItemTitle>
+    <ItemDescription>有重要事件时给我发邮件</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+
+// 联系人列表
+<ItemGroup>
+  {users.map((u) => (
+    <Item key={u.id} interactive>
+      <ItemMedia>
+        <Avatar><AvatarFallback>{u.initials}</AvatarFallback></Avatar>
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>{u.name}</ItemTitle>
+        <ItemDescription>{u.email}</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button variant="ghost" size="sm">邀请</Button>
+      </ItemActions>
+    </Item>
+  ))}
+</ItemGroup>
+
+// 独立卡片化 Item
+<Item variant="outline" interactive>
+  <ItemContent>
+    <ItemTitle>升级到 Pro</ItemTitle>
+    <ItemDescription>解锁更多组件与高级模板</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button>升级</Button>
+  </ItemActions>
+</Item>
+```

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

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemGroup,
+} from './item';
+import { Avatar, AvatarFallback } from '@/components/avatar/avatar';
+import { Button } from '@/components/button/button';
+import { Switch } from '@/components/switch/switch';
+
+const meta: Meta<typeof Item> = {
+  title: '布局与容器 · Layout/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。',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['default', 'outline', 'muted'] },
+    interactive: { control: 'boolean' },
+  },
+  args: { variant: 'default', interactive: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Item>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Item {...args}>
+      <ItemContent>
+        <ItemTitle>邮件通知</ItemTitle>
+        <ItemDescription>有重要事件时给我发邮件</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Switch defaultChecked />
+      </ItemActions>
+    </Item>
+  ),
+};
+
+const users = [
+  { id: 1, name: 'Alice Wong', email: 'alice@example.com', initials: 'AW' },
+  { id: 2, name: 'Bob Lin', email: 'bob@example.com', initials: 'BL' },
+  { id: 3, name: 'Carol Sun', email: 'carol@example.com', initials: 'CS' },
+];
+
+export const ContactList: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ItemGroup className="w-96 rounded-md border">
+      {users.map((u) => (
+        <Item key={u.id} interactive className="px-3 py-2">
+          <ItemMedia>
+            <Avatar>
+              <AvatarFallback>{u.initials}</AvatarFallback>
+            </Avatar>
+          </ItemMedia>
+          <ItemContent>
+            <ItemTitle>{u.name}</ItemTitle>
+            <ItemDescription>{u.email}</ItemDescription>
+          </ItemContent>
+          <ItemActions>
+            <Button variant="ghost" size="sm">
+              邀请
+            </Button>
+          </ItemActions>
+        </Item>
+      ))}
+    </ItemGroup>
+  ),
+};
+
+export const OutlineCard: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Item variant="outline" interactive className="w-96">
+      <ItemContent>
+        <ItemTitle>升级到 Pro</ItemTitle>
+        <ItemDescription>解锁更多组件与高级模板</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button>升级</Button>
+      </ItemActions>
+    </Item>
+  ),
+};
+
+export const Muted: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Item variant="muted" className="w-96">
+      <ItemContent>
+        <ItemTitle>提示</ItemTitle>
+        <ItemDescription>该 workspace 还没有任何项目</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button variant="outline" size="sm">
+          新建
+        </Button>
+      </ItemActions>
+    </Item>
+  ),
+};

package/src/components/item/item.tsx

@@ -0,0 +1,171 @@
+import * as React from 'react';
+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',
+  {
+    variants: {
+      variant: {
+        default: '',
+        outline: 'rounded-md border bg-card p-3 text-card-foreground shadow-sm',
+        muted: 'rounded-md bg-muted p-3',
+      },
+      interactive: {
+        true: 'cursor-pointer hover:bg-accent',
+        false: '',
+      },
+    },
+    defaultVariants: { variant: 'default', interactive: false },
+  },
+);
+
+export interface ItemProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof itemVariants> {
+  /**
+   * 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。
+   * @default "default"
+   */
+  variant?: 'default' | 'outline' | 'muted';
+  /**
+   * 是否带 hover 高亮 + cursor-pointer(行可点击场景)。
+   * @default false
+   */
+  interactive?: boolean;
+}
+
+/**
+ * 通用列表项 / 卡片项容器 — shadcn 2025-10 新增。
+ * 用 `<ItemMedia>` `<ItemContent>` `<ItemTitle>` `<ItemDescription>` `<ItemActions>`
+ * 五个语义槽组合,替代之前 antd `List.Item` + `List.Item.Meta` 的强结构。
+ *
+ * 排列容器请用 `<ItemGroup>`(纵向 + divider)或直接用 div / ul 自行布局。
+ */
+const Item = React.forwardRef<HTMLDivElement, ItemProps>(
+  ({ variant, interactive, className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(itemVariants({ variant, interactive }), className)}
+      {...props}
+    />
+  ),
+);
+Item.displayName = 'Item';
+
+// ─── ItemMedia(头像 / 图标 / 缩略图槽)──────────────────────────────────
+
+export interface ItemMediaProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 媒体尺寸 — `default` 用于头像 / 图标;`lg` 用于缩略图。
+   * @default "default"
+   */
+  size?: 'default' | 'lg';
+}
+
+const ItemMedia = React.forwardRef<HTMLDivElement, ItemMediaProps>(
+  ({ size = 'default', className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        'flex shrink-0 items-center justify-center text-muted-foreground',
+        size === 'lg' && 'size-16',
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+ItemMedia.displayName = 'ItemMedia';
+
+// ─── ItemContent(主体内容容器)─────────────────────────────────────────
+
+const ItemContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex min-w-0 flex-1 flex-col gap-1', className)}
+    {...props}
+  />
+));
+ItemContent.displayName = 'ItemContent';
+
+// ─── ItemTitle / ItemDescription ───────────────────────────────────────
+
+const ItemTitle = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('truncate text-sm font-semibold leading-none', className)}
+    {...props}
+  />
+));
+ItemTitle.displayName = 'ItemTitle';
+
+const ItemDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('truncate text-sm text-muted-foreground', className)}
+    {...props}
+  />
+));
+ItemDescription.displayName = 'ItemDescription';
+
+// ─── ItemActions(右侧操作槽)──────────────────────────────────────────
+
+const ItemActions = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex shrink-0 items-center gap-2', className)}
+    {...props}
+  />
+));
+ItemActions.displayName = 'ItemActions';
+
+// ─── ItemGroup(纵向排列容器,自带分隔线)──────────────────────────────
+
+export interface ItemGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 项之间是否显示分隔线。
+   * @default true
+   */
+  divided?: boolean;
+}
+
+const ItemGroup = React.forwardRef<HTMLDivElement, ItemGroupProps>(
+  ({ divided = true, className, ...props }, ref) => (
+    <div
+      ref={ref}
+      role="list"
+      className={cn(
+        'flex w-full flex-col',
+        divided && 'divide-y divide-border',
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+ItemGroup.displayName = 'ItemGroup';
+
+export {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemGroup,
+  itemVariants,
+};

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

@@ -0,0 +1,85 @@
+---
+id: kbd
+name: Kbd
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Kbd
+
+键位展示 — shadcn 2025-10 新增。语义化的 `<kbd>` 元素 + `KbdGroup` 组合容器,用于在 UI 中标注**快捷键**(`⌘K` / `Ctrl + Enter` / `Esc`)。常见于 Command Palette、Tooltip、文档 / 帮助提示。
+
+## When to use
+
+- Command Palette 项右侧的快捷键提示
+- Tooltip / 帮助气泡里指明键盘快捷键
+- 文档 / 帮助页中表达"按某键"
+
+## When NOT to use
+
+- 引用代码片段 → 用 `<code>` / Typography Code(`<Kbd>` 语义是物理键位)
+- 普通行内强调 → 用 `<strong>` / Typography Text strong
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add kbd` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **单键用 `<Kbd>`,组合键必须用 `<KbdGroup>`** — 不要直接用空格连接多个 Kbd,会丢失语义
+- **`separator` 仅做视觉**(`+` / `→`),按键间距已默认 `gap-1`,常见 mac 风格留空即可
+- **键名规范**:macOS 用 ⌘ ⇧ ⌥ ⌃ ⏎ 符号;Windows 用 `Ctrl` `Shift` `Alt` 缩写。同一界面保持一致
+- **不要嵌套 `<Kbd>` 在按钮内**做"按这个键"的提示 — 按钮已表达可点击,语义重复;改用 `aria-keyshortcuts` + Tooltip
+- **`size="lg"`** 仅用于 Command Palette / 教程页等视觉高亮,默认与正文同高
+
+## Examples
+
+```tsx
+import { Kbd, KbdGroup } from '@/components/ui/kbd';
+
+// 单键
+<Kbd>Esc</Kbd>
+
+// 组合(mac 风格)
+<KbdGroup>
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</KbdGroup>
+
+// 组合(Win 风格,带分隔)
+<KbdGroup separator="+">
+  <Kbd>Ctrl</Kbd>
+  <Kbd>Shift</Kbd>
+  <Kbd>P</Kbd>
+</KbdGroup>
+
+// 配 Command Palette
+<CommandItem>
+  打开搜索
+  <KbdGroup className="ml-auto">
+    <Kbd>⌘</Kbd><Kbd>K</Kbd>
+  </KbdGroup>
+</CommandItem>
+```

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

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Kbd, KbdGroup } from './kbd';
+
+const meta: Meta<typeof Kbd> = {
+  title: '基础原语 · Foundation/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。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+  },
+  args: { size: 'default', children: 'K' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Kbd>;
+
+export const Playground: Story = {};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-end gap-3">
+      <Kbd size="sm">K</Kbd>
+      <Kbd size="default">K</Kbd>
+      <Kbd size="lg">K</Kbd>
+    </div>
+  ),
+};
+
+export const MacCombo: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <KbdGroup>
+      <Kbd>⌘</Kbd>
+      <Kbd>K</Kbd>
+    </KbdGroup>
+  ),
+};
+
+export const WinCombo: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <KbdGroup separator="+">
+      <Kbd>Ctrl</Kbd>
+      <Kbd>Shift</Kbd>
+      <Kbd>P</Kbd>
+    </KbdGroup>
+  ),
+};
+
+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">
+      <span>打开命令面板</span>
+      <KbdGroup>
+        <Kbd>⌘</Kbd>
+        <Kbd>K</Kbd>
+      </KbdGroup>
+    </div>
+  ),
+};

package/src/components/kbd/kbd.tsx

@@ -0,0 +1,81 @@
+import * as React from 'react';
+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)]',
+  {
+    variants: {
+      size: {
+        sm: 'h-4 px-1 text-[10px]',
+        default: 'h-5 px-1.5 text-xs',
+        lg: 'h-6 px-2 text-sm',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+export interface KbdProps
+  extends React.HTMLAttributes<HTMLElement>,
+    VariantProps<typeof kbdVariants> {
+  /**
+   * 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * 单个键位展示 — shadcn 2025-10 新增。语义化的 `<kbd>` 元素,
+ * 配 `KbdGroup` 表达"⌘ + K"等组合键。
+ */
+const Kbd = React.forwardRef<HTMLElement, KbdProps>(
+  ({ size, className, ...props }, ref) => (
+    <kbd
+      ref={ref as React.Ref<HTMLElement>}
+      className={cn(kbdVariants({ size }), className)}
+      {...props}
+    />
+  ),
+);
+Kbd.displayName = 'Kbd';
+
+export interface KbdGroupProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /**
+   * 组合分隔符(纯视觉) — 默认 ` `(键位间距即可),如 "Ctrl + K" 风格传 "+";"⌘K" 风格传空串。
+   * @default ""
+   */
+  separator?: string;
+}
+
+/**
+ * 组合键容器 — 渲染多个 `<Kbd>` 之间的间距与可选分隔符(`Ctrl + K`、`⇧⌘P`)。
+ */
+const KbdGroup = React.forwardRef<HTMLSpanElement, KbdGroupProps>(
+  ({ separator = '', className, children, ...props }, ref) => {
+    const items = React.Children.toArray(children).filter(Boolean);
+    return (
+      <span
+        ref={ref}
+        className={cn('inline-flex items-center gap-1', className)}
+        {...props}
+      >
+        {items.map((child, i) => (
+          <React.Fragment key={i}>
+            {i > 0 && separator ? (
+              <span aria-hidden="true" className="text-xs text-muted-foreground">
+                {separator}
+              </span>
+            ) : null}
+            {child}
+          </React.Fragment>
+        ))}
+      </span>
+    );
+  },
+);
+KbdGroup.displayName = 'KbdGroup';
+
+export { Kbd, KbdGroup, kbdVariants };