@teamix-evo/ui 0.1.1

package/src/components/anchor/anchor.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Anchor } from './anchor';
+
+const meta: Meta<typeof Anchor> = {
+  title: '导航 · Navigation/Anchor',
+  component: Anchor,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '锚点导航 — 长文档 / 详情页侧边目录,点击滚动到 id 节点,滚动时 IntersectionObserver 自动高亮。等价 antd `Anchor`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Anchor>;
+
+const items = [
+  { key: 'intro', title: '介绍' },
+  {
+    key: 'install',
+    title: '安装',
+    children: [
+      { key: 'npm', title: 'npm' },
+      { key: 'pnpm', title: 'pnpm' },
+      { key: 'yarn', title: 'yarn' },
+    ],
+  },
+  { key: 'usage', title: '使用' },
+  { key: 'faq', title: 'FAQ' },
+];
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex gap-6">
+      <aside className="sticky top-0 h-fit w-44 shrink-0">
+        <Anchor items={items} offsetTop={20} />
+      </aside>
+      <article className="flex-1 space-y-12 text-sm">
+        <section id="intro">
+          <h2 className="mb-2 text-lg font-semibold">介绍</h2>
+          <p>{Array(8).fill('这是介绍段落。').join(' ')}</p>
+        </section>
+        <section id="install">
+          <h2 className="mb-2 text-lg font-semibold">安装</h2>
+          <section id="npm" className="mb-6">
+            <h3 className="mb-2 font-semibold">npm</h3>
+            <p>{Array(6).fill('npm install.').join(' ')}</p>
+          </section>
+          <section id="pnpm" className="mb-6">
+            <h3 className="mb-2 font-semibold">pnpm</h3>
+            <p>{Array(6).fill('pnpm add.').join(' ')}</p>
+          </section>
+          <section id="yarn">
+            <h3 className="mb-2 font-semibold">yarn</h3>
+            <p>{Array(6).fill('yarn add.').join(' ')}</p>
+          </section>
+        </section>
+        <section id="usage">
+          <h2 className="mb-2 text-lg font-semibold">使用</h2>
+          <p>{Array(10).fill('使用说明文字。').join(' ')}</p>
+        </section>
+        <section id="faq">
+          <h2 className="mb-2 text-lg font-semibold">FAQ</h2>
+          <p>{Array(10).fill('常见问题。').join(' ')}</p>
+        </section>
+      </article>
+    </div>
+  ),
+};

package/src/components/anchor/anchor.tsx

@@ -0,0 +1,130 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+
+export interface AnchorItem {
+  /** 目标元素 id(组件会按 `#${id}` 滚动到该元素)。 */
+  key: string;
+  /** 显示文本。 */
+  title: React.ReactNode;
+  /** 子节点(渲染为嵌套缩进)。 */
+  children?: AnchorItem[];
+}
+
+export interface AnchorProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
+  /** 锚点项树(antd `items` 并集)。 */
+  items: AnchorItem[];
+  /**
+   * 当目标元素距视口顶部小于此值时高亮(IntersectionObserver `rootMargin`)。
+   * @default 0
+   */
+  offsetTop?: number;
+  /**
+   * 点击锚点平滑滚动行为。
+   * @default "smooth"
+   */
+  scrollBehavior?: 'smooth' | 'auto';
+  /** 当前高亮变化回调。 */
+  onChange?: (key: string) => void;
+}
+
+function flatten(items: AnchorItem[]): AnchorItem[] {
+  const out: AnchorItem[] = [];
+  const walk = (it: AnchorItem) => {
+    out.push(it);
+    it.children?.forEach(walk);
+  };
+  items.forEach(walk);
+  return out;
+}
+
+/**
+ * 锚点导航 — antd 独有补足。**等价 antd `Anchor`**。长文档 / 详情页侧边的目录,
+ * 点击锚点滚动到对应 `id` 节点,滚动时自动高亮当前可见的锚点(IntersectionObserver)。
+ */
+const Anchor = React.forwardRef<HTMLElement, AnchorProps>(
+  (
+    {
+      items,
+      offsetTop = 0,
+      scrollBehavior = 'smooth',
+      onChange,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const [active, setActive] = React.useState<string>('');
+    const flat = React.useMemo(() => flatten(items), [items]);
+
+    React.useEffect(() => {
+      if (typeof window === 'undefined') return;
+      const observer = new IntersectionObserver(
+        (entries) => {
+          const visible = entries.find((e) => e.isIntersecting);
+          if (visible) {
+            const id = visible.target.id;
+            setActive(id);
+            onChange?.(id);
+          }
+        },
+        {
+          rootMargin: `-${offsetTop}px 0px -50% 0px`,
+          threshold: 0,
+        },
+      );
+      flat.forEach((it) => {
+        const el = document.getElementById(it.key);
+        if (el) observer.observe(el);
+      });
+      return () => observer.disconnect();
+    }, [flat, offsetTop, onChange]);
+
+    const handleClick = (e: React.MouseEvent, key: string) => {
+      e.preventDefault();
+      const el = document.getElementById(key);
+      if (el) {
+        const top = el.getBoundingClientRect().top + window.scrollY - offsetTop;
+        window.scrollTo({ top, behavior: scrollBehavior });
+        setActive(key);
+        onChange?.(key);
+      }
+    };
+
+    const renderItem = (it: AnchorItem, depth: number): React.ReactNode => (
+      <li key={it.key}>
+        <a
+          href={`#${it.key}`}
+          onClick={(e) => handleClick(e, it.key)}
+          className={cn(
+            'block border-l-2 py-1 pr-2 text-sm transition-colors',
+            depth === 0 ? 'pl-3' : depth === 1 ? 'pl-6' : 'pl-9',
+            active === it.key
+              ? 'border-primary text-primary'
+              : 'border-transparent text-muted-foreground hover:text-foreground',
+          )}
+        >
+          {it.title}
+        </a>
+        {it.children && it.children.length > 0 ? (
+          <ul>{it.children.map((c) => renderItem(c, depth + 1))}</ul>
+        ) : null}
+      </li>
+    );
+
+    return (
+      <nav
+        ref={ref}
+        aria-label="目录"
+        className={cn('text-sm', className)}
+        {...props}
+      >
+        <ul>{items.map((it) => renderItem(it, 0))}</ul>
+      </nav>
+    );
+  },
+);
+Anchor.displayName = 'Anchor';
+
+export { Anchor };

package/src/components/app/app.meta.md

@@ -0,0 +1,86 @@
+---
+id: app
+name: App
+type: component
+category: shell
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# App
+
+应用根容器 — antd 独有补足。**对标 antd `App`** 的核心职责:挂全局 Toaster + 设置 dir / lang + 承载根级 className。**与 antd 区别**:不接管主题(本库主题靠 design tokens / CSS vars,**不引入 runtime ConfigProvider**),也不收敛 `useApp()` hook(toast / notification 直接 import 即可)。
+
+## When to use
+
+- 整个应用的最外层容器(`layout.tsx` / `_app.tsx` / `main.tsx` root)
+- 需要"挂一次 Toaster,后续到处 toast"的场景
+- 国际化需要 `dir="rtl"` 时
+
+## When NOT to use
+
+- 子页面层级容器 → 用 `Flex` / `Grid` / 普通 div
+- 需要 runtime 切换主题色 → 改 CSS variables(design tokens),**不要**通过 ConfigProvider
+- 单独需要 Toaster → 直接挂 `<Toaster />`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `withToaster` | `boolean` | `true` | – | 是否挂载 `<Toaster />`(antd `App` 内部托管 message / notification 静态实例) — 全应用根挂一次。 |
+| `toasterProps` | `ToasterProps` | – | – | 传递给 Toaster 的配置(位置 / 主题 / 自动关闭等) — 仅 `withToaster=true` 时生效。 |
+| `dir` | `'ltr' \| 'rtl'` | `"ltr"` | – | 文字方向 — 设到根容器的 `dir` 属性,Radix 等组件会自动适配。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add app` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `sonner` | component | Toast 通知 — sonner 包装,等价 antd message + notification 并集(toast() 函数式 API + Toaster 容器) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **整应用挂一次** — 子级别再嵌 `App` 会造成 Toaster 重复渲染
+- **不要把它当 Layout 用** — 它只是根 mount 点,真正的页面布局用 `Flex` / `Grid`
+- **`withToaster=false`** 仅当你已经在别处单独挂了 `<Toaster />` 时关闭,避免重复
+- **`dir="rtl"`** 仅在阿语 / 希伯来语等右到左语言场景设;Radix 组件已自动适配
+- **不要在 App 内做主题切换**:换 `class="dark"` 或写 CSS var 覆盖,**不要**走 React state
+
+## Examples
+
+```tsx
+import { App } from '@/components/ui/app';
+
+// 应用根
+function Root() {
+  return (
+    <App>
+      <Header />
+      <Main />
+      <Footer />
+    </App>
+  );
+}
+
+// 自定义 Toaster 位置
+<App toasterProps={{ position: 'top-center', richColors: true }}>
+  ...
+</App>
+
+// RTL
+<App dir="rtl">...</App>
+
+// 已自挂 Toaster
+<App withToaster={false}>
+  <Toaster position="bottom-right" />
+  ...
+</App>
+```

package/src/components/app/app.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { App } from './app';
+import { Button } from '@/components/button/button';
+import { toast } from '@/components/sonner/sonner';
+import { notification } from '@/components/notification/notification';
+
+const meta: Meta<typeof App> = {
+  title: '应用壳 · Shell/App',
+  component: App,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '应用根容器 — 挂全局 Toaster + 设置 dir / lang + 承载根级 className。对标 antd `App`,但不接管主题(主题靠 design tokens / CSS vars),也不收敛 useApp() hook。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    withToaster: { control: 'boolean' },
+    dir: { control: 'inline-radio', options: ['ltr', 'rtl'] },
+  },
+  args: { withToaster: true, dir: 'ltr' },
+};
+
+export default meta;
+type Story = StoryObj<typeof App>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <App {...args} className="rounded-md border p-6">
+      <div className="flex flex-col gap-3">
+        <span className="text-sm text-muted-foreground">App 内挂载了 Toaster,可直接触发:</span>
+        <div className="flex gap-2">
+          <Button onClick={() => toast.success('已保存')}>触发 toast</Button>
+          <Button
+            variant="outline"
+            onClick={() =>
+              notification.info({
+                title: 'App 容器在生效',
+                description: '右上角 Toaster 是 App 默认挂载的',
+              })
+            }
+          >
+            触发 notification
+          </Button>
+        </div>
+      </div>
+    </App>
+  ),
+};
+
+export const RTL: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <App dir="rtl" className="rounded-md border p-6">
+      <div className="text-sm">
+        当前方向: <strong>rtl</strong> — 你会看到自然的右到左流向
+      </div>
+    </App>
+  ),
+};

package/src/components/app/app.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+import { Toaster, type ToasterProps } from '@/components/sonner/sonner';
+
+export interface AppProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 是否挂载 `<Toaster />`(antd `App` 内部托管 message / notification 静态实例) — 全应用根挂一次。
+   * @default true
+   */
+  withToaster?: boolean;
+  /**
+   * 传递给 Toaster 的配置(位置 / 主题 / 自动关闭等) — 仅 `withToaster=true` 时生效。
+   */
+  toasterProps?: ToasterProps;
+  /**
+   * 文字方向 — 设到根容器的 `dir` 属性,Radix 等组件会自动适配。
+   * @default "ltr"
+   */
+  dir?: 'ltr' | 'rtl';
+}
+
+/**
+ * 应用根容器 — antd 独有补足。**对标 antd `App`** 的核心职责:
+ *   - **挂载全局 Toaster**(后续 toast / notification 静态调用的渲染层)
+ *   - **设置 dir / lang** 等顶层属性
+ *   - **承载根级 className**(让业务侧把 design tokens 挂到这一层即可)
+ *
+ * 与 antd 区别:
+ *   - 不接管主题(本库主题靠 design tokens / CSS vars,**不引入 runtime ConfigProvider**)
+ *   - 不收敛 `useApp()` hook 提供 message/notification(直接 import `toast` / `notification` 即可)
+ */
+const App = React.forwardRef<HTMLDivElement, AppProps>(
+  (
+    {
+      withToaster = true,
+      toasterProps,
+      dir = 'ltr',
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => (
+    <div
+      ref={ref}
+      dir={dir}
+      className={cn('min-h-screen bg-background text-foreground', className)}
+      {...props}
+    >
+      {children}
+      {withToaster ? <Toaster {...toasterProps} /> : null}
+    </div>
+  ),
+);
+App.displayName = 'App';
+
+export { App };

package/src/components/aspect-ratio/aspect-ratio.meta.md

@@ -0,0 +1,81 @@
+---
+id: aspect-ratio
+name: AspectRatio
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# AspectRatio
+
+容器保持宽高比 — 基于 `@radix-ui/react-aspect-ratio`,内部用 padding-bottom 技巧实现,**无 layout shift**。
+shadcn-only,antd 无对标。
+
+## When to use
+
+- 图片占位(`<img>` 加载完成前避免布局抖动)
+- 视频 / iframe 容器(YouTube 16:9、TikTok 9:16)
+- 卡片封面图固定比例
+
+## When NOT to use
+
+- 内容尺寸已知 → 直接 `width` + `height`
+- 比例随父容器变化 → 用 `aspect-*` Tailwind utility
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `ratio` | `number` | `1` | – | 宽高比 = 宽 / 高(必传)。常见值:`16 / 9` / `4 / 3` / `1` / `9 / 16`。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+_无 — 本组件不依赖其他 ui entry。_
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-aspect-ratio@^1.1.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 `<div>` 原生属性。`ratio: number` 是最关键的 prop(必传),如 `16 / 9` / `4 / 3` / `1`。
+
+## AI 生成纪律
+
+- **`ratio` 必传**:不传时默认 1,但显式声明语义更清晰
+- **子元素用绝对定位**:Radix 内部用 `position: relative`,子元素需 `absolute inset-0` 才能填满
+- **不要嵌套**:嵌套 AspectRatio 会让父级失效(都基于 padding-bottom)
+
+## Examples
+
+```tsx
+import { AspectRatio } from '@/components/ui/aspect-ratio';
+
+// 16:9 图片
+<AspectRatio ratio={16 / 9}>
+  <img src="/cover.jpg" alt="" className="size-full rounded-lg object-cover" />
+</AspectRatio>
+
+// 1:1 头像位
+<AspectRatio ratio={1} className="w-32">
+  <div className="size-full rounded-full bg-muted" />
+</AspectRatio>
+
+// YouTube 嵌入
+<AspectRatio ratio={16 / 9}>
+  <iframe src="https://www.youtube.com/embed/..." className="size-full rounded-lg" />
+</AspectRatio>
+```

package/src/components/aspect-ratio/aspect-ratio.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AspectRatio } from './aspect-ratio';
+
+const meta: Meta<typeof AspectRatio> = {
+  title: '基础原语 · Foundation/AspectRatio',
+  component: AspectRatio,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '宽高比容器 — 强制子元素按指定比例渲染，常用于图片 / 视频 / iframe 等响应式封面容器。基于 Radix AspectRatio，通过 `ratio` prop 传入任意宽高比(如 16/9、4/3、1)。shadcn 专有，填补了 antd 未提供的纯布局能力。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    ratio: { control: 'number' },
+  },
+  args: { ratio: 16 / 9 },
+};
+
+export default meta;
+type Story = StoryObj<typeof AspectRatio>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <div className="w-80">
+      <AspectRatio {...args} className="rounded-lg bg-muted">
+        <div className="flex size-full items-center justify-center text-sm text-muted-foreground">
+          {args.ratio?.toFixed(2)} ratio
+        </div>
+      </AspectRatio>
+    </div>
+  ),
+};
+
+export const Common: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="grid grid-cols-3 gap-4">
+      {[
+        { label: '16:9', ratio: 16 / 9 },
+        { label: '4:3', ratio: 4 / 3 },
+        { label: '1:1', ratio: 1 },
+        { label: '3:4', ratio: 3 / 4 },
+        { label: '9:16', ratio: 9 / 16 },
+        { label: '21:9', ratio: 21 / 9 },
+      ].map((c) => (
+        <div key={c.label} className="w-40">
+          <AspectRatio ratio={c.ratio} className="rounded-md bg-muted">
+            <div className="flex size-full items-center justify-center text-sm text-muted-foreground">
+              {c.label}
+            </div>
+          </AspectRatio>
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/components/aspect-ratio/aspect-ratio.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import * as AspectRatioPrimitive from '@radix-ui/react-aspect-ratio';
+
+export interface AspectRatioProps
+  extends React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root> {
+  /**
+   * 宽高比 = 宽 / 高(必传)。常见值:`16 / 9` / `4 / 3` / `1` / `9 / 16`。
+   * @default 1
+   */
+  ratio?: number;
+}
+
+/**
+ * 容器保持指定宽高比(`ratio = width / height`)。基于 `@radix-ui/react-aspect-ratio`,
+ * 内部用 padding-bottom 技巧实现,无 layout shift。常见用于图片 / 视频 / iframe 等
+ * 内容尺寸不可控的占位场景。
+ *
+ * antd 无对标组件 — shadcn-only。
+ */
+const AspectRatio = AspectRatioPrimitive.Root;
+
+export { AspectRatio };

package/src/components/auto-complete/auto-complete.meta.md

@@ -0,0 +1,102 @@
+---
+id: auto-complete
+name: AutoComplete
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# AutoComplete
+
+输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。键入触发候选下拉,可选可改;**最终 value 可以是任意字符串**(不强制为选项之一),与 `Combobox`(必选)互补。配 `onSearch` 实现异步建议。
+
+## When to use
+
+- 输入框需要"历史 / 推荐 / 自动补全"建议(搜索框、地址、邮箱补全)
+- 候选可能很多 / 需要异步拉取
+- 允许用户输入选项以外的自定义值
+
+## When NOT to use
+
+- 必选下拉(value 必须是某选项) → `Combobox` / `Select`
+- 多选 → `Select multiple`
+- @提及输入 → `Mentions`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `AutoCompleteOption[]` | – | ✓ | 候选项(antd `options` 并集) — 通常由 onSearch 回调刷新。 |
+| `value` | `string` | – | – | 受控值。 |
+| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
+| `onChange` | `(value: string) => void` | – | – | 值变化回调 — 用户键入 / 选中候选时触发。 |
+| `onSearch` | `(query: string) => void` | – | – | 用户输入时回调,用于刷新 `options`(异步建议)。 |
+| `onSelect` | `(value: string, option: AutoCompleteOption) => void` | – | – | 选中候选时回调。 |
+| `openOnFocus` | `boolean` | `false` | – | 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。 |
+| `emptyText` | `string` | `"无匹配项"` | – | 无匹配时的提示文本。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 容器尺寸 — 透传 Input.size。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add auto-complete` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `input` | component | 文本输入 — shadcn 简洁基底 + antd prefix/suffix/clearable/showCount/addonBefore/addonAfter/size |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`value` 是自由文本** — onChange / onSelect 都可能产生,业务侧拿到任意 string,**不要**假设它是 options 之一
+- **`onSearch` 异步刷新**:用户键入时触发,业务侧用最新 query 拉接口刷新 `options`;**不要**在组件内做 debounce(由业务侧自行 throttle 接口)
+- **`openOnFocus=true`** 适合"历史搜索词"场景 — 默认 false,避免空状态弹出令人困惑
+- **键盘 ↑↓ + Enter 已实现** — 不要再监听 keydown 加自定义选择
+- **`emptyText`** 写"业务态"文案(如"没有匹配的城市"),不要用默认的英文 / 通用占位
+- **不要嵌套 AutoComplete** — 它本身就是组合控件,二次嵌套语义混乱
+
+## Examples
+
+```tsx
+import { AutoComplete } from '@/components/ui/auto-complete';
+import * as React from 'react';
+
+// 基础(静态候选)
+<AutoComplete
+  options={[
+    { value: 'react' },
+    { value: 'vue' },
+    { value: 'angular' },
+  ]}
+  placeholder="输入框架名..."
+/>
+
+// 异步建议
+const [opts, setOpts] = React.useState([]);
+<AutoComplete
+  options={opts}
+  onSearch={async (q) => {
+    const list = await searchCities(q);
+    setOpts(list.map((c) => ({ value: c.name })));
+  }}
+  placeholder="搜索城市..."
+/>
+
+// 邮箱补全
+<AutoComplete
+  options={
+    /\S+@\S*$/.test(query)
+      ? []
+      : ['@gmail.com', '@outlook.com', '@qq.com'].map((d) => ({ value: query + d }))
+  }
+/>
+
+// 聚焦显示历史
+<AutoComplete openOnFocus options={historyOptions} />
+```