@teamix-evo/ui 0.1.1

package/src/components/auto-complete/auto-complete.stories.tsx

@@ -0,0 +1,93 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { AutoComplete } from './auto-complete';
+
+const meta: Meta<typeof AutoComplete> = {
+  title: '表单与输入 · Form/AutoComplete',
+  component: AutoComplete,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '输入即建议 — 键入触发候选下拉,可选可改。最终 value 是自由文本,不强制为选项之一(与 Combobox 必选互补)。配 onSearch 实现异步建议。等价 antd `AutoComplete`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AutoComplete>;
+
+const frameworks = [
+  { value: 'React' },
+  { value: 'Vue' },
+  { value: 'Svelte' },
+  { value: 'Angular' },
+  { value: 'Solid' },
+];
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <AutoComplete
+      options={frameworks}
+      placeholder="输入框架名..."
+      className="w-64"
+    />
+  ),
+};
+
+export const OpenOnFocus: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <AutoComplete
+      openOnFocus
+      options={['react', 'vue', 'svelte', 'angular'].map((v) => ({ value: v }))}
+      placeholder="聚焦即显示历史..."
+      className="w-64"
+    />
+  ),
+};
+
+export const EmailSuggest: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState('');
+    const domains = ['@gmail.com', '@outlook.com', '@qq.com', '@163.com'];
+    const localPart = v.includes('@') ? v.slice(0, v.indexOf('@')) : v;
+    const opts = !localPart
+      ? []
+      : domains.map((d) => ({ value: localPart + d }));
+    return (
+      <AutoComplete
+        value={v}
+        onChange={setV}
+        options={opts}
+        placeholder="输入邮箱前缀..."
+        className="w-72"
+      />
+    );
+  },
+};
+
+export const AsyncSearch: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const all = ['北京', '上海', '深圳', '广州', '杭州', '成都', '武汉'];
+    const [opts, setOpts] = React.useState(all.map((v) => ({ value: v })));
+    return (
+      <AutoComplete
+        options={opts}
+        onSearch={(q) => {
+          window.setTimeout(() => {
+            setOpts(all.filter((v) => v.includes(q)).map((v) => ({ value: v })));
+          }, 80);
+        }}
+        placeholder="搜索城市(模拟异步)..."
+        emptyText="没有匹配的城市"
+        className="w-64"
+      />
+    );
+  },
+};

package/src/components/auto-complete/auto-complete.tsx

@@ -0,0 +1,205 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+import { Input } from '@/components/input/input';
+
+export interface AutoCompleteOption {
+  /** 真实写入到输入框的 value(也作为建议列表 key)。 */
+  value: string;
+  /** 建议下拉显示文本(不传则用 value)。 */
+  label?: React.ReactNode;
+  /** 禁用此项(不可被选中)。 */
+  disabled?: boolean;
+}
+
+export interface AutoCompleteProps
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    'onChange' | 'value' | 'defaultValue' | 'onSelect' | 'size'
+  > {
+  /** 候选项(antd `options` 并集) — 通常由 onSearch 回调刷新。 */
+  options: AutoCompleteOption[];
+  /** 受控值。 */
+  value?: string;
+  /** uncontrolled 初值。 */
+  defaultValue?: string;
+  /**
+   * 值变化回调 — 用户键入 / 选中候选时触发。
+   */
+  onChange?: (value: string) => void;
+  /**
+   * 用户输入时回调,用于刷新 `options`(异步建议)。
+   */
+  onSearch?: (query: string) => void;
+  /**
+   * 选中候选时回调。
+   */
+  onSelect?: (value: string, option: AutoCompleteOption) => void;
+  /**
+   * 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。
+   * @default false
+   */
+  openOnFocus?: boolean;
+  /**
+   * 无匹配时的提示文本。
+   * @default "无匹配项"
+   */
+  emptyText?: string;
+  /**
+   * 容器尺寸 — 透传 Input.size。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * 输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。
+ * 与 `Combobox` 区别:Combobox 是"必选下拉",输入框只接受选项中的值;
+ * AutoComplete 是"自由输入 + 选项建议",最终 value 可以是任意字符串。
+ */
+const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
+  (
+    {
+      options,
+      value,
+      defaultValue,
+      onChange,
+      onSearch,
+      onSelect,
+      openOnFocus = false,
+      emptyText = '无匹配项',
+      size = 'default',
+      className,
+      onFocus,
+      onBlur,
+      onKeyDown,
+      placeholder,
+      disabled,
+      ...props
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<string>(defaultValue ?? '');
+    const current = isControlled ? value! : internal;
+
+    const [open, setOpen] = React.useState(false);
+    const [activeIdx, setActiveIdx] = React.useState(0);
+
+    const filtered = React.useMemo(() => {
+      const q = current.toLowerCase();
+      return q === ''
+        ? options
+        : options.filter((o) => o.value.toLowerCase().includes(q));
+    }, [current, options]);
+
+    React.useEffect(() => {
+      setActiveIdx(0);
+    }, [current]);
+
+    const update = (next: string) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    };
+
+    const select = (opt: AutoCompleteOption) => {
+      if (opt.disabled) return;
+      update(opt.value);
+      onSelect?.(opt.value, opt);
+      setOpen(false);
+    };
+
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (open && filtered.length > 0) {
+        if (e.key === 'ArrowDown') {
+          e.preventDefault();
+          setActiveIdx((i) => (i + 1) % filtered.length);
+          return;
+        }
+        if (e.key === 'ArrowUp') {
+          e.preventDefault();
+          setActiveIdx((i) => (i - 1 + filtered.length) % filtered.length);
+          return;
+        }
+        if (e.key === 'Enter') {
+          const opt = filtered[activeIdx];
+          if (opt && !opt.disabled) {
+            e.preventDefault();
+            select(opt);
+            return;
+          }
+        }
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          setOpen(false);
+          return;
+        }
+      }
+      onKeyDown?.(e);
+    };
+
+    const shouldShow = open && (filtered.length > 0 || current !== '');
+
+    return (
+      <div className={cn('relative', className)}>
+        <Input
+          ref={ref}
+          value={current}
+          placeholder={placeholder}
+          disabled={disabled}
+          size={size}
+          onChange={(e) => {
+            update(e.target.value);
+            onSearch?.(e.target.value);
+            setOpen(true);
+          }}
+          onFocus={(e) => {
+            if (openOnFocus) setOpen(true);
+            onFocus?.(e);
+          }}
+          onBlur={(e) => {
+            window.setTimeout(() => setOpen(false), 120);
+            onBlur?.(e);
+          }}
+          onKeyDown={handleKeyDown}
+          {...props}
+        />
+        {shouldShow ? (
+          <ul
+            role="listbox"
+            className="absolute left-0 right-0 top-full z-50 mt-1 max-h-60 overflow-auto rounded-md border bg-popover p-1 text-sm text-popover-foreground shadow-md"
+          >
+            {filtered.length === 0 ? (
+              <li className="px-2 py-1.5 text-center text-xs text-muted-foreground">
+                {emptyText}
+              </li>
+            ) : (
+              filtered.map((opt, i) => (
+                <li
+                  key={opt.value}
+                  role="option"
+                  aria-selected={i === activeIdx}
+                  onMouseDown={(e) => {
+                    e.preventDefault();
+                    select(opt);
+                  }}
+                  onMouseEnter={() => setActiveIdx(i)}
+                  className={cn(
+                    'cursor-pointer rounded-sm px-2 py-1.5',
+                    i === activeIdx && !opt.disabled && 'bg-accent text-accent-foreground',
+                    opt.disabled && 'cursor-not-allowed opacity-50',
+                  )}
+                >
+                  {opt.label ?? opt.value}
+                </li>
+              ))
+            )}
+          </ul>
+        ) : null}
+      </div>
+    );
+  },
+);
+AutoComplete.displayName = 'AutoComplete';
+
+export { AutoComplete };

package/src/components/avatar/avatar.meta.md

@@ -0,0 +1,94 @@
+---
+id: avatar
+name: Avatar
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Avatar
+
+头像 — Radix Avatar(图片加载失败自动回退到 Fallback)+ antd Avatar 的 `size / shape / Avatar.Group` 并集。
+
+## When to use
+
+- 用户身份标识(列表 / 评论 / 顶部导航)
+- 多人协作场景的成员展示(`AvatarGroup max`)
+- 资源所有者标记
+
+## When NOT to use
+
+- 装饰性图标 → 用 `lucide-react` 图标
+- 大尺寸内容头图 → 用 `AspectRatio` + `<img>` 自由布局
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
+| `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状(antd 并集)。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add avatar` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-avatar@^1.1.0 class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+> 子组件:`AvatarImage`(图片源)/ `AvatarFallback`(加载失败 / 无图时的占位)/ `AvatarGroup`(多头像折叠组,带 `max` 与 `size`)。
+
+## AI 生成纪律
+
+- **必须配 Fallback**:`AvatarImage` 加载失败时无 Fallback 会渲染空白;**永远**写 `<AvatarImage /> + <AvatarFallback>{initials}</AvatarFallback>` 的对子
+- **Fallback 内容用首字母**:取 name 首字母 1~2 个,**不要**塞图标(图标用 `<img>` 直接渲染更准确)
+- **Group 内尺寸统一**:`AvatarGroup` 的 `size` 会覆盖子项 — 不要在 Group 内混用不同尺寸的 Avatar
+- **shape="square" 用于品牌 / 产品 Logo**:用户头像保持 `circle` 默认
+
+## Examples
+
+```tsx
+import {
+  Avatar, AvatarImage, AvatarFallback, AvatarGroup,
+} from '@/components/ui/avatar';
+
+// 基础
+<Avatar>
+  <AvatarImage src="/u/lyca.jpg" alt="lyca" />
+  <AvatarFallback>LY</AvatarFallback>
+</Avatar>
+
+// 尺寸 + 形状
+<Avatar size="lg" shape="square">
+  <AvatarImage src="/p/teamix.svg" alt="Teamix" />
+  <AvatarFallback>TE</AvatarFallback>
+</Avatar>
+
+// 协作组(超出 3 收起)
+<AvatarGroup max={3} size="sm">
+  <Avatar><AvatarImage src="/u/a.jpg" /><AvatarFallback>A</AvatarFallback></Avatar>
+  <Avatar><AvatarImage src="/u/b.jpg" /><AvatarFallback>B</AvatarFallback></Avatar>
+  <Avatar><AvatarImage src="/u/c.jpg" /><AvatarFallback>C</AvatarFallback></Avatar>
+  <Avatar><AvatarImage src="/u/d.jpg" /><AvatarFallback>D</AvatarFallback></Avatar>
+  <Avatar><AvatarImage src="/u/e.jpg" /><AvatarFallback>E</AvatarFallback></Avatar>
+</AvatarGroup>
+```

package/src/components/avatar/avatar.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from './avatar';
+
+const meta: Meta<typeof Avatar> = {
+  title: '基础原语 · Foundation/Avatar',
+  component: Avatar,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '头像 — 表示用户或对象，支持图片 / 文字 / 图标三种回退源。基于 Radix Avatar(图片加载失败自动回退到 fallback) + antd 增强:尺寸 sm/default/lg、形状 circle/square、`AvatarGroup` 堆叠。Image / Fallback 通过命名子组件组合。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'select', options: ['sm', 'default', 'lg', 'xl'] },
+    shape: { control: 'inline-radio', options: ['circle', 'square'] },
+  },
+  args: { size: 'default', shape: 'circle' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Avatar {...args}>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>SH</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+export const SizesAndShapes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-end gap-3">
+      {(['sm', 'default', 'lg', 'xl'] as const).map((s) => (
+        <Avatar key={s} size={s}>
+          <AvatarImage src="https://github.com/shadcn.png" />
+          <AvatarFallback>SH</AvatarFallback>
+        </Avatar>
+      ))}
+      <Avatar shape="square">
+        <AvatarFallback>TE</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+export const FallbackOnly: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar>
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>李</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>?</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+export const Group: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <AvatarGroup max={3}>
+      {['A', 'B', 'C', 'D', 'E'].map((c) => (
+        <Avatar key={c}>
+          <AvatarFallback>{c}</AvatarFallback>
+        </Avatar>
+      ))}
+    </AvatarGroup>
+  ),
+};

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,126 @@
+import * as React from 'react';
+import * as AvatarPrimitive from '@radix-ui/react-avatar';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const avatarVariants = cva(
+  'relative flex shrink-0 overflow-hidden bg-muted',
+  {
+    variants: {
+      size: {
+        sm: 'size-8 text-xs',
+        default: 'size-10 text-sm',
+        lg: 'size-12 text-base',
+        xl: 'size-16 text-lg',
+      },
+      shape: {
+        circle: 'rounded-full',
+        square: 'rounded-md',
+      },
+    },
+    defaultVariants: { size: 'default', shape: 'circle' },
+  },
+);
+
+export interface AvatarProps
+  extends React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>,
+    VariantProps<typeof avatarVariants> {
+  /**
+   * 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg' | 'xl';
+  /**
+   * 形状(antd 并集)。
+   * @default "circle"
+   */
+  shape?: 'circle' | 'square';
+}
+
+const Avatar = React.forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Root>,
+  AvatarProps
+>(({ className, size, shape, ...props }, ref) => (
+  <AvatarPrimitive.Root
+    ref={ref}
+    className={cn(avatarVariants({ size, shape }), className)}
+    {...props}
+  />
+));
+Avatar.displayName = AvatarPrimitive.Root.displayName;
+
+const AvatarImage = React.forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Image>,
+  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image>
+>(({ className, ...props }, ref) => (
+  <AvatarPrimitive.Image
+    ref={ref}
+    className={cn('aspect-square size-full object-cover', className)}
+    {...props}
+  />
+));
+AvatarImage.displayName = AvatarPrimitive.Image.displayName;
+
+const AvatarFallback = React.forwardRef<
+  React.ElementRef<typeof AvatarPrimitive.Fallback>,
+  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback>
+>(({ className, ...props }, ref) => (
+  <AvatarPrimitive.Fallback
+    ref={ref}
+    className={cn(
+      'flex size-full items-center justify-center font-medium text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+));
+AvatarFallback.displayName = AvatarPrimitive.Fallback.displayName;
+
+// ─── AvatarGroup(antd 并集)────────────────────────────────────────────────
+
+export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 显示前 N 个 Avatar,其余收为 `+N` 折叠气泡。
+   * @default 3
+   */
+  max?: number;
+  /** Group 内所有 Avatar 共享的尺寸,会覆盖单个 Avatar 的 size。 */
+  size?: AvatarProps['size'];
+}
+
+const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
+  ({ className, max = 3, size, children, ...props }, ref) => {
+    const items = React.Children.toArray(children);
+    const visible = items.slice(0, max);
+    const overflow = items.length - max;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex items-center -space-x-2 [&>*]:ring-2 [&>*]:ring-background',
+          className,
+        )}
+        {...props}
+      >
+        {visible.map((child, i) =>
+          React.isValidElement(child) && size
+            ? React.cloneElement(
+                child as React.ReactElement<AvatarProps>,
+                { size, key: i },
+              )
+            : child,
+        )}
+        {overflow > 0 ? (
+          <Avatar size={size}>
+            <AvatarFallback>+{overflow}</AvatarFallback>
+          </Avatar>
+        ) : null}
+      </div>
+    );
+  },
+);
+AvatarGroup.displayName = 'AvatarGroup';
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, avatarVariants };