@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/scroll-area/stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ScrollArea, ScrollBar } from './index';
+import { Separator } from '@/components/separator';
+
+const meta: Meta<typeof ScrollArea> = {
+  title: '布局 · Layout/ScrollArea 滚动区域',
+  component: ScrollArea,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const tags = Array.from({ length: 50 }, (_, i) => `v1.${i}.0`);
+
+/** 垂直滚动区域，限定高度后内容超出时出现滚动条。 */
+export const Vertical: Story = {
+  render: () => (
+    <ScrollArea className="h-72 w-48 rounded-md border border-border">
+      <div className="p-4">
+        <h4 className="mb-3 text-xs font-medium">版本列表</h4>
+        {tags.map((tag) => (
+          <div key={tag}>
+            <div className="py-1.5 text-xs">{tag}</div>
+            <Separator />
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+const artworks = [
+  { title: '落日余晖', artist: '张三' },
+  { title: '山水清音', artist: '李四' },
+  { title: '春江花月', artist: '王五' },
+  { title: '秋日私语', artist: '赵六' },
+  { title: '晨光初照', artist: '孙七' },
+  { title: '暮色苍茫', artist: '周八' },
+  { title: '雪后初晴', artist: '吴九' },
+];
+
+/** 水平滚动区域，通过设置内容宽度和 `orientation="horizontal"` 实现。 */
+export const HorizontalScroll: Story = {
+  render: () => (
+    <ScrollArea className="w-96 whitespace-nowrap rounded-md border border-border">
+      <div className="flex gap-4 p-4">
+        {artworks.map((art) => (
+          <figure key={art.title} className="shrink-0">
+            <div className="h-24 w-36 overflow-hidden rounded-md bg-muted" />
+            <figcaption className="pt-2 text-xs">
+              <span className="font-medium">{art.title}</span>
+              <span className="ml-2 text-muted-foreground">{art.artist}</span>
+            </figcaption>
+          </figure>
+        ))}
+      </div>
+      <ScrollBar orientation="horizontal" />
+    </ScrollArea>
+  ),
+};
+
+/** 同时支持垂直和水平双向滚动的区域。 */
+export const BothDirections: Story = {
+  render: () => (
+    <ScrollArea className="h-48 w-64 rounded-md border border-border">
+      <div className="w-96 p-4">
+        <p className="text-xs text-muted-foreground">
+          这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+          垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+          这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+          垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+        </p>
+        <p className="mt-4 text-xs text-muted-foreground">
+          这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+          垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+        </p>
+      </div>
+      <ScrollBar orientation="horizontal" />
+    </ScrollArea>
+  ),
+};

package/src/components/select/index.tsx

@@ -0,0 +1,325 @@
+/**
+ * 选择器 Select
+ *
+ * 在下拉菜单中选择一个选项，适用于选项较多时代替 RadioGroup。
+ *
+ * @when
+ * - 选项数量较多（>5 个）不宜平铺展示时
+ * - 需要分组展示选项时
+ * - 页面空间有限，需折叠展示选项时
+ *
+ * 组合结构：Select > SelectTrigger ( SelectPrefix? + SelectValue + SelectSuffix? ) + SelectContent > ( SelectGroup > SelectLabel + ) SelectItem
+ */
+
+import * as React from 'react';
+import { Select as SelectPrimitive } from 'radix-ui';
+import { ChevronDownIcon, CheckIcon, ChevronUpIcon, XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Spinner } from '@/components/spinner';
+
+interface SelectProps
+  extends Omit<
+    React.ComponentProps<typeof SelectPrimitive.Root>,
+    | 'open'
+    | 'defaultOpen'
+    | 'onOpenChange'
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+    | 'disabled'
+    | 'required'
+    | 'name'
+    | 'dir'
+  > {
+  /** 受控下拉面板是否打开。 */
+  open?: boolean;
+  /** 非受控初始下拉面板是否打开。 @default false */
+  defaultOpen?: boolean;
+  /**
+   * 下拉面板状态变化回调。
+   * @param open 当前是否打开
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** 受控选中项的 value。 */
+  value?: string;
+  /** 非受控初始选中项的 value。 */
+  defaultValue?: string;
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项的 value
+   */
+  onValueChange?: (value: string) => void;
+  /** 禁用。 @default false */
+  disabled?: boolean;
+  /** 是否为表单必填项。 @default false */
+  required?: boolean;
+  /** 表单提交时的字段名。 */
+  name?: string;
+  /** 文字方向。 */
+  dir?: 'ltr' | 'rtl';
+}
+
+function Select({ ...props }: SelectProps) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />;
+}
+
+function SelectGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn('scroll-my-1 p-1', className)}
+      {...props}
+    />
+  );
+}
+
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+}
+
+interface SelectTriggerProps
+  extends React.ComponentProps<typeof SelectPrimitive.Trigger> {
+  /** 触发器尺寸：sm 28px / default 32px / lg 36px，对齐 Button、Input 三档规范 */
+  size?: 'sm' | 'default' | 'lg';
+  /** 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"` 供外部样式穿透 */
+  loading?: boolean;
+  /**
+   * 清除回调：传入后右侧 chevron 切换为 × 按钮，点击调用此回调清空 value（受控）。
+   * 通常以 `onClear={value ? () => setValue('') : undefined}` 实现"已选时显示 ×、未选时显示 chevron"的互斥行为。
+   * 优先级：loading > onClear > chevron。
+   */
+  onClear?: () => void;
+}
+
+function SelectTrigger({
+  className,
+  size = 'default',
+  loading = false,
+  onClear,
+  children,
+  ...props
+}: SelectTriggerProps) {
+  const showClear = !loading && typeof onClear === 'function';
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      data-loading={loading ? 'true' : undefined}
+      className={cn(
+        "flex w-fit cursor-pointer items-center justify-between gap-1.5 rounded-md border border-input bg-transparent py-2 pr-2 pl-2.5 text-xs whitespace-nowrap transition-colors outline-none select-none focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=lg]:h-9 data-[size=lg]:text-sm *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {showClear ? (
+        <span
+          role="button"
+          aria-label="清除"
+          tabIndex={-1}
+          data-slot="select-clear"
+          onPointerDown={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+          }}
+          onClick={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            onClear?.();
+          }}
+          className="inline-flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors hover:text-foreground"
+        >
+          <XIcon className="size-3.5" />
+        </span>
+      ) : (
+        <SelectPrimitive.Icon asChild>
+          {loading ? (
+            <Spinner size="md" tone="muted" className="pointer-events-none" />
+          ) : (
+            <ChevronDownIcon className="pointer-events-none size-4 text-muted-foreground" />
+          )}
+        </SelectPrimitive.Icon>
+      )}
+    </SelectPrimitive.Trigger>
+  );
+}
+
+/**
+ * 触发器内的前缀装饰：放置于 `SelectValue` 之前，用于展示固定标签（如 "size:"）。
+ */
+function SelectPrefix({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="select-prefix"
+      className={cn(
+        'inline-flex items-center gap-1.5 text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 触发器内的后缀装饰：放置于 `SelectValue` 之后、`SelectClear` 与 chevron 之前，用于展示单位/补充信息（如 "GB"）。
+ */
+function SelectSuffix({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="select-suffix"
+      className={cn(
+        'inline-flex items-center gap-1.5 text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function SelectContent({
+  className,
+  children,
+  position = 'popper',
+  align = 'start',
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        data-slot="select-content"
+        data-align-trigger={position === 'item-aligned'}
+        className={cn(
+          // 面板高度上限 `max-h-80`（20rem ≈ 10 个选项），避免选项多时面板过长；
+          // 配合 `overflow-y-auto` 使用浏览器原生滚动条，不再渲染 ScrollUp/Down 按钮。
+          'relative z-50 max-h-80 min-w-(--radix-select-trigger-width) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          position === 'popper' &&
+            'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
+          className,
+        )}
+        position={position}
+        align={align}
+        sideOffset={sideOffset}
+        {...props}
+      >
+        <SelectPrimitive.Viewport
+          data-position={position}
+          className={cn(
+            'data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)',
+            position === 'popper' && '',
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  );
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn('px-1.5 py-1 text-xs text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "relative flex h-8 w-full cursor-pointer items-center gap-1.5 rounded-md py-1 pr-2 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-[state=checked]:text-primary data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className,
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-4 items-center justify-center">
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="pointer-events-none text-primary" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  );
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn('pointer-events-none -mx-1 my-1 h-px bg-border', className)}
+      {...props}
+    />
+  );
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "z-10 flex cursor-pointer items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      <ChevronUpIcon />
+    </SelectPrimitive.ScrollUpButton>
+  );
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "z-10 flex cursor-pointer items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      <ChevronDownIcon />
+    </SelectPrimitive.ScrollDownButton>
+  );
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectPrefix,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectSuffix,
+  SelectTrigger,
+  SelectValue,
+};
+export type { SelectProps, SelectTriggerProps };

package/src/components/select/meta.md

@@ -0,0 +1,183 @@
+# Select
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+选择器 Select
+在下拉菜单中选择一个选项，适用于选项较多时代替 RadioGroup。
+
+## 使用场景
+
+- 选项数量较多（>5 个）不宜平铺展示时
+- 需要分组展示选项时
+- 页面空间有限，需折叠展示选项时
+- 组合结构：Select > SelectTrigger ( SelectPrefix? + SelectValue + SelectSuffix? ) + SelectContent > ( SelectGroup > SelectLabel + ) SelectItem
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控下拉面板是否打开。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始下拉面板是否打开。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 下拉面板状态变化回调。 |
+| `value` | `string` | – | – | 受控选中项的 value。 |
+| `defaultValue` | `string` | – | – | 非受控初始选中项的 value。 |
+| `onValueChange` | `(value: string) => void` | – | – | 选中项变化回调。 |
+| `disabled` | `boolean` | `false` | – | 禁用。 |
+| `required` | `boolean` | `false` | – | 是否为表单必填项。 |
+| `name` | `string` | – | – | 表单提交时的字段名。 |
+| `dir` | `'ltr' \| 'rtl'` | – | – | 文字方向。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | – | – | 触发器尺寸：sm 28px / default 32px / lg 36px，对齐 Button、Input 三档规范 |
+| `loading` | `boolean` | – | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"` 供外部样式穿透 |
+| `onClear` | `() => void` | – | – | 清除回调：传入后右侧 chevron 切换为 × 按钮，点击调用此回调清空 value（受控）。 通常以 `onClear={value ? () => setValue('') : undefined}` 实现"已选时显示 ×、未选时显示 chevron"的互斥行为。 优先级：loading > onClear > chevron。 |
+
+## 示例
+
+### WithGroups
+
+带分组的选择器。
+
+```tsx
+<Select>
+  <SelectTrigger className="w-48">
+    <SelectValue placeholder="选择一个时区" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>亚太地区</SelectLabel>
+      <SelectItem value="cst">中国标准时间 (CST)</SelectItem>
+      <SelectItem value="jst">日本标准时间 (JST)</SelectItem>
+      <SelectItem value="kst">韩国标准时间 (KST)</SelectItem>
+    </SelectGroup>
+    <SelectGroup>
+      <SelectLabel>欧洲</SelectLabel>
+      <SelectItem value="gmt">格林威治时间 (GMT)</SelectItem>
+      <SelectItem value="cet">中欧时间 (CET)</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+### DisabledItems
+
+禁用某些选项。
+
+```tsx
+<Select>
+  <SelectTrigger className="w-48">
+    <SelectValue placeholder="选择方案" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="free">免费版</SelectItem>
+    <SelectItem value="pro">专业版</SelectItem>
+    <SelectItem value="enterprise" disabled>
+      企业版（即将推出）
+    </SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Small
+
+小尺寸选择器。
+
+```tsx
+<Select>
+  <SelectTrigger className="w-36" size="sm">
+    <SelectValue placeholder="选择" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="10">10 条/页</SelectItem>
+    <SelectItem value="20">20 条/页</SelectItem>
+    <SelectItem value="50">50 条/页</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Sizes
+
+三档尺寸：sm / default / lg，对齐 Button、Input 三档规范。
+
+```tsx
+<div className="flex items-center gap-3">
+  <Select>
+    <SelectTrigger className="w-32" size="sm">
+      <SelectValue placeholder="sm" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="a">选项 A</SelectItem>
+      <SelectItem value="b">选项 B</SelectItem>
+    </SelectContent>
+  </Select>
+  <Select>
+    <SelectTrigger className="w-36">
+      <SelectValue placeholder="default" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="a">选项 A</SelectItem>
+      <SelectItem value="b">选项 B</SelectItem>
+    </SelectContent>
+  </Select>
+  <Select>
+    <SelectTrigger className="w-40" size="lg">
+      <SelectValue placeholder="lg" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="a">选项 A</SelectItem>
+      <SelectItem value="b">选项 B</SelectItem>
+    </SelectContent>
+  </Select>
+</div>
+```
+
+### WithPrefixSuffix
+
+触发器内的前后缀装饰：用 `SelectPrefix` / `SelectSuffix` 组合显示固定标签与单位。
+
+```tsx
+<Select defaultValue="50">
+  <SelectTrigger className="w-56">
+    <SelectPrefix>大小</SelectPrefix>
+    <SelectValue />
+    <SelectSuffix>GB</SelectSuffix>
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="10">10</SelectItem>
+    <SelectItem value="50">50</SelectItem>
+    <SelectItem value="100">100</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Loading
+
+加载态：`<SelectTrigger loading>` 把 chevron 替换为旋转 spinner。
+
+```tsx
+<Select>
+  <SelectTrigger className="w-48" loading>
+    <SelectValue placeholder="正在加载选项..." />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">选项 A</SelectItem>
+    <SelectItem value="b">选项 B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Invalid
+
+错误态：通过 `aria-invalid` 触发 destructive 边框与 ring（与 shadcn 单一真相对齐）。
+
+```tsx
+<Select>
+  <SelectTrigger className="w-48" aria-invalid>
+    <SelectValue placeholder="必填项未选择" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">选项 A</SelectItem>
+    <SelectItem value="b">选项 B</SelectItem>
+  </SelectContent>
+</Select>
+```