@teamix-evo/ui 0.3.0 → 0.5.0

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

@@ -1,82 +0,0 @@
----
-id: aspect-ratio
-name: AspectRatio
-displayName: 宽高比
-type: component
-category: deprecated
-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

@@ -1,59 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { AspectRatio } from './aspect-ratio';
-
-const meta: Meta<typeof AspectRatio> = {
-  title: '废弃 · Deprecated/AspectRatio',
-  component: AspectRatio,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n宽高比容器 — 强制子元素按指定比例渲染，常用于图片 / 视频 / iframe 等响应式封面容器。基于 Radix AspectRatio，通过 `ratio` prop 传入任意宽高比。shadcn 专有，填补了 antd 未提供的纯布局能力。',
-      },
-    },
-  },
-  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

@@ -1,22 +0,0 @@
-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

@@ -1,110 +0,0 @@
----
-id: auto-complete
-name: AutoComplete
-type: component
-category: data-entry
-since: 0.1.0
-package: '@teamix-evo/ui'
-displayName: 自动补全
----
-
-# AutoComplete 自动补全
-
-输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。键入触发候选下拉,可选可改;**最终 value 可以是任意字符串**(不强制为选项之一),与 `Combobox`(必选)互补。配 `onSearch` 实现异步建议。
-
-## When to use
-
-- 输入框需要"历史 / 推荐 / 自动补全"建议(搜索框、地址、邮箱补全)
-- 候选可能很多 / 需要异步拉取
-- 允许用户输入选项以外的自定义值
-
-## When NOT to use
-
-- 必选下拉(value 必须是某选项) → `Combobox` / `Select`
-- 多选 → `Select multiple`
-- @提及输入 → `Mentions`
-
-## Props
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `options` | `AutoCompleteOption[]` | – | ✓ | 候选项(antd `options` 并集) — 通常由 onSearch 回调刷新。 |
-| `value` | `string` | – | – | 受控值。 |
-| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
-| `onChange` | `(value: string) => void` | – | – | 值变化回调 — 用户键入 / 选中候选时触发。 |
-| `onSearch` | `(query: string) => void` | – | – | 用户输入时回调,用于刷新 `options`(异步建议)。 提供该回调后,内部不再对 `options` 做本地过滤(由外部按 query 自行刷新)。 |
-| `onSelect` | `(value: string, option: AutoCompleteOption) => void` | – | – | 选中候选时回调。 |
-| `openOnFocus` | `boolean` | `false` | – | 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。 |
-| `emptyText` | `string` | `"无匹配项"` | – | 无匹配时的提示文本。 |
-| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"md"` | – | 容器尺寸 — 透传 Input.size。 |
-| `error` | `boolean` | `false` | – | 错误态视觉(校验失败) — 透传给内部 Input,红色 border + ring,自动写 `aria-invalid="true"`。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add auto-complete` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `input` | component | 单行文本输入 — clearable / showCount / size(sm 24 / md 32 / lg 36,与 Button 同档)/ error 四档内建能力。前缀/后缀/addon 等复合形态已拆出独立 InputGroup;多行已拆出独立 Textarea |
-| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
-| `command` | component | 命令面板 / 下拉底座 — cmdk(Linear / Raycast 风格)提供过滤 / 键盘导航 / a11y;同时为 Combobox / Select / AutoComplete 提供同源下拉内核 |
-
-### 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} />
-```

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

@@ -1,136 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { AutoComplete } from './auto-complete';
-
-const meta: Meta<typeof AutoComplete> = {
-  title: '数据录入 · Data Entry/AutoComplete',
-  component: AutoComplete,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '自动补全 — 输入即建议，键入触发候选下拉，可选可改，最终 value 是自由文本（不强制为选项之一）。**Input 为底** + antd `AutoComplete` 的人机交互并集：`options` / `onSearch` / `onSelect` / `openOnFocus` / `size` / `error`，与 Combobox（必选）互补。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/tokens`，无 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 Sizes: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-3">
-      <AutoComplete
-        size="sm"
-        options={frameworks}
-        placeholder="sm"
-        className="w-64"
-      />
-      <AutoComplete
-        options={frameworks}
-        placeholder="default"
-        className="w-64"
-      />
-      <AutoComplete
-        size="lg"
-        options={frameworks}
-        placeholder="lg"
-        className="w-64"
-      />
-    </div>
-  ),
-};
-
-export const ErrorState: Story = {
-  name: 'Error 错误态',
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col gap-1">
-      <AutoComplete
-        options={frameworks}
-        placeholder="输入框架名(必填)"
-        error
-        className="w-64"
-      />
-      <span className="text-xs text-destructive">该字段为必填项</span>
-    </div>
-  ),
-};
-
-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

@@ -1,253 +0,0 @@
-import * as React from 'react';
-
-import {
-  Command,
-  CommandEmpty,
-  CommandGroup,
-  CommandItem,
-  CommandList,
-} from '@/components/command/command';
-import { Input } from '@/components/input/input';
-import {
-  Popover,
-  PopoverAnchor,
-  PopoverContent,
-} from '@/components/popover/popover';
-
-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`(异步建议)。
-   * 提供该回调后,内部不再对 `options` 做本地过滤(由外部按 query 自行刷新)。
-   */
-  onSearch?: (query: string) => void;
-  /**
-   * 选中候选时回调。
-   */
-  onSelect?: (value: string, option: AutoCompleteOption) => void;
-  /**
-   * 是否在输入框聚焦但 query 为空时显示完整 `options`(antd `defaultActiveFirstOption` 行为的近似)。
-   * @default false
-   */
-  openOnFocus?: boolean;
-  /**
-   * 无匹配时的提示文本。
-   * @default "无匹配项"
-   */
-  emptyText?: string;
-  /**
-   * 容器尺寸 — 透传 Input.size。
-   * @default "md"
-   */
-  size?: 'sm' | 'md' | 'default' | 'lg';
-  /**
-   * 错误态视觉(校验失败) — 透传给内部 Input,红色 border + ring,自动写 `aria-invalid="true"`。
-   * @default false
-   */
-  error?: boolean;
-}
-
-/**
- * 输入即建议 — antd 独有补足。**等价 antd `AutoComplete`**。
- *
- * 与 `Combobox` 区别:Combobox 是"必选下拉",输入框只接受选项中的值(closed-list);
- * AutoComplete 是"自由输入 + 选项建议",最终 value 可以是任意字符串(open-list)。
- *
- * 内核与 `Select` 同源 —— 基于 `Popover + cmdk Command`,共享下拉视觉、键盘导航与 a11y。
- */
-const AutoComplete = React.forwardRef<HTMLInputElement, AutoCompleteProps>(
-  (
-    {
-      options,
-      value,
-      defaultValue,
-      onChange,
-      onSearch,
-      onSelect,
-      openOnFocus = false,
-      emptyText = '无匹配项',
-      size = 'md',
-      error = false,
-      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 [activeValue, setActiveValue] = React.useState<string>('');
-
-    // 提供 onSearch 时,默认认为外部按 query 异步刷过 options;否则内部本地过滤
-    const filtered = React.useMemo(() => {
-      if (onSearch) return options;
-      const q = current.toLowerCase();
-      return q === ''
-        ? options
-        : options.filter((o) => o.value.toLowerCase().includes(q));
-    }, [current, options, onSearch]);
-
-    // filtered 变化时,默认高亮第一个可用项
-    React.useEffect(() => {
-      const first = filtered.find((o) => !o.disabled);
-      setActiveValue(first?.value ?? '');
-    }, [filtered]);
-
-    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 moveActive = (dir: 1 | -1) => {
-      const enabled = filtered.filter((o) => !o.disabled);
-      if (enabled.length === 0) return;
-      const idx = enabled.findIndex((o) => o.value === activeValue);
-      const nextIdx =
-        (idx === -1 ? 0 : idx + dir + enabled.length) % enabled.length;
-      const nextOpt = enabled[nextIdx];
-      if (nextOpt) setActiveValue(nextOpt.value);
-    };
-
-    const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
-      if (open) {
-        if (e.key === 'ArrowDown') {
-          e.preventDefault();
-          moveActive(1);
-          return;
-        }
-        if (e.key === 'ArrowUp') {
-          e.preventDefault();
-          moveActive(-1);
-          return;
-        }
-        if (e.key === 'Enter') {
-          const opt = filtered.find((o) => o.value === activeValue);
-          if (opt && !opt.disabled) {
-            e.preventDefault();
-            select(opt);
-            return;
-          }
-        }
-        if (e.key === 'Escape') {
-          e.preventDefault();
-          setOpen(false);
-          return;
-        }
-      } else if (e.key === 'ArrowDown' && filtered.length > 0) {
-        e.preventDefault();
-        setOpen(true);
-        return;
-      }
-      onKeyDown?.(e);
-    };
-
-    return (
-      <Popover open={open} onOpenChange={setOpen}>
-        <PopoverAnchor asChild>
-          <Input
-            ref={ref}
-            value={current}
-            placeholder={placeholder}
-            disabled={disabled}
-            size={size}
-            error={error}
-            className={className}
-            role="combobox"
-            aria-autocomplete="list"
-            aria-expanded={open}
-            onChange={(e) => {
-              const next = e.target.value;
-              update(next);
-              onSearch?.(next);
-              setOpen(true);
-            }}
-            onFocus={(e) => {
-              if (openOnFocus) setOpen(true);
-              onFocus?.(e);
-            }}
-            onBlur={(e) => {
-              window.setTimeout(() => setOpen(false), 120);
-              onBlur?.(e);
-            }}
-            onKeyDown={handleKeyDown}
-            {...props}
-          />
-        </PopoverAnchor>
-        <PopoverContent
-          align="start"
-          sideOffset={4}
-          onOpenAutoFocus={(e) => e.preventDefault()}
-          // 读 Radix 暴露的 CSS 变量让弹层宽度追平 Input 宽度;主动选 style 而非 Tailwind
-          // arbitrary value(`w-[var(--...)]`),避免 `teamix-evo/no-arbitrary-tw-value` lint 告警
-          style={{ width: 'var(--radix-popover-trigger-width)' }}
-          className="p-0"
-        >
-          <Command
-            shouldFilter={false}
-            value={activeValue}
-            onValueChange={setActiveValue}
-          >
-            <CommandList>
-              <CommandEmpty>{emptyText}</CommandEmpty>
-              {filtered.length > 0 && (
-                <CommandGroup>
-                  {filtered.map((opt) => (
-                    <CommandItem
-                      key={opt.value}
-                      value={opt.value}
-                      disabled={opt.disabled}
-                      onSelect={() => select(opt)}
-                      // 阻止鼠标按下时让 Input 失焦,避免选中前 popover 已关闭
-                      onMouseDown={(e) => e.preventDefault()}
-                    >
-                      {opt.label ?? opt.value}
-                    </CommandItem>
-                  ))}
-                </CommandGroup>
-              )}
-            </CommandList>
-          </Command>
-        </PopoverContent>
-      </Popover>
-    );
-  },
-);
-AutoComplete.displayName = 'AutoComplete';
-
-export { AutoComplete };