@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/carousel/index.tsx

@@ -0,0 +1,481 @@
+/**
+ * 轮播 Carousel
+ *
+ * 在有限空间内循环展示一组内容，常用于 banner、特性介绍与同主题素材的浏览。
+ *
+ * 组合结构：Carousel > CarouselContent > CarouselItem，搭配 CarouselPrevious / CarouselNext / CarouselDots 控件。
+ *
+ * @when
+ * - 单图 banner 轮播展示，承载运营位
+ * - 多图同时展示并按页滚动浏览
+ * - 需要自动播放、悬浮暂停、无穷循环、淡入淡出等增强行为
+ * - 业务需要受控当前页索引（如外部按钮跳转）
+ */
+
+import * as React from 'react';
+import useEmblaCarousel, {
+  type UseEmblaCarouselType,
+} from 'embla-carousel-react';
+import Autoplay from 'embla-carousel-autoplay';
+import Fade from 'embla-carousel-fade';
+import { ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+
+type CarouselApi = UseEmblaCarouselType[1];
+type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
+type CarouselOptions = UseCarouselParameters[0];
+type CarouselPlugin = UseCarouselParameters[1];
+
+/** Autoplay 行为配置（{@link Carousel} 的 `autoplay` prop 对象形式） */
+export interface CarouselAutoplayOptions {
+  /** 单页停留时长，单位 ms */
+  delay?: number;
+  /** 用户交互（拖拽 / 点击箭头）后停止自动播放 */
+  stopOnInteraction?: boolean;
+  /** 鼠标悬浮时暂停 */
+  stopOnMouseEnter?: boolean;
+}
+
+export interface CarouselProps
+  extends Omit<React.ComponentProps<'div'>, 'onChange'> {
+  /** Embla 原生选项，会与便捷 prop 合并（便捷 prop 优先） */
+  opts?: CarouselOptions;
+  /** Embla 原生插件，会与内部注入的 Autoplay/Fade 合并 */
+  plugins?: CarouselPlugin;
+  /** 滚动方向 */
+  orientation?: 'horizontal' | 'vertical';
+  /** 暴露 embla api 给上层使用 */
+  setApi?: (api: CarouselApi) => void;
+  /** 是否无穷循环 */
+  loop?: boolean;
+  /** 滑动对齐策略 */
+  align?: 'start' | 'center' | 'end';
+  /** 单次滚动张数 */
+  slidesToScroll?: number | 'auto';
+  /** 自动播放：true 走默认 4000ms，对象可调速 + 控制悬浮暂停 */
+  autoplay?: boolean | CarouselAutoplayOptions;
+  /** 切换动画用渐变（注入 embla-carousel-fade 插件） */
+  fade?: boolean;
+  /** 受控：当前页索引 */
+  activeIndex?: number;
+  /** 非受控：初始页索引 */
+  defaultActiveIndex?: number;
+  /** 切换回调，参数为新的页索引 */
+  onChange?: (index: number) => void;
+  /** 箭头按钮位置 */
+  arrowPosition?: 'inner' | 'outer';
+}
+
+type CarouselContextProps = {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  api: ReturnType<typeof useEmblaCarousel>[1];
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  scrollTo: (index: number) => void;
+  canScrollPrev: boolean;
+  canScrollNext: boolean;
+  selectedIndex: number;
+  scrollSnaps: number[];
+  orientation: 'horizontal' | 'vertical';
+  arrowPosition: 'inner' | 'outer';
+};
+
+const CarouselContext = React.createContext<CarouselContextProps | null>(null);
+
+function useCarousel() {
+  const context = React.useContext(CarouselContext);
+
+  if (!context) {
+    throw new Error('useCarousel must be used within a <Carousel />');
+  }
+
+  return context;
+}
+
+function Carousel({
+  orientation = 'horizontal',
+  opts,
+  setApi,
+  plugins,
+  loop,
+  align,
+  slidesToScroll,
+  autoplay = false,
+  fade = false,
+  activeIndex,
+  defaultActiveIndex,
+  onChange,
+  arrowPosition = 'outer',
+  className,
+  children,
+  ...props
+}: CarouselProps) {
+  // ─── 合并 embla options（便捷 prop 优先于 opts）────────────────────────
+  const mergedOpts = React.useMemo<CarouselOptions>(
+    () => ({
+      ...opts,
+      axis: orientation === 'horizontal' ? 'x' : 'y',
+      ...(loop !== undefined ? { loop } : {}),
+      ...(align !== undefined ? { align } : {}),
+      ...(slidesToScroll !== undefined ? { slidesToScroll } : {}),
+      ...(defaultActiveIndex !== undefined && activeIndex === undefined
+        ? { startIndex: defaultActiveIndex }
+        : {}),
+    }),
+    [
+      opts,
+      orientation,
+      loop,
+      align,
+      slidesToScroll,
+      defaultActiveIndex,
+      activeIndex,
+    ],
+  );
+
+  // ─── 合并 plugins：内部 Autoplay / Fade + 外部 plugins ────────────────
+  const mergedPlugins = React.useMemo<CarouselPlugin>(() => {
+    const list: NonNullable<CarouselPlugin> = [];
+    if (autoplay) {
+      const opt =
+        typeof autoplay === 'object'
+          ? autoplay
+          : ({} as CarouselAutoplayOptions);
+      list.push(
+        Autoplay({
+          delay: opt.delay ?? 4000,
+          stopOnInteraction: opt.stopOnInteraction ?? true,
+          stopOnMouseEnter: opt.stopOnMouseEnter ?? false,
+        }),
+      );
+    }
+    if (fade) {
+      list.push(Fade());
+    }
+    if (plugins) list.push(...plugins);
+    return list;
+  }, [autoplay, fade, plugins]);
+
+  const [carouselRef, api] = useEmblaCarousel(mergedOpts, mergedPlugins);
+  const [canScrollPrev, setCanScrollPrev] = React.useState(false);
+  const [canScrollNext, setCanScrollNext] = React.useState(false);
+  const [selectedIndex, setSelectedIndex] = React.useState(
+    defaultActiveIndex ?? 0,
+  );
+  const [scrollSnaps, setScrollSnaps] = React.useState<number[]>([]);
+
+  const onSelect = React.useCallback(
+    (api: CarouselApi) => {
+      if (!api) return;
+      setCanScrollPrev(api.canScrollPrev());
+      setCanScrollNext(api.canScrollNext());
+      const idx = api.selectedScrollSnap();
+      setSelectedIndex(idx);
+      onChange?.(idx);
+    },
+    [onChange],
+  );
+
+  const onReInit = React.useCallback((api: CarouselApi) => {
+    if (!api) return;
+    setScrollSnaps(api.scrollSnapList());
+  }, []);
+
+  const scrollPrev = React.useCallback(() => {
+    api?.scrollPrev();
+  }, [api]);
+
+  const scrollNext = React.useCallback(() => {
+    api?.scrollNext();
+  }, [api]);
+
+  const scrollTo = React.useCallback(
+    (index: number) => {
+      api?.scrollTo(index);
+    },
+    [api],
+  );
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault();
+        scrollPrev();
+      } else if (event.key === 'ArrowRight') {
+        event.preventDefault();
+        scrollNext();
+      }
+    },
+    [scrollPrev, scrollNext],
+  );
+
+  // ─── 暴露 api ────────────────────────────────────────────────────────
+  React.useEffect(() => {
+    if (!api || !setApi) return;
+    setApi(api);
+  }, [api, setApi]);
+
+  // ─── 监听 select / reInit 同步 state ──────────────────────────────────
+  React.useEffect(() => {
+    if (!api) return;
+    onSelect(api);
+    onReInit(api);
+    api.on('reInit', onSelect);
+    api.on('reInit', onReInit);
+    api.on('select', onSelect);
+
+    return () => {
+      api.off('reInit', onSelect);
+      api.off('reInit', onReInit);
+      api.off('select', onSelect);
+    };
+  }, [api, onSelect, onReInit]);
+
+  // ─── 受控：activeIndex 变化时同步到 embla ─────────────────────────────
+  React.useEffect(() => {
+    if (!api || activeIndex === undefined) return;
+    if (api.selectedScrollSnap() !== activeIndex) {
+      api.scrollTo(activeIndex);
+    }
+  }, [api, activeIndex]);
+
+  return (
+    <CarouselContext.Provider
+      value={{
+        carouselRef,
+        api,
+        scrollPrev,
+        scrollNext,
+        scrollTo,
+        canScrollPrev,
+        canScrollNext,
+        selectedIndex,
+        scrollSnaps,
+        orientation,
+        arrowPosition,
+      }}
+    >
+      <div
+        onKeyDownCapture={handleKeyDown}
+        className={cn('relative', className)}
+        role="region"
+        aria-roledescription="carousel"
+        data-slot="carousel"
+        data-orientation={orientation}
+        data-arrow-position={arrowPosition}
+        {...props}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+}
+
+function CarouselContent({ className, ...props }: React.ComponentProps<'div'>) {
+  const { carouselRef, orientation } = useCarousel();
+
+  return (
+    <div
+      ref={carouselRef}
+      className="overflow-hidden"
+      data-slot="carousel-content"
+    >
+      <div
+        className={cn(
+          'flex',
+          orientation === 'horizontal' ? '-ml-4' : '-mt-4 flex-col',
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+}
+
+function CarouselItem({ className, ...props }: React.ComponentProps<'div'>) {
+  const { orientation } = useCarousel();
+
+  return (
+    <div
+      role="group"
+      aria-roledescription="slide"
+      data-slot="carousel-item"
+      className={cn(
+        'min-w-0 shrink-0 grow-0 basis-full',
+        orientation === 'horizontal' ? 'pl-4' : 'pt-4',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function CarouselPrevious({
+  className,
+  variant = 'outline',
+  size = 'icon-sm',
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, arrowPosition, scrollPrev, canScrollPrev } =
+    useCarousel();
+
+  const innerH = 'top-1/2 left-2 -translate-y-1/2';
+  const outerH = 'top-1/2 -left-12 -translate-y-1/2';
+  const innerV = 'top-2 left-1/2 -translate-x-1/2 rotate-90';
+  const outerV = '-top-12 left-1/2 -translate-x-1/2 rotate-90';
+
+  const positionClass =
+    orientation === 'horizontal'
+      ? arrowPosition === 'inner'
+        ? innerH
+        : outerH
+      : arrowPosition === 'inner'
+      ? innerV
+      : outerV;
+
+  return (
+    <Button
+      data-slot="carousel-previous"
+      variant={variant}
+      size={size}
+      shape="circle"
+      className={cn(
+        'absolute z-10 touch-manipulation',
+        arrowPosition === 'inner' &&
+          'bg-background/80 backdrop-blur-sm shadow-sm',
+        positionClass,
+        className,
+      )}
+      disabled={!canScrollPrev}
+      onClick={scrollPrev}
+      {...props}
+    >
+      <ChevronLeftIcon />
+      <span className="sr-only">Previous slide</span>
+    </Button>
+  );
+}
+
+function CarouselNext({
+  className,
+  variant = 'outline',
+  size = 'icon-sm',
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, arrowPosition, scrollNext, canScrollNext } =
+    useCarousel();
+
+  const innerH = 'top-1/2 right-2 -translate-y-1/2';
+  const outerH = 'top-1/2 -right-12 -translate-y-1/2';
+  const innerV = 'bottom-2 left-1/2 -translate-x-1/2 rotate-90';
+  const outerV = '-bottom-12 left-1/2 -translate-x-1/2 rotate-90';
+
+  const positionClass =
+    orientation === 'horizontal'
+      ? arrowPosition === 'inner'
+        ? innerH
+        : outerH
+      : arrowPosition === 'inner'
+      ? innerV
+      : outerV;
+
+  return (
+    <Button
+      data-slot="carousel-next"
+      variant={variant}
+      size={size}
+      shape="circle"
+      className={cn(
+        'absolute z-10 touch-manipulation',
+        arrowPosition === 'inner' &&
+          'bg-background/80 backdrop-blur-sm shadow-sm',
+        positionClass,
+        className,
+      )}
+      disabled={!canScrollNext}
+      onClick={scrollNext}
+      {...props}
+    >
+      <ChevronRightIcon />
+      <span className="sr-only">Next slide</span>
+    </Button>
+  );
+}
+
+export interface CarouselDotsProps extends React.ComponentProps<'div'> {
+  /** 单个指示点附加 className（不传 render 时生效） */
+  dotClassName?: string;
+  /** 自定义指示点渲染（高级使用） */
+  render?: (props: {
+    index: number;
+    selected: boolean;
+    onClick: () => void;
+  }) => React.ReactNode;
+}
+
+function CarouselDots({
+  className,
+  dotClassName,
+  render,
+  ...props
+}: CarouselDotsProps) {
+  const { orientation, scrollSnaps, selectedIndex, scrollTo } = useCarousel();
+
+  if (scrollSnaps.length <= 1) return null;
+
+  return (
+    <div
+      data-slot="carousel-dots"
+      className={cn(
+        'absolute z-10 flex',
+        orientation === 'horizontal'
+          ? 'bottom-3 left-1/2 -translate-x-1/2 gap-2'
+          : 'top-1/2 right-3 -translate-y-1/2 flex-col gap-2',
+        className,
+      )}
+      {...props}
+    >
+      {scrollSnaps.map((_, index) => {
+        const selected = index === selectedIndex;
+        const onClick = () => scrollTo(index);
+        if (render) {
+          return (
+            <React.Fragment key={index}>
+              {render({ index, selected, onClick })}
+            </React.Fragment>
+          );
+        }
+        return (
+          <button
+            key={index}
+            type="button"
+            role="tab"
+            aria-label={`Go to slide ${index + 1}`}
+            aria-selected={selected}
+            data-slot="carousel-dot"
+            data-state={selected ? 'active' : 'inactive'}
+            onClick={onClick}
+            className={cn(
+              'h-2 cursor-pointer rounded-full bg-foreground/30 transition-all hover:bg-foreground/50',
+              selected ? 'w-4 bg-primary hover:bg-primary' : 'w-2',
+              dotClassName,
+            )}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+export {
+  type CarouselApi,
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselDots,
+  useCarousel,
+};

package/src/components/carousel/meta.md

@@ -0,0 +1,208 @@
+# Carousel
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+轮播 Carousel
+在有限空间内循环展示一组内容，常用于 banner、特性介绍与同主题素材的浏览。
+组合结构：Carousel > CarouselContent > CarouselItem，搭配 CarouselPrevious / CarouselNext / CarouselDots 控件。
+
+## 使用场景
+
+- 单图 banner 轮播展示，承载运营位
+- 多图同时展示并按页滚动浏览
+- 需要自动播放、悬浮暂停、无穷循环、淡入淡出等增强行为
+- 业务需要受控当前页索引（如外部按钮跳转）
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `opts` | `CarouselOptions` | – | – | Embla 原生选项，会与便捷 prop 合并（便捷 prop 优先） |
+| `plugins` | `CarouselPlugin` | – | – | Embla 原生插件，会与内部注入的 Autoplay/Fade 合并 |
+| `orientation` | `'horizontal' \| 'vertical'` | – | – | 滚动方向 |
+| `setApi` | `(api: CarouselApi) => void` | – | – | 暴露 embla api 给上层使用 |
+| `loop` | `boolean` | – | – | 是否无穷循环 |
+| `align` | `'start' \| 'center' \| 'end'` | – | – | 滑动对齐策略 |
+| `slidesToScroll` | `number \| 'auto'` | – | – | 单次滚动张数 |
+| `autoplay` | `boolean \| CarouselAutoplayOptions` | – | – | 自动播放：true 走默认 4000ms，对象可调速 + 控制悬浮暂停 |
+| `fade` | `boolean` | – | – | 切换动画用渐变（注入 embla-carousel-fade 插件） |
+| `activeIndex` | `number` | – | – | 受控：当前页索引 |
+| `defaultActiveIndex` | `number` | – | – | 非受控：初始页索引 |
+| `onChange` | `(index: number) => void` | – | – | 切换回调，参数为新的页索引 |
+| `arrowPosition` | `'inner' \| 'outer'` | – | – | 箭头按钮位置 |
+| `dotClassName` | `string` | – | – | 单个指示点附加 className（不传 render 时生效） |
+| `render` | `(props: { index: number; selected: boolean; onClick: () => void; }) => React.ReactNode` | – | – | 自定义指示点渲染（高级使用） |
+
+## 示例
+
+### MultipleItems
+
+多图同时展示，按页滚动。
+
+```tsx
+<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>
+```
+
+### Loop
+
+无穷循环。
+
+```tsx
+<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>
+```
+
+### Autoplay
+
+自动播放，悬浮暂停。
+
+```tsx
+<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
+
+渐变切换动画（fade）。
+
+```tsx
+<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>
+```
+
+### Vertical
+
+垂直方向。
+
+```tsx
+<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>
+```
+
+### ArrowInside
+
+箭头叠在内容之上（适合大图 banner）。
+
+```tsx
+<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>
+```
+
+### CustomDots
+
+自定义指示点渲染。
+
+```tsx
+<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>
+```