@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/carousel/stories.tsx

@@ -0,0 +1,271 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselDots,
+} from './index';
+import { Card, CardContent } from '@/components/card';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Carousel> = {
+  title: '数据展示 · Data Display/Carousel 轮播',
+  component: Carousel,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const slides = Array.from({ length: 5 }, (_, i) => i + 1);
+
+const slideTones = [
+  'bg-primary/10 text-primary',
+  'bg-secondary text-secondary-foreground',
+  'bg-accent text-accent-foreground',
+  'bg-muted text-foreground',
+  'bg-primary/20 text-primary',
+];
+
+const Slide = ({
+  index,
+  children,
+}: {
+  index: number;
+  children: React.ReactNode;
+}) => (
+  <Card className="overflow-hidden border-0 p-0">
+    <CardContent
+      className={`flex aspect-square items-center justify-center p-6 ${
+        slideTones[index % slideTones.length]
+      }`}
+    >
+      <span className="text-4xl font-semibold">{children}</span>
+    </CardContent>
+  </Card>
+);
+
+/** 给 outer 模式留出箭头空间的容器（默认箭头位于 -left-12 / -right-12）。 */
+const Outer = ({ children }: { children: React.ReactNode }) => (
+  <div className="px-12 py-2">{children}</div>
+);
+
+/** 基础单页轮播。 */
+export const Default: Story = {
+  render: () => (
+    <Outer>
+      <Carousel className="w-full max-w-xs">
+        <CarouselContent>
+          {slides.map((i) => (
+            <CarouselItem key={i}>
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </Outer>
+  ),
+};
+
+/** 多图同时展示，按页滚动。 */
+export const MultipleItems: Story = {
+  render: () => (
+    <Outer>
+      <Carousel
+        className="w-full max-w-md"
+        slidesToScroll={3}
+        opts={{ align: 'start' }}
+      >
+        <CarouselContent>
+          {Array.from({ length: 9 }, (_, i) => i + 1).map((i) => (
+            <CarouselItem key={i} className="basis-1/3">
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+      </Carousel>
+    </Outer>
+  ),
+};
+
+/** 无穷循环。 */
+export const Loop: Story = {
+  render: () => (
+    <Outer>
+      <Carousel className="w-full max-w-xs" loop>
+        <CarouselContent>
+          {slides.map((i) => (
+            <CarouselItem key={i}>
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </Outer>
+  ),
+};
+
+/** 自动播放，悬浮暂停。 */
+export const Autoplay: Story = {
+  render: () => (
+    <Outer>
+      <Carousel
+        className="w-full max-w-xs"
+        loop
+        autoplay={{ delay: 2000, stopOnMouseEnter: true }}
+      >
+        <CarouselContent>
+          {slides.map((i) => (
+            <CarouselItem key={i}>
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </Outer>
+  ),
+};
+
+/** 渐变切换动画（fade）。 */
+export const Fade: Story = {
+  render: () => (
+    <Outer>
+      <Carousel className="w-full max-w-xs" fade loop autoplay>
+        <CarouselContent>
+          {slides.map((i) => (
+            <CarouselItem key={i}>
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </Outer>
+  ),
+};
+
+/** 垂直方向。 */
+export const Vertical: Story = {
+  render: () => (
+    <div className="py-12">
+      <Carousel
+        orientation="vertical"
+        className="w-full max-w-xs"
+        opts={{ align: 'start' }}
+      >
+        <CarouselContent className="h-64">
+          {slides.map((i) => (
+            <CarouselItem key={i} className="basis-1/2">
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </div>
+  ),
+};
+
+/** 箭头叠在内容之上（适合大图 banner）。 */
+export const ArrowInside: Story = {
+  render: () => (
+    <Carousel className="w-full max-w-md" arrowPosition="inner" loop>
+      <CarouselContent>
+        {slides.map((i) => (
+          <CarouselItem key={i}>
+            <Slide index={i - 1}>{i}</Slide>
+          </CarouselItem>
+        ))}
+      </CarouselContent>
+      <CarouselPrevious />
+      <CarouselNext />
+      <CarouselDots />
+    </Carousel>
+  ),
+};
+
+/** 受控当前页：外部按钮跳转。 */
+export const Controlled: Story = {
+  render: () => {
+    const [active, setActive] = React.useState(0);
+    return (
+      <div className="flex w-full max-w-xs flex-col gap-3 px-12">
+        <Carousel activeIndex={active} onChange={setActive}>
+          <CarouselContent>
+            {slides.map((i) => (
+              <CarouselItem key={i}>
+                <Slide index={i - 1}>{i}</Slide>
+              </CarouselItem>
+            ))}
+          </CarouselContent>
+          <CarouselPrevious />
+          <CarouselNext />
+        </Carousel>
+        <div className="flex flex-wrap gap-2">
+          {slides.map((_, i) => (
+            <Button
+              key={i}
+              size="sm"
+              variant={i === active ? 'default' : 'outline'}
+              onClick={() => setActive(i)}
+            >
+              {i + 1}
+            </Button>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+/** 自定义指示点渲染。 */
+export const CustomDots: Story = {
+  render: () => (
+    <Outer>
+      <Carousel className="w-full max-w-xs" loop>
+        <CarouselContent>
+          {slides.map((i) => (
+            <CarouselItem key={i}>
+              <Slide index={i - 1}>{i}</Slide>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots
+          render={({ index, selected, onClick }) => (
+            <button
+              type="button"
+              onClick={onClick}
+              className={
+                selected
+                  ? 'h-6 w-6 cursor-pointer rounded-md bg-primary text-xs text-primary-foreground'
+                  : 'h-6 w-6 cursor-pointer rounded-md bg-muted text-xs text-muted-foreground hover:bg-accent'
+              }
+            >
+              {index + 1}
+            </button>
+          )}
+        />
+      </Carousel>
+    </Outer>
+  ),
+};

package/src/components/cascader-select/index.tsx

@@ -0,0 +1,308 @@
+/**
+ * 级联选择 CascaderSelect
+ *
+ * 多层级数据的逐级选择，适合省/市/区、分类目录等场景。
+ *
+ * @when
+ * - 省市区三级地址选择
+ * - 分类目录的层级导航选择
+ * - 组织架构的逐层定位
+ */
+import * as React from 'react';
+import { ChevronDown, ChevronRight, Check, X as XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Spinner } from '@/components/spinner';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface CascaderOption {
+  /** 唯一标识。 */
+  value: string;
+  /** 显示文本。 */
+  label: string;
+  /** 子选项。 */
+  children?: CascaderOption[];
+  /** 是否禁用。 */
+  disabled?: boolean;
+  /** 是否为叶节点。 */
+  isLeaf?: boolean;
+}
+
+interface CascaderSelectProps
+  extends Omit<React.ComponentProps<'div'>, 'onChange'> {
+  /** 级联数据源。 */
+  options: CascaderOption[];
+  /** 选中的路径 value 数组（受控）。 */
+  value?: string[];
+  /** 默认选中路径。 */
+  defaultValue?: string[];
+  /** 选择变化回调。 */
+  onChange?: (value: string[], selectedOptions: CascaderOption[]) => void;
+  /** 占位文本。@default '请选择' */
+  placeholder?: string;
+  /** 是否禁用。@default false */
+  disabled?: boolean;
+  /** 尺寸。@default 'default' */
+  size?: 'sm' | 'default';
+  /**
+   * 是否允许清空：有选中值且未加载/未禁用时，右侧 chevron 切为 × 按钮。
+   * 与 Select 一致：右侧图标优先级 loading > clear > chevron，三者互斥、占同一位置。
+   * @default true
+   */
+  allowClear?: boolean;
+  /**
+   * 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"` 供外部样式穿透。
+   * @default false
+   */
+  loading?: boolean;
+}
+
+// ─── CascaderPanel ──────────────────────────────────────────────────────────
+
+function CascaderPanel({
+  columns,
+  activeValues,
+  onSelect,
+  size = 'default',
+}: {
+  columns: CascaderOption[][];
+  activeValues: string[];
+  onSelect: (value: string, depth: number) => void;
+  size?: 'sm' | 'default';
+}) {
+  return (
+    <div className="flex max-h-56 divide-x divide-border overflow-hidden rounded-md border border-border bg-popover shadow-md">
+      {columns.map((column, depth) => (
+        <div key={depth} className="min-w-32 overflow-y-auto p-1">
+          {column.map((option) => {
+            const isActive = activeValues[depth] === option.value;
+            const hasChildren =
+              !option.isLeaf && option.children && option.children.length > 0;
+
+            return (
+              <div
+                key={option.value}
+                role="option"
+                aria-selected={isActive}
+                className={cn(
+                  'flex cursor-pointer items-center justify-between gap-1 rounded-sm px-2 text-xs transition-colors',
+                  size === 'default' && 'h-8',
+                  size === 'sm' && 'py-1',
+                  isActive && 'bg-accent text-accent-foreground',
+                  !isActive && 'hover:bg-accent/50',
+                  option.disabled && 'pointer-events-none opacity-50',
+                )}
+                onClick={() => {
+                  if (option.disabled) return;
+                  onSelect(option.value, depth);
+                }}
+              >
+                <span className="flex items-center gap-1 truncate">
+                  {isActive && !hasChildren && (
+                    <Check className="size-3 shrink-0" />
+                  )}
+                  <span className="truncate">{option.label}</span>
+                </span>
+                {hasChildren && (
+                  <ChevronRight className="size-3 shrink-0 text-muted-foreground" />
+                )}
+              </div>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ─── CascaderSelect ─────────────────────────────────────────────────────────
+
+function CascaderSelect({
+  options,
+  value: controlledValue,
+  defaultValue = [],
+  onChange,
+  placeholder = '请选择',
+  disabled = false,
+  size = 'default',
+  allowClear = true,
+  loading = false,
+  className,
+  ...props
+}: CascaderSelectProps) {
+  const [internalValue, setInternalValue] =
+    React.useState<string[]>(defaultValue);
+  const [open, setOpen] = React.useState(false);
+  const [activeValues, setActiveValues] = React.useState<string[]>([]);
+  const containerRef = React.useRef<HTMLDivElement>(null);
+
+  const value = controlledValue ?? internalValue;
+
+  // Build columns from activeValues
+  const columns = React.useMemo(() => {
+    const cols: CascaderOption[][] = [options];
+    let current = options;
+    for (const val of activeValues) {
+      const found = current.find((o) => o.value === val);
+      if (found?.children && found.children.length > 0) {
+        cols.push(found.children);
+        current = found.children;
+      } else {
+        break;
+      }
+    }
+    return cols;
+  }, [options, activeValues]);
+
+  // Initialize activeValues from value
+  React.useEffect(() => {
+    if (value.length > 0) {
+      setActiveValues(value);
+    }
+  }, [value]);
+
+  // Get display label
+  const getDisplayLabel = (): string => {
+    const labels: string[] = [];
+    let current = options;
+    for (const val of value) {
+      const found = current.find((o) => o.value === val);
+      if (found) {
+        labels.push(found.label);
+        current = found.children ?? [];
+      } else {
+        break;
+      }
+    }
+    return labels.join(' / ');
+  };
+
+  const handleSelect = (val: string, depth: number) => {
+    const newActiveValues = [...activeValues.slice(0, depth), val];
+    setActiveValues(newActiveValues);
+
+    // Find the selected option
+    let current = options;
+    const selectedOptions: CascaderOption[] = [];
+    for (const v of newActiveValues) {
+      const found = current.find((o) => o.value === v);
+      if (found) {
+        selectedOptions.push(found);
+        current = found.children ?? [];
+      }
+    }
+
+    // Check if leaf
+    const lastOption = selectedOptions[selectedOptions.length - 1];
+    const isLeaf =
+      lastOption?.isLeaf ??
+      (!lastOption?.children || lastOption.children.length === 0);
+
+    if (isLeaf) {
+      if (controlledValue === undefined) setInternalValue(newActiveValues);
+      onChange?.(newActiveValues, selectedOptions);
+      setOpen(false);
+    }
+  };
+
+  const handleClear = () => {
+    if (controlledValue === undefined) setInternalValue([]);
+    setActiveValues([]);
+    onChange?.([], []);
+  };
+
+  // Close on outside click
+  React.useEffect(() => {
+    if (!open) return;
+    const handleClick = (e: MouseEvent) => {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(e.target as Node)
+      ) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [open]);
+
+  const displayLabel = getDisplayLabel();
+  const showClear = !loading && allowClear && value.length > 0 && !disabled;
+
+  return (
+    <div
+      data-slot="cascader-select"
+      ref={containerRef}
+      className={cn('relative inline-block', className)}
+      {...props}
+    >
+      {/* Trigger */}
+      <button
+        type="button"
+        data-slot="cascader-select-trigger"
+        data-size={size}
+        data-loading={loading ? 'true' : undefined}
+        disabled={disabled}
+        onClick={() => setOpen(!open)}
+        className={cn(
+          'flex w-fit min-w-36 cursor-pointer items-center justify-between gap-1.5 rounded-md border border-input bg-transparent px-2.5 text-xs 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',
+          size === 'default' && 'h-8',
+          size === 'sm' && 'h-7',
+        )}
+      >
+        <span
+          className={cn('truncate', !displayLabel && 'text-muted-foreground')}
+        >
+          {displayLabel || placeholder}
+        </span>
+        {showClear ? (
+          <span
+            role="button"
+            aria-label="清除"
+            tabIndex={-1}
+            data-slot="cascader-select-clear"
+            onPointerDown={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+            }}
+            onClick={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+              handleClear();
+            }}
+            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>
+        ) : loading ? (
+          <Spinner size="md" tone="muted" className="pointer-events-none" />
+        ) : (
+          <ChevronDown
+            className={cn(
+              'pointer-events-none size-4 shrink-0 text-muted-foreground transition-transform',
+              open && 'rotate-180',
+            )}
+          />
+        )}
+      </button>
+
+      {/* Dropdown */}
+      {open && (
+        <div className="absolute left-0 top-full z-50 mt-1">
+          <CascaderPanel
+            columns={columns}
+            activeValues={activeValues}
+            onSelect={handleSelect}
+            size={size}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export { CascaderSelect };
+export type { CascaderSelectProps, CascaderOption };

package/src/components/cascader-select/meta.md

@@ -0,0 +1,28 @@
+# CascaderSelect
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+级联选择 CascaderSelect
+多层级数据的逐级选择，适合省/市/区、分类目录等场景。
+
+## 使用场景
+
+- 省市区三级地址选择
+- 分类目录的层级导航选择
+- 组织架构的逐层定位
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `options` | `CascaderOption[]` | – | ✓ | 级联数据源。 |
+| `value` | `string[]` | – | – | 选中的路径 value 数组（受控）。 |
+| `defaultValue` | `string[]` | – | – | 默认选中路径。 |
+| `onChange` | `(value: string[], selectedOptions: CascaderOption[]) => void` | – | – | 选择变化回调。 |
+| `placeholder` | `string` | – | – | 占位文本。@default '请选择' |
+| `disabled` | `boolean` | – | – | 是否禁用。@default false |
+| `size` | `'sm' \| 'default'` | – | – | 尺寸。@default 'default' |
+| `allowClear` | `boolean` | `true` | – | 是否允许清空：有选中值且未加载/未禁用时，右侧 chevron 切为 × 按钮。 与 Select 一致：右侧图标优先级 loading > clear > chevron，三者互斥、占同一位置。 |
+| `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"` 供外部样式穿透。 |