@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/combobox/meta.md

@@ -0,0 +1,83 @@
+# ComboboxTrigger
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+组合选择器 Combobox
+可搜索的下拉选择器，支持单选与多选。多选模式下触发区以可关闭的 Tag 组展示
+选中项，超出 `maxTagCount` 自动折叠为 `+N` 摘要。
+
+## 使用场景
+
+- 选项数量较多需要边输入边过滤时
+- 需要多选并以可关闭标签形式展示已选时
+- Select 无法满足搜索 / 多选 / 远程数据等场景时
+- 组合结构：Combobox > ComboboxTrigger ( ComboboxValue ) + ComboboxContent > ComboboxInput? + ComboboxList > ( ComboboxEmpty | ComboboxGroup > ComboboxItem | ComboboxSeparator )
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'default' \| 'lg'` | – | – | 触发器尺寸，对齐 SelectTrigger 三档：sm 28px / default 32px / lg 36px。 |
+| `onClear` | `() => void` | – | – | 清除回调：传入后右侧 chevron 切换为 × 按钮，点击调用此回调清空选中。 受控模式下由调用方传入 `() => setValue([])`；不传则不展示清除按钮。 |
+| `placeholder` | `React.ReactNode` | – | – | 未选时占位文案。 |
+| `shouldFilter` | `boolean` | `true` | – | 是否启用 cmdk 内置过滤逻辑；关闭后由外部接管搜索结果。 |
+| `filter` | `(value: string, search: string, keywords?: string[]) => number` | – | – | 自定义匹配评分函数：返回 0 表示不匹配，>0 越大越靠前。 |
+| `loop` | `boolean` | `false` | – | 到达列表末尾时是否循环回到起点。 |
+| `label` | `string` | – | – | 命令面板的可访问性标签。 |
+| `value` | `string` | – | ✓ | 选项值，必填，用于受控状态匹配。 |
+| `disabled` | `boolean` | – | – | 是否禁用。 |
+| `keywords` | `string[]` | – | – | cmdk 搜索关键字（除 children 文本外补充匹配项）。 |
+
+## 示例
+
+### Disabled
+
+禁用态。
+
+```tsx
+<Combobox multiple disabled defaultValue={['bj', 'hz']}>
+  <ComboboxTrigger className="w-72">
+    <ComboboxValue placeholder="禁用状态" />
+  </ComboboxTrigger>
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxGroup>
+        {cityOptions.map((o) => (
+          <ComboboxItem key={o.value} value={o.value}>
+            {o.label}
+          </ComboboxItem>
+        ))}
+      </ComboboxGroup>
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+### Sizes
+
+三档尺寸。
+
+```tsx
+<div className="flex flex-col gap-3">
+  {(['sm', 'default', 'lg'] as const).map((s) => (
+    <Combobox key={s} multiple defaultValue={['bj', 'hz']}>
+      <ComboboxTrigger size={s} className="w-72">
+        <ComboboxValue placeholder={`size=${s}`} />
+      </ComboboxTrigger>
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxGroup>
+            {cityOptions.map((o) => (
+              <ComboboxItem key={o.value} value={o.value}>
+                {o.label}
+              </ComboboxItem>
+            ))}
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  ))}
+</div>
+```

package/src/components/combobox/stories.tsx

@@ -0,0 +1,179 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxTrigger,
+  ComboboxValue,
+} from './index';
+
+const meta: Meta<typeof Combobox> = {
+  title: '数据录入 · Data Entry/Combobox 组合选择器',
+  component: Combobox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      source: { type: 'dynamic' },
+      description: {
+        component:
+          '可搜索的下拉选择器，支持单选与多选；多选触发区以可关闭 Tag 组展示选中项。',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+const cityOptions = [
+  { value: 'bj', label: '北京' },
+  { value: 'sh', label: '上海' },
+  { value: 'hz', label: '杭州' },
+  { value: 'sz', label: '深圳' },
+  { value: 'cd', label: '成都' },
+  { value: 'gz', label: '广州' },
+];
+
+/** 单选基线：等价于 Select，但带搜索能力。 */
+export const Default: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<string>('');
+    return (
+      <Combobox value={value} onValueChange={setValue}>
+        <ComboboxTrigger
+          className="w-60"
+          onClear={value ? () => setValue('') : undefined}
+        >
+          <ComboboxValue placeholder="请选择城市" />
+        </ComboboxTrigger>
+        <ComboboxContent>
+          <ComboboxList>
+            <ComboboxEmpty>无匹配结果</ComboboxEmpty>
+            <ComboboxGroup>
+              {cityOptions.map((o) => (
+                <ComboboxItem key={o.value} value={o.value}>
+                  {o.label}
+                </ComboboxItem>
+              ))}
+            </ComboboxGroup>
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    );
+  },
+};
+
+/** 多选：选中项以可关闭 Tag 形式展示在触发区。 */
+export const Multiple: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<string[]>(['bj', 'hz']);
+    return (
+      <Combobox multiple value={value} onValueChange={setValue}>
+        <ComboboxTrigger
+          className="w-72"
+          onClear={value.length ? () => setValue([]) : undefined}
+        >
+          <ComboboxValue placeholder="选择多个城市" />
+        </ComboboxTrigger>
+        <ComboboxContent>
+          <ComboboxList>
+            <ComboboxEmpty>无匹配结果</ComboboxEmpty>
+            <ComboboxGroup>
+              {cityOptions.map((o) => (
+                <ComboboxItem key={o.value} value={o.value}>
+                  {o.label}
+                </ComboboxItem>
+              ))}
+            </ComboboxGroup>
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    );
+  },
+};
+
+/** maxTagCount 折叠：超出阈值的选中项以 +N 摘要展示。 */
+export const WithMaxTagCount: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<string[]>([
+      'bj',
+      'sh',
+      'hz',
+      'sz',
+    ]);
+    return (
+      <Combobox multiple maxTagCount={2} value={value} onValueChange={setValue}>
+        <ComboboxTrigger
+          className="w-72"
+          onClear={value.length ? () => setValue([]) : undefined}
+        >
+          <ComboboxValue placeholder="最多展示 2 个 Tag，其余折叠 +N" />
+        </ComboboxTrigger>
+        <ComboboxContent>
+          <ComboboxList>
+            <ComboboxGroup>
+              {cityOptions.map((o) => (
+                <ComboboxItem key={o.value} value={o.value}>
+                  {o.label}
+                </ComboboxItem>
+              ))}
+            </ComboboxGroup>
+          </ComboboxList>
+        </ComboboxContent>
+      </Combobox>
+    );
+  },
+};
+
+/** 禁用态。 */
+export const Disabled: Story = {
+  render: () => (
+    <Combobox multiple disabled defaultValue={['bj', 'hz']}>
+      <ComboboxTrigger className="w-72">
+        <ComboboxValue placeholder="禁用状态" />
+      </ComboboxTrigger>
+      <ComboboxContent>
+        <ComboboxList>
+          <ComboboxGroup>
+            {cityOptions.map((o) => (
+              <ComboboxItem key={o.value} value={o.value}>
+                {o.label}
+              </ComboboxItem>
+            ))}
+          </ComboboxGroup>
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  ),
+};
+
+/** 三档尺寸。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {(['sm', 'default', 'lg'] as const).map((s) => (
+        <Combobox key={s} multiple defaultValue={['bj', 'hz']}>
+          <ComboboxTrigger size={s} className="w-72">
+            <ComboboxValue placeholder={`size=${s}`} />
+          </ComboboxTrigger>
+          <ComboboxContent>
+            <ComboboxList>
+              <ComboboxGroup>
+                {cityOptions.map((o) => (
+                  <ComboboxItem key={o.value} value={o.value}>
+                    {o.label}
+                  </ComboboxItem>
+                ))}
+              </ComboboxGroup>
+            </ComboboxList>
+          </ComboboxContent>
+        </Combobox>
+      ))}
+    </div>
+  ),
+};

package/src/components/command/index.tsx

@@ -0,0 +1,238 @@
+/**
+ * 命令面板 Command
+ *
+ * 可搜索的命令面板，支持分组、快捷键和空状态，基于 cmdk。
+ *
+ * @when
+ * - 全局命令面板（Cmd+K）
+ * - 搜索下拉列表
+ * - 操作快捷入口
+ */
+import * as React from 'react';
+import { Command as CommandPrimitive } from 'cmdk';
+
+import { cn } from '@/lib/utils';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/dialog';
+import { InputGroup, InputGroupAddon } from '@/components/input-group';
+import { SearchIcon, CheckIcon } from 'lucide-react';
+
+export interface CommandProps
+  extends Omit<
+    React.ComponentProps<typeof CommandPrimitive>,
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+    | 'shouldFilter'
+    | 'filter'
+    | 'loop'
+    | 'label'
+    | 'disablePointerSelection'
+    | 'vimBindings'
+  > {
+  /** 受控当前选中项 value（与 CommandItem 的 value 对应）。 */
+  value?: string;
+  /** 非受控初始选中项 value。 */
+  defaultValue?: string;
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项 value
+   */
+  onValueChange?: (value: string) => void;
+  /** 是否启用内置过滤逻辑；关闭后由外部接管搜索结果。 @default true */
+  shouldFilter?: boolean;
+  /**
+   * 自定义匹配评分函数：返回 0 表示不匹配，>0 越大越靠前。
+   * @param value CommandItem 的 value
+   * @param search 当前搜索关键字
+   * @param keywords CommandItem 的额外关键字
+   */
+  filter?: (value: string, search: string, keywords?: string[]) => number;
+  /** 到达列表末尾时是否循环回到起点。 @default false */
+  loop?: boolean;
+  /** 命令面板的可访问性标签（aria-label）。 */
+  label?: string;
+  /** 关闭键盘上下键移动时鼠标 hover 项也跟随选中的行为。 @default false */
+  disablePointerSelection?: boolean;
+  /** 是否启用 vim 风格快捷键（Ctrl+N / Ctrl+P 等）。 @default false */
+  vimBindings?: boolean;
+}
+
+function Command({ className, ...props }: CommandProps) {
+  return (
+    <CommandPrimitive
+      data-slot="command"
+      className={cn(
+        'flex size-full flex-col overflow-hidden rounded-md! bg-popover p-1 text-popover-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandDialog({
+  title = 'Command Palette',
+  description = 'Search for a command to run...',
+  children,
+  className,
+  showCloseButton = false,
+  ...props
+}: React.ComponentProps<typeof Dialog> & {
+  title?: string;
+  description?: string;
+  className?: string;
+  showCloseButton?: boolean;
+}) {
+  return (
+    <Dialog {...props}>
+      <DialogContent
+        className={cn(
+          'top-1/3 translate-y-0 overflow-hidden rounded-md! p-0',
+          className,
+        )}
+        showCloseButton={showCloseButton}
+      >
+        <DialogHeader className="sr-only">
+          <DialogTitle>{title}</DialogTitle>
+          <DialogDescription>{description}</DialogDescription>
+        </DialogHeader>
+        {children}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function CommandInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+  return (
+    <div data-slot="command-input-wrapper" className="p-1 pb-0">
+      <InputGroup className="h-8! rounded-md! border-input/30 bg-input/30 shadow-none! *:data-[slot=input-group-addon]:pl-2!">
+        <CommandPrimitive.Input
+          data-slot="command-input"
+          className={cn(
+            'w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50',
+            className,
+          )}
+          {...props}
+        />
+        <InputGroupAddon>
+          <SearchIcon className="size-4 shrink-0 opacity-50" />
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  );
+}
+
+function CommandList({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.List>) {
+  return (
+    <CommandPrimitive.List
+      data-slot="command-list"
+      className={cn(
+        'no-scrollbar max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto outline-none',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandEmpty({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+  return (
+    <CommandPrimitive.Empty
+      data-slot="command-empty"
+      className={cn('py-6 text-center text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+function CommandGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+  return (
+    <CommandPrimitive.Group
+      data-slot="command-group"
+      className={cn(
+        'overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group-heading]]:text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+  return (
+    <CommandPrimitive.Separator
+      data-slot="command-separator"
+      className={cn('-mx-1 h-px bg-border', className)}
+      {...props}
+    />
+  );
+}
+
+function CommandItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+  return (
+    <CommandPrimitive.Item
+      data-slot="command-item"
+      className={cn(
+        "group/command-item relative flex h-8 cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-muted data-[selected=true]:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[selected=true]:*:[svg]:text-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <CheckIcon className="ml-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" />
+    </CommandPrimitive.Item>
+  );
+}
+
+function CommandShortcut({
+  className,
+  ...props
+}: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="command-shortcut"
+      className={cn(
+        'ml-auto text-xs tracking-widest text-muted-foreground group-data-[selected=true]/command-item:text-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+};

package/src/components/command/meta.md

@@ -0,0 +1,48 @@
+# Command
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+命令面板 Command
+可搜索的命令面板，支持分组、快捷键和空状态，基于 cmdk。
+
+## 使用场景
+
+- 全局命令面板（Cmd+K）
+- 搜索下拉列表
+- 操作快捷入口
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控当前选中项 value（与 CommandItem 的 value 对应）。 |
+| `defaultValue` | `string` | – | – | 非受控初始选中项 value。 |
+| `onValueChange` | `(value: string) => void` | – | – | 选中项变化回调。 |
+| `shouldFilter` | `boolean` | `true` | – | 是否启用内置过滤逻辑；关闭后由外部接管搜索结果。 |
+| `filter` | `(value: string, search: string, keywords?: string[]) => number` | – | – | 自定义匹配评分函数：返回 0 表示不匹配，>0 越大越靠前。 |
+| `loop` | `boolean` | `false` | – | 到达列表末尾时是否循环回到起点。 |
+| `label` | `string` | – | – | 命令面板的可访问性标签（aria-label）。 |
+| `disablePointerSelection` | `boolean` | `false` | – | 关闭键盘上下键移动时鼠标 hover 项也跟随选中的行为。 |
+| `vimBindings` | `boolean` | `false` | – | 是否启用 vim 风格快捷键（Ctrl+N / Ctrl+P 等）。 |
+
+## 示例
+
+### WithDisabled
+
+带禁用项
+
+```tsx
+<Command className="rounded-lg border border-border shadow-md">
+  <CommandInput placeholder="搜索..." />
+  <CommandList>
+    <CommandEmpty>未找到结果</CommandEmpty>
+    <CommandGroup heading="操作">
+      <CommandItem>新建文档</CommandItem>
+      <CommandItem>打开文件</CommandItem>
+      <CommandItem disabled>删除项目（无权限）</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```

package/src/components/command/stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+  CommandShortcut,
+} from './index';
+import {
+  CalendarIcon,
+  SettingsIcon,
+  UserIcon,
+  SmileIcon,
+  CalculatorIcon,
+} from 'lucide-react';
+
+const meta: Meta<typeof Command> = {
+  title: '数据录入 · Data Entry/Command 命令面板',
+  component: Command,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Command>;
+
+/** 基础命令面板 */
+export const Default: Story = {
+  render: () => (
+    <Command className="rounded-lg border border-border shadow-md">
+      <CommandInput placeholder="搜索命令..." />
+      <CommandList>
+        <CommandEmpty>未找到结果</CommandEmpty>
+        <CommandGroup heading="建议">
+          <CommandItem>
+            <CalendarIcon />
+            日历
+          </CommandItem>
+          <CommandItem>
+            <SmileIcon />
+            表情
+          </CommandItem>
+          <CommandItem>
+            <CalculatorIcon />
+            计算器
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="设置">
+          <CommandItem>
+            <UserIcon />
+            个人信息
+            <CommandShortcut>⌘P</CommandShortcut>
+          </CommandItem>
+          <CommandItem>
+            <SettingsIcon />
+            偏好设置
+            <CommandShortcut>⌘,</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  ),
+};
+
+/** 带禁用项 */
+export const WithDisabled: Story = {
+  render: () => (
+    <Command className="rounded-lg border border-border shadow-md">
+      <CommandInput placeholder="搜索..." />
+      <CommandList>
+        <CommandEmpty>未找到结果</CommandEmpty>
+        <CommandGroup heading="操作">
+          <CommandItem>新建文档</CommandItem>
+          <CommandItem>打开文件</CommandItem>
+          <CommandItem disabled>删除项目（无权限）</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  ),
+};