@teamix-evo/ui 0.1.1

package/src/components/color-picker/color-picker.tsx

@@ -0,0 +1,160 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+import { Input } from '@/components/input/input';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/popover/popover';
+
+export interface ColorPickerProps {
+  /** 受控值 — `#RRGGBB` 或 `#RRGGBBAA`(开 `allowAlpha` 时)。 */
+  value?: string;
+  /** uncontrolled 初值。 @default "#000000" */
+  defaultValue?: string;
+  /** 值变化回调。 */
+  onChange?: (value: string) => void;
+  /**
+   * 是否允许透明度(antd `format=hex8` 类似行为) — 启用后展示 alpha 滑块,value 变为 8 位 hex。
+   * @default false
+   */
+  allowAlpha?: boolean;
+  /**
+   * 预设色块(antd `presets` 并集) — 一组常用颜色快捷选择。
+   */
+  presets?: string[];
+  /** 整体禁用。 */
+  disabled?: boolean;
+  /** 触发器尺寸。 @default "default" */
+  size?: 'sm' | 'default' | 'lg';
+  /** 触发器 className。 */
+  className?: string;
+}
+
+function clampHex(hex: string, allowAlpha: boolean): string {
+  const cleaned = hex.replace(/[^0-9a-fA-F#]/g, '');
+  const withHash = cleaned.startsWith('#') ? cleaned : `#${cleaned}`;
+  const expected = allowAlpha ? 9 : 7;
+  return withHash.slice(0, expected);
+}
+
+/**
+ * 颜色选择 — antd 独有补足。**等价 antd `ColorPicker`**(v5.5+)。基于原生
+ * `<input type="color">` + alpha range 输入 + hex 文本输入 + 预设色块,
+ * 提供"触发器(色块)→ 弹出面板"的标准交互。
+ */
+const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
+  (
+    {
+      value,
+      defaultValue = '#000000',
+      onChange,
+      allowAlpha = false,
+      presets,
+      disabled = false,
+      size = 'default',
+      className,
+    },
+    ref,
+  ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<string>(defaultValue);
+    const current = isControlled ? value! : internal;
+
+    const update = (next: string) => {
+      const v = clampHex(next, allowAlpha);
+      if (!isControlled) setInternal(v);
+      onChange?.(v);
+    };
+
+    const baseHex = current.slice(0, 7);
+    const alphaHex = allowAlpha && current.length >= 9 ? current.slice(7, 9) : 'ff';
+    const alphaInt = parseInt(alphaHex, 16);
+
+    const swatchSize = size === 'sm' ? 'size-7' : size === 'lg' ? 'size-11' : 'size-9';
+
+    return (
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            ref={ref}
+            type="button"
+            disabled={disabled}
+            className={cn(
+              'inline-flex items-center justify-center rounded-md border border-input bg-background shadow-sm transition-colors',
+              'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+              'disabled:cursor-not-allowed disabled:opacity-50',
+              swatchSize,
+              className,
+            )}
+            aria-label="选择颜色"
+            style={{ padding: 2 }}
+          >
+            <span
+              className="block size-full rounded-sm"
+              style={{ backgroundColor: current }}
+            />
+          </button>
+        </PopoverTrigger>
+        <PopoverContent className="w-64 p-3" align="start">
+          <div className="flex flex-col gap-3">
+            <input
+              type="color"
+              value={baseHex}
+              disabled={disabled}
+              onChange={(e) => update(allowAlpha ? `${e.target.value}${alphaHex}` : e.target.value)}
+              className="h-10 w-full cursor-pointer rounded-md border border-input bg-transparent"
+            />
+            {allowAlpha ? (
+              <div className="flex items-center gap-2">
+                <span className="w-12 text-xs text-muted-foreground">Alpha</span>
+                <input
+                  type="range"
+                  min={0}
+                  max={255}
+                  value={alphaInt}
+                  disabled={disabled}
+                  onChange={(e) => {
+                    const a = Number(e.target.value).toString(16).padStart(2, '0');
+                    update(`${baseHex}${a}`);
+                  }}
+                  className="flex-1"
+                />
+                <span className="w-10 text-right text-xs tabular-nums">
+                  {Math.round((alphaInt / 255) * 100)}%
+                </span>
+              </div>
+            ) : null}
+            <Input
+              value={current}
+              disabled={disabled}
+              onChange={(e) => update(e.target.value)}
+              placeholder={allowAlpha ? '#RRGGBBAA' : '#RRGGBB'}
+            />
+            {presets && presets.length > 0 ? (
+              <div className="flex flex-wrap gap-1.5">
+                {presets.map((p) => (
+                  <button
+                    key={p}
+                    type="button"
+                    aria-label={p}
+                    onClick={() => update(p)}
+                    className={cn(
+                      'size-6 rounded-sm border border-border ring-offset-background transition-all',
+                      'hover:scale-110 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                    )}
+                    style={{ backgroundColor: p }}
+                  />
+                ))}
+              </div>
+            ) : null}
+          </div>
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);
+ColorPicker.displayName = 'ColorPicker';
+
+export { ColorPicker };

package/src/components/combobox/combobox.meta.md

@@ -0,0 +1,93 @@
+---
+id: combobox
+name: Combobox
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Combobox
+
+可搜索单选下拉 — `Command + Popover` 复合,等价 antd `AutoComplete` / `Select showSearch` 的核心场景。
+**单选**(刻意不做多选,保持语义简单);多选请直接用 `Command` + 自管 selected 数组。
+
+## When to use
+
+- 选项较多需要搜索筛选(国家 / 时区 / 用户列表 / 标签)
+- 选项动态加载(异步 — 在父组件准备数据后传给 `options`)
+
+## When NOT to use
+
+- 选项 ≤ 7 个 → `Select`(无需搜索)
+- 多选 → `Command` 自定义,或 `CheckboxGroup`
+- 自由文本输入 → `Input` + 自定义 suggestion(超出本组件范围)
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `ComboboxOption[]` | – | ✓ | 选项列表(antd `AutoComplete.options` 并集)。 |
+| `value` | `string` | – | – | 受控 value(单选)。 |
+| `onChange` | `(value: string) => void` | – | – | value 变化回调。 |
+| `placeholder` | `string` | `"请选择..."` | – | 触发器占位文本(未选)。 |
+| `searchPlaceholder` | `string` | `"搜索..."` | – | 搜索框占位文本。 |
+| `emptyText` | `string` | `"无匹配项"` | – | 无匹配时的提示文本。 |
+| `className` | `string` | `"w-[200px]"` | – | 触发器宽度。 |
+| `disabled` | `boolean` | – | – | 是否禁用。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add combobox` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `command` | component | 命令面板 — cmdk(Linear / Raycast 风格),全局搜索 / 命令执行;Combobox 的底座 |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 选项类型 `ComboboxOption`:`{ value: string; label: ReactNode; disabled?: boolean }`。
+
+## AI 生成纪律
+
+- **`value` 稳定**:用业务 ID,不要用 index
+- **`label` 可富节点**:支持图标 + 文本,不止 string
+- **第二次点击当前 value 会清空**:`onChange('')` 触发,业务侧据此实现"取消选择"
+- **大量选项(>1000) → 自定义虚拟滚动**:本组件未集成 virtualizer
+- **异步加载选项**:父组件 fetch 后传 `options`,加 loading 占位符在 options 列表外
+
+## Examples
+
+```tsx
+import { Combobox, type ComboboxOption } from '@/components/ui/combobox';
+import * as React from 'react';
+
+const frameworks: ComboboxOption[] = [
+  { value: 'next', label: 'Next.js' },
+  { value: 'sveltekit', label: 'SvelteKit' },
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'remix', label: 'Remix' },
+  { value: 'astro', label: 'Astro' },
+];
+
+const [v, setV] = React.useState('');
+<Combobox
+  options={frameworks}
+  value={v}
+  onChange={setV}
+  placeholder="选择框架"
+  searchPlaceholder="搜索框架..."
+/>
+```

package/src/components/combobox/combobox.stories.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Combobox, type ComboboxOption } from './combobox';
+
+const meta: Meta<typeof Combobox> = {
+  title: '表单与输入 · Form/Combobox',
+  component: Combobox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '可搜索单选下拉 — Command + Popover 复合,对标 antd AutoComplete / Select showSearch。键盘可达、模糊搜索、空态、再次选中清空,适合选项数 > 7 的单选场景。OpenTrek tokens 适配。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Combobox>;
+
+const frameworks: ComboboxOption[] = [
+  { value: 'next', label: 'Next.js' },
+  { value: 'sveltekit', label: 'SvelteKit' },
+  { value: 'nuxt', label: 'Nuxt' },
+  { value: 'remix', label: 'Remix' },
+  { value: 'astro', label: 'Astro' },
+  { value: 'qwik', label: 'Qwik', disabled: true },
+];
+
+export const Default: Story = {
+  render: () => {
+    const [v, setV] = React.useState('');
+    return (
+      <Combobox
+        options={frameworks}
+        value={v}
+        onChange={setV}
+        placeholder="选择框架"
+        searchPlaceholder="搜索框架..."
+      />
+    );
+  },
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Combobox options={frameworks} placeholder="sm" size="sm" />
+      <Combobox options={frameworks} placeholder="default" />
+      <Combobox options={frameworks} placeholder="lg" size="lg" />
+    </div>
+  ),
+};

package/src/components/combobox/combobox.tsx

@@ -0,0 +1,130 @@
+import * as React from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/command/command';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/popover/popover';
+
+export interface ComboboxOption {
+  /** 选项值(受控 value 比对的依据,稳定 ID)。 */
+  value: string;
+  /** 显示文本。 */
+  label: React.ReactNode;
+  /** 禁用此选项。 */
+  disabled?: boolean;
+}
+
+export interface ComboboxProps {
+  /** 选项列表(antd `AutoComplete.options` 并集)。 */
+  options: ComboboxOption[];
+  /** 受控 value(单选)。 */
+  value?: string;
+  /** value 变化回调。 */
+  onChange?: (value: string) => void;
+  /** 触发器占位文本(未选)。 @default "请选择..." */
+  placeholder?: string;
+  /** 搜索框占位文本。 @default "搜索..." */
+  searchPlaceholder?: string;
+  /** 无匹配时的提示文本。 @default "无匹配项" */
+  emptyText?: string;
+  /** 触发器宽度。 @default "w-[200px]" */
+  className?: string;
+  /** 是否禁用。 */
+  disabled?: boolean;
+  /** 触发器尺寸。 @default "default" */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * 可搜索单选下拉 — Command + Popover 复合,等价 antd `AutoComplete` /
+ * `Select showSearch` 的核心场景。
+ *
+ * 多选场景请直接用 Command + 自管 selected 数组(本组件刻意不做多选,保持
+ * 单选语义清晰)。
+ */
+const Combobox = React.forwardRef<HTMLButtonElement, ComboboxProps>(
+  (
+    {
+      options,
+      value,
+      onChange,
+      placeholder = '请选择...',
+      searchPlaceholder = '搜索...',
+      emptyText = '无匹配项',
+      className,
+      disabled,
+      size = 'default',
+    },
+    ref,
+  ) => {
+    const [open, setOpen] = React.useState(false);
+    const selected = options.find((o) => o.value === value);
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant="outline"
+            size={size}
+            disabled={disabled}
+            role="combobox"
+            aria-expanded={open}
+            className={cn(
+              'w-[200px] justify-between font-normal',
+              !value && 'text-muted-foreground',
+              className,
+            )}
+          >
+            {selected ? selected.label : placeholder}
+            <ChevronsUpDown className="ml-2 size-4 shrink-0 opacity-50" />
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-[200px] p-0">
+          <Command>
+            <CommandInput placeholder={searchPlaceholder} />
+            <CommandList>
+              <CommandEmpty>{emptyText}</CommandEmpty>
+              <CommandGroup>
+                {options.map((opt) => (
+                  <CommandItem
+                    key={opt.value}
+                    value={opt.value}
+                    disabled={opt.disabled}
+                    onSelect={(v) => {
+                      onChange?.(v === value ? '' : v);
+                      setOpen(false);
+                    }}
+                  >
+                    <Check
+                      className={cn(
+                        'mr-2 size-4',
+                        opt.value === value ? 'opacity-100' : 'opacity-0',
+                      )}
+                    />
+                    {opt.label}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);
+Combobox.displayName = 'Combobox';
+
+export { Combobox };

package/src/components/command/command.meta.md

@@ -0,0 +1,104 @@
+---
+id: command
+name: Command
+type: component
+category: shell
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Command
+
+命令面板 — 基于 [`cmdk`](https://cmdk.paco.me/),提供"按 ⌘K 打开"的全局搜索 / 命令执行体验(Linear / Raycast / Vercel 风格)。
+**shadcn-only**(antd 无对标)。是 `Combobox` 的底座(Combobox = Command + Popover)。
+
+## When to use
+
+- 全局命令面板(⌘K 搜索 / 跳转 / 执行任务)
+- 复杂筛选 / 多条件搜索
+- 编辑器命令(quick action)
+- 配 `Popover` 做 Combobox(可搜索下拉)
+- 配 `CommandDialog` 做模态命令面板
+
+## When NOT to use
+
+- 简单单选下拉 → `Select`
+- 静态菜单 → `DropdownMenu`
+- 需要表单语义 → `Combobox`(基于本组件)
+
+<!-- auto:props:begin -->
+_(no props)_
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add command` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add cmdk@^1.0.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 子组件:`Command`(Root 容器)/ `CommandDialog`(模态版,内部组合 Dialog)/ `CommandInput`(自带搜索图标)/ `CommandList`(可滚动列表)/ `CommandEmpty`(无匹配空态)/ `CommandGroup`(分组,带 heading)/ `CommandItem`(选项,支持 `onSelect`)/ `CommandSeparator` / `CommandShortcut`(右对齐快捷键)。
+
+## AI 生成纪律
+
+- **`CommandList` 内必有 `CommandEmpty`**:无搜索结果时不渲染会让 UI 空白
+- **`CommandItem` 用 `onSelect` 不是 `onClick`**:cmdk 通过 keyboard 导航触发,需要 `onSelect`
+- **value 必稳定**:`<CommandItem value="...">` 用稳定 ID(决定搜索匹配)
+- **CommandDialog 全局监听 ⌘K**:业务侧加一个 `useEffect` 监听键盘事件 toggle open
+- **不嵌套 Command**:嵌套是反模式
+
+## Examples
+
+```tsx
+import {
+  Command, CommandInput, CommandList, CommandEmpty,
+  CommandGroup, CommandItem, CommandShortcut,
+} from '@/components/ui/command';
+import { Calendar, Mail, User } from 'lucide-react';
+
+// 内联
+<Command className="rounded-lg border">
+  <CommandInput placeholder="输入命令或搜索..." />
+  <CommandList>
+    <CommandEmpty>无结果。</CommandEmpty>
+    <CommandGroup heading="建议">
+      <CommandItem><Calendar /> 日历 <CommandShortcut>⌘K</CommandShortcut></CommandItem>
+      <CommandItem><Mail /> 邮件</CommandItem>
+    </CommandGroup>
+    <CommandGroup heading="设置">
+      <CommandItem><User /> 个人资料</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+
+// 模态(全局 ⌘K)
+import { CommandDialog } from '@/components/ui/command';
+const [open, setOpen] = React.useState(false);
+React.useEffect(() => {
+  const onKey = (e: KeyboardEvent) => {
+    if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      setOpen((o) => !o);
+    }
+  };
+  document.addEventListener('keydown', onKey);
+  return () => document.removeEventListener('keydown', onKey);
+}, []);
+
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput placeholder="..." />
+  <CommandList>...</CommandList>
+</CommandDialog>
+```

package/src/components/command/command.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Calendar, Mail, Settings, User } from 'lucide-react';
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+} from './command';
+
+const meta: Meta<typeof Command> = {
+  title: '应用壳 · Shell/Command',
+  component: Command,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '命令面板 — 全局搜索 / 命令执行(Linear / Raycast / Vercel 风格)。基于 cmdk,提供键盘导航、模糊搜索、分组、空态、快捷键提示;模态版用 CommandDialog 监听 ⌘K 全局触发。OpenTrek tokens 适配,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Command>;
+
+export const Inline: Story = {
+  render: () => (
+    <Command className="w-80 rounded-lg border">
+      <CommandInput placeholder="输入命令或搜索..." />
+      <CommandList>
+        <CommandEmpty>无结果。</CommandEmpty>
+        <CommandGroup heading="建议">
+          <CommandItem>
+            <Calendar /> 日历
+            <CommandShortcut>⌘K</CommandShortcut>
+          </CommandItem>
+          <CommandItem>
+            <Mail /> 邮件
+            <CommandShortcut>⌘E</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="设置">
+          <CommandItem>
+            <User /> 个人资料
+          </CommandItem>
+          <CommandItem>
+            <Settings /> 偏好设置
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  ),
+};